Native berichten

Extensies en apps kunnen berichten uitwisselen met native applicaties met behulp van een API die vergelijkbaar is met de andere API's voor het doorgeven van berichten . Native applicaties die deze functie ondersteunen, moeten een native messaging-host registreren die weet hoe te communiceren met de extensie. 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 manifestbestand installeren dat de native messaging host-configuratie definieert. Hieronder ziet u een voorbeeld van het manifestbestand:

{
  "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:

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 de registersleutel HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ maken en de standaardwaarde van die sleutel instellen op 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 OS X 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 een submap binnen de gebruikersprofielmap met de naam NativeMessagingHosts .

• OS X (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
• OS X (gebruikerspecifiek, 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 wordt 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 . Waarschuwing : in Windows, in Chrome 54 en eerder, werd de oorsprong doorgegeven als de tweede parameter in plaats van de eerste parameter.

Wanneer een berichtenpoort wordt gemaakt met behulp van 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, afgehandeld als een reactie op het oorspronkelijke verzoek, dat wil zeggen dat Chrome het doorgeeft 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.

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 achtergrondscriptpagina is.

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 . Deze methoden kunnen alleen worden gebruikt als de machtiging 'nativeMessaging' is gedeclareerd in het manifestbestand van uw app.

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

runtime.sendNativeMessage kan worden gebruikt om een ​​bericht naar de eigen 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);
  });

Fouten opsporen in native berichten

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

Hier volgen enkele fouten en tips voor het oplossen van de problemen:

• Kan native messaging-host niet starten.
  • Controleer of u voldoende rechten heeft om het bestand 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.
  • Is de naam correct gespeld in de extensie en in het manifestbestand?
  • Staat het manifest in de juiste directory en met de juiste naam? Zie de native messaging-hostlocatie voor de verwachte formaten.
  • Heeft het manifestbestand het juiste formaat? Is de JSON-syntaxis in het bijzonder correct 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 OS X 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 is een veel voorkomende fout en 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 .