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:

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)
  • W rejestrze systemu Windows nie znaleziono hosta natywnego przesyłania komunikatów. Sprawdź za pomocą: regedit czy klucz został rzeczywiście utworzony i czy pasuje do wymaganego formatu zgodnie z dokumentacją natywną lokalizacja hosta wiadomości.
• 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.