Ta strona została przetłumaczona przez Cloud Translation API.

Wiadomości natywne

Rozszerzenia mogą wymieniać wiadomości z aplikacjami natywnymi za pomocą interfejsu API podobnego do innych interfejsów API do przekazywania wiadomości. Aplikacje natywne obsługujące tę funkcję muszą zarejestrować hosta natywnych aplikacji do obsługi wiadomości, który może komunikować się z rozszerzeniem. Chrome uruchamia hosta w osobnym procesie i komunikuje się z nim za pomocą standardowych strumieni wejściowych i wyjściowych.

Host natywnego przesyłania komunikatów

Aby zarejestrować hosta wiadomości natywnych, aplikacja musi zapisać plik, który definiuje konfigurację hosta wiadomości natywnych.

Oto przykład pliku:

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

Plik manifestu hosta wiadomości natywnych musi być prawidłowym plikiem JSON i zawierać te pola:

name: Nazwa hosta natywnej aplikacji do obsługi wiadomości. Klienci przekazują ten ciąg do runtime.connectNative() lub runtime.sendNativeMessage(). Nazwa może zawierać tylko małe znaki alfanumeryczne, podkreślenia i kropki. Nazwa nie może zaczynać się ani kończyć kropką, a po kropce nie może następować kolejna kropka.
description: Krótki opis aplikacji.
path: Ścieżka do pliku binarnego hosta natywnego przesyłania komunikatów. W systemach Linux i macOS ścieżka musi być bezwzględna. W systemie Windows może być względna w stosunku do katalogu zawierającego plik manifestu. Proces hosta jest uruchamiany z bieżącym katalogiem ustawionym na katalog zawierający plik binarny hosta. Jeśli np. ten parametr ma wartość C:\Application\nm_host.exe, zostanie uruchomiony w bieżącym katalogu „C:\Application”.
type: Typ interfejsu używanego do komunikacji z hostem wiadomości natywnych. Ten parametr ma jedną możliwą wartość: stdio. Oznacza to, że Chrome powinien używać protokołów stdin i stdout do komunikacji z hostem.
allowed_origins: Lista rozszerzeń, które powinny mieć dostęp do hosta natywnej aplikacji do obsługi wiadomości. Wartości allowed-origins nie mogą zawierać symboli wieloznacznych.

Lokalizacja hosta natywnego przesyłania komunikatów

Lokalizacja pliku manifestu zależy od platformy.

W Windows plik manifestu może znajdować się w dowolnym miejscu w systemie plików. Instalator aplikacji musi utworzyć klucz rejestru, HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application lub HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application, i ustawić domyślną wartość tego klucza na pełną ścieżkę do pliku manifestu. Na przykład używając tego polecenia:

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

lub użyć tego pliku .reg:

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

Gdy Chrome szuka hostów wiadomości natywnych, najpierw wysyła zapytanie do rejestru 32-bitowego, a potem do rejestru 64-bitowego.

W systemach macOS i Linux lokalizacja pliku manifestu hosta wiadomości natywnych różni się w zależności od przeglądarki (Google Chrome lub Chromium). Hosty natywnych aplikacji do obsługi wiadomości na poziomie systemu są wyszukiwane w ustalonym miejscu, a hosty natywnych aplikacji do obsługi wiadomości na poziomie użytkownika są wyszukiwane w NativeMessagingHosts/ podkatalogu katalogu profilu użytkownika.

macOS (cały 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 (ścieżka specyficzna dla użytkownika, domyślna): 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 (w całym systemie): 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 (ścieżka domyślna, specyficzna dla użytkownika): Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json; Chromium: ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

Protokół natywnego przesyłania komunikatów

Chrome uruchamia każdy host wiadomości natywnych w osobnym procesie i komunikuje się z nim za pomocą standardowego wejścia (stdin) i standardowego wyjścia (stdout). Ten sam format jest używany do wysyłania wiadomości w obu kierunkach. Każda wiadomość jest serializowana za pomocą JSON, kodowana w UTF-8 i poprzedzona 32-bitową długością wiadomości w natywnej kolejności bajtów. Maksymalny rozmiar pojedynczej wiadomości z hosta wiadomości natywnych to 1 MB. Ma to na celu ochronę Chrome przed nieprawidłowo działającymi aplikacjami natywnymi. Maksymalny rozmiar wiadomości wysyłanej do hosta wiadomości natywnych to 64 MiB.

Pierwszym argumentem hosta wiadomości natywnych jest pochodzenie wywołującego, zwyklechrome-extension://[ID of allowed extension]. Umożliwia to hostom natywnych aplikacji do obsługi wiadomości identyfikowanie źródła wiadomości, gdy w allowed_origins w pliku manifestu hosta natywnej aplikacji do obsługi wiadomości określono wiele rozszerzeń.

W systemie Windows do hosta natywnego przesyłania komunikatów przekazywany jest też argument wiersza poleceń z uchwytem do wywołującego okna natywnego Chrome: --parent-window=<decimal handle value>. Dzięki temu host natywnego przesyłania komunikatów może tworzyć okna natywnego interfejsu, które są prawidłowo powiązane z elementem nadrzędnym. Pamiętaj, że ta wartość będzie wynosić 0, jeśli kontekstem wywołania jest service worker.

Gdy port do przesyłania wiadomości zostanie utworzony za pomocą runtime.connectNative(), Chrome uruchamia proces hosta przesyłania wiadomości w formacie natywnym i utrzymuje go w ruchu, dopóki port nie zostanie zniszczony. Z drugiej strony, gdy wiadomość jest wysyłana za pomocą runtime.sendNativeMessage() bez tworzenia portu do przesyłania wiadomości, Chrome uruchamia nowy proces hosta do przesyłania wiadomości natywnych dla każdej wiadomości. W takim przypadku pierwsza wiadomość wygenerowana przez proces hosta jest traktowana jako odpowiedź na pierwotne żądanie, a Chrome przekazuje ją do funkcji zwrotnej odpowiedzi określonej podczas wywoływania funkcji runtime.sendNativeMessage(). W takim przypadku wszystkie inne wiadomości wygenerowane przez hosta natywnej aplikacji do obsługi wiadomości są ignorowane.

Łączenie się z aplikacją natywną

Wysyłanie i odbieranie wiadomości do i z aplikacji natywnej jest bardzo podobne do przesyłania wiadomości między rozszerzeniami. Główna różnica polega na tym, że zamiast runtime.connect() używa się operatora runtime.connectNative(), a zamiast runtime.sendMessage() – operatora runtime.sendNativeMessage().

Aby używać tych metod, musisz zadeklarować uprawnienie „nativeMessaging” w pliku manifestu rozszerzenia.

Te metody nie są dostępne w skryptach treści, tylko na stronach rozszerzenia i w jego procesie roboczym usługi. Jeśli chcesz komunikować się ze skryptu treści z aplikacją natywną, wyślij wiadomość do procesu roboczego usługi, aby przekazać ją do aplikacji natywnej.

W tym przykładzie tworzony jest obiekt runtime.Port połączony z hostem natywnego przesyłania wiadomościcom.my_company.my_application, który zaczyna nasłuchiwać wiadomości z tego portu i wysyła jedną wiadomość wychodzącą:

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

Użyj runtime.sendNativeMessage, aby wysłać wiadomość do aplikacji natywnej bez tworzenia portu, np.:

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

Debugowanie natywnego przesyłania komunikatów

W przypadku niektórych błędów związanych z komunikacją natywną dane wyjściowe są zapisywane w dzienniku błędów Chrome. Obejmuje to sytuacje, w których host natywnych aplikacji do obsługi wiadomości nie uruchamia się, zapisuje dane w stderr lub narusza protokół komunikacyjny. W systemach Linux i macOS możesz uzyskać dostęp do tego dziennika, uruchamiając Chrome z wiersza poleceń i obserwując jego dane wyjściowe w terminalu. W systemie Windows użyj --enable-logging zgodnie z instrukcjami w artykule Jak włączyć logowanie.

Oto kilka typowych błędów i wskazówki dotyczące ich rozwiązywania:

Nie udało się uruchomić hosta wiadomości natywnych.

Sprawdź, czy masz wystarczające uprawnienia do uruchomienia pliku hosta natywnej aplikacji do obsługi wiadomości.

Podano nieprawidłową nazwę hosta przesyłania wiadomości natywnych.

Sprawdź, czy nazwa zawiera nieprawidłowe znaki. Dozwolone są tylko małe znaki alfanumeryczne, podkreślenia i kropki. Nazwa nie może zaczynać się ani kończyć kropką, a po kropce nie może występować kolejna kropka.

Host natywny został zamknięty.

Potok do hosta natywnej aplikacji do obsługi wiadomości został przerwany, zanim Chrome odczytał wiadomość. Najprawdopodobniej jest to inicjowane przez hosta natywnych aplikacji do obsługi wiadomości.

Nie udało się znaleźć podanego hosta natywnych aplikacji do obsługi wiadomości.

Sprawdź, czy:

Czy nazwa jest poprawnie zapisana w rozszerzeniu i pliku manifestu?
Czy plik manifestu znajduje się w odpowiednim katalogu i ma prawidłową nazwę? Oczekiwane formaty znajdziesz w sekcji native messaging host location.
Czy plik manifestu ma prawidłowy format? W szczególności, czy plik JSON jest prawidłowy i dobrze sformatowany oraz czy wartości są zgodne z definicją pliku manifestu hosta wiadomości natywnych?
Czy plik określony w parametrze path istnieje? W systemie Windows ścieżki mogą być względne, ale w systemach macOS i Linux muszą być bezwzględne.

Host natywnej aplikacji do obsługi wiadomości nazwa hosta nie jest zarejestrowany. (tylko Windows)

Nie znaleziono hosta natywnej aplikacji do obsługi wiadomości w rejestrze systemu Windows. Sprawdź, czy klucz został utworzony i czy jest zgodny z wymaganym formatem, zgodnie z dokumentacją w sekcji Lokalizacja hosta wiadomości natywnych.regedit

Dostęp do określonego hosta natywnych aplikacji do obsługi wiadomości jest zabroniony.

Czy punkt początkowy rozszerzenia jest wymieniony w allowed_origins?

Błąd podczas komunikacji z hostem wiadomości natywnych.

Oznacza to nieprawidłową implementację protokołu komunikacji w hoście natywnych aplikacji do obsługi wiadomości.

Upewnij się, że wszystkie dane wyjściowe w stdout są zgodne z protokołem natywnych aplikacji do obsługi wiadomości. Jeśli chcesz wydrukować niektóre dane na potrzeby debugowania, napisz na adres stderr.
Sprawdź, czy 32-bitowa długość wiadomości jest w natywnym formacie liczb całkowitych platformy (little-endian/big-endian).
Długość wiadomości nie może przekraczać 1024*1024.
Rozmiar wiadomości musi być równy liczbie bajtów w wiadomości. Może się to różnić od „długości” ciągu znaków, ponieważ znaki mogą być reprezentowane przez wiele bajtów.
Tylko Windows: upewnij się, że tryb wejścia/wyjścia programu jest ustawiony na O_BINARY. Domyślnie tryb wejścia/wyjścia to O_TEXT, co powoduje uszkodzenie formatu wiadomości, ponieważ znaki końca wiersza (\n = 0A) są zastępowane znakami końca wiersza w stylu Windows (\r\n = 0D 0A). Tryb wejścia/wyjścia można ustawić za pomocą polecenia __setmode.

Wiadomości natywne Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.