Deze pagina is vertaald door de Cloud Translation API.

Native berichten

Extensies kunnen berichten uitwisselen met native applicaties via een API die vergelijkbaar is met andere API's voor berichtuitwisseling . Native applicaties die deze functie ondersteunen, moeten een native berichtenhost registreren die met de extensie kan communiceren. Chrome start de host in een apart proces en communiceert ermee via standaardinvoer- en standaarduitvoerstreams.

Native berichtenhost

Om een native berichtenhost te registreren, moet de applicatie een bestand opslaan waarin de configuratie van de native berichtenhost is gedefinieerd.

Een voorbeeld van het bestand ziet er als volgt uit:

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

Het manifestbestand van de native berichtenhost moet geldige JSON zijn en de volgende velden bevatten:

name: De naam van de native berichtenhost. Clients geven deze tekenreeks door aan runtime.connectNative() of runtime.sendNativeMessage() . Deze naam mag alleen kleine letters, cijfers, underscores en punten bevatten. De naam mag niet beginnen of eindigen met een punt, en een punt mag niet gevolgd worden door een andere punt.
description: Korte beschrijving van de applicatie.
path: Pad naar het binaire bestand van de native berichtenhost. Op Linux en macOS moet het pad absoluut zijn. Op Windows kan het relatief zijn ten opzichte van de map waarin het manifestbestand zich bevindt. Het hostproces wordt gestart met de huidige map ingesteld op de map die het hostbinaire bestand bevat. Als deze parameter bijvoorbeeld is ingesteld op C:\Application\nm_host.exe , wordt het gestart met de huidige map `C:\Application`.
type: Het type interface dat wordt gebruikt om te communiceren met de native berichtenhost. Deze parameter heeft één mogelijke waarde: stdio . Dit geeft aan dat Chrome stdin en stdout moet gebruiken om met de host te communiceren.
allowed_origins: Lijst met extensies die toegang moeten hebben tot de native berichtenhost. Waarden in allowed-origins mogen geen wildcards bevatten.

Native messaging hostlocatie

De locatie van het manifestbestand is afhankelijk van het platform.

Op Windows kan het manifestbestand zich overal in het bestandssysteem bevinden. Het installatieprogramma van de applicatie moet een registersleutel aanmaken, ofwel HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application of HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application , en de standaardwaarde van die sleutel instellen op het volledige pad naar het manifestbestand. Bijvoorbeeld met behulp van de volgende opdracht:

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

of door gebruik te maken van het volgende .reg -bestand:

Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application]
@="C:\\path\\to\\nmh-manifest.json"

Wanneer Chrome zoekt naar native berichtenhosts, wordt eerst het 32-bits register geraadpleegd en vervolgens het 64-bits register.

Op macOS en Linux verschilt de locatie van het manifestbestand van de native messaging host per browser (Google Chrome, Google Chrome voor testen of Chromium). De systeemwijde native messaging hosts worden op een vaste locatie opgezocht, terwijl de native messaging hosts op gebruikersniveau worden opgezocht in de subdirectory NativeMessagingHosts/ van de gebruikersprofielmap .

macOS (systeembreed): Google Chrome: /Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome voor testen: /Library/Google/ChromeForTesting/NativeMessagingHosts/com.my_company.my_application.json; Chromium: /Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json
macOS (gebruikersspecifiek, standaardpad ): Google Chrome: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome voor testen: ~/Library/Application Support/Google/ChromeForTesting/NativeMessagingHosts/com.my_company.my_application.json; Chromium: ~/Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json
Linux (systeembreed): Google Chrome: /etc/opt/chrome/native-messaging-hosts/com.my_company.my_application.json; Google Chrome voor testen: /etc/opt/chrome_for_testing/native-messaging-hosts/com.my_company.my_application.json; Chromium: /etc/chromium/native-messaging-hosts/com.my_company.my_application.json
Linux (gebruikersspecifiek, standaardpad ): Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome voor testen: ~/.config/google-chrome-for-testing/NativeMessagingHosts/com.my_company.my_application.json; Chromium: ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

Native berichtenprotocol

Chrome start elke native berichtenhost in een apart proces en communiceert ermee via standaardinvoer ( stdin ) en standaarduitvoer ( stdout ). Hetzelfde formaat wordt gebruikt om berichten in beide richtingen te verzenden; elk bericht wordt geserialiseerd met JSON, UTF-8-gecodeerd en voorafgegaan door een 32-bits berichtlengte in native bytevolgorde. De maximale grootte van een enkel bericht van de native berichtenhost is 1 MB, voornamelijk om Chrome te beschermen tegen problemen met native applicaties. De maximale grootte van het bericht dat naar de native berichtenhost wordt verzonden, is 64 MiB.

Het eerste argument voor de native messaging host is de oorsprong van de beller, meestal chrome-extension://[ID of allowed extension] . Dit stelt native messaging hosts in staat de bron van het bericht te identificeren wanneer meerdere extensies zijn gespecificeerd in de sleutel allowed_origins in het manifest van de native messaging host .

Op Windows krijgt de native berichtenhost ook een opdrachtregelargument mee met een handle naar het aanroepende native Chrome-venster: --parent-window=<decimal handle value> . Hiermee kan de native berichtenhost native UI-vensters maken die correct gekoppeld zijn aan een oudervenster. Merk op dat deze waarde 0 zal zijn als de aanroepende context een service worker is.

Wanneer een berichtenpoort wordt aangemaakt met runtime.connectNative() , start Chrome een native berichtenhostproces en houdt dit actief totdat de poort wordt vernietigd. Aan de andere kant, wanneer een bericht wordt verzonden met runtime.sendNativeMessage() , zonder een berichtenpoort aan te maken, start Chrome voor elk bericht een nieuw native berichtenhostproces. In dat geval wordt het eerste bericht dat door het hostproces wordt gegenereerd, behandeld als een antwoord op het oorspronkelijke verzoek en geeft Chrome dit door aan de callbackfunctie die is opgegeven bij het aanroepen runtime.sendNativeMessage() . Alle andere berichten die in dat geval door het native berichtenhostproces worden gegenereerd, worden genegeerd.

Verbinding maken met een native applicatie

Het verzenden en ontvangen van berichten van en naar een native applicatie is vergelijkbaar met berichtenuitwisseling tussen extensies. Het belangrijkste verschil is dat runtime.connectNative() wordt gebruikt in plaats van runtime.connect() , en runtime.sendNativeMessage() in plaats van runtime.sendMessage() .

Om deze methoden te kunnen gebruiken, moet de machtiging "nativeMessaging" in het manifestbestand van uw extensie worden opgenomen .

Deze methoden zijn niet beschikbaar binnen contentscripts, alleen binnen de pagina's en de service worker van uw extensie. Als u vanuit een contentscript met de native applicatie wilt communiceren, moet u het bericht naar uw service worker sturen, die het vervolgens doorstuurt naar de native applicatie.

Het volgende voorbeeld maakt een runtime.Port -object aan dat is verbonden met de native berichtenhost com.my_company.my_application , begint te luisteren naar berichten van die poort en verzendt één uitgaand bericht:

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

Gebruik runtime.sendNativeMessage om een bericht naar de native applicatie te sturen zonder een poort aan te maken, bijvoorbeeld:

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

Foutopsporing van native berichten

Wanneer er bepaalde fouten optreden bij de native berichtenverwerking, wordt de uitvoer naar het foutenlogboek van Chrome geschreven. Dit gebeurt bijvoorbeeld wanneer de native berichtenhost niet start, naar stderr schrijft of het communicatieprotocol schendt. Op Linux en macOS is dit logboek toegankelijk door Chrome vanuit de opdrachtregel te starten en de uitvoer in de terminal te bekijken. Op Windows gebruikt u --enable-logging zoals uitgelegd in Hoe logboekregistratie in te schakelen .

Hieronder vindt u enkele veelvoorkomende fouten en tips om ze op te lossen:

Het is niet gelukt om de native berichtenhost te starten.

Controleer of u voldoende machtigingen hebt om het native berichtenhostbestand uit te voeren.

Er is een ongeldige hostnaam voor native berichtenverkeer opgegeven.

Controleer of de naam ongeldige tekens bevat. Alleen kleine letters, cijfers, underscores en punten zijn toegestaan. Een naam mag niet met een punt beginnen of eindigen, en een punt mag niet door een ander punt worden gevolgd.

De native host is afgesloten.

De verbinding met de native berichtenserver werd verbroken voordat Chrome het bericht kon lezen. Dit wordt hoogstwaarschijnlijk veroorzaakt door uw native berichtenserver.

De opgegeven native berichtenhost is niet gevonden.

Controleer het volgende:

Is de naam correct gespeld in de extensie en in het manifestbestand?
Staat het manifest in de juiste map en heeft het de juiste naam? Zie de locatie van de native berichtenhost voor de verwachte formaten.
Heeft het manifestbestand het juiste formaat? Is de JSON in het bijzonder geldig en goed opgemaakt en komen de waarden overeen met de definitie van een native messaging host-manifest ?
Bestaat het bestand dat in path is opgegeven? Op Windows mogen paden relatief zijn, maar op macOS en Linux moeten paden absoluut zijn.

De hostnaam van de native berichtenhost is niet geregistreerd. (Alleen voor Windows)

De native messaging host is niet gevonden in het Windows-register. Controleer met regedit of de sleutel daadwerkelijk is aangemaakt en overeenkomt met het vereiste formaat zoals beschreven op de pagina over de native messaging host .

Toegang tot de opgegeven native berichtenhost is verboden.

Staat de oorsprong van de extensie vermeld in allowed_origins ?

Fout bij de communicatie met de native berichtenhost.

Dit duidt op een onjuiste implementatie van het communicatieprotocol in de native berichtenhost.

Zorg ervoor dat alle uitvoer naar stdout voldoet aan het native berichtenprotocol . Als u gegevens wilt afdrukken voor debugdoeleinden, schrijf dan naar stderr .
Zorg ervoor dat de 32-bits berichtlengte de native integer-indeling van het platform heeft (little-endian / big-endian).
De lengte van het bericht mag niet groter zijn dan 1024*1024.
De berichtgrootte moet gelijk zijn aan het aantal bytes in het bericht. Dit kan verschillen van de "lengte" van een tekenreeks, omdat tekens door meerdere bytes kunnen worden weergegeven.
Alleen voor Windows: Zorg ervoor dat de I/O-modus van het programma is ingesteld op O_BINARY . Standaard is de I/O-modus O_TEXT , wat de berichtindeling verstoort doordat regeleinden ( \n = 0A ) worden vervangen door regeleinden in Windows-stijl ( \r\n = 0D 0A ). De I/O-modus kan worden ingesteld met __setmode .