IPC API

Purpose overview: The main process uses jade_on to subscribe to events dispatched by the library (window lifecycle, navigation, script results, etc.); uses register_ipc_handler to respond to jade.invoke('command', data) calls from web pages; and uses send_ipc_message to proactively push messages to the renderer process.

Basic Types

Callback type (`IpcCallback`)

Main-process-side events and jade.invoke share the same C callback type (consistent with JadeView.h):

typedef const char *(*IpcCallback)(uint32_t window_id, const char *event_data);

Parameters

Return value (const char *)

The same function pointer type has different meanings in the two usages:

Event Subscription

Subscribe to events (`jade_on`)

Purpose: Register a callback by event name string; the library calls your IpcCallback when the event occurs. There are two dispatch-thread classes: interception events (window-closing, webview-will-navigate, webview-new-window, webview-download-started, and the enter/drop of drag-drop) are called inline synchronously on the GUI thread, where the library reads the return value immediately to decide allow/block, so return as quickly as possible; all other notification events are dispatched asynchronously by a worker thread pool.

uint32_t jade_on(const char *event_name, IpcCallback callback);

Parameters

Return value

Timing and conventions

• app-ready: Must be registered before JadeView_init, otherwise you will miss the first ready or failure notification (see Core API).
• Other events: Generally you can register them after app-ready succeeds and you start creating windows; for event names and event_data shapes, see Event Types.
• Multiple registrations: You can register multiple callbacks for the same event_name, and each jade_on returns a different id; when triggered, the execution order is implementation-defined — do not rely on order for mutual-exclusion logic.

Callback return value convention (`jade_on`)

For an IpcCallback registered via jade_on, the return value only has semantics on some events; for most notification-only events the return value can be ignored by the library, and it is conventional to uniformly write return NULL;.

• With "intercept / allow" semantics: such as window-closing, webview-will-navigate, webview-new-window (non-NULL = block); and webview-download-started (only NULL = allow the download, blocked by default). When blocking, it is recommended to write return (const char *)(uintptr_t)1;.
• Without interception semantics: return NULL.

For the complete list and explanation, see Event Types · IpcCallback return values.

About app-ready: Decide success solely by window_id == 1 — on success event_data is the JSON {"ok":true,"message":"success"}; window_id == 0 means failure, with event_data being a plain-text error description (a runtime crash goes through the separate crash event, not this one). For parsing, see Event Types. The 2.0 new event names such as second-instance, global-hotkey, tray-menu-command, and tray-event are on the same page.

Unsubscribe (jade_off)

Purpose: Cancel that single subscription by event_name + the id returned by jade_on; it will not accidentally remove other callbacks under the same event name.

int32_t jade_off(const char *event_name, uint32_t callback_id);

Two-way Messages

Send an IPC message (send_ipc_message)

Purpose: From the C side, proactively push a message to the renderer process in a specified window (type + body); the renderer process receives it with jade.on(message_type, ...).

int32_t send_ipc_message(
  uint32_t window_id,
  const char *message_type,
  const char *message_content
);

When the body is particularly large, 2.0 may internally use optimization paths such as chunking/referencing; it is still recommended to keep a single send within about 252MB to avoid memory pressure on WebView2 and the main process.

Register an invocation handler (register_ipc_handler)

Purpose: Bind a channel name string to a C callback; when the renderer process calls await jade.invoke(channel, payload, options), that IpcCallback is invoked.

int32_t register_ipc_handler(const char *channel, IpcCallback ipc_cb);

Return value convention (`register_ipc_handler`)

Here the IpcCallback return value represents the reply to the renderer process, which is different from the "interception" semantics of jade_on:

• Returning NULL, (const char *)1, or another special address recognized by the implementation: the library returns the default success JSON to the renderer process and will not call jade_text_free on that pointer.
• Returning another pointer: it is treated as the UTF-8 reply body, and the library calls jade_text_free after reading it; allocate it with jade_text_create (see Tools API).

In 2.0, the renderer process should use jade.invoke(command, payload, { timeout }); the legacy invokeAsync has been removed. For details, see Frontend Communication API.