BlinkGTK Application Integration API Reference — Custom Schemes, Messaging, Script Injection

Version: 1.2.5-build5
Last updated: 2026-07-30

日本語

About this page

APIs that connect your application and the web page in both directions:

• Create your own URL scheme — your application answers URLs like
  ebook://book/chapter1.html. An e-book reader can decrypt the contents of
  an encrypted EPUB and hand them to the page, for example
• Exchange messages with the page — call C callbacks from the page's
  JavaScript, and call the page's JavaScript from C
• Inject scripts and CSS into every page — add your application's
  JavaScript or styles without touching the content

Beyond signatures, each API description includes its behavioral details —
which thread it runs on, when it fires, who frees which memory, and what
happens in edge cases. These descriptions were written against the current
implementation; points that may improve in future versions are marked with
"in the current implementation".

Getting started

/* Register the "app" scheme. The application answers app://... requests */
static char* on_app_scheme(BlinkWebView *view, const char *uri, gpointer data) {
    return g_strdup("<html><body><h1>Served by the app</h1></body></html>");
}

blink_web_view_register_custom_scheme(view, "app", on_app_scheme, NULL);
blink_web_view_load_uri(view, "app://home/");

Overview

Receiving the result of execute_javascript()

The result given to the callback is a JSON string.

static void on_js(const char *result, gpointer user_data) {
  /* result is never NULL */
  if (result[0] == '\0') {
    /* the script could not run (no WebContents / no main frame) */
    return;
  }
  /* parse as JSON from here. A value that could not be encoded arrives as "null" */
}
blink_web_view_execute_javascript(BLINK_WEB_VIEW(view), "1+1", on_js, NULL);

Note: result is never NULL. When the script could not run you get an empty
string; when the value could not be encoded you get the four characters
null. Checking only for NULL lets both cases through.

JSON.parse("") throws. Test for the empty string first.

A script that returns a string yields a value wrapped in quotes ("...") —
it is JSON — so strcmp against the bare text will never match.

Passing NULL as callback runs the script without delivering a result.

Custom URL schemes

Three things to know first

1. Scheme names are pre-registered. You can use the five built-in names —
   app / blinkgtk / res / resource / ebook — plus any names added
   before blink_gtk_init() with blink_gtk_register_scheme()
   (since 1.2.3-build2) or the BLINKGTK_EXTRA_SCHEMES environment variable
   (comma-separated). URL scheme classification is fixed early in the engine's
   startup sequence, so register_custom_scheme() cannot introduce new names
   afterwards (see "Available scheme names" below)
2. Every kind of load fires the callback. Not just top-level navigations:
   subresources like <img src="app://...">, and fetch() / XHR from
   JavaScript all reach your handler. This is what makes it possible to run a
   whole SPA (single-page application) on top of a custom scheme
3. The callback runs synchronously on the GTK main thread. The UI is
   blocked until your handler returns. Decrypting large files or waiting on
   the network inside the handler freezes the window for that long. Do the
   heavy preparation ahead of time and only hand out in-memory data from the
   handler

blink_web_view_register_custom_scheme()

Registers a URI scheme. When a load for that scheme occurs, your callback is
called instead of any network access, and the string it returns becomes the
response.

Signature:

typedef char* (*BlinkCustomSchemeCallback)(BlinkWebView* web_view,
                                           const char* uri,
                                           gpointer user_data);

void blink_web_view_register_custom_scheme(BlinkWebView* web_view,
                                           const char* scheme,
                                           BlinkCustomSchemeCallback callback,
                                           gpointer user_data);

• Allocate the returned string with g_strdup() or similar. Ownership
  transfers to the engine, which frees it with g_free(). The response body
  is copied internally, so reusing your buffers after the callback returns is
  safe
• The response is a C string, so it is cut at the first 0x00. Use
  register_custom_scheme_full() for binary data such as images
• Returning NULL produces an empty page (HTTP 200, zero-byte body).
  The current implementation has no way to return a 404 or any other status
  code. To express "not found" to the reader, return an HTML page that says so
• Passing NULL as callback unregisters the scheme

blink_web_view_register_custom_scheme_full()

The binary-capable variant. Use it for anything that may contain 0x00 —
images, audio, fonts.

Signature:

typedef GBytes* (*BlinkCustomSchemeBytesCallback)(BlinkWebView* web_view,
                                                  const char* uri,
                                                  char** out_mime,
                                                  gpointer user_data);

void blink_web_view_register_custom_scheme_full(BlinkWebView* web_view,
                                                const char* scheme,
                                                BlinkCustomSchemeBytesCallback callback,
                                                gpointer user_data);

• Return the response as GBytes (binary-safe because it carries its own
  length). The engine calls g_bytes_unref() on it
• Set out_mime with something like g_strdup("image/jpeg"); the engine
  frees it with g_free(). If you leave it NULL, the type is guessed from
  the URI extension (see the table below). Parameters such as
  "text/html; charset=utf-8" are accepted from 1.2.3 (up to 1.2.2, HTML
  with parameters was shown as <pre> text)
• Returning NULL gives the same empty page (200) as the text variant

Example: serving an image from the application

static GBytes* on_ebook_scheme(BlinkWebView *view, const char *uri,
                               char **out_mime, gpointer data) {
    if (g_str_has_suffix(uri, "/cover.jpg")) {
        gsize len = 0;
        gchar *bytes = NULL;
        if (g_file_get_contents("/path/to/cover.jpg", &bytes, &len, NULL)) {
            *out_mime = g_strdup("image/jpeg");
            return g_bytes_new_take(bytes, len);
        }
    }
    return NULL;  /* becomes an empty page (200) */
}

What the URI looks like — parsing is the handler's job

Your callback receives the entire URI, such as
ebook://book/chapter1.xhtml?page=2. Splitting host and path and interpreting
the query are up to you. Three things real applications trip on:

1. Percent-decoding is required. Non-ASCII file names arrive encoded, like
   %E8%A1%A8%E7%B4%99.xhtml. Without g_uri_unescape_string() the file
   lookup misses and "a file that exists" turns into a 404
2. Reject path traversal. If you map paths to the file system, letting
   .. through exposes files outside your content root. Do the check after
   percent-decoding (to catch %2e%2e)
3. Decide what to do with query and fragment before stripping them. If you
   route purely on the path, strip everything from ?; if some feature (such
   as search) needs the query, save it first

static char* path_from_uri(const char *uri) {
    const char *p = strstr(uri, "://");
    if (!p) return NULL;
    const char *slash = strchr(p + 3, '/');          /* skip the host part */
    char *path = g_strdup(slash ? slash + 1 : "");
    char *q = strpbrk(path, "?#");                    /* strip query/fragment */
    if (q) *q = '\0';
    char *decoded = g_uri_unescape_string(path, NULL); /* 1: percent-decode */
    g_free(path);
    if (decoded && strstr(decoded, "..")) {           /* 2: reject traversal */
        g_free(decoded);
        return NULL;
    }
    return decoded;  /* path relative to your content root */
}

Available scheme names

Why pre-registered: classifying a scheme as a "standard scheme" (one with
scheme://host/path structure, where relative URLs resolve) and as a secure
context happens early in engine startup and cannot be done later.
register_custom_scheme() runs after that point, so it assigns a handler
to an already-registered name rather than adding new names.

To add a name, call blink_gtk_register_scheme() before blink_gtk_init()
(since 1.2.3-build2). It has the same effect as listing the name in
BLINKGTK_EXTRA_SCHEMES, and lets applications that cannot set an environment
variable do it in code.

#include <blink_gtk/blink_gtk.h>
#include <gtk/gtk.h>
#include <string.h>

/* called for every myapp:// load */
static GBytes* on_myapp(BlinkWebView* view, const char* uri,
                        char** out_mime, gpointer user_data) {
  static const char html[] = "<!doctype html><title>myapp</title><p>hello</p>";
  *out_mime = g_strdup("text/html");
  return g_bytes_new_static(html, strlen(html));
}

int main(int argc, char** argv) {
  if (!blink_gtk_register_scheme("myapp")) return 1;   /* call before init */ /* FALSE + warning if not */
  if (!blink_gtk_init(&argc, &argv)) return 1;
  GtkWidget* window = gtk_window_new();
  GtkWidget* view = blink_web_view_new();
  gtk_window_set_child(GTK_WINDOW(window), view);
  blink_web_view_register_custom_scheme_full(BLINK_WEB_VIEW(view), "myapp",
                                             on_myapp, NULL);
  blink_web_view_load_uri(BLINK_WEB_VIEW(view), "myapp://app/index.html");
  gtk_window_present(GTK_WINDOW(window));
  blink_gtk_run_main_loop();
  blink_gtk_shutdown();
  return 0;
}

• Returns gboolean. Called after blink_gtk_init() it has no effect, logs a
  warning and returns FALSE. It also returns FALSE for a name that is not a
  valid scheme name (a letter first, then letters, digits, +, -, .)
• The name is registered in lower case

BLINKGTK_EXTRA_SCHEMES and fetch(): from 1.2.3, page JavaScript can call
fetch() on schemes added via the environment variable. Up to 1.2.2 a renderer-side
gate rejected them (navigations and subresources such as <img> did work).
If you target 1.2.2 or earlier, use one of the five built-in schemes.

Why a custom scheme instead of file://

Local content can be shown over file://, but file:// pages cannot use
fetch() and have a peculiar origin. Custom schemes are treated as a real
origin with a secure context (HTTPS-equivalent), so fetch(), Service
Workers and secure-context-only web APIs just work. An EPUB reader
built on BlinkGTK serves the entire Readium SPA and all book data over
ebook:// for exactly this reason — the fetch()-based web app runs
unmodified where file:// could not support it.

Behavioral details

Multiple WebViews: there is one registration per scheme per process. To
serve different content per WebView, tell them apart by the host or path of
the URI (such as app://reader/... and app://settings/...) or use different
scheme names. The callback's web_view argument is the WebView that registered
the scheme, not the one that made the request, so it cannot be used to branch. Also, in the current implementation
destroying a WebView does not unregister its schemes — unregister
(callback=NULL) before destroying it, or a handler pointing at the destroyed
WebView remains registered.

Security note: the current implementation does not check which page
initiated a request. If a handler returns sensitive data, either avoid
displaying external content in the same WebView or validate URIs strictly.

JS ↔︎ C messaging

A window.blinkgtk object is made available to JavaScript running in the page.

Three things to know first

1. window.blinkgtk is ready before the page's own scripts run
   (since 1.2.3-build2), so inline scripts at the top of the page can use it.
   Up to 1.2.3-build1 it appeared after the page finished loading (onload); if
   you also target those versions, initialize inside
   window.addEventListener('load', ...) or check for its existence first
2. JavaScript-side handler registrations are lost on navigation (each new
   document gets a fresh window). The page must call addMessageHandler
   again on every navigation. The C-side handlers belong to the WebView
   and survive navigations — no re-registration needed
3. The data that reaches C is a Base64-encoded byte sequence. Decode it
   with g_base64_decode(). The reverse direction (C → JS) is not
   Base64-encoded — the raw string is delivered. The encoding is asymmetric

blink_web_view_register_message_handler()

Registers a JS → C message handler.

Signature:

typedef void (*BlinkMessageCallback)(const char* name,
                                     const guint8* data,
                                     gsize length,
                                     gpointer user_data);

void blink_web_view_register_message_handler(BlinkWebView* web_view,
                                             const char* name,
                                             BlinkMessageCallback callback,
                                             gpointer user_data);

• name is the channel name. Use alphanumeric characters only (names
  containing delimiter characters are not delivered correctly)
• The callback runs on the GTK main thread; you can call GTK APIs directly
• Re-registering the same channel overwrites (one handler per channel on
  both the C and JS sides). To receive in several places, use the
  message-received signal below
• The lifetime of user_data is your responsibility (there is no destroy
  notification). Pass data that outlives the WebView, or free it yourself when
  you unregister

What you can pass from JavaScript (the data of postMessage(name, data)):

The message-received signal (multiple subscribers)

Independently of the per-channel callbacks, every message is also emitted
as the GObject signal message-received. Any number of g_signal_connect()
subscribers can listen, which suits cross-cutting concerns such as logging.

/* name: channel, data: Base64 string */
static void on_any_message(BlinkWebView *view, const char *name,
                           const char *data, gpointer user_data) {
    g_print("message on channel '%s'\n", name);
}
g_signal_connect(view, "message-received", G_CALLBACK(on_any_message), NULL);

The signal is not filtered by channel — check name in your handler.

blink_web_view_unregister_message_handler()

Unregisters a handler.

Signature:

void blink_web_view_unregister_message_handler(BlinkWebView* web_view,
                                               const char* name);

Note the post-unregister behavior: messages to an unregistered channel
(including channels that were never registered) are silently dropped — no
error anywhere. If messages seem to vanish during development, check the
channel name and registration first. The message-received signal keeps
firing regardless of unregistration.

blink_web_view_send_message_to_page()

Sends a message from C to the page's JavaScript.

Signature:

void blink_web_view_send_message_to_page(BlinkWebView* web_view,
                                         const char* name,
                                         const char* data);

The page registers its handler first:

<script>
window.addEventListener('load', function () {
  window.blinkgtk.addMessageHandler('page-turn', function (data) {
    console.log('instruction from the app:', data);
  });
});
</script>

Know when it does not arrive: this function has no queue. Messages
sent before the page finishes loading, or before the page calls
addMessageHandler, are silently discarded (no return value, no error).
The reliable pattern is to let the page announce readiness first:

/* Page side: send 'ready' once prepared
 *   window.blinkgtk.postMessage('ready', '');
 * C side: start sending only after 'ready' arrives */
static void on_ready(const char *name, const guint8 *data,
                     gsize length, gpointer user_data) {
    BlinkWebView *view = BLINK_WEB_VIEW(user_data);
    blink_web_view_send_message_to_page(view, "config",
                                        "{\"theme\":\"dark\"}");
}
blink_web_view_register_message_handler(BLINK_WEB_VIEW(view), "ready",
                                        on_ready, view);

Behavioral details

Security note: postMessage can be called by any script in the page
(there is no sender verification). In WebViews that display external content
or third-party scripts, never trust incoming data — validate it on the C side.

Script and CSS injection

blink_web_view_inject_user_script()

Injects JavaScript into the page.

Signature:

void blink_web_view_inject_user_script(BlinkWebView* web_view,
                                       const char* script,
                                       gboolean inject_at_document_start);

• inject_at_document_start=FALSE: runs once, immediately in the current
  page (equivalent to blink_web_view_execute_javascript()). It is not
  applied to later pages

• inject_at_document_start=TRUE: the script is kept and runs on every later
  page before the page's own <script> elements (1.2.0-build6 and later).
  The script is handed to the renderer process when that process starts, so:

  • Register it before the first blink_web_view_load_uri(). A script
    added while the renderer is already running does not reach that renderer;
    it takes effect from the next page that starts a renderer process
    (a warning is logged when this happens)
  • Scripts are shared by every BlinkWebView served by the same renderer
    process. If two views register different scripts, both views get both

• Scripts run in the same variable space as the page itself (the main world).
  You can read and write the page's variables — and the page can touch yours.
  Wrap your code in an IIFE to avoid name collisions

blink_web_view_inject_user_stylesheet()

Injects CSS into the current page and all later pages.

Signature:

void blink_web_view_inject_user_stylesheet(BlinkWebView* web_view,
                                           const char* css);

Useful for things like a reading app's dark theme or line-height adjustments —
changing the presentation without touching the content. Behavioral details:

• Applied immediately to the current page; on later pages it is applied
  after onload completes, so the pre-injection style may be visible for
  a moment on each new page (structurally unavoidable; styles that must
  apply from first paint belong in the content's own CSS, or in HTML served
  through your custom scheme)
• Implemented as appending a <style> element. Because it is added after
  the page's own styles, it wins ties at equal specificity
• Injecting the same CSS twice adds it twice (no deduplication). If you call
  it on every settings change, pair it with a script that removes the previous
  injection:

/* Idempotent replacement: remove the previous injection, then re-inject */
blink_web_view_execute_javascript(view,
    "var e = document.getElementById('myapp-style'); if (e) e.remove();",
    NULL, NULL);
char *js = g_strdup_printf(
    "var s = document.createElement('style');"
    "s.id = 'myapp-style'; s.textContent = '%s';"
    "document.head.appendChild(s);", escaped_css);
blink_web_view_execute_javascript(view, js, NULL, NULL);
g_free(js);

blink_web_view_remove_all_user_scripts()

Removes all registered scripts and stylesheets (the name says scripts, but
CSS is included).

Signature:

void blink_web_view_remove_all_user_scripts(BlinkWebView* web_view);

The effect is "stop applying to future pages." <style> elements already
injected into the currently displayed page are not removed. To remove them
immediately, inject with an id as in the idempotent pattern above and
remove() it via execute_javascript().

Running JavaScript from C

blink_web_view_execute_javascript()

Runs JavaScript in the current page's main frame.

Signature:

typedef void (*BlinkJavaScriptCallback)(const char* result, gpointer user_data);

void blink_web_view_execute_javascript(BlinkWebView* web_view,
                                       const char* script,
                                       BlinkJavaScriptCallback callback,
                                       gpointer user_data);

Behavioral details:

• Pass a callback to receive the value of the expression as a string; pass
  NULL to fire and forget
• If the result is a string, its raw value is delivered (no JSON quoting).
  Numbers, objects and other values arrive as a debug representation. For
  structured results, JSON.stringify() on the script side is the reliable
  approach:

blink_web_view_execute_javascript(view,
    "JSON.stringify({title: document.title, y: window.scrollY})",
    on_result, NULL);

• Promises are not resolved. You cannot receive the result of an async
  function or fetch() through the return value. Have the page send
  asynchronous results via window.blinkgtk.postMessage() when they complete
• Runs in the main frame only, in the page's own variable space (main world)
• Once a load has started, it can be called any time from load-changed's
  BLINK_LOAD_COMMITTED onwards. On errors (e.g. after the WebView is
  destroyed) the callback receives an empty string

Complete example: custom scheme + two-way messaging

The application serves app://home/, waits for the page to announce
readiness, then sends configuration; button clicks notify the C side.

#include <blink_gtk/blink_gtk.h>
#include <gtk/gtk.h>

static char* on_app_scheme(BlinkWebView *view, const char *uri, gpointer data) {
    return g_strdup(
        "<html><body>"
        "<h1>Served by the app</h1>"
        "<button onclick=\"window.blinkgtk.postMessage('clicked','hello')\">"
        "Notify C</button>"
        "<script>"
        "window.addEventListener('load', function () {"
        "  window.blinkgtk.addMessageHandler('config', function (d) {"
        "    document.body.style.background = d;"
        "  });"
        "  window.blinkgtk.postMessage('ready', '');"  /* announce readiness */
        "});"
        "</script>"
        "</body></html>");
}

static void on_message(const char *name, const guint8 *data,
                       gsize length, gpointer user_data) {
    if (g_strcmp0(name, "ready") == 0) {
        /* The page is ready — sends are reliable from here on */
        blink_web_view_send_message_to_page(BLINK_WEB_VIEW(user_data),
                                            "config", "#fffbe6");
        return;
    }
    gsize out_len = 0;
    guchar *decoded = g_base64_decode((const gchar *)data, &out_len);
    g_print("from the page '%s': %.*s\n", name, (int)out_len, decoded);
    g_free(decoded);
}

int main(int argc, char **argv) {
    blink_gtk_init(&argc, &argv);

    GtkWidget *win = gtk_window_new();
    gtk_window_set_default_size(GTK_WINDOW(win), 800, 600);

    GtkWidget *view = blink_web_view_new();
    gtk_window_set_child(GTK_WINDOW(win), view);

    blink_web_view_register_custom_scheme(BLINK_WEB_VIEW(view), "app",
                                          on_app_scheme, NULL);
    blink_web_view_register_message_handler(BLINK_WEB_VIEW(view), "ready",
                                            on_message, view);
    blink_web_view_register_message_handler(BLINK_WEB_VIEW(view), "clicked",
                                            on_message, view);

    gtk_window_present(GTK_WINDOW(win));
    blink_web_view_load_uri(BLINK_WEB_VIEW(view), "app://home/");

    int rc = blink_gtk_run_main_loop();
    blink_gtk_shutdown();  /* shut BlinkGTK down after the main loop returns */
    return rc;
}

Build:

cc -o app-integration app-integration.c $(pkg-config --cflags --libs blinkgtk-0.1)

A real-world configuration: an EPUB reader

An EPUB reader built on BlinkGTK runs "a web application shipped as a GTK
product" using only the APIs on this page. Design points worth borrowing:

• Serve the whole application over one scheme — both the reader UI (an
  SPA) and the book data (XHTML, images, audio) are returned by the ebook://
  handler. fetch() from the SPA works same-origin, so the web-app side needs
  almost no changes
• Binary goes through register_custom_scheme_full() — cover images and
  narration audio are returned as GBytes with an explicit MIME type
• URI handling in the order decode → validate → route — percent-decode
  first, reject .., then route on the leading path segment (reader,
  bookshelf, store)
• Split message channels by feature — separate channels like reader,
  shelf and store keep each C handler single-purpose and safe to add or
  remove

Limitations (current version)

Related

• How do I…? — find the function by goal
• Signals API — load-changed and other signals
• Settings API — enabling/disabling JavaScript etc.
• C API Reference — the complete function index

History