Wiadomości natywne

Rozszerzenia i aplikacje mogą wymieniać wiadomości z natywnymi aplikacjami przy użyciu interfejsu API podobnego do inne interfejsy API do przekazywania wiadomości. Aplikacje natywne, które obsługują tę funkcję, muszą zarejestrować parametr host natywnego przesyłania komunikatów, który wie, jak komunikować się z rozszerzeniem. Chrome uruchamia hosta za w oddzielnym procesie i komunikuje się z nim za pomocą standardowych strumieni wejściowych i wyjściowych.

Host natywnego przesyłania komunikatów

Aby zarejestrować hosta natywnego przesyłania komunikatów, aplikacja musi zainstalować plik manifestu, który definiuje konfigurację hosta natywnego przesyłania komunikatów. Poniżej znajduje się przykładowy plik manifestu:

{
  "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 natywnego przesyłania wiadomości musi być prawidłowym plikiem JSON i zawierać te pola:

NazwaOpis
nameNazwa hosta natywnego przesyłania komunikatów. Klienty przekazują ten ciąg znaków do runtime.connectNative lub runtime.sendNativeMessage. Ta nazwa może zawierać wyłącznie 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ć inna kropka.
descriptionKrótki opis aplikacji.
pathŚcieżka do pliku binarnego hosta natywnego przesyłania komunikatów. W systemach Linux i OS X ścieżka musi być bezwzględna. W systemie Windows może to być katalog, w którym znajduje się plik manifestu. Proces hosta rozpoczyna się, gdy bieżący katalog jest ustawiony na katalog zawierający plik binarny hosta. Jeśli np. parametr ma wartość C:\Application\nm_host.exe, rozpocznie się od bieżącego katalogu C:\Application\.
typeTyp interfejsu używanego do komunikacji z hostem natywnego przesyłania komunikatów. Obecnie ten parametr może mieć tylko jedną wartość: stdio. Oznacza to, że Chrome powinien używać interfejsów stdin i stdout do komunikacji z hostem.
allowed_originsLista rozszerzeń, które powinny mieć dostęp do hosta natywnego przesyłania komunikatów. Symbole wieloznaczne, takie jak chrome-extension://*/*, są niedozwolone.

Lokalizacja hosta natywnego przesyłania komunikatów

Lokalizacja pliku manifestu zależy od platformy.

W systemie Windows plik manifestu może się znajdować w dowolnym miejscu w systemie plików. Aplikacja instalator 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 ustaw domyślną wartość tego klucza na pełną ścieżkę do pliku manifestu. Na przykład użycie parametru to polecenie:

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 za pomocą 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 natywnego przesyłania komunikatów, najpierw wysyła zapytanie do 32-bitowego rejestru, a dopiero potem do 64-bitowego rejestru rejestr.

W systemach OS X i Linux lokalizacja pliku manifestu natywnego hosta wiadomości różni się w zależności od przeglądarki (Google Chrome lub Chromium). Stosowane w całym systemie hosty natywnego przesyłania komunikatów są sprawdzane , a hosty natywnego przesyłania komunikatów na poziomie użytkownika są wyszukiwane w podkatalogu katalogu profili użytkownika o nazwie NativeMessagingHosts.

  • OS X (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
  • OS X (zależnie od użytkownika, ścieżka 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 (cały system)
    • 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 (zależna od użytkownika, ścieżka domyślna)
    • 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 natywnego przesyłania komunikatów w osobnym procesie i komunikuje się z nim za pomocą standardowy strumień wejścia (stdin) i wyjście standardowy (stdout). Ten sam format jest używany do wysyłania wiadomości w obu kierunkach: każda wiadomość jest zserializowana przy użyciu kodu JSON w formacie UTF-8 i jest poprzedzona 32-bitowym Długość wiadomości w natywnej kolejności bajtów. Maksymalny rozmiar pojedynczej wiadomości z wiadomości natywnej. rozmiar hosta to 1 MB, głównie w celu ochrony Chrome przed nieprawidłowymi aplikacjami natywnymi. Maksymalny rozmiar pola rozmiar wiadomości wysyłanej do hosta natywnego przesyłania komunikatów ma rozmiar 4 GB.

Pierwszym argumentem hosta natywnego przesyłania komunikatów jest pochodzenie elementu wywołującego, zwykle chrome-extension://[ID of allowed extension] Dzięki temu hosty natywnego przesyłania komunikatów mogą identyfikować źródła wiadomości, jeśli w kluczu allowed_origins w kluczu allowed_origins jest określone wiele rozszerzeń plik manifestu natywnego przesyłania komunikatów. Ostrzeżenie: w systemie Windows w Chrome 54 i starszych wersjach źródło było przekazywane jako drugi parametr. zamiast pierwszego parametru.

Gdy port przesyłania zostanie utworzony przy użyciu polecenia runtime.connectNative, Chrome uruchamia obsługę natywnego przesyłania komunikatów procesem hosta i działa, dopóki port nie zostanie zniszczony. Z drugiej strony, gdy wiadomość jest wysłane za pomocą runtime.sendNativeMessage (bez tworzenia portu przesyłania), Chrome uruchamia nowy proces hosta natywnego przesyłania komunikatów w przypadku każdej wiadomości. W takim przypadku pierwsza wiadomość wygenerowana przez gospodarza jest obsługiwany jako odpowiedź na pierwotne żądanie, tj.Chrome przekaże go do odpowiedzi. wywołanie zwrotne określone podczas wywoływania funkcji runtime.sendNativeMessage. Wszystkie inne wiadomości wygenerowane przez hosta natywnego przesyłania komunikatów jest ignorowany.

W systemie Windows host natywnego przesyłania komunikatów również jest przekazywany jako argument wiersza poleceń z uchwytem do wywołując natywne okno Chrome: --parent-window=<decimal handle value>. Dzięki temu reklamy natywne host przesyłania wiadomości tworzy natywne okna interfejsu, które są określone jako nadrzędne. Pamiętaj, że ta wartość wynosi Wartość 0, jeśli kontekstem wywołania jest strona skryptu w tle.

Nawiązywanie połączenia z aplikacją natywną

Wysyłanie i odbieranie wiadomości do i z aplikacji natywnej jest bardzo podobne do funkcji na potrzeby różnych rozszerzeń i wysyłanie wiadomości. Główna różnica polega na tym, że zamiastruntime.connectNative Zamiast nich używane są runtime.connect i runtime.sendNativeMessage runtime.sendMessage. Tych metod można używać tylko wtedy, gdy opcja „nativeMessaging” są zadeklarowane w tagu manifestu.

Poniższy przykład pokazuje obiekt runtime.Port połączony z hostem natywnego przesyłania komunikatów. com.my_company.my_application, zaczyna nasłuchiwać wiadomości z tego portu i wysyła jedno połączenie wychodzące wiadomość:

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

Za pomocą polecenia runtime.sendNativeMessage można wysłać wiadomość do natywnej aplikacji bez konieczności tworzenia port, np.:

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

Debugowanie natywnego przesyłania komunikatów

Gdy host natywnego przesyłania wiadomości nie uruchomi się, zapisze dane w usłudze stderr lub gdy narusza protokołu komunikacyjnego, dane wyjściowe są zapisywane w dzienniku błędów Chrome. W systemach Linux i OS X ten dziennik można łatwo otworzyć, uruchamiając Chrome z wiersza poleceń i obserwując wynik złącze. W systemie Windows należy używać --enable-logging zgodnie z opisem w sekcji Jak włączyć logowanie.

Oto kilka błędów i wskazówek, które pomogą Ci rozwiązać problemy:

  • Nie udało się uruchomić hosta natywnego przesyłania komunikatów.
    • Sprawdź, czy masz wystarczające uprawnienia do wykonania pliku.
  • Podano nieprawidłową nazwę hosta natywnego przesyłania komunikatów.
    • Sprawdź, czy nazwa zawiera nieprawidłowe znaki. tylko małe znaki alfanumeryczne, znaki podkreślenia i kropki są dozwolone. Nazwa nie może zaczynać się ani kończyć kropką, a kropka nie może po nim kolejną kropkę.
  • Host natywny został zamknięty.
    • Rura do hosta natywnego przesyłania wiadomości została uszkodzona, zanim wiadomość została odczytana przez Chrome. To najbardziej prawdopodobnie zainicjowane przez hosta natywnego przesyłania komunikatów.
  • Nie znaleziono określonego hosta natywnego przesyłania komunikatów.
    • Czy nazwa jest poprawnie napisana w rozszerzeniu i pliku manifestu?
    • Czy plik manifestu znajduje się w odpowiednim katalogu i ma prawidłową nazwę? Zobacz hosta natywnego przesyłania komunikatów lokalizacji w przypadku oczekiwanych formatów.
    • Czy plik manifestu ma prawidłowy format? Przede wszystkim sprawdź, czy składnia JSON jest poprawna i czy które są zgodne z definicją pliku manifestu natywnego przesyłania wiadomości?
    • Czy plik określony w path istnieje? W Windows ścieżki mogą być względne, ale w OS X i Linux ścieżki muszą być bezwzględne.
  • Nazwa hosta natywnego przesyłania komunikatów nie jest zarejestrowana. (tylko system Windows)
  • Dostęp do określonego hosta natywnego przesyłania komunikatów jest zabroniony.
    • Czy źródło rozszerzenia jest podane w tym kraju: allowed_origins?
  • Podczas komunikacji z hostem natywnego przesyłania komunikatów występuje błąd.
    • To bardzo częsty błąd, który wskazuje nieprawidłową implementację protokołu komunikacyjnego na hoście natywnego przesyłania komunikatów.
    • Wszystkie dane wyjściowe w stdout muszą być zgodne z protokołem natywnego przesyłania komunikatów. Jeśli chcesz aby wydrukować dane na potrzeby debugowania, zapisz je w usłudze stderr.
    • Upewnij się, że 32-bitowa długość wiadomości jest zgodna z natywnym formatem liczby całkowitej 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 wiadomości. Może się ono różnić od „długość” ciągu, ponieważ znaki mogą być reprezentowane przez kilka bajtów.
    • Tylko w systemie Windows: upewnij się, że tryb wejścia-wyjścia programu jest ustawiony na O_BINARY. Domyślnie tryb to O_TEXT, co powoduje uszkodzenie formatu wiadomości przez zamianę wierszy (\n = 0A) na Końcówki linii w stylu Windows (\r\n = 0D 0A). Tryb wejścia-wyjścia można ustawić za pomocą __setmode.