IPC 通信 API

用途概括：宿主用 jade_on 订阅库派发的事件（窗口生命周期、导航、脚本结果等）；用 register_ipc_handler 响应网页里的 jade.invoke('命令', 数据)；用 send_ipc_message 主动给页面推消息。

---

IpcCallback

宿主侧事件与 jade.invoke 共用同一种 C 回调类型（与 JadeView.h 一致）：

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

参数

参数	说明
window_id	事件或请求关联的窗口。多数窗口事件里是当前窗口 id；与所有窗口无关的全局事件（如 app-ready、second-instance、global-hotkey、托盘相关）多为 0，以 事件类型 各节为准。
event_data	只读的 UTF-8 字符串，以 \0 结尾。内容多为 JSON 文本；少数为纯文本（如 app-ready 成功时的 success）。仅在本次回调执行期间保证有效，回调返回后不要保存裸指针；需要留存请自行拷贝。

返回值（const char *）

同一函数指针类型在两种用法下含义不同：

用于	返回值含义
jade_on(...) 注册的回调	见下文 jade_on 与回调返回值 及 事件类型 · 速查（拦截类：NULL 放行，(const char *)(uintptr_t)1 等非空表示阻止；webview-download-started 特例等）。
register_ipc_handler	见下文 register_ipc_handler 的返回值（NULL / (const char *)1 等为默认成功；其它指针为应答正文并由库 jade_text_free）。

备注

不要在回调里长时间阻塞或做重活，以免卡住 GUI / 消息线程；可投递到自己的队列里异步处理。

---

jade_on

用途：按事件名字符串注册一个回调；库在对应事件发生时同步调用你的 IpcCallback。

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

参数

参数	说明
event_name	事件名，UTF-8、以 \0 结尾，与文档及页面约定一致（如 app-ready、window-closing、javascript-result）。
callback	类型为 IpcCallback；收到事件时由库调用，参数含义见上节。

返回值

返回值	含义
> 0	本次注册的 callback id，供 jade_off(event_name, callback_id) 精确注销。
0	注册失败（空指针、内存不足等，以实际实现为准）。

调用时机与约定

• app-ready：必须在 JadeView_init 之前注册，否则会漏掉第一条就绪或失败通知（见 核心 API）。
• 其它事件：一般在 app-ready 成功、开始创建窗口之后再注册即可；事件名与 event_data 形态见 事件类型。
• 多次注册：同一 event_name 可注册多个回调，每次 jade_on 返回不同 id；触发时执行顺序以实现为准，不要依赖顺序做互斥逻辑。

jade_on 与回调返回值

对 jade_on 注册的 IpcCallback，返回值只在部分事件上有语义；多数仅通知类事件的返回值可被库忽略，习惯统一写 return NULL; 即可。

• 有「拦截 / 放行」语义的：如 window-closing、webview-will-navigate、webview-new-window（非 NULL = 阻止）；webview-download-started（仅 NULL = 允许下载，默认拦截）。推荐阻止时写 return (const char *)(uintptr_t)1;。
• 无拦截语义：返回 NULL。

完整列表与说明见 事件类型 · IpcCallback 返回值。

关于 app-ready：除文本 success 外，还可能 window_id == 0 且 event_data 为 JSON 错误或纯文本崩溃信息；解析方式见 事件类型。2.0 新增事件名如 second-instance、global-hotkey、tray-menu-command、tray-event 等同页。

---

jade_off

用途：按 event_name + jade_on 返回的 id 取消那一次订阅；不会误删同事件名下的其它回调。

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

参数	说明
event_name	与注册时相同的事件名。
callback_id	对应 jade_on 的返回值（> 0）。

返回值	含义
1	成功注销。
0	失败（未找到、参数无效等）。

---

send_ipc_message

用途：从 C 侧主动推一条消息给指定窗口里的页面（类型 + 正文），页面用 jade.on(message_type, ...) 接收。

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

参数	说明
window_id	目标窗口 id。
message_type	前端订阅用的类型名，与 jade.on 第一个参数一致。
message_content	一般为 JSON 文本；也可按你与页面约定传其它 UTF-8 串。

正文特别大时，2.0 内部可走分片/引用等优化路径；仍建议单次控制在约 252MB 以内，避免 WebView2 与宿主内存压力。

---

register_ipc_handler

用途：把 channel 名字符串与 C 回调绑定；页面 await jade.invoke(channel, payload, options) 时会调用该 IpcCallback。

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

参数	说明
channel	与前端 jade.invoke 第一个参数完全一致（区分大小写）。
ipc_cb	IpcCallback：window_id 为发起请求的窗口；event_data 一般为请求的 payload（常为 JSON 文本）。

返回值	含义
1	注册成功。
0	注册失败。

register_ipc_handler 的返回值

此处 IpcCallback 的返回值表示给前端的应答，与 jade_on 的「拦截」语义不同：

• 返回 NULL、(const char *)1 或实现认定的其它特殊地址：库向前端返回默认成功 JSON，不会对该指针调用 jade_text_free。
• 返回其它指针：视为 UTF-8 应答正文，读完后由库 jade_text_free；请用 jade_text_create 分配（见 工具 API）。

2.0 前端请使用 jade.invoke(command, payload, { timeout })；旧版 invokeAsync 已移除。详见 前端通信 API。