Mensajería nativa

Las extensiones y apps pueden intercambiar mensajes con aplicaciones nativas usando una API similar a las otras APIs de pase de mensajes. Las aplicaciones nativas que admiten esta función deben registrar un host de mensajería nativa que sepa cómo comunicarse con la extensión. Chrome inicia el host en en un proceso separado y se comunica con él mediante transmisiones de entrada y salida estándar.

Host de mensajería nativa

Para registrar un host de mensajería nativa, la aplicación debe instalar un archivo de manifiesto que define la configuración del host de mensajería nativa. A continuación, se muestra un ejemplo del archivo de manifiesto:

{
  "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/"
  ]
}

El archivo de manifiesto del host de mensajería nativa debe ser JSON válido y contener los siguientes campos:

Ubicación del host de mensajería nativa

La ubicación del archivo de manifiesto depende de la plataforma.

En Windows, el archivo de manifiesto puede ubicarse en cualquier parte del sistema de archivos. La aplicación el instalador debe crear una clave de registro HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ o HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ y establece el valor predeterminado de esa clave en la ruta completa al archivo de manifiesto. Por ejemplo, si usas el siguiente comando:

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

o usa el siguiente archivo .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"

Cuando Chrome busca hosts de mensajería nativa, primero se consulta el registro de 32 bits y, luego, el de 64 bits. registro.

En OS X y Linux, la ubicación del archivo de manifiesto del host de mensajería nativa varía según el navegador (Google Chrome o Chromium). Los hosts de mensajería nativa de todo el sistema se buscan en una ubicación local, mientras que los hosts de mensajería nativa a nivel del usuario se buscan en un subdirectorio dentro del directorio de perfil del usuario llamado NativeMessagingHosts.

• OS X (en todo el sistema)
  • 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 (ruta de acceso predeterminada específica del usuario)
  • 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 (en todo el sistema)
  • 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 (específica del usuario, ruta default)
  • Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Chromium: ~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json

Protocolo de mensajería nativa

Chrome inicia cada host de mensajería nativa en un proceso independiente y se comunica con él usando entrada estándar (stdin) y salida estándar (stdout). Se utiliza el mismo formato para enviar mensajes en en ambas direcciones: cada mensaje se serializa con JSON, codificado en UTF-8 y está precedido por una de la longitud del mensaje en orden nativo de bytes. El tamaño máximo de un solo mensaje de la mensajería nativa host es de 1 MB, principalmente para proteger Chrome de aplicaciones nativas que funcionan mal. El tamaño máximo del enviado al host de mensajería nativa es de 4 GB.

El primer argumento para el host de mensajería nativa es el origen del emisor, que, por lo general, chrome-extension://[ID of allowed extension] Esto permite que los hosts de mensajería nativa identifiquen la fuente del mensaje cuando se especifican varias extensiones en la clave allowed_origins de la manifiesto del host de mensajería nativa. Advertencia: En Windows, en Chrome 54 y versiones anteriores, el origen se pasaba como el segundo parámetro. en lugar del primer parámetro.

Cuando se crea un puerto de mensajería con runtime.connectNative, Chrome inicia la mensajería nativa. y lo mantiene en ejecución hasta que se destruya el puerto. Por otro lado, cuando un mensaje es enviados con runtime.sendNativeMessage, sin crear un puerto de mensajería, Chrome inicia un nuevo de mensajería nativa para cada mensaje. En ese caso, el primer mensaje generado por el host proceso se maneja como respuesta a la solicitud original, es decir, Chrome lo enviará a la respuesta La devolución de llamada especificada cuando se llama a runtime.sendNativeMessage. Todos los demás mensajes generados por el host de mensajería nativa, en ese caso, se ignorarán.

En Windows, el host de mensajería nativa también recibe un argumento de línea de comandos con un controlador para Llamando a la ventana nativa de Chrome: --parent-window=<decimal handle value>. Esto permite que el nativo de mensajería crea ventanas de IU nativas con una jerarquía superior correcta. Ten en cuenta que este valor será 0 si el contexto de llamada es una página de secuencia de comandos en segundo plano.

Conéctate a una aplicación nativa

Enviar y recibir mensajes hacia y desde una aplicación nativa es muy similar a usar extensiones cruzadas. la mensajería. La principal diferencia es que se usa runtime.connectNative en lugar de se usan runtime.connect y runtime.sendNativeMessage en lugar de runtime.sendMessage. Estos métodos solo se pueden usar si la carpeta "nativeMessaging" el permiso se declara en el directorio .

En el siguiente ejemplo, se crea un objeto runtime.Port que está conectado al host de mensajería nativa. com.my_company.my_application, comienza a escuchar los mensajes de ese puerto y envía uno saliente. mensaje:

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 se puede usar para enviar un mensaje a una aplicación nativa sin crear un puerto, p.ej.:

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

Depuración de la mensajería nativa

Cuando el host de mensajería nativa no se inicia, escribe en stderr o cuando infringe el protocolo de comunicación, el resultado se escribe en el registro de errores de Chrome. En Linux y OS X, este registro se puede acceder a él fácilmente iniciando Chrome desde la línea de comandos y viendo el resultado en la terminal. En Windows, usa --enable-logging como se explica en Cómo habilitar el registro.

Estos son algunos errores y sugerencias para resolver los problemas:

• No se pudo iniciar el host de mensajería nativa.
  • Verifica si tienes los permisos necesarios para ejecutar el archivo.
• El nombre de host de mensajería nativa especificado no es válido.
  • Verifica si el nombre contiene caracteres no válidos. Solo caracteres alfanuméricos en minúscula Se permiten guiones bajos y puntos. Los nombres no pueden empezar ni terminar con un punto, y un punto no puede ser seguido de otro punto.
• Se cerró el host nativo.
  • El canal al host de mensajería nativo se rompió antes de que Chrome leera el mensaje. Esto es lo más que probablemente se inicie desde el host de mensajería nativa.
• No se encontró el host de mensajería nativa especificado.
  • ¿El nombre está escrito correctamente en la extensión y en el archivo de manifiesto?
  • ¿El manifiesto se encuentra en el directorio correcto y con el nombre correcto? Consulta host de mensajería nativa. ubicación para los formatos esperados.
  • ¿El archivo de manifiesto tiene el formato correcto? En particular, ¿es correcta la sintaxis JSON? coinciden con la definición de un manifiesto de host de mensajería nativa?
  • ¿Existe el archivo especificado en path? En Windows, las rutas de acceso pueden ser relativas, pero en OS X y Linux, las rutas de acceso deben ser absolutas.
• El nombre de host del host de mensajería nativa no está registrado. (Solo para Windows)
  • No se encontró el host de mensajería nativa en el registro de Windows. Vuelve a verificar con regedit si la clave se creó realmente y coincide con el formato requerido según se documenta en ubicación del host de mensajería.
• El acceso al host de mensajería nativa especificado está prohibido.
  • ¿El origen de la extensión aparece en allowed_origins?
• Se produjo un error durante la comunicación con el host de mensajería nativa.
  • Este es un error muy común e indica una implementación incorrecta del protocolo de comunicación. en el host de mensajería nativa.
  • Asegúrate de que todos los resultados en stdout cumplan con el protocolo de mensajería nativa. Si quieres Para imprimir algunos datos con fines de depuración, escribe en stderr.
  • Asegúrate de que la longitud del mensaje de 32 bits esté en el formato de número entero nativo de la plataforma (pequeño endian) / big-endian).
  • La longitud del mensaje no debe exceder 1,024*1,024.
  • El tamaño del mensaje debe ser igual a la cantidad de bytes que tiene. Esto puede diferir del "length" de una cadena, porque los caracteres pueden estar representados por múltiples bytes.
  • Solo para Windows: Asegúrate de que el modo de E/S del programa esté establecido en O_BINARY. De forma predeterminada, la capa de E/S el modo es O_TEXT, lo que daña el formato del mensaje, ya que los saltos de línea (\n = 0A) se reemplazan por Terminaciones de líneas de estilo Windows (\r\n = 0D 0A) El modo de E/S se puede configurar con __setmode.