Diese Seite wurde von der Cloud Translation API übersetzt.

Natives Messaging

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

Host für natives Messaging

Zum Registrieren eines nativen Nachrichtenhosts muss die Anwendung eine Datei speichern, in der die Konfiguration des nativen Nachrichtenhosts 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 natives Messaging muss eine gültige JSON-Datei sein und die folgenden Felder enthalten:

name: Name des Hosts für das native Messaging Clients übergeben diesen String an runtime.connectNative() oder runtime.sendNativeMessage(). Dieser Name darf nur kleingeschriebene alphanumerische Zeichen, Unterstriche und Punkte enthalten. Der Name darf nicht mit einem Punkt beginnen oder enden und einem Punkt darf kein weiterer Punkt folgen.
description: Kurze Anwendungsbeschreibung
path: Pfad zum Binärprogramm des Hosts für das native Messaging. Unter Linux und macOS muss der Pfad absolut sein. Unter Windows kann sie relativ zu dem Verzeichnis sein, das die Manifestdatei enthält. Der Hostprozess wird mit dem aktuellen Verzeichnis gestartet, das auf das Verzeichnis festgelegt ist, das die Host-Binärdatei enthält. Wenn dieser Parameter beispielsweise auf C:\Application\nm_host.exe gesetzt ist, wird er mit dem aktuellen Verzeichnis „C:\Application“ gestartet.
type: Typ der Schnittstelle, die für die Kommunikation mit dem Host für natives Messaging verwendet wird. Dieser Parameter hat einen möglichen Wert: stdio. Damit wird festgelegt, 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 sollten. allowed-origins-Werte dürfen keine Platzhalter enthalten.

Hoststandort 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. Das App-Installationsprogramm muss einen Registrierungsschlüssel (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) erstellen und als Standardwert dieses Schlüssels den vollständigen Pfad zur Manifestdatei festlegen. Verwenden Sie beispielsweise den 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 mithilfe 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 Nachrichtenhosts sucht, wird zuerst die 32-Bit-Registry und dann die 64-Bit-Registry abgefragt.

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

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 Nachrichtenhost in einem separaten Prozess und kommuniziert mit ihm über die Standardeingabe (stdin) und die Standardausgabe (stdout). Das gleiche Format wird verwendet, um Nachrichten in beide Richtungen zu senden. Jede Nachricht wird im JSON-Format mit UTF-8 codiert und erhält eine 32-Bit-Nachrichtenlänge in nativer Bytereihenfolge. Die maximale Größe einer einzelnen Nachricht vom nativen Nachrichtenhost beträgt 1 MB. Dies dient hauptsächlich dazu, Chrome vor fehlerhaften nativen Anwendungen zu schützen. Die maximale Größe der an den nativen Nachrichtenhost gesendeten Nachricht beträgt 4 GB.

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

Unter Windows wird dem nativen Nachrichtenhost auch ein Befehlszeilenargument mit einem Handle an das aufrufende native Chrome-Fenster übergeben: --parent-window=<decimal handle value>. Dadurch kann der native Nachrichtenhost native UI-Fenster erstellen, die korrekt übergeordnet sind. Dieser Wert ist 0, wenn der aufrufende Kontext ein Service Worker ist.

Wenn mit runtime.connectNative() ein Messaging-Port erstellt wird, startet Chrome den nativen Messaging-Hostprozess und läuft weiter, bis der Port gelöscht wird. Wenn dagegen eine Nachricht mit runtime.sendNativeMessage() gesendet wird, ohne einen Messaging-Port zu erstellen, 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 leitet sie an den Antwort-Callback weiter, der beim Aufruf von runtime.sendNativeMessage() angegeben wird. Alle anderen Nachrichten, die in diesem Fall vom nativen Nachrichtenhost generiert wurden, werden ignoriert.

Verbindung zu einer nativen Anwendung herstellen

Das Senden und Empfangen von Nachrichten an und von einer nativen Anwendung ähnelt sehr der erweiterungsübergreifenden Nachrichtenfunktion. 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 Erweiterungen deklariert werden.

Diese Methoden sind nicht in Content-Skripts, sondern nur auf den Seiten Ihrer Erweiterung und im Service Worker verfügbar. Wenn Sie von einem Inhaltsskript mit der nativen Anwendung kommunizieren möchten, senden Sie die Nachricht an den 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, Nachrichten von diesem Port überwacht und eine ausgehende Nachricht sendet:

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. Beispiel:

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

Fehler beim nativen Messaging beheben

Wenn bestimmte native Messaging-Fehler auftreten, wird die Ausgabe in das Fehlerprotokoll von Chrome geschrieben. Dies gilt auch, wenn der native Messaging-Host nicht gestartet wird, in stderr schreibt oder gegen das Kommunikationsprotokoll verstößt. Unter Linux und macOS können Sie auf dieses Log zugreifen, indem Sie Chrome über die Befehlszeile starten und die Ausgabe im Terminal beobachten. Verwenden Sie unter Windows --enable-logging wie unter Protokollierung aktivieren erläutert.

Im Folgenden finden Sie einige häufige Fehler und Tipps zu deren Behebung:

Der Host für natives Messaging konnte nicht gestartet werden.

Prüfen Sie, ob Sie ausreichende Berechtigungen zum Ausführen der Datei mit dem nativen Messaging-Host haben.

Ungültiger Hostname für natives Messaging angegeben.

Prüfen Sie, ob der Name ungültige Zeichen enthält. Es sind nur kleingeschriebene alphanumerische Zeichen, 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 Pipe zum nativen Nachrichtenhost wurde unterbrochen, bevor die Nachricht von Chrome gelesen wurde. Dieser Vorgang wird wahrscheinlich von Ihrem nativen Nachrichtenhost initiiert.

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

Folgende Voraussetzungen müssen erfüllt sein:

Ist der Name in der Erweiterung und in der Manifestdatei richtig geschrieben?
Befindet sich das Manifest im richtigen Verzeichnis und mit dem richtigen Namen? Informationen zu den erwarteten Formaten finden Sie unter Hoststandort für natives Messaging.
Hat die Manifest-Datei das richtige Format? Sind insbesondere die JSON-Daten gültig und korrekt 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 für den nativen Messaging-Host 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 Host für native Nachrichten dokumentiert.

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 Nachrichtenhost.

Dies weist auf eine falsche Implementierung des Kommunikationsprotokolls im nativen Messaging-Host hin.

Achten Sie darauf, dass die gesamte Ausgabe in stdout dem nativen Messaging-Protokoll entspricht. Wenn Sie zu Fehlerbehebungszwecken einige Daten ausgeben möchten, schreiben Sie in stderr.
Achten Sie darauf, dass die 32-Bit-Nachrichtenlänge im nativen Ganzzahlformat der Plattform angegeben ist (Little-Endian/Big-Endian).
Die Nachrichtenlänge darf 1.024 × 1.024 nicht überschreiten.
Die Nachrichtengröße muss der Anzahl von Byte in der Nachricht entsprechen. Diese 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 eingestellt sein. Standardmäßig ist der E/A-Modus O_TEXT, wodurch das Nachrichtenformat beschädigt wird, da Zeilenumbrüche (\n = 0A) durch Zeilenende im Windows-Stil (\r\n = 0D 0A) ersetzt werden. Der E/A-Modus kann mit __setmode festgelegt werden.