Messaggi nativi

Le estensioni e le app possono scambiare messaggi con applicazioni native utilizzando un'API simile alle altre API per la trasmissione di messaggi. Le applicazioni native che supportano questa funzionalità devono registrare un host di messaggistica nativo che sappia come comunicare con l'estensione. Chrome avvia l'host in un processo separato e comunica con l'host utilizzando flussi di input standard e stream di output standard.

Host di messaggistica nativo

Per registrare un host di messaggistica nativo, l'applicazione deve installare un file manifest che definisca la configurazione dell'host di messaggistica nativo. Di seguito è riportato un esempio di file manifest:

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

Il file manifest dell'host di messaggistica nativo deve essere un file JSON valido e contenere i seguenti campi:

Posizione host di messaggistica nativa

La posizione del file manifest dipende dalla piattaforma.

Su Windows, il file manifest può essere posizionato ovunque nel file system. Il programma di installazione dell'applicazione deve creare la chiave del Registro di sistema 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_ e impostare il valore predefinito della chiave sul percorso completo del file manifest. Ad esempio, utilizzando il seguente 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 utilizzando il seguente file .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 Chrome cerca host di messaggistica nativi, viene eseguita prima una query sul Registro di sistema a 32 bit, poi sul Registro di sistema a 64 bit.

Su OS X e Linux, la posizione del file manifest dell'host di messaggistica nativo varia a seconda del browser (Google Chrome o Chromium). Gli host di messaggistica nativi a livello di sistema vengono individuati in una posizione fissa, mentre gli host di messaggistica nativi a livello di utente vengono individuati in una sottodirectory all'interno della directory del profilo utente denominata NativeMessagingHosts.

• OS X (a livello di sistema)
  • Google Chrome: /Library/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Cromo: /Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
• OS X (specifico dell'utente, percorso predefinito)
  • Google Chrome: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Cromo: ~/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
• Linux (a livello di sistema)
  • Google Chrome: /etc/opt/chrome/native-messaging-hosts/_com.my_company.my_application_.json
  • Cromo: /etc/chromium/native-messaging-hosts/_com.my_company.my_application_.json
• Linux (specifico dell'utente, percorso predefinito)
  • Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Cromo: ~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json

Protocollo di messaggistica nativo

Chrome avvia ogni host di messaggistica nativo in un processo separato e comunica con l'host standard utilizzando l'input standard (stdin) e l'output standard (stdout). Lo stesso formato viene utilizzato per inviare messaggi in entrambe le direzioni: ogni messaggio viene serializzato utilizzando JSON con codifica UTF-8 ed è preceduto da una lunghezza del messaggio a 32 bit in ordine di byte nativi. La dimensione massima di un singolo messaggio proveniente dall'host di messaggistica nativo è 1 MB, principalmente per proteggere Chrome dal comportamento anomalo delle applicazioni native. La dimensione massima del messaggio inviato all'host di messaggistica nativo è 4 GB.

Il primo argomento dell'host di messaggistica nativo è l'origine del chiamante, di solito chrome-extension://[ID of allowed extension]. In questo modo gli host di messaggi nativi possono identificare l'origine del messaggio quando sono specificate più estensioni nella chiave allowed_origins nel manifest dell'host di messaggistica nativo. Avviso: in Windows, in Chrome 54 e versioni precedenti, l'origine è stata passata come secondo parametro anziché come primo.

Quando viene creata una porta di messaggistica utilizzando runtime.connectNative, Chrome avvia il processo host di messaggistica nativo e lo mantiene in esecuzione fino all'eliminazione della porta. Quando invece un messaggio viene inviato utilizzando runtime.sendNativeMessage, senza creare una porta per i messaggi, Chrome avvia un nuovo processo nativo dell'host di messaggistica per ciascun messaggio. In questo caso il primo messaggio generato dal processo host viene gestito come una risposta alla richiesta originale, ad esempio Chrome lo passa al callback di risposta specificato quando viene chiamato runtime.sendNativeMessage. In questo caso, tutti gli altri messaggi generati dall'host di messaggistica nativo vengono ignorati.

Su Windows, all'host di messaggistica nativo viene passato anche un argomento della riga di comando con un handle alla finestra nativa di Chrome della chiamata: --parent-window=<decimal handle value>. Ciò consente all'host di messaggistica nativa di creare finestre dell'interfaccia utente native che vengono correttamente associate come genitore. Tieni presente che questo valore sarà 0 se il contesto della chiamata è una pagina di script in background.

Connessione a un'applicazione nativa

L'invio e la ricezione di messaggi da e verso un'applicazione nativa è molto simile alla messaggistica su più estensioni. La differenza principale è che viene utilizzato runtime.connectNative al posto di runtime.connect, che al posto di runtime.sendMessage.runtime.sendNativeMessage Questi metodi possono essere utilizzati solo se l'autorizzazione "nativeMessaging" è stata dichiarata nel file manifest dell'app.

L'esempio seguente crea un oggetto runtime.Port connesso all'host di messaggistica nativo com.my_company.my_application, inizia ad ascoltare i messaggi provenienti da quella porta e invia un messaggio in uscita:

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 può essere utilizzato per inviare un messaggio a un'applicazione nativa senza creare una porta, ad esempio:

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

Debug della messaggistica nativa

Se l'host di messaggistica nativo non si avvia, scrive su stderr o viola il protocollo di comunicazione, l'output viene scritto nel log degli errori di Chrome. Su Linux e OS X, è facile accedere a questo log avviando Chrome dalla riga di comando e osservando l'output nel terminale. Su Windows, utilizza --enable-logging come spiegato in Come abilitare il logging.

Di seguito sono riportati alcuni errori e suggerimenti per risolvere i problemi:

• Impossibile avviare l'host di messaggistica nativo.
  • Verifica di disporre di autorizzazioni sufficienti per eseguire il file.
• Nome host di messaggistica nativa specificato non valido.
  • Controlla se il nome contiene caratteri non validi. Sono consentiti solo caratteri alfanumerici minuscoli, trattini bassi e punti. Un nome non può iniziare o terminare con un punto e un punto non può essere seguito da un altro punto.
• L'host nativo è uscito.
  • La barra verticale che rimanda all'host di messaggistica nativa è stata interrotta prima che il messaggio venisse letto da Chrome. È molto probabile che venga avviata dall'host di messaggistica nativo.
• Host di messaggistica nativo specificato non trovato.
  • Il nome è scritto correttamente nell'estensione e nel file manifest?
  • Il file manifest è inserito nella directory corretta e con il nome corretto? Consulta la località dell'host di messaggistica nativa per i formati previsti.
  • Il formato del file manifest è corretto? In particolare, la sintassi JSON è corretta e i valori corrispondono alla definizione di un manifest dell'host di messaggistica nativo?
  • Il file specificato in path esiste? Su Windows, i percorsi possono essere relativi, ma su OS X e Linux devono essere assoluti.
• Il nome host dell'host di messaggistica nativo non è registrato. (Solo Windows)
  • Impossibile trovare l'host di messaggistica nativo nel Registro di sistema di Windows. Verifica con regedit se la chiave è stata effettivamente creata e se corrisponde al formato richiesto come documentato nella località host di messaggistica nativa.
• È vietato accedere all'host di messaggistica nativo specificato.
  • L'origine dell'estensione è elencata in allowed_origins?
• Errore durante la comunicazione con l'host di messaggistica nativo.
  • Questo è un errore molto comune e indica un'implementazione errata del protocollo di comunicazione nell'host di messaggistica nativo.
  • Assicurati che tutto l'output in stdout rispetti il protocollo di messaggistica nativo. Se vuoi stampare alcuni dati a scopo di debug, scrivi in stderr.
  • Assicurati che la lunghezza del messaggio a 32 bit sia nel formato intero nativo della piattaforma (little-endian/big-endian).
  • La lunghezza del messaggio non deve essere superiore a 1024*1024.
  • Le dimensioni del messaggio devono essere uguali al numero di byte nel messaggio. Può differire dalla "lunghezza" di una stringa, perché i caratteri possono essere rappresentati da più byte.
  • Solo Windows: assicurati che la modalità I/O del programma sia impostata su O_BINARY. Per impostazione predefinita, la modalità I/O è O_TEXT, che danneggia il formato del messaggio poiché le interruzioni di riga (\n = 0A) vengono sostituite con terminazioni di riga in stile Windows (\r\n = 0D 0A). La modalità I/O può essere impostata utilizzando __setmode.