Mensagens nativas

Extensões e aplicativos podem trocar mensagens com aplicativos nativos usando uma API semelhante à as outras APIs de transmissão de mensagens. Os aplicativos nativos compatíveis com esse recurso precisam registrar um host de mensagens nativas que saiba se comunicar com a extensão. O Chrome inicia o host em um processo separado e se comunica com ele usando fluxos de entrada e saída padrão.

Host de mensagens nativas

Para registrar um host de mensagens nativas, o aplicativo deve instalar um arquivo de manifesto que define a configuração do host de mensagens nativas. Confira abaixo um exemplo do arquivo de manifesto:

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

O arquivo de manifesto do host de mensagens nativas precisa ser um JSON válido e conter os seguintes campos:

Local do host de mensagens nativas

O local do arquivo de manifesto depende da plataforma.

No Windows, o arquivo de manifesto pode estar localizado em qualquer lugar no sistema de arquivos. O aplicativo o instalador precisa criar uma chave de registro HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ ou HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ e defina o valor padrão dessa chave como o caminho completo para o arquivo de manifesto. Por exemplo, usar o método seguinte 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

ou usando o seguinte arquivo .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"

Quando o Chrome procura hosts de mensagens nativas, primeiro o registro de 32 bits é consultado, depois o de 64 bits de registros.

No OS X e no Linux, o local do arquivo de manifesto do host de mensagens nativas varia de acordo navegador (Google Chrome ou Chromium). Os hosts de mensagens nativas de todo o sistema são procurados em um local, enquanto os hosts de mensagens nativas no nível do usuário são procurados em um subdiretório dentro do diretório de perfil de usuário chamado NativeMessagingHosts.

• OS X (todo o 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 (específico do usuário, caminho padrão)
  • 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 (todo o 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ífico do usuário, caminho 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 mensagens nativas

O Chrome inicia cada host de mensagens nativas em um processo separado e se comunica com ele usando entrada padrão (stdin) e saída padrão (stdout). O mesmo formato é usado para enviar mensagens nas duas direções: cada mensagem é serializada usando JSON e codificada em UTF-8 e é precedida por caracteres tamanho da mensagem na ordem de bytes nativa. O tamanho máximo de uma única mensagem das mensagens nativas host tem 1 MB, principalmente para proteger o Chrome de aplicativos nativos com comportamento inadequado. O tamanho máximo do enviada para o host de mensagens nativas tem 4 GB.

O primeiro argumento para o host de mensagens nativas é a origem do autor da chamada, geralmente chrome-extension://[ID of allowed extension]: Isso permite que os hosts de mensagens nativas identifiquem origem da mensagem quando várias extensões são especificadas na chave allowed_origins na manifesto do host de mensagens nativas. Aviso: no Windows, no Chrome 54 e anteriores, a origem foi transmitida como o segundo parâmetro. em vez do primeiro parâmetro.

Quando uma porta de mensagens é criada usando runtime.connectNative, o Chrome inicia as mensagens nativas e o mantém em execução até que a porta seja destruída. Por outro lado, quando uma mensagem é enviado usando runtime.sendNativeMessage, sem criar uma porta de mensagens, o Chrome inicia uma nova processo do host de mensagens nativas. Nesse caso, a primeira mensagem gerada pelo host processo é tratado como uma resposta à solicitação original, ou seja, o Chrome o transmite para a resposta callback especificado quando runtime.sendNativeMessage é chamado. Todas as outras mensagens geradas por o host de mensagens nativas, nesse caso, serão ignorados.

No Windows, o host de mensagens nativas também recebe um argumento de linha de comando com um identificador para o chamando a janela nativa do Chrome --parent-window=<decimal handle value>. Assim, o ambiente nativo host de mensagens cria janelas de interface nativas com os pais corretamente. Observe que esse valor será 0 se o contexto de chamada for uma página de script em segundo plano.

Como se conectar a um aplicativo nativo

O envio e recebimento de mensagens de e para um aplicativo nativo é muito semelhante à transferência entre extensões troca de mensagens. A principal diferença é que runtime.connectNative é usado em vez de runtime.connect e runtime.sendNativeMessage são usados em vez de runtime.sendMessage. Esses métodos só podem ser usados se a tag "nativeMessaging" permissão seja declarada no arquivo de manifesto do app.

O exemplo a seguir cria um objeto runtime.Port que é conectado ao host de mensagens nativas com.my_company.my_application, inicia a detecção de mensagens dessa porta e envia um mensagem:

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 pode ser usado 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 o host de mensagens nativas não é iniciado, grava em stderr ou quando viola a protocolo de comunicação, a saída é gravada no registro de erros do Chrome. No Linux e no OS X, esse registro pode ser acessado facilmente iniciando o Chrome pela linha de comando e observando seu resultado no terminal. No Windows, use --enable-logging conforme explicado em Como ativar a geração de registros.

Veja alguns erros e dicas para resolver os problemas:

• Falha ao iniciar o host de mensagens nativas.
  • Verifique se você tem permissões suficientes para executar o arquivo.
• O nome do host de mensagens nativas especificado é inválido.
  • Verifique se o nome contém caracteres inválidos. Use apenas caracteres alfanuméricos minúsculos, sublinhados e pontos são permitidos. O nome não pode começar nem terminar com um ponto nem um ponto seguido por outro ponto.
• O host nativo foi fechado.
  • O canal para o host de mensagens nativas foi interrompido antes da mensagem ser lida pelo Chrome. Isso é mais provavelmente iniciado no host de mensagens nativas.
• O host de mensagens nativas especificado não foi encontrado.
  • O nome está escrito corretamente na extensão e no arquivo de manifesto?
  • O manifesto foi colocado no diretório correto e com o nome correto? Consulte o host de mensagens nativas local para os formatos esperados.
  • O arquivo de manifesto está no formato correto? A sintaxe JSON está correta e faz valores correspondem à definição de um manifesto do host de mensagens nativas?
  • O arquivo especificado em path existe? No Windows, os caminhos podem ser relativos, mas, no OS X e no Linux, os caminhos devem ser absolutos.
• O nome do host de mensagens nativas não está registrado. (somente para Windows)
  • O host de mensagens nativas não foi encontrado no registro do Windows. Checar usando regedit se a chave foi realmente criada e corresponde ao formato exigido, conforme documentado na documentação do local do host de mensagens.
• O acesso ao host de mensagens nativas especificado é proibido.
  • A origem da extensão está listada em allowed_origins?
• Erro ao se comunicar com o host de mensagens nativas.
  • Este é um erro muito comum e indica uma implementação incorreta do protocolo de comunicação no host de mensagens nativas.
  • Verifique se todas as saídas em stdout obedecem ao protocolo de mensagens nativas. Se você quiser para mostrar alguns dados para fins de depuração, grave em stderr.
  • Confira se o tamanho da mensagem de 32 bits está no formato inteiro nativo da plataforma (little-endian) / big-endian).
  • O tamanho da mensagem não pode ser maior que 1.024 x 1.024.
  • O tamanho da mensagem precisa ser igual ao número de bytes dela. Ele pode ser diferente do "tamanho" de uma string, porque os caracteres podem ser representados por múltiplos bytes.
  • Somente Windows: confira se o modo de E/S do programa está definido como O_BINARY. Por padrão, o E/S O modo é O_TEXT, o que corrompe o formato da mensagem porque as quebras de linha (\n = 0A) são substituídas por Fim de linha no estilo Windows (\r\n = 0D 0A). O modo E/S pode ser definido usando __setmode.