原生消息传递

扩展程序和应用可以使用类似于 消息传递 API。支持此功能的原生应用必须注册 原生消息传递主机,它知道如何与扩展程序通信。Chrome 会在以下位置启动该主机: 一个单独的进程,并使用标准输入流和标准输出流与之进行通信。

原生消息传递主机

为了注册原生消息传递主机,应用必须安装一个清单文件, 定义了本地消息传递主机配置。以下是清单文件的示例:

{
  "name": "com.my_company.my_application",
  "description": "My Application",
  "path": "C:\\Program Files\\My Application\\chrome_native_messaging_host.exe",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"
  ]
}

原生消息传递主机清单文件必须是有效的 JSON 且包含以下字段:

名称说明
name原生消息传递主机的名称。客户端会将此字符串传递给 runtime.connectNativeruntime.sendNativeMessage。此名称只能包含小写字母数字字符、下划线和英文句点。名称不能以句点开头或结尾,并且一个句点后面不能跟其他句点。
description简短的应用说明。
path指向原生消息传递主机二进制文件的路径。在 Linux 和 OSX 上,路径必须为绝对路径。在 Windows 中,此文件可以相对于清单文件所在的目录。启动主机进程时,将当前目录设置为包含主机二进制文件的目录。例如,如果此参数设置为 C:\Application\nm_host.exe,则将使用当前目录 C:\Application\ 启动。
type用于与原生消息传递主机通信的接口类型。目前,此参数只有一个可能的值:stdio。它表示 Chrome 应使用 stdinstdout 与主机通信。
allowed_origins应有权访问原生消息传递主机的扩展程序的列表。允许使用 chrome-extension://*/* 等通配符。

原生消息传递主机位置

清单文件的位置取决于平台。

Windows 上,清单文件可以位于文件系统中的任何位置。应用 安装程序必须创建注册表项 HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_和 将该键的默认值设为清单文件的完整路径。例如,使用 以下命令:

REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f

或使用以下 .reg 文件:

Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application]
@="C:\\path\\to\\nmh-manifest.json"

当 Chrome 查找本地消息传递主机时,首先查询 32 位注册表,然后查询 64 位注册表。 注册表中。

OS XLinux 上,原生消息传递主机清单文件的位置因 浏览器(Google Chrome 或 Chromium)。系统会查找系统级原生消息传递主机, 而用户级本地消息传递主机在 用户个人资料目录(名为 NativeMessagingHosts)。

  • OS X(系统级) <ph type="x-smartling-placeholder">
      </ph>
    • Google Chrome:/Library/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
    • Chromium:/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
  • OS X(特定于用户的默认路径) <ph type="x-smartling-placeholder">
      </ph>
    • Google Chrome:~/Library/Application Support/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
    • Chromium:~/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
  • Linux(系统级) <ph type="x-smartling-placeholder">
      </ph>
    • Google Chrome:/etc/opt/chrome/native-messaging-hosts/_com.my_company.my_application_.json
    • Chromium:/etc/chromium/native-messaging-hosts/_com.my_company.my_application_.json
  • Linux(特定于用户的默认路径) <ph type="x-smartling-placeholder">
      </ph>
    • Google Chrome:~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
    • Chromium:~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json

原生消息传递协议

Chrome 在单独的进程中启动每个原生消息传递主机,并使用 标准输入 (stdin) 和标准输出 (stdout)。发送消息时也使用相同格式, 双向:使用 JSON 和 UTF-8 编码的每条消息进行序列化,并以 32 位开头的 消息长度(按原生字节顺序)。来自原生消息传递的单条消息的大小上限 主机大小为 1 MB,这主要是为了防止 Chrome 本地应用程序出现异常行为。每个广告素材的 为 4 GB。

本地消息传递主机的第一个参数是调用方的来源,通常是 chrome-extension://[ID of allowed extension]。这样,原生消息传递主机就能够识别 在 allowed_origins 键中指定了多个扩展名的情况,这些扩展名是 原生消息传递主机清单警告:在 Windows 的 Chrome 54 及更低版本中,来源作为第二个参数传递 而不是第一个参数。

使用 runtime.connectNative 创建消息传递端口后,Chrome 会启动原生消息传递 并使其运行,直到端口被销毁。另一方面,当 使用 runtime.sendNativeMessage 发送新消息时(不创建消息传递端口),Chrome 会启动一个新的 创建本地消息传递主机进程在这种情况下,主机生成的第一条消息 进程作为对原始请求的响应进行处理,也就是说,Chrome 会将该进程传递给响应中 在调用 runtime.sendNativeMessage 时指定的回调。由 生成的所有其他消息 本地消息传递主机将被忽略。

在 Windows 上,系统还会向本地消息传递主机传递一个带有句柄的命令行参数 正在调用 Chrome 原生窗口:--parent-window=<decimal handle value>。这样,原生 消息主机创建正确父级的原生界面窗口。请注意,该值将 如果调用上下文是后台脚本页面,则为 0。

连接到原生应用

向原生应用发送和接收来自原生应用的消息与跨扩展非常相似 消息。主要区别在于使用的是 runtime.connectNative 使用 runtime.connectruntime.sendNativeMessage,而不是 runtime.sendMessage. 这些方法只能在“nativeMessaging”权限时(在应用的声明中) 清单文件

以下示例创建了一个连接到原生消息传递主机的 runtime.Port 对象 com.my_company.my_application,开始监听来自该端口的消息,并发送一条外发消息 消息:

var port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener(function(msg) {
  console.log("Received" + msg);
});
port.onDisconnect.addListener(function() {
  console.log("Disconnected");
});
port.postMessage({ text: "Hello, my_application" });

runtime.sendNativeMessage 可用于向原生应用发送消息,而无需创建 端口,例如:

chrome.runtime.sendNativeMessage('com.my_company.my_application',
  { text: "Hello" },
  function(response) {
    console.log("Received " + response);
  });

调试原生消息传递

当原生消息传递主机无法启动时,向 stderr 写入数据或当它违反 通信协议,会将输出写入 Chrome 的错误日志。在 Linux 和 OS X 上,此日志 通过从命令行启动 Chrome 并在 终端。在 Windows 上,请按照如何启用日志记录中的说明使用 --enable-logging

以下是一些错误和问题解决方法:

  • 未能启动原生消息传递主机。
    • 检查您是否有足够的权限来执行文件。
  • 指定的本地消息传递主机名称无效。
    • 检查名称是否包含任何无效字符。只能包含小写字母数字字符、 允许使用下划线和英文句点。名称不能以句点开头或结尾,也不能以句点结尾 后面跟一个点
  • 原生主机已退出。
    • 在 Chrome 读取消息之前,通向本地消息传递主机的管道已损坏。这是 可能是由原生消息传递主机发起的。
  • 找不到指定的原生消息传递主机。
    • 名称在扩展程序和清单文件中是否拼写正确?
    • 清单是否位于正确的目录中并且使用了正确的名称?请参阅原生消息传递主机 location
    • 清单文件的格式是否正确?具体而言,JSON 语法是否正确? 值是否与原生消息传递主机清单的定义相符?
    • path 中指定的文件是否存在?在 Windows 上,路径可能是相对路径;但在 OS X 和 Linux 上 路径必须是绝对路径
  • 原生消息传递主机主机名未注册。(仅限 Windows) <ph type="x-smartling-placeholder">
      </ph>
    • 在 Windows 注册表中找不到原生消息传递主机。使用 regedit 进行核查 键是否确实已创建,以及键是否与 native 消息主机位置
  • 禁止访问指定的本地消息传递主机。
    • allowed_origins 中是否列出了扩展程序的来源?
  • 与本地消息传递主机通信时出错。
    • 这是一个很常见的错误,表示通信协议的实现不正确 本地消息传递主机中。
    • 确保 stdout 中的所有输出均符合原生消息传递协议。如果您想 如需输出一些数据以进行调试,请将其写入 stderr
    • 确保 32 位消息长度采用平台的原生整数格式(小端字节序) / big-endian)。
    • 消息长度不得超过 1024*1024。
    • 消息大小必须等于消息中的字节数。这可能不同于 “长度”因为字符可以用多个字节表示。
    • 仅适用于 Windows:确保程序的 I/O 模式设置为 O_BINARY。默认情况下,I/O 模式为 O_TEXT,这会破坏邮件格式,因为换行符 (\n = 0A) 替换为 Windows 样式的行结尾 (\r\n = 0D 0A)。您可以使用 __setmode 设置 I/O 模式。