Mensajería nativa

Artículo
01/19/2024

Para comunicarse con una aplicación win32 nativa instalada en el dispositivo de un usuario, una extensión usa una API similar a las demás API de paso de mensajes . El host de aplicación nativo envía y recibe mensajes con extensiones mediante la entrada estándar y la salida estándar.

Las extensiones que usan mensajería nativa se instalan en Microsoft Edge de forma similar a cualquier otra extensión. Sin embargo, Microsoft Edge no instala ni administra las aplicaciones nativas.

Para adquirir la extensión y el host de aplicación nativo, hay dos modelos de distribución diferentes:

Empaquete la extensión y el host juntos. Cuando un usuario instala el paquete, se instalan la extensión y el host.
O bien, instale la extensión mediante el sitio web de complementos de Microsoft Edge y la extensión solicitará a los usuarios que instalen el host.

Para crear la extensión para enviar y recibir mensajes con hosts de aplicación nativos, siga estos pasos.

Paso 1: Agregar permisos al manifiesto de extensión

Agregue el nativeMessaging permiso al archivo manifest.json de la extensión.

Este es el archivo de manifiesto de extensión, no el archivo de manifiesto de host de mensajería nativo, que se trata en secciones posteriores.

A continuación se muestra un archivo manifest.json de ejemplo:

Manifiesto V3
Manifiesto V2

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 3,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 2,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

Paso 2: Creación del archivo de manifiesto del host de mensajería nativo

Las aplicaciones nativas deben proporcionar un archivo de manifiesto de host de mensajería nativo. Un archivo de manifiesto de host de mensajería nativo contiene la siguiente información:

Ruta de acceso al entorno de ejecución del host de mensajería nativo.
Método de comunicación con la extensión.
Lista de extensiones permitidas a las que se comunica.

El explorador lee y valida el manifiesto del host de mensajería nativo. El explorador no instala ni administra el archivo de manifiesto del host de mensajería nativo.

El archivo de manifiesto del host de mensajería nativo es distinto del archivo de manifiesto V3 o V2 que forma parte de la extensión de Microsoft Edge.

Ejemplo de un archivo de manifiesto de host de mensajería nativo:

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

El archivo de manifiesto del host de mensajería nativo debe ser un archivo JSON válido que contenga las claves siguientes:

Clave	Detalles
`name`	Especifica el nombre del host de mensajería nativo. Los clientes pasan la cadena a `runtime.connectNative` o `runtime.sendNativeMessage`. El valor solo debe contener caracteres alfanuméricos en minúsculas, caracteres de subrayado y puntos. El valor no debe iniciarse ni terminar con un punto (un punto) y un punto no debe ir seguido de otro punto.
`description`	Describe la aplicación.
`path`	Especifica la ruta de acceso al binario del host de mensajería nativo. En dispositivos Windows, puede usar rutas de acceso relativas al directorio que contiene el archivo de manifiesto del host de mensajería nativo. En macOS y Linux, la ruta de acceso debe ser absoluta. El proceso de host comienza con el directorio actual establecido en el directorio que contiene el binario del host. Por ejemplo (Windows), si el parámetro se establece en `C:\App\nm_host.exe`, el binario se inicia con el directorio actual (`C:\App\`).
`type`	Especifica el tipo de interfaz que se usa para comunicarse con el host de mensajería nativo. El valor indica a Microsoft Edge que use `stdin` y `stdout` se comunique con el host. El único valor aceptable es `stdio`.
`allowed_origins`	Especifica la lista de extensiones que tienen acceso al host de mensajería nativo. Para activar la aplicación para identificar y comunicarse con una extensión, establezca el siguiente valor en el archivo de manifiesto del host de mensajería nativo: `"allowed_origins": ["chrome-extension://{microsoft_catalog_extension_id}"]`

Transferir localmente la extensión para probar la mensajería nativa con el host. Para transferir localmente la extensión durante el desarrollo y recuperar microsoft_catalog_extension_id:

Vaya a y, a edge://extensionscontinuación, active el botón de alternancia Modo de desarrollador .
Seleccione Cargar desempaquetado y, a continuación, seleccione el paquete de extensión para transferir localmente.
Haga clic en Aceptar.
Vaya a la edge://extensions página y compruebe que aparece la extensión.
Copie la clave de microsoft_catalog_extension_id (id.) de la lista de extensiones de la página.

Cuando esté listo para distribuir la extensión a los usuarios, publique la extensión en el sitio web de complementos de Microsoft Edge. El identificador de extensión de la extensión publicada puede diferir del identificador que se usa al transferir localmente la extensión. Si el identificador ha cambiado, actualice allowed_origins en el archivo de manifiesto del host de mensajería nativo con el identificador de la extensión publicada.

Paso 3: Copia del archivo de manifiesto del host de mensajería nativo en el sistema

El último paso implica copiar el archivo de manifiesto del host de mensajería nativo en el equipo y asegurarse de que este archivo de manifiesto está configurado correctamente. Para asegurarse de que el archivo de manifiesto del host de mensajería nativo se coloca en la ubicación esperada, siga estos pasos. La ubicación varía según la plataforma.

En Linux y macOS:

Asegúrese de proporcionar permisos de lectura en el archivo de manifiesto del host de mensajería nativo.
Asegúrese de proporcionar permisos de ejecución en el entorno de ejecución del host.

El archivo de manifiesto del host de mensajería nativo puede encontrarse en cualquier lugar del sistema de archivos. El instalador de la aplicación debe crear una clave del Registro y establecer el valor predeterminado de la clave en la ruta de acceso completa del archivo de manifiesto del host de mensajería nativo.

Las siguientes ubicaciones son ejemplos de claves del Registro:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

Para agregar una clave del Registro al directorio con la clave de manifiesto, realice una de las siguientes acciones:

Ejecute un comando en el símbolo del sistema:

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

O bien, cree un .reg archivo y ejecútelo de la siguiente manera:
1. Copie el siguiente comando en un .reg archivo:
```
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app]
@="C:\\path\\to\\nmh-manifest.json"
```
2. Ejecute el .reg archivo. Si ejecuta el archivo creado .reg como parte de un script por lotes, asegúrese de ejecutarlo mediante un símbolo del sistema de administrador.

Microsoft Edge consulta la HKEY_CURRENT_USER clave raíz, seguida de HKEY_LOCAL_MACHINE. En ambas claves, primero se busca en el registro de 32 bits y, a continuación, se busca en el registro de 64 bits para identificar los hosts de mensajería nativos. La clave del Registro especifica la ubicación del archivo de manifiesto del host de mensajería nativo.

Si las entradas del Registro de Microsoft Edge no tienen la ubicación del archivo de manifiesto del host de mensajería nativo, las ubicaciones del registro de Chromium y Chrome se usan como opciones de reserva.

Si Microsoft Edge encuentra la clave del Registro en cualquiera de las ubicaciones enumeradas anteriormente, no consulta las ubicaciones que aparecen en el siguiente fragmento de código.

El orden de búsqueda de las ubicaciones del Registro es:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\

Nodo del Registro WOW6432Node

El HKEY_CURRENT_USER\SOFTWARE\WOW6432Node nodo del Registro no se busca en máquinas de 64 bits, debido a la forma en que el registro funciona en ellos. Para obtener más información, vea Claves del Registro afectadas por las instalaciones de Windows que incluyen compatibilidad con Windows en Windows (WOW) para varias arquitecturas de procesador.

Identificadores de extensión necesarios para ambos almacenes

Si tiene extensiones en los complementos de Microsoft Edge y chrome Web Store, debe agregar los identificadores de extensión correspondientes a ambos almacenes del allowed_origins archivo de manifiesto del host de mensajería nativo. Esto es necesario porque solo se lee el archivo de manifiesto de host de mensajería nativo que corresponde a la primera ubicación del Registro encontrada.

Para almacenar el archivo de manifiesto del host de mensajería nativo:

Los hosts de mensajería nativos de todo el sistema, que están disponibles para todos los usuarios, se almacenan en una ubicación fija. Por ejemplo, el archivo de manifiesto del host de mensajería nativo debe almacenarse en la siguiente ubicación:
```
/Library/Microsoft/Edge/NativeMessagingHosts/com.my_company.my_app.json
```
Los hosts de mensajería nativos específicos del usuario, que solo están disponibles para el usuario actual, se encuentran en el NativeMessagingHosts subdirectorio del directorio de datos del usuario. Por ejemplo, el archivo de manifiesto del host de mensajería nativo debe almacenarse en la siguiente ubicación:
```
~/Library/Application Support/Microsoft Edge {Channel_Name}/NativeMessagingHosts/com.my_company.my_app.json
```
El {Channel_Name} elemento en Microsoft Edge {Channel_Name} debe ser uno de los siguientes valores:
- Canary
- Dev
- Beta
Cuando se usa el canal Estable, {Channel_Name} no es necesario.

Para almacenar el archivo de manifiesto del host de mensajería nativo:

Los hosts de mensajería nativos de todo el sistema, que están disponibles para todos los usuarios, se almacenan en una ubicación fija. El archivo de manifiesto del host de mensajería nativo debe almacenarse en la siguiente ubicación:
```
/etc/opt/edge/native-messaging-hosts
```
Los hosts de mensajería nativos específicos del usuario, que solo están disponibles para el usuario actual, se encuentran en el NativeMessagingHosts subdirectorio del directorio de datos del usuario. El archivo de manifiesto del host de mensajería nativo debe almacenarse en la siguiente ubicación:
```
~/.config/microsoft-edge/NativeMessagingHosts
```

Protocolo de mensajería nativo

Microsoft Edge inicia cada host de mensajería nativo en un proceso independiente y se comunica con él mediante la entrada estándar (stdin) y la salida estándar (stdout). El mismo formato se usa para enviar mensajes en ambas direcciones; cada mensaje se serializa mediante JSON, con codificación UTF-8 y va precedido de una longitud de mensaje de 32 bits en orden de bytes nativo. El tamaño máximo de un solo mensaje del host de mensajería nativo es de 1 MB, principalmente para proteger Microsoft Edge frente a aplicaciones nativas que se comportan mal. El tamaño máximo del mensaje enviado al host de mensajería nativo es de 4 GB.

El primer argumento para el host de mensajería nativo es el origen del autor de la llamada, normalmente chrome-extension://[ID of allowed extension]. Esto permite que los hosts de mensajería nativos identifiquen el origen del mensaje cuando se especifican varias extensiones en la allowed_origins clave del manifiesto del host de mensajería nativo; consulte Paso 2: Crear el archivo de manifiesto de host de mensajería nativo, anteriormente.

En Windows, el host de mensajería nativo también se pasa un argumento de línea de comandos con un identificador a la ventana nativa de Microsoft Edge que realiza la llamada: --parent-window=<decimal handle value>. Esto permite que el host de mensajería nativo cree ventanas de interfaz de usuario nativas que estén correctamente primarias. Tenga en cuenta que este valor será 0 si el contexto de llamada es un trabajo de servicio.

Cuando se crea un puerto de mensajería mediante runtime.connectNative, Microsoft Edge inicia un proceso de host de mensajería nativo y lo mantiene en ejecución hasta que se destruye el puerto. Por otro lado, cuando se envía un mensaje mediante runtime.sendNativeMessage, sin crear un puerto de mensajería, Microsoft Edge inicia un nuevo proceso de host de mensajería nativo para cada mensaje. En ese caso, el primer mensaje generado por el proceso de host se controla como respuesta a la solicitud original y Microsoft Edge lo pasará a la devolución de llamada de respuesta especificada cuando runtime.sendNativeMessage se llame a . Todos los demás mensajes generados por el host de mensajería nativo en ese caso se omiten.

Conexión a una aplicación nativa

El envío y la recepción de mensajes hacia y desde una aplicación nativa es muy similar a la mensajería entre extensiones. La principal diferencia es que runtime.connectNative se usa en lugar de runtime.connect, y runtime.sendNativeMessage se usa en lugar de runtime.sendMessage.

Para usar estos métodos, el permiso debe declararse en el nativeMessaging archivo de manifiesto de las extensiones; consulte Paso 1: Agregar permisos al manifiesto de extensión anterior.

Estos métodos no están disponibles dentro de los scripts de contenido, solo dentro de las páginas de la extensión y del trabajo de servicio. Si desea comunicarse desde un script de contenido a la aplicación nativa, envíe el mensaje al trabajador del servicio para pasarlo a la aplicación nativa.

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

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'});

Use runtime.sendNativeMessage para enviar un mensaje a la aplicación nativa sin crear un puerto; por ejemplo:

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

Depuración de mensajería nativa

Cuando se producen determinados errores de mensajería nativos, la salida se escribe en el registro de errores de Microsoft Edge. Esto incluye cuando el host de mensajería nativo no se inicia, escribe stderr en o infringe el protocolo de comunicación. En Linux y macOS, se puede acceder fácilmente a este registro iniciando Microsoft Edge desde la línea de comandos y observando su salida en el terminal. En Windows, use --enable-logging como se explica en Cómo habilitar el registro.

Estos son algunos errores comunes y sugerencias para resolverlos:

No se pudo iniciar el host de mensajería nativo.

Compruebe si tiene permisos suficientes para ejecutar el archivo de host de mensajería nativo.

Nombre de host de mensajería nativo no válido especificado.

Compruebe si el nombre contiene caracteres no válidos. Solo se permiten caracteres alfanuméricos en minúsculas, caracteres de subrayado y puntos (puntos). Un nombre no puede iniciarse ni terminar con un punto y un punto no puede ir seguido de otro punto.

El host nativo ha salido.

La canalización al host de mensajería nativo se interrumpió antes de que Microsoft Edge leyese el mensaje. Lo más probable es que se inicie desde el host de mensajería nativo.

No se encontró el host de mensajería nativo especificado.

Compruebe lo siguiente:

¿El nombre está escrito correctamente en la extensión y en el archivo de manifiesto?
¿El manifiesto está en el directorio correcto y con el nombre correcto? Consulte ubicación del host de mensajería nativa para ver los formatos esperados.
¿El archivo de manifiesto tiene el formato correcto? En concreto, ¿el json es válido y está bien formado, y los valores coinciden con la definición de un manifiesto de host de mensajería nativo, según el paso 2: Crear el archivo de manifiesto de host de mensajería nativo anterior?
¿Existe el archivo especificado en path ? En Windows, las rutas de acceso pueden ser relativas, pero en macOS y Linux, las rutas de acceso deben ser absolutas.

El nombre de host de host de mensajería nativa no está registrado. (solo Windows)

El host de mensajería nativo no se encontró en el registro de Windows. regedit Compruebe si la clave se creó realmente y coincide con el formato necesario, tal como se documenta en la ubicación del host de mensajería nativo.

El acceso al host de mensajería nativo especificado está prohibido.

¿El origen de la extensión aparece en allowed_origins?

Error al comunicarse con el host de mensajería nativo.

Esto indica una implementación incorrecta del protocolo de comunicación en el host de mensajería nativo.

Asegúrese de que toda la salida de stdout se ajusta al protocolo de mensajería nativo. Si desea imprimir algunos datos con fines de depuración, escriba en stderr.
Asegúrese de que la longitud del mensaje de 32 bits está en el formato entero nativo de la plataforma (little-endian o big-endian).
La longitud del mensaje no debe superar 1024*1024.
El tamaño del mensaje debe ser igual al número de bytes del mensaje. Esto puede diferir de la "longitud" de una cadena, ya que los caracteres pueden representarse mediante varios bytes.
Solo Windows: Asegúrese de que el modo de E/S del programa esté establecido en O_BINARY. De forma predeterminada, el modo de E/S es O_TEXT, que daña el formato del mensaje, ya que los saltos de línea (0A = \n) se reemplazan por finales de línea de estilo Windows ().\r\n = 0D 0A El modo de E/S se puede establecer mediante __setmode.

Nota:

Las partes de esta página son modificaciones basadas en el trabajo creado y compartido por Google y usadas según los términos descritos en la licencia internacional creative Commons Attribution 4.0. La página original se encuentra aquí.

Esta obra está licenciada bajo una Licencia Internacional Creative Commons Attribution 4.0.