Messaggi nativi

Le estensioni e le applicazioni possono scambiare messaggi con applicazioni native utilizzando un'API simile l'altra API di trasmissione dei messaggi. Le applicazioni native che supportano questa funzionalità devono registrare un host di messaggistica nativo che sa come comunicare con l'estensione. Chrome avvia l'host in un processo separato e comunica con quest'ultimo utilizzando flussi di input standard e di output standard.

Host di messaggistica nativa

Per registrare un host di messaggistica nativo, l'applicazione deve installare un file manifest definisce la configurazione dell'host di messaggistica nativa. 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 in formato JSON valido e contenere i seguenti campi:

Posizione host di messaggistica nativa

Il percorso del file manifest dipende dalla piattaforma.

Su Windows, il file manifest può trovarsi ovunque nel file system. L'applicazione il programma di installazione deve creare una 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 di quella chiave sul percorso completo del file manifest. Ad esempio, utilizzando 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 usando 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 la query sul registro a 32 bit, poi su quello a 64 bit registro di sistema.

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

• OS X (a livello di 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 (specifico dell'utente, percorso predefinito)
  .
  • 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 (a livello di 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 (specifico dell'utente, percorso predefinito)
  .
  • Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Chromium: ~/.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 ciascuno di essi utilizzando input standard (stdin) e output standard (stdout). Lo stesso formato viene utilizzato per inviare messaggi in in entrambe le direzioni: ogni messaggio è serializzato utilizzando JSON, codifica UTF-8 ed è preceduto da lunghezza del messaggio in ordine nativo dei byte. La dimensione massima di un singolo messaggio del messaggio nativo è di 1 MB, principalmente per proteggere Chrome dal comportamento anomalo delle applicazioni native. La dimensione massima del un messaggio inviato all'host di messaggistica nativo è di 4 GB.

Il primo argomento per l'host di messaggistica nativo è l'origine del chiamante, di solito chrome-extension://[ID of allowed extension]. Ciò consente agli host di messaggistica nativa di identificare l'origine del messaggio quando sono specificate più estensioni nella chiave allowed_origins all'interno manifest dell'host di messaggistica nativa. Avviso: in Windows, in Chrome 54 e versioni precedenti, l'origine è stata passata come secondo parametro anziché il primo parametro.

Quando viene creata una porta di messaggistica utilizzando runtime.connectNative, Chrome avvia la messaggistica nativa il processo host e lo mantiene in esecuzione finché la porta non viene eliminata. Al contrario, quando un messaggio viene inviato utilizzando runtime.sendNativeMessage, senza creare una porta di messaggistica, Chrome avvia una nuova dell'host di messaggistica nativa per ogni messaggio. In questo caso, il primo messaggio generato dall'host processo viene gestito come risposta alla richiesta originale, ovvero Chrome lo trasmetterà alla risposta specificato quando viene chiamato runtime.sendNativeMessage. Tutti gli altri messaggi generati da l'host di messaggistica nativo viene ignorato.

Su Windows, all'host di messaggistica nativo viene inviato anche un argomento della riga di comando con un handle alla chiamata alla finestra nativa di Chrome: --parent-window=<decimal handle value>. Questo consente agli utenti nativi l'host di messaggistica crea finestre UI native che siano correttamente padre. Tieni presente che questo valore 0 se il contesto di 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 alle estensioni incrociate i messaggi. La differenza principale è che viene utilizzato runtime.connectNative al posto di vengono utilizzati runtime.connect e runtime.sendNativeMessage al posto di runtime.sendMessage. Questi metodi possono essere utilizzati solo se la classe "nativeMessaging" l'autorizzazione è dichiarata nella console manifest.

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

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 dei messaggi nativi

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

Di seguito sono riportati alcuni errori e suggerimenti per la risoluzione dei problemi:

• Impossibile avviare l'host di messaggistica nativo.
  • Verifica di disporre di autorizzazioni sufficienti per eseguire il file.
• Il nome host specificato per la messaggistica nativa non è valido.
  • Controlla se il nome contiene caratteri non validi. Solo caratteri alfanumerici minuscoli, sono consentiti 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 è stato chiuso.
  • La barra verticale che indirizza all'host di messaggistica nativo si è interrotta prima che il messaggio venisse letto da Chrome. Questo è il numero massimo probabilmente è stata avviata dal tuo host di messaggistica nativo.
• Host di messaggistica nativa specificato non trovato.
  • Il nome è scritto correttamente nell'estensione e nel file manifest?
  • Il file manifest è posizionato nella directory corretta e con il nome corretto? Vedi Host di messaggistica nativa posizione per i formati previsti.
  • Il formato del file manifest è corretto? In particolare, la sintassi JSON è corretta e corrispondono alla definizione di un file manifest host di messaggistica nativo?
  • Il file specificato in path esiste? Su Windows, i percorsi possono essere relativi, ma su OS X e Linux i percorsi devono essere assoluti.
• Il nome host dell'host di messaggistica nativa non è registrato. (Solo Windows)
  • Impossibile trovare l'host di messaggistica nativo nel registro di Windows. Ricontrolla utilizzando regedit se la chiave è stata davvero creata e corrisponde al formato richiesto come documentato in native la posizione dell'host dei messaggi.
• L'accesso all'host di messaggistica nativo specificato non è consentito.
  • L'origine dell'estensione è elencata in allowed_origins?
• Errore durante la comunicazione con l'host di messaggistica nativo.
  • Si tratta di un errore molto comune e indica un'implementazione errata del protocollo di comunicazione nell'host di messaggistica nativo.
  • Assicurati che tutti gli output in stdout siano conformi al protocollo di messaggistica nativo. Se vuoi per 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 superare 1024*1024.
  • Le dimensioni del messaggio devono corrispondere al numero di byte del messaggio. Questo valore può essere diverso "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, è O_TEXT, che danneggia il formato del messaggio perché le interruzioni di riga (\n = 0A) vengono sostituite con Fine delle righe in stile Windows (\r\n = 0D 0A). La modalità I/O può essere impostata utilizzando __setmode.