WebKitWebExtension: WPE WebExtensions and DOM Reference Manual

## WebKitWebExtension WebKitWebExtension — Represents a WebExtension of the WebProcess |

## Functions

void | (*WebKitWebExtensionInitializeFunction) ()
void | (*WebKitWebExtensionInitializeWithUserDataFunction) ()
WebKitWebPage * | webkit_web_extension_get_page ()
void | webkit_web_extension_send_message_to_context ()
WebKitUserMessage * | webkit_web_extension_send_message_to_context_finish ()

## Signals

void | page-created | Run Last
void | user-message-received | Run Last

## Types and Values

struct | WebKitWebExtension

## Object Hierarchy

        GObject
        ╰── WebKitWebExtension

## Description

WebKitWebExtension is a loadable module for the WebProcess. It allows you to execute code in the WebProcess and being able to use the DOM API, to change any request or to inject custom JavaScript code, for example.

To create a WebKitWebExtension you should write a module with an initialization function that could be either `webkit_web_extension_initialize()` with prototype WebKitWebExtensionInitializeFunction or `webkit_web_extension_initialize_with_user_data()` with prototype WebKitWebExtensionInitializeWithUserDataFunction. This function has to be public and it has to use the G_MODULE_EXPORT macro. It is called when the web process is initialized.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    static void
    web_page_created_callback (WebKitWebExtension *extension,
                               WebKitWebPage      *web_page,
                               gpointer            user_data)
    {
        g_print ("Page %d created for %s\n",
                 webkit_web_page_get_id (web_page),
                 webkit_web_page_get_uri (web_page));
    }

    G_MODULE_EXPORT void
    webkit_web_extension_initialize (WebKitWebExtension *extension)
    {
        g_signal_connect (extension, "page-created",
                          G_CALLBACK (web_page_created_callback),
                          NULL);
    }

The previous piece of code shows a trivial example of an extension that notifies when a WebKitWebPage is created.

WebKit has to know where it can find the created WebKitWebExtension. To do so you should use the `webkit_web_context_set_web_extensions_directory()` function. The signal “initialize-web-extensions” is the recommended place to call it.

To provide the initialization data used by the `webkit_web_extension_initialize_with_user_data()` function, you have to call `webkit_web_context_set_web_extensions_initialization_user_data()` with the desired data as parameter. You can see an example of this in the following piece of code:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    #define WEB_EXTENSIONS_DIRECTORY /* ... */

    static void
    initialize_web_extensions (WebKitWebContext *context,
                               gpointer          user_data)
    {
      /* Web Extensions get a different ID for each Web Process */
      static guint32 unique_id = 0;

      webkit_web_context_set_web_extensions_directory (
         context, WEB_EXTENSIONS_DIRECTORY);
      webkit_web_context_set_web_extensions_initialization_user_data (
         context, g_variant_new_uint32 (unique_id++));
    }

    int main (int argc, char **argv)
    {
      g_signal_connect (webkit_web_context_get_default (),
                       "initialize-web-extensions",
                        G_CALLBACK (initialize_web_extensions),
                        NULL);

      GtkWidget *view = webkit_web_view_new ();

      /* ... */
    }

## Functions

### WebKitWebExtensionInitializeFunction ()

    void
    (*WebKitWebExtensionInitializeFunction)
                                   (WebKitWebExtension *extension);

Type definition for a function that will be called to initialize the web extension when the web process starts.

#### Parameters

extension | a WebKitWebExtension |

### WebKitWebExtensionInitializeWithUserDataFunction ()

    void
    (*WebKitWebExtensionInitializeWithUserDataFunction)
                                   (WebKitWebExtension *extension,
                                    const GVariant *user_data);

Type definition for a function that will be called to initialize the web extensions when the web process starts, and which receives as additional argument the user data set with `webkit_web_context_set_web_extensions_initialization_user_data()`.

#### Parameters

extension | a WebKitWebExtension |
user_data | a GVariant |

Since: 2.4

### webkit_web_extension_get_page ()

    WebKitWebPage *
    webkit_web_extension_get_page (WebKitWebExtension *extension,
                                   guint64 page_id);

Get the web page of the given `page_id` .

#### Parameters

extension | a WebKitWebExtension |
page_id | the identifier of the WebKitWebPage to get |

#### Returns

the WebKitWebPage for the given `page_id` , or `NULL` if the identifier doesn't correspond to an existing web page.

[transfer none]

### webkit_web_extension_send_message_to_context ()

    void
    webkit_web_extension_send_message_to_context
                                   (WebKitWebExtension *extension,
                                    WebKitUserMessage *message,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Send `message` to the WebKitWebContext corresponding to `extension` . If `message` is floating, it's consumed.

If you don't expect any reply, or you simply want to ignore it, you can pass `NULL` as `calback` . When the operation is finished, `callback` will be called. You can then call `webkit_web_extension_send_message_to_context_finish()` to get the message reply.

#### Parameters

extension | a WebKitWebExtension |
message | a WebKitUserMessage |
cancellable | a GCancellable or `NULL` to ignore. | [nullable]
callback | (nullable): A GAsyncReadyCallback to call when the request is satisfied or `NULL`. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 2.28

### webkit_web_extension_send_message_to_context_finish ()

    WebKitUserMessage *
    webkit_web_extension_send_message_to_context_finish
                                   (WebKitWebExtension *extension,
                                    GAsyncResult *result,
                                    GError **error);

Finish an asynchronous operation started with `webkit_web_extension_send_message_to_context()`.

#### Parameters

extension | a WebKitWebExtension |
result | a GAsyncResult |
error | return location for error or `NULL` to ignor |

#### Returns

a WebKitUserMessage with the reply or `NULL` in case of error.

[transfer full]

Since: 2.28

## Types and Values

### struct WebKitWebExtension

    struct WebKitWebExtension;

## Signal Details

### The `“page-created”` signal

    void
    user_function (WebKitWebExtension *extension,
                   WebKitWebPage      *web_page,
                   gpointer            user_data)

This signal is emitted when a new WebKitWebPage is created in the Web Process.

#### Parameters

extension | the WebKitWebExtension on which the signal is emitted |
web_page | the WebKitWebPage created |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“user-message-received”` signal

    void
    user_function (WebKitWebExtension *extension,
                   WebKitUserMessage  *message,
                   gpointer            user_data)

This signal is emitted when a WebKitUserMessage is received from the WebKitWebContext corresponding to `extension` . Messages sent by WebKitWebContext are always broadcasted to all WebKitWebExtensions and they can't be replied to. Calling `webkit_user_message_send_reply()` will do nothing.

#### Parameters

extension | the WebKitWebExtension on which the signal is emitted |
message | the WebKitUserMessage received |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.28