Sistema de mensagens nativo

Para se comunicar com um aplicativo Win32 nativo instalado no dispositivo de um usuário, uma extensão usa uma API semelhante às outras APIs de passagem de mensagens. O host de aplicativo nativo envia e recebe mensagens com extensões usando entrada e saída padrão.

As extensões que usam mensagens nativas são instaladas no Microsoft Edge de forma semelhante a qualquer outra extensão. No entanto, os aplicativos nativos não são instalados ou gerenciados pelo Microsoft Edge.

Para adquirir a extensão e o host do aplicativo nativo, há dois modelos de distribuição diferentes:

• Empacote sua extensão e o host juntos. Quando um usuário instala o pacote, tanto a extensão quanto o host são instalados.

• Ou instale sua extensão dos Complementos do Microsoft Edge e sua extensão solicitará que os usuários instalem o host.

Para criar sua extensão para enviar e receber mensagens com hosts de aplicativos nativos, execute as etapas a seguir.

Etapa 1: adicionar permissões ao manifesto da extensão

Adicione a nativeMessaging permissão ao arquivo manifest.json da extensão.

Este é o arquivo de manifesto de extensão, não o arquivo de manifesto do host de mensagem nativo, que é abordado em seções posteriores.

Veja a seguir um exemplo manifest.json arquivo:

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

Etapa 2: criar seu arquivo de manifesto do host de mensagens nativo

Os aplicativos nativos devem fornecer um arquivo de manifesto do host de mensagens nativo. Um arquivo de manifesto do host de mensagens nativo contém as seguintes informações:

• O caminho para o tempo de execução do host de mensagem nativo.

• O método de comunicação com a extensão.

• Uma lista de extensões permitidas com as quais ele se comunica.

O navegador lê e valida o manifesto do host de mensagens nativo. O navegador não instala ou gerencia o arquivo de manifesto do host de mensagens nativo.

O arquivo de manifesto do host de mensagens nativo é diferente do arquivo de manifesto V3 ou V2 que faz parte da extensão Microsoft Edge.

Exemplo de um arquivo de manifesto do host de mensagens 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/"
    ]
}

O arquivo de manifesto do host de mensagens nativo deve ser um arquivo JSON válido que contenha as seguintes chaves:

Faça o sideload de sua extensão para testar mensagens nativas com o host. Para fazer sideload de sua extensão durante o desenvolvimento e recuperar microsoft_catalog_extension_id:

1. Vá para edge://extensionse ative o botão de alternância do modo de desenvolvedor .

2. Selecione Carregar desempacotado e, em seguida, selecione o pacote de extensão para fazer o sideload.

3. Clique em OK.

4. Vá para a edge://extensions página e verifique se sua extensão está listada.

5. Copie a chave de microsoft_catalog_extension_id (ID) da lista de extensões na página.

Quando você estiver pronto para distribuir sua extensão aos usuários, publique sua extensão em Complementos do Microsoft Edge. A ID da extensão publicada pode ser diferente da ID usada durante o sideload da extensão. Se a ID foi alterada, atualize allowed_origins no arquivo de manifesto do host de mensagens nativo com a ID da sua extensão publicada.

Etapa 3: Copiar o arquivo de manifesto do host de mensagens nativo para o sistema

A etapa final envolve copiar o arquivo de manifesto do host de mensagens nativo para o computador e garantir que esse arquivo de manifesto esteja configurado corretamente. Para garantir que o arquivo de manifesto do host de mensagens nativo seja colocado no local esperado, execute as etapas a seguir. A localização varia de acordo com a plataforma.

No Linux e no macOS:

• Certifique-se de fornecer permissões de leitura no arquivo de manifesto do host de mensagens nativo.
• Certifique-se de fornecer permissões de execução no tempo de execução do host.

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

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

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\

Protocolo de mensagens nativo

O Microsoft Edge inicia cada host de mensagem nativo em um processo separado e se comunica com ele usando a entrada padrão (stdin) e a saída padrão (stdout). O mesmo formato é usado para enviar mensagens em ambas as direções; cada mensagem é serializada usando JSON, codificada em UTF-8 e é precedida por um comprimento de mensagem de 32 bits na ordem de byte nativo. O tamanho máximo de uma única mensagem do host de mensagens nativo é de 1 MB, principalmente para proteger o Microsoft Edge contra mau comportamento de aplicativos nativos. O tamanho máximo da mensagem enviada para o host de mensagens nativo é de 4 GB.

O primeiro argumento para o host de mensagens nativo é a origem do chamador, geralmente chrome-extension://[ID of allowed extension]. Isso permite que hosts de mensagens nativas identifiquem a origem da mensagem quando várias extensões são especificadas na allowed_origins chave no manifesto do host de mensagens nativo; consulte Etapa 2: Criar seu arquivo de manifesto do host de mensagens nativo, acima.

No Windows, o host de mensagens nativo também recebe um argumento de linha de comando com um identificador para a janela nativa de chamada do Microsoft Edge: --parent-window=<decimal handle value>. Isso permite que o host de mensagens nativo crie janelas de interface do usuário nativas que são corretamente parentais. Esse valor será 0 se o contexto de chamada for um trabalho de serviço.

Quando uma porta de mensagens é criada usando runtime.connectNativeo , o Microsoft Edge inicia um processo de host de mensagem nativo e o mantém em execução até que a porta seja destruída. Por outro lado, quando uma mensagem é enviada usando runtime.sendNativeMessage, sem criar uma porta de mensagens, o Microsoft Edge inicia um novo processo de host de mensagens nativo para cada mensagem. Nesse caso, a primeira mensagem gerada pelo processo do host é tratada como uma resposta à solicitação original e o Microsoft Edge a passará para o retorno de chamada de resposta especificado quando runtime.sendNativeMessage for chamado. Todas as outras mensagens geradas pelo host de mensagens nativo nesse caso são ignoradas.

Conectando-se a um aplicativo nativo

Enviar e receber mensagens de e para um aplicativo nativo é muito semelhante às mensagens de extensão cruzada. A principal diferença é que runtime.connectNativeé usado em vez de runtime.connect, e runtime.sendNativeMessage é usado em vez deruntime.sendMessage .

Para usar esses métodos, a permissão deve ser declarada no arquivo de manifesto nativeMessaging de suas extensões; consulte Etapa 1: Adicionar permissões ao manifesto de extensão, acima.

Esses métodos não estão disponíveis em scripts de conteúdo, apenas nas páginas da sua extensão e no trabalho de serviço. Se você quiser se comunicar de um script de conteúdo para o aplicativo nativo, envie a mensagem ao seu trabalho de serviço para passá-la para o aplicativo nativo.

O exemplo a seguir cria um runtime.Port objeto conectado ao host com.my_company.my_applicationde mensagens nativo, começa a escutar mensagens dessa porta e envia uma mensagem de saída:

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 uma mensagem ao aplicativo nativo sem criar uma porta; por exemplo:

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

Depuração de mensagens nativas

Quando ocorrem determinadas falhas de mensagens nativas, a saída é gravada no log de erros do Microsoft Edge. Isso inclui quando o host de mensagens nativo não inicia, grava stderr ou viola o protocolo de comunicação. No Linux e no macOS, esse log pode ser facilmente acessado iniciando o Microsoft Edge na linha de comando e observando sua saída no terminal. No Windows, use --enable-logging conforme explicado em Como habilitar o registro em log.

Aqui estão alguns erros comuns e dicas para resolvê-los:

Falha ao iniciar o host de mensagens nativo.

Verifique se você tem permissões suficientes para executar o arquivo host de mensagem nativo.

Nome de host de mensagem nativo inválido especificado.

Verifique se o nome contém caracteres inválidos. Somente caracteres alfanuméricos minúsculos, sublinhados e pontos (pontos) são permitidos. Um nome não pode começar nem terminar com um ponto, e um ponto não pode ser seguido por outro ponto.

O host nativo saiu.

O pipe para o host de mensagens nativo foi interrompido antes que a mensagem fosse lida pelo Microsoft Edge. Isso provavelmente foi iniciado a partir do seu host de mensagens nativo.

Host de mensagens nativo especificado não encontrado.

Verificar o seguinte:

• O nome está escrito corretamente na extensão e no arquivo de manifesto?

• O manifesto está no diretório correto e com o nome correto? Consulte o local do host de mensagens nativo para obter os formatos esperados.

• O arquivo de manifesto está no formato correto? Em particular, o JSON é válido e bem formado, e os valores correspondem à definição de um manifesto de host de mensagens nativo, de acordo com a Etapa 2: Criar seu arquivo de manifesto de host de mensagens nativo acima?

• O arquivo especificado existe path ? No Windows, os caminhos podem ser relativos, mas no macOS e no Linux, os caminhos devem ser absolutos.

O nome do host do host de mensagens nativo não está registrado. (Somente Windows)

O host de mensagens nativo não foi encontrado no Registro do Windows. Usar marcar duplo se regedit a chave foi realmente criada e corresponde ao formato necessário, conforme documentado no local do host de mensagem nativo.

O acesso ao host de mensagens nativo especificado é proibido.

A origem da extensão está listada em allowed_origins?

Erro ao se comunicar com o host de mensagens nativo.

Isso indica uma implementação incorreta do protocolo de comunicação no host de mensagens nativo.

• Certifique-se de que todas as saídas stdout sigam o protocolo de mensagens nativo. Se você quiser imprimir alguns dados para fins de depuração, escreva para stderr.

• Verifique se o comprimento da mensagem de 32 bits está no formato inteiro nativo da plataforma (little-endian ou big-endian).

• O comprimento da mensagem não deve exceder 1024*1024.

• O tamanho da mensagem deve ser igual ao número de bytes na mensagem. Isso pode ser diferente do "comprimento" de uma cadeia de caracteres, pois os caracteres podem ser representados por vários bytes.

• Windows somente: Certifique-se de que o modo de E/S do programa esteja definido como O_BINARY. Por padrão, o modo de E/S é O_TEXT, que corrompe o formato da mensagem à medida que quebras de linha (0A = \n) são substituídas por terminações de linha no estilo do Windows ().\r\n = 0D 0A O modo de E/S pode ser definido usando __setmode.

Este trabalho está licenciado sob uma Licença Creative Commons Atribuição 4.0 Internacional.