Diese Seite wurde von der Cloud Translation API übersetzt.

Natives Messaging

Erweiterungen können Nachrichten mit nativen Anwendungen austauschen. Dazu wird eine API verwendet, die den anderen APIs für die Nachrichtenübergabe ä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 mit ihm über Standard-Ein- und ‑Ausgabestreams.

Host für natives Messaging

Um einen Host für die native Nachrichtenübermittlung zu registrieren, muss die Anwendung eine Datei speichern, in der die Konfiguration des Hosts für die native Nachrichtenübermittlung definiert ist.

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 Hosts für die native Nachrichtenübermittlung muss gültiges JSON enthalten und die folgenden Felder aufweisen:

name: Name des Hosts für natives Messaging. Clients übergeben diesen String an runtime.connectNative() oder runtime.sendNativeMessage(). Dieser Name darf nur alphanumerische Kleinbuchstaben, Unterstriche und Punkte enthalten. Der Name darf nicht mit einem Punkt beginnen oder enden und auf einen Punkt darf kein weiterer 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: 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 einem beliebigen Ort im Dateisystem befinden. Das 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. Zum Beispiel mit dem folgenden Befehl:

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 Hosts für die native Nachrichtenübermittlung sucht, wird zuerst die 32‑Bit-Registrierung und dann die 64‑Bit-Registrierung abgefragt.

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

macOS (für das ganze System): 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

Protokoll für natives Messaging

Chrome startet jeden nativen Messaging-Host in einem separaten Prozess und kommuniziert mit ihm über die Standardeingabe (stdin) und die Standardausgabe (stdout). Für das Senden von Nachrichten in beide Richtungen wird dasselbe Format verwendet. Jede Nachricht wird mit JSON serialisiert, UTF-8-codiert und mit einer 32-Bit-Nachrichtenlänge in nativer Byte-Reihenfolge versehen. Die maximale Größe einer einzelnen Nachricht vom Host für die native Nachrichtenübermittlung 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 MiB.

Das erste Argument für den nativen Messaging-Host ist der Ursprung des Aufrufers, in der Regel chrome-extension://[ID of allowed extension]. So können Hosts für natives Messaging die Quelle der Nachricht identifizieren, wenn im allowed_origins-Schlüssel 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 Host für natives Messaging native UI-Fenster erstellen, die korrekt übergeordnet sind. Beachten Sie, dass dieser Wert 0 ist, wenn der aufrufende Kontext ein Service Worker ist.

Wenn ein Nachrichtenport mit runtime.connectNative() erstellt wird, startet Chrome den nativen Messaging-Hostprozess und führt ihn aus, bis der Port zerstört wird. Wenn eine Nachricht mit runtime.sendNativeMessage() gesendet wird, ohne dass ein Messaging-Port erstellt wird, startet Chrome für jede Nachricht einen neuen Prozess für den nativen Messaging-Host. In diesem Fall wird die erste vom Hostprozess generierte Nachricht als Antwort auf die ursprüngliche Anfrage behandelt und von Chrome an den Antwort-Callback übergeben, der beim Aufrufen von runtime.sendNativeMessage() angegeben wurde. Alle anderen Nachrichten, die vom nativen Nachrichtenhost in diesem Fall generiert werden, werden ignoriert.

Verbindung zu einer nativen Anwendung herstellen

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

Damit Sie diese Methoden verwenden können, muss die Berechtigung „nativeMessaging“ in der Manifestdatei Ihrer Erweiterung deklariert werden.

Diese Methoden sind nicht in Inhaltsscripts, sondern nur auf den Seiten und im Service Worker Ihrer Erweiterung verfügbar. Wenn Sie von einem Content-Script aus 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 beginnt, Nachrichten von diesem Port zu empfangen, und sendet eine ausgehende Nachricht:

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

Bei bestimmten Fehlern bei der nativen Nachrichtenübermittlung wird die Ausgabe in das Fehlerlog von Chrome geschrieben. Das kann beispielsweise der Fall sein, wenn der Host für natives Messaging nicht gestartet wird, in stderr geschrieben wird oder gegen das Kommunikationsprotokoll verstößt. Unter Linux und macOS kann auf dieses Log zugegriffen werden, indem Chrome über die Befehlszeile gestartet und die Ausgabe im Terminal beobachtet wird. 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 die native Messaging-Funktion verfügen.

Ungültiger Hostname für das native Messaging angegeben.

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

Der native Host wurde beendet.

Die Verbindung zum nativen Messaging-Host wurde unterbrochen, bevor die Nachricht von Chrome gelesen wurde. Das 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 nativen Messaging-Hosts.
Hat die Manifestdatei das richtige Format? Ist das JSON gültig und wohlgeformt und entsprechen die Werte der Definition eines Manifests für native Messaging-Hosts?
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 Host für natives Messaging host name 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, wie unter Standort des nativen Messaging-Hosts beschrieben.

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 zu Debugging-Zwecken ausgeben möchten, schreiben Sie in stderr.
Achten Sie darauf, dass die 32‑Bit-Nachrichtenlänge im nativen Ganzzahlformat der Plattform (Little-Endian/Big-Endian) vorliegt.
Die Nachrichtenlänge darf 1024*1024 nicht überschreiten.
Die Nachrichtengröße muss der Anzahl der Byte in der Nachricht entsprechen. Das kann sich von der „Länge“ eines Strings unterscheiden, da Zeichen durch mehrere Byte dargestellt werden können.
Nur Windows:Der E/A-Modus des Programms muss auf O_BINARY eingestellt sein. Standardmäßig ist der E/A-Modus O_TEXT, wodurch das Nachrichtenformat beschädigt wird, da Zeilenumbrüche (\n = 0A) durch Windows-Zeilenenden (\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.