Deze pagina is vertaald door de Cloud Translation API.

Native berichten

Extensies kunnen berichten uitwisselen met native applicaties met behulp van een API die vergelijkbaar is met de andere API's voor het doorgeven van berichten . Systeemeigen toepassingen die deze functie ondersteunen, moeten een systeemeigen berichtenhost registreren die met de extensie kan communiceren. Chrome start de host in een afzonderlijk proces en communiceert ermee via standaardinvoer- en standaarduitvoerstromen.

Native berichtenhost

Om een native messaging host te registreren, moet de applicatie een bestand opslaan dat de native messaging host-configuratie definieert.

Een voorbeeld van het bestand is als volgt:

{
  "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 native messaging-hostmanifestbestand moet geldige JSON zijn en de volgende velden bevatten:

name: Naam van de native berichtenhost. Clients geven deze tekenreeks door aan runtime.connectNative() of runtime.sendNativeMessage() . Deze naam mag alleen alfanumerieke kleine letters, onderstrepingstekens en punten bevatten. De naam mag niet beginnen of eindigen met een punt, en een punt kan niet worden gevolgd door een andere punt.
description: Korte toepassingsbeschrijving.
path: Pad naar het binaire bestand van de systeemeigen berichtenhost. Op Linux en macOS moet het pad absoluut zijn. Op Windows kan dit relatief zijn ten opzichte van de map die het manifestbestand bevat. Het hostproces wordt gestart met de huidige map ingesteld op de map die het binaire hostbestand bevat. Als deze parameter bijvoorbeeld is ingesteld op C:\Application\nm_host.exe , wordt deze gestart met de huidige directory `C:\Application`.
type: Type interface dat wordt gebruikt om te communiceren met de native messaging-host. Deze parameter heeft één mogelijke waarde: stdio . Het 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 messaging-host. allowed-origins waarden mogen geen jokertekens bevatten.

Hostlocatie voor native berichten

De locatie van het manifestbestand is afhankelijk van het platform.

In Windows kan het manifestbestand zich overal in het bestandssysteem bevinden. Het installatieprogramma van de toepassing moet een registersleutel maken, 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 naar het volledige pad naar het manifestbestand. Gebruik bijvoorbeeld 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 gebruik 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 messaging-hosts, wordt eerst het 32-bits register opgevraagd en vervolgens het 64-bits register.

Op macOS en Linux varieert de locatie van het manifestbestand van de native messaging-host per browser (Google Chrome of Chromium). De systeembrede native messaging-hosts worden opgezocht op een vaste locatie, terwijl de native messaging-hosts op gebruikersniveau worden opgezocht in de NativeMessagingHosts/ submap van de gebruikersprofieldirectory .

macOS (systeembreed): Google Chrome: /Library/Google/Chrome/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; 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; 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; Chromium: ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

Native berichtenprotocol

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

Het eerste argument voor de native messaging-host is de oorsprong van de beller, meestal chrome-extension://[ID of allowed extension] . Hierdoor kunnen native messaging-hosts de bron van het bericht identificeren wanneer meerdere extensies zijn opgegeven in de allowed_origins sleutel in het native messaging-hostmanifest .

In Windows krijgt de native messaging-host ook een opdrachtregelargument met een handle doorgegeven aan het aanroepende Chrome-native venster: --parent-window=<decimal handle value> . Hierdoor kan de native messaging-host native UI-vensters maken met de juiste parent-instellingen. Houd er rekening mee dat deze waarde 0 is als de aanroepende context een servicemedewerker is.

Wanneer een berichtenpoort wordt gemaakt met runtime.connectNative() start Chrome het 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 te maken, start Chrome voor elk bericht een nieuw native messaging-hostproces. In dat geval wordt het eerste bericht dat door het hostproces wordt gegenereerd, verwerkt als reactie op het oorspronkelijke verzoek, en geeft Chrome dit door aan de respons-callback die is opgegeven wanneer runtime.sendNativeMessage() wordt aangeroepen. Alle andere berichten die in dat geval door de native messaging-host worden gegenereerd, worden genegeerd.

Verbinding maken met een native applicatie

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

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

Deze methoden zijn niet beschikbaar in inhoudsscripts, alleen op de pagina's en servicemedewerkers van uw extensie. Als u vanuit een inhoudsscript naar de native applicatie wilt communiceren, stuurt u het bericht naar uw servicemedewerker om het door te geven aan de native applicatie.

In het volgende voorbeeld wordt een runtime.Port object gemaakt dat is verbonden met de systeemeigen berichtenhost com.my_company.my_application , begint te luisteren naar berichten van die poort en één uitgaand bericht te verzenden:

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 te creëren, bijvoorbeeld:

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

Debuggen van native berichten

Wanneer bepaalde native messaging-fouten optreden, wordt de uitvoer naar het foutenlogboek van Chrome geschreven. Dit geldt ook als de native messaging-host niet start, naar stderr schrijft of het communicatieprotocol schendt. Op Linux en macOS is dit logboek toegankelijk door Chrome te starten vanaf de opdrachtregel en de uitvoer ervan in de terminal te bekijken. In Windows gebruikt u --enable-logging zoals uitgelegd in Logboekregistratie inschakelen .

Hier volgen enkele veelvoorkomende fouten en tips om deze op te lossen:

Kan native messaging-host niet starten.

Controleer of u voldoende rechten heeft om het native messaging-hostbestand uit te voeren.

Ongeldige hostnaam voor systeemeigen berichten opgegeven.

Controleer of de naam ongeldige tekens bevat. Alleen alfanumerieke kleine letters, onderstrepingstekens en punten zijn toegestaan. Een naam kan niet beginnen of eindigen met een punt, en een punt kan niet worden gevolgd door een andere punt.

Native host is verlaten.

De pijp naar de native messaging-host werd verbroken voordat het bericht door Chrome werd gelezen. Dit wordt hoogstwaarschijnlijk geïnitieerd vanaf uw native messaging-host.

Opgegeven native messaging-host 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 met de juiste naam? Zie de native messaging-hostlocatie voor de verwachte formaten.
Heeft het manifestbestand het juiste formaat? Is de JSON in het bijzonder geldig en goed gevormd en komen de waarden overeen met de definitie van een native messaging host-manifest ?
Bestaat het bestand dat is opgegeven in path ? Op Windows kunnen paden relatief zijn, maar op macOS en Linux moeten de paden absoluut zijn.

Hostnaam van native messaging-host is niet geregistreerd. (alleen Windows)

De native messaging-host is niet gevonden in het Windows-register. Controleer nogmaals met regedit of de sleutel echt is gemaakt en overeenkomt met het vereiste formaat zoals gedocumenteerd op de native messaging host-locatie .

Toegang tot de opgegeven native messaging-host is verboden.

Staat de oorsprong van de extensie vermeld in allowed_origins ?

Fout bij communicatie met de native messaging-host.

Dit duidt op een onjuiste implementatie van het communicatieprotocol in de native messaging-host.

Zorg ervoor dat alle uitvoer in stdout voldoet aan het native messaging-protocol . Als u gegevens wilt afdrukken voor foutopsporingsdoeleinden, schrijft u naar stderr .
Zorg ervoor dat de berichtlengte van 32 bits de oorspronkelijke integer-indeling van het platform heeft (little-endian / big-endian).
De berichtlengte 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 string, omdat karakters 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 het berichtformaat corrumpeert omdat regeleinden ( \n = 0A ) worden vervangen door regeleinden in Windows-stijl ( \r\n = 0D 0A ). De I/O-modus kan worden ingesteld met __setmode .