Diese Seite wurde von der Cloud Translation API übersetzt.

Natives Messaging

Erweiterungen können Nachrichten mit nativen Anwendungen über eine API austauschen, die den anderen APIs für die Nachrichtenweitergabe ähnelt. Native Anwendungen, die diese Funktion unterstützen, müssen einen nativen Messaging-Host registrieren, der mit der Erweiterung kommunizieren kann. Chrome startet den Host in einem separaten Prozess und kommuniziert über Standardeingabe- und Standardausgabestreams mit ihm.

Host für natives Messaging

Um einen Native Messaging-Host zu registrieren, muss die Anwendung eine Datei speichern, die die Native Messaging-Hostkonfiguration definiert.

Hier ein Beispiel für die Datei:

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

Die Manifestdatei des Native Messaging-Hosts muss ein gültiges JSON-Format haben und die folgenden Felder enthalten:

name: Name des Hosts für natives Messaging. Clients übergeben diesen String an runtime.connectNative() oder runtime.sendNativeMessage(). Dieser Name darf nur Kleinbuchstaben, alphanumerische Zeichen, Unterstriche und Punkte enthalten. Der Name darf nicht mit einem Punkt beginnen oder enden und ein Punkt darf nicht auf einen anderen Punkt folgen.
description: Kurze Beschreibung der Anwendung.
path: Pfad zur Binärdatei des Hosts für natives Messaging. Unter Linux und macOS muss der Pfad absolut sein. Unter Windows kann er relativ zum Verzeichnis sein, das die Manifestdatei enthält. Der Hostprozess wird gestartet, wobei das aktuelle Verzeichnis auf das Verzeichnis festgelegt ist, das die Host-Binärdatei enthält. Wenn dieser Parameter beispielsweise auf C:\Application\nm_host.exe festgelegt ist, wird er mit dem aktuellen Verzeichnis „C:\Application“ gestartet.
type: Der Typ der Schnittstelle, die für die Kommunikation mit dem nativen Messaging-Host verwendet wird. Dieser Parameter hat einen möglichen Wert: stdio. Es gibt an, dass Chrome stdin und stdout für die Kommunikation mit dem Host verwenden soll.
allowed_origins: Liste der Erweiterungen, die Zugriff auf den Host für natives Messaging haben sollen. allowed-origins-Werte dürfen keine Platzhalter enthalten.

Standort des Hosts für natives Messaging

Der Speicherort der Manifestdatei hängt von der Plattform ab.

Unter Windows kann sich die Manifestdatei an einer beliebigen Stelle im Dateisystem befinden. Der Installationsprogramm der Anwendung muss einen Registrierungsschlüssel erstellen, entweder HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application oder HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application, und den Standardwert dieses Schlüssels auf den vollständigen Pfad zur Manifestdatei festlegen. Beispiel:

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

oder mit der folgenden .reg-Datei:

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

Wenn Chrome nach nativen Messaging-Hosts sucht, wird zuerst die 32-Bit-Registry und dann die 64-Bit-Registry abgefragt.

Unter macOS und Linux hängt der Speicherort der Manifestdatei des nativen Messaging-Hosts vom Browser (Google Chrome oder Chromium) ab. Die systemweiten Hosts für natives Messaging werden an einem festen Speicherort abgerufen, während die Hosts für natives Messaging auf Nutzerebene im Unterverzeichnis NativeMessagingHosts/ des Nutzerprofilverzeichnisses abgerufen werden.

macOS (systemweit): 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 (nutzerspezifischer, Standardpfad): 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 (systemweit): 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 (nutzerspezifischer, Standardpfad): Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json; Chromium: ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

Natives Messaging-Protokoll

Chrome startet jeden nativen Messaging-Host in einem separaten Prozess und kommuniziert mit ihm über die Standardeingabe (stdin) und die Standardausgabe (stdout). Das gleiche Format wird zum Senden von Nachrichten in beide Richtungen verwendet. Jede Nachricht wird mit JSON serialisiert, UTF-8-codiert und durch eine 32-Bit-Nachrichtenlänge in nativer Byte-Reihenfolge eingeleitet. Die maximale Größe einer einzelnen Nachricht vom nativen Messaging-Host beträgt 1 MB. Dies dient hauptsächlich dazu, Chrome vor fehlerhaften nativen Anwendungen zu schützen. Die maximale Größe der Nachricht, die an den nativen Messaging-Host gesendet wird, beträgt 64 MB.

Das erste Argument für den nativen Messaging-Host ist der Ursprung des Anrufers, in der Regel chrome-extension://[ID of allowed extension]. So können Hosts für natives Messaging die Quelle der Nachricht ermitteln, wenn im Schlüssel allowed_origins im Manifest des Hosts für natives Messaging mehrere Erweiterungen angegeben sind.

Unter Windows wird dem Host für natives Messaging auch ein Befehlszeilenargument mit einem Handle für das aufrufende native Chrome-Fenster übergeben: --parent-window=<decimal handle value>. So kann der native Messaging-Host native UI-Fenster erstellen, die korrekt übergeordnet sind. Hinweis: Dieser Wert ist 0, wenn der Aufrufkontext ein Dienstworker ist.

Wenn ein Nachrichten-Port mit runtime.connectNative() erstellt wird, startet Chrome den nativen Messaging-Hostprozess und hält ihn so lange am Laufen, bis der Port gelöscht wird. Wenn eine Nachricht hingegen mit runtime.sendNativeMessage() gesendet wird, ohne dass ein Messaging-Port erstellt wird, startet Chrome für jede Nachricht einen neuen nativen Messaging-Hostprozess. In diesem Fall wird die erste vom Hostprozess generierte Nachricht als Antwort auf die ursprüngliche Anfrage verarbeitet und Chrome übergibt sie an den Antwort-Callback, der beim Aufrufen von runtime.sendNativeMessage() angegeben wurde. Alle anderen vom nativen Nachrichtenhost generierten Nachrichten werden in diesem Fall ignoriert.

Verbindung zu einer nativen Anwendung herstellen

Das Senden und Empfangen von Nachrichten an und von einer nativen Anwendung ähnelt dem plattformübergreifenden Senden und Empfangen von Nachrichten. Der Hauptunterschied besteht darin, dass runtime.connectNative() anstelle von runtime.connect() und runtime.sendNativeMessage() anstelle von runtime.sendMessage() verwendet wird.

Wenn Sie diese Methoden verwenden möchten, muss die Berechtigung „nativeMessaging“ in der Manifestdatei Ihrer Erweiterung deklariert werden.

Diese Methoden sind nicht in Inhaltsscripts verfügbar, sondern nur auf den Seiten und im Service Worker Ihrer Erweiterung. Wenn Sie von einem Inhaltsskript mit der nativen Anwendung kommunizieren möchten, senden Sie die Nachricht an Ihren Service Worker, damit er sie an die native Anwendung weiterleitet.

Im folgenden Beispiel wird ein runtime.Port-Objekt erstellt, das mit dem nativen Messaging-Host com.my_company.my_application verbunden ist. Es wird dann damit begonnen, nach Nachrichten von diesem Port zu suchen, und eine ausgehende Nachricht wird gesendet:

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

Verwenden Sie runtime.sendNativeMessage, um eine Nachricht an die native Anwendung zu senden, ohne einen Port zu erstellen, z.B.:

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

Natives Messaging debuggen

Wenn bestimmte Fehler bei der nativen Nachrichtenübermittlung auftreten, wird die Ausgabe in das Fehlerprotokoll von Chrome geschrieben. Dazu gehört auch, wenn der Host für natives Messaging nicht gestartet wird, auf stderr schreibt oder gegen das Kommunikationsprotokoll verstößt. Unter Linux und macOS können Sie auf dieses Protokoll zugreifen, indem Sie Chrome über die Befehlszeile starten und die Ausgabe im Terminal beobachten. Verwenden Sie unter Windows --enable-logging, wie unter Logging aktivieren beschrieben.

Im Folgenden finden Sie einige häufige Fehler und Tipps zur Fehlerbehebung:

Der native Messaging-Host konnte nicht gestartet werden.

Prüfen Sie, ob Sie über ausreichende Berechtigungen zum Ausführen der Hostdatei für native Nachrichten verfügen.

Ungültiger Hostname für native Nachrichten angegeben.

Prüfen Sie, ob der Name ungültige Zeichen enthält. Nur alphanumerische Zeichen in Kleinschreibung, Unterstriche und Punkte sind zulässig. Ein Name darf nicht mit einem Punkt beginnen oder enden und ein Punkt darf nicht auf einen anderen Punkt folgen.

Der native Host wurde beendet.

Die Verbindung zum nativen Messaging-Host war unterbrochen, bevor die Nachricht von Chrome gelesen wurde. Dies wird höchstwahrscheinlich von Ihrem Host für natives Messaging initiiert.

Der angegebene Host für natives Messaging wurde nicht gefunden.

Dann machen Sie Folgendes:

Ist der Name in der Erweiterung und in der Manifestdatei richtig geschrieben?
Befindet sich das Manifest im richtigen Verzeichnis und hat es den richtigen Namen? Informationen zu den erwarteten Formaten finden Sie unter Speicherort des Hosts für native Nachrichten.
Hat die Manifestdatei das richtige Format? Ist das JSON-Objekt insbesondere gültig und wohlgeformt und stimmen die Werte mit der Definition eines Manifests für einen nativen Messaging-Host überein?
Ist die in path angegebene Datei vorhanden? Unter Windows können Pfade relativ sein, unter macOS und Linux müssen sie jedoch absolut sein.

Der Hostname des Hosts für natives Messaging ist nicht registriert. (nur Windows)

Der Host für natives Messaging wurde in der Windows-Registrierung nicht gefunden. Prüfen Sie mit regedit, ob der Schlüssel wirklich erstellt wurde und dem erforderlichen Format entspricht, das unter Speicherort des Messaging-Hosts beschrieben ist.

Der Zugriff auf den angegebenen Host für natives Messaging ist verboten.

Ist der Ursprung der Erweiterung in allowed_origins aufgeführt?

Fehler bei der Kommunikation mit dem nativen Messaging-Host.

Dies weist auf eine falsche Implementierung des Kommunikationsprotokolls im Host für natives Messaging hin.

Achten Sie darauf, dass die gesamte Ausgabe in stdout dem nativen Messaging-Protokoll entspricht. Wenn Sie einige Daten zur Fehlerbehebung drucken möchten, schreiben Sie an stderr.
Die 32-Bit-Nachrichtenlänge muss im nativen Ganzzahlformat der Plattform (Little-Endian/Big-Endian) vorliegen.
Die Nachrichtenlänge darf 1.024 × 1.024 nicht überschreiten.
Die Nachrichtengröße muss der Anzahl der Byte in der Nachricht entsprechen. Dieser Wert kann von der „Länge“ eines Strings abweichen, da Zeichen durch mehrere Byte dargestellt werden können.
Nur Windows:Der E/A-Modus des Programms muss auf O_BINARY festgelegt sein. Standardmäßig ist der E/A-Modus O_TEXT. Dadurch wird das Nachrichtenformat beschädigt, da Zeilenumbrüche (\n = 0A) durch Windows-Zeilenden (\r\n = 0D 0A) ersetzt werden. Der E/A-Modus kann mit __setmode festgelegt werden.

Natives Messaging Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.