Messagerie native

Les extensions et les applications peuvent échanger des messages avec les applications natives à l'aide d'une API semblable à les autres API de transmission de messages. Les applications natives qui prennent en charge cette fonctionnalité doivent enregistrer un hôte de messagerie native qui sait comment communiquer avec l'extension. Chrome démarre l'hôte dans un processus distinct et communique avec lui en utilisant des flux d'entrée et de sortie standards.

Hôte de messagerie native

Pour enregistrer un hôte de messagerie native, l'application doit installer un fichier manifeste définit la configuration de l'hôte de messagerie native. Voici un exemple de fichier manifeste:

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

Le fichier manifeste de l'hôte de messagerie native doit être au format JSON valide et contenir les champs suivants:

NomDescription
nameNom de l'hôte de messagerie native. Les clients transmettent cette chaîne à runtime.connectNative ou à runtime.sendNativeMessage. Ce nom ne peut contenir que des caractères alphanumériques en minuscules, des traits de soulignement et des points. Le nom ne peut pas commencer ni se terminer par un point, et un point ne peut pas être suivi d'un autre point.
descriptionBrève description de l'application.
pathChemin d'accès au binaire de l'hôte de messagerie native. Sous Linux et OSX, le chemin d'accès doit être absolu. Sous Windows, il peut être relatif au répertoire dans lequel se trouve le fichier manifeste. Le processus hôte démarre avec le répertoire actuel défini sur le répertoire qui contient le binaire hôte. Par exemple, si ce paramètre est défini sur C:\Application\nm_host.exe, il sera démarré avec le répertoire actuel, C:\Application\.
typeType d'interface utilisé pour communiquer avec l'hôte de messagerie native. Actuellement, il n'existe qu'une seule valeur possible pour ce paramètre: stdio. Elle indique que Chrome doit utiliser stdin et stdout pour communiquer avec l'hôte.
allowed_originsListe des extensions qui doivent avoir accès à l'hôte de messagerie native. Les caractères génériques tels que chrome-extension://*/* ne sont pas autorisés.

Emplacement de l'hôte de messagerie native

L'emplacement du fichier manifeste dépend de la plate-forme.

Sous Windows, le fichier manifeste se trouve n'importe où dans le système de fichiers. L'application le programme d'installation doit créer une clé de registre HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ ou HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ définir la valeur par défaut de cette clé sur le chemin d’accès complet au fichier manifeste. Par exemple, si vous utilisez la commande suivante:

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

ou à l'aide du fichier .reg suivant:

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

Lorsque Chrome recherche des hôtes de messagerie native, le registre 32 bits est d'abord interrogé, puis le registre 64 bits registre.

Sous OS X et Linux, l'emplacement du fichier manifeste de l'hôte de messagerie native varie en fonction (Google Chrome ou Chromium). Les hôtes de messagerie native à l'échelle du système sont recherchés sur un alors que les hôtes de messagerie native au niveau de l'utilisateur sont recherchés dans un sous-répertoire répertoire de profils utilisateur appelé NativeMessagingHosts.

  • OS X (à l'échelle du système) <ph type="x-smartling-placeholder">
      </ph>
    • 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 (propre à l'utilisateur, chemin d'accès par défaut) <ph type="x-smartling-placeholder">
      </ph>
    • 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 (à l'échelle du système) <ph type="x-smartling-placeholder">
      </ph>
    • 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 (propre à l'utilisateur, chemin d'accès default) <ph type="x-smartling-placeholder">
      </ph>
    • Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
    • Chromium: ~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json

Protocole de messagerie natif

Chrome démarre chaque hôte de messagerie native dans un processus distinct et communique avec lui via entrée standard (stdin) et sortie standard (stdout). Le même format est utilisé pour envoyer des messages dans dans les deux sens: chaque message est sérialisé au format JSON, encodé en UTF-8 et précédé de caractères 32 bits la longueur du message dans l'ordre natif des octets. Taille maximale d'un seul message de la messagerie native est de 1 Mo, principalement pour protéger Chrome contre les applications natives inappropriées. La taille maximale du tag envoyé à l'hôte de messagerie native est de 4 Go.

Le premier argument de l'hôte de messagerie native est l'origine de l'appelant, généralement chrome-extension://[ID of allowed extension] Cela permet aux hôtes de messagerie native d'identifier la source du message lorsque plusieurs extensions sont spécifiées dans la clé allowed_origins du fichier manifeste de l'hôte de messagerie native. Avertissement: Dans Windows, dans Chrome 54 et versions antérieures, l'origine était transmise en tant que deuxième paramètre. au lieu du premier paramètre.

Lorsqu'un port de messagerie est créé à l'aide de runtime.connectNative, Chrome lance la messagerie native le processus hôte et le maintient en cours d’exécution jusqu’à ce que le port soit détruit. En revanche, lorsqu'un message est envoyé à l'aide de runtime.sendNativeMessage, sans créer de port de messagerie, Chrome lance un nouveau le processus hôte de la messagerie native pour chaque message. Dans ce cas, le premier message généré par l'hôte processus est traité comme une réponse à la requête initiale, c'est-à-dire que Chrome le transmet à la réponse spécifié lors de l'appel de runtime.sendNativeMessage. Tous les autres messages générés par l'hôte de messagerie native sont alors ignorés.

Sous Windows, l'hôte de messagerie native reçoit également un argument de ligne de commande avec un handle vers le Appel de la fenêtre native Chrome en cours: --parent-window=<decimal handle value>. Ainsi, le format natif l'hôte de messagerie créent des fenêtres d'UI natives dont la parenté est correcte. Notez que cette valeur sera 0 si le contexte appelant est une page de script en arrière-plan.

Se connecter à une application native

L'envoi et la réception de messages depuis et vers une application native sont très semblables à ceux des autres extensions. messagerie. La principale différence est que runtime.connectNative est utilisé à la place de runtime.connect et runtime.sendNativeMessage à la place de runtime.sendMessage. Vous ne pouvez utiliser ces méthodes que si la règle "nativeMessaging" l'autorisation est déclarée dans le fichier fichier manifeste.

L'exemple suivant permet de créer un objet runtime.Port connecté à l'hôte de messagerie native com.my_company.my_application, commence à écouter les messages de ce port et en envoie un message:

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

runtime.sendNativeMessage pour envoyer un message à une application native sans créer de message un port, par exemple :

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

Déboguer la messagerie native

Lorsque l'hôte de messagerie native ne démarre pas, écrit dans stderr ou lorsqu'il ne respecte pas le le résultat est écrit dans le journal d'erreurs de Chrome. Sous Linux et OS X, ce journal sont facilement accessibles en démarrant Chrome depuis la ligne de commande et en surveillant le résultat dans la du terminal. Sous Windows, utilisez --enable-logging comme expliqué dans la section Activer la journalisation.

Voici quelques erreurs et conseils pour résoudre les problèmes:

  • Échec du démarrage de l'hôte de messagerie native.
    • Vérifiez si vous disposez des autorisations nécessaires pour exécuter le fichier.
  • Le nom d'hôte de messagerie native spécifié n'est pas valide.
    • Vérifiez que le nom ne contient pas de caractères non valides. Seuls les caractères alphanumériques en minuscules, les traits de soulignement et les points sont autorisés. Un nom ne peut pas commencer ni se terminer par un point, et un point ne peut pas être suivi d'un autre point.
  • L'hôte natif s'est fermé.
    • Le canal vers l'hôte de messagerie native était interrompu avant la lecture du message par Chrome. Il s'agit de probablement initiée par votre hôte de messagerie native.
  • L'hôte de messagerie native spécifié est introuvable.
    • Le nom est-il correctement orthographié dans l'extension et dans le fichier manifeste ?
    • Le fichier manifeste est-il placé dans le bon répertoire et avec le bon nom ? Voir l'hôte de messagerie native emplacement pour les formats attendus.
    • Le format du fichier manifeste est-il correct ? En particulier, la syntaxe JSON est-elle correcte et correspondent à la définition d'un fichier manifeste d'hôte de messagerie native ?
    • Le fichier spécifié dans path existe-t-il ? Sous Windows, les chemins d'accès peuvent être relatifs, mais sous OS X et Linux, les chemins doivent être absolus.
  • Le nom d'hôte de l'hôte de messagerie native n'est pas enregistré. (Windows uniquement) <ph type="x-smartling-placeholder">
      </ph>
    • Impossible de trouver l'hôte de messagerie native dans le Registre Windows. Vérifier à l'aide de regedit si la clé a bien été créée et correspond au format requis tel qu'indiqué sur la page native emplacement de l'hôte de messagerie.
  • L'accès à l'hôte de messagerie native spécifié est interdit.
    • L'origine de l'extension est-elle indiquée dans allowed_origins ?
  • Erreur lors de la communication avec l'hôte de messagerie native.
    • Il s'agit d'une erreur très courante qui indique une mise en œuvre incorrecte du protocole de communication. de l'hôte de messagerie native.
    • Assurez-vous que tous les résultats dans stdout respectent le protocole de messagerie native. Si vous voulez Pour imprimer des données à des fins de débogage, écrivez dans stderr.
    • Assurez-vous que la longueur du message de 32 bits est dans le format d'entier natif de la plate-forme (little-endian / big-endian).
    • La longueur du message ne doit pas dépasser 1 024 x 1 024.
    • La taille du message doit être égale au nombre d'octets qu'il contient. Il peut être différent de "longueur" d'une chaîne, car les caractères peuvent être représentés par plusieurs octets.
    • Windows uniquement: assurez-vous que le mode E/S du programme est défini sur O_BINARY. Par défaut, les opérations d'E/S est O_TEXT, ce qui corrompt le format du message car les sauts de ligne (\n = 0A) sont remplacés par Fins de lignes de style Windows (\r\n = 0D 0A) Vous pouvez définir le mode E/S avec __setmode.