Messagerie native

Article
01/19/2024

Pour communiquer avec une application Win32 native installée sur l’appareil d’un utilisateur, une extension utilise une API similaire aux autres API de passage de message . L’hôte d’application natif envoie et reçoit des messages avec des extensions à l’aide d’une entrée et d’une sortie standard standard.

Les extensions qui utilisent la messagerie native sont installées dans Microsoft Edge comme n’importe quelle autre extension. Toutefois, les applications natives ne sont pas installées ou gérées par Microsoft Edge.

Pour acquérir l’extension et l’hôte d’application natif, il existe deux modèles de distribution différents :

Empaquetez votre extension et l’hôte ensemble. Lorsqu’un utilisateur installe le package, l’extension et l’hôte sont installés.
Vous pouvez également installer votre extension à l’aide du site web des modules complémentaires Microsoft Edge, et votre extension invite les utilisateurs à installer l’hôte.

Pour créer votre extension pour envoyer et recevoir des messages avec des hôtes d’application natifs, procédez comme suit.

Étape 1 : Ajouter des autorisations au manifeste d’extension

Ajoutez l’autorisation nativeMessaging au fichier manifest.json de l’extension.

Il s’agit du fichier manifeste d’extension, et non du fichier manifeste de l’hôte de messagerie native, qui est abordé dans les sections ultérieures.

Voici un exemple de fichier manifest.json :

Manifeste V3
Manifeste V2

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 3,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 2,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

Étape 2 : Créer votre fichier manifeste d’hôte de messagerie natif

Les applications natives doivent fournir un fichier manifeste d’hôte de messagerie natif. Un fichier manifeste d’hôte de messagerie native contient les informations suivantes :

Chemin d’accès au runtime de l’hôte de messagerie native.
Méthode de communication avec l’extension.
Liste des extensions autorisées avec lesquelles il communique.

Le navigateur lit et valide le manifeste de l’hôte de messagerie native. Le navigateur n’installe ni ne gère le fichier manifeste de l’hôte de messagerie native.

Le fichier manifeste de l’hôte de messagerie native est distinct du fichier Manifeste V3 ou V2 qui fait partie de l’extension Microsoft Edge.

Exemple de fichier manifeste d’hôte de messagerie native :

{
    "name": "com.my_company.my_app",
    "description": "My App",
    "path": "C:\\Program Files\\My App\\chrome_native_messaging_host.exe",
    "type": "stdio",
    "allowed_origins": [
        "chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"
    ]
}

Le fichier manifeste de l’hôte de messagerie native doit être un fichier JSON valide contenant les clés suivantes :

Clé	Détails
`name`	Spécifie le nom de l’hôte de messagerie native. Les clients passent la chaîne à `runtime.connectNative` ou `runtime.sendNativeMessage`. La valeur doit contenir uniquement des caractères alphanumériques minuscules, des traits de soulignement et des points. La valeur ne doit pas commencer ou se terminer par un point (point), et un point ne doit pas être suivi d’un autre point.
`description`	Décrit l’application.
`path`	Spécifie le chemin d’accès au binaire de l’hôte de messagerie native. Sur les appareils Windows, vous pouvez utiliser des chemins d’accès relatifs au répertoire qui contient le fichier manifeste de l’hôte de messagerie native. Sur macOS et Linux, le chemin doit être absolu. Le processus hôte commence par le répertoire actif défini sur le répertoire qui contient le fichier binaire hôte. Par exemple (Windows), si le paramètre est défini sur `C:\App\nm_host.exe`, le fichier binaire est démarré à l’aide du répertoire actif (`C:\App\`).
`type`	Spécifie le type de l’interface utilisée pour communiquer avec l’hôte de messagerie native. La valeur indique à Microsoft Edge d’utiliser `stdin` et `stdout` de communiquer avec l’hôte. La seule valeur acceptable est `stdio`.
`allowed_origins`	Spécifie la liste des extensions qui ont accès à l’hôte de messagerie native. Pour activer votre application afin d’identifier et de communiquer avec une extension, dans le fichier manifeste de votre hôte de messagerie native, définissez la valeur suivante : `"allowed_origins": ["chrome-extension://{microsoft_catalog_extension_id}"]`

Chargez une version test de votre extension pour tester la messagerie native avec l’hôte. Pour charger une version test de votre extension pendant le développement et récupérer microsoft_catalog_extension_id:

Accédez à edge://extensions, puis activez le bouton bascule mode développeur .
Sélectionnez Charger décompressé, puis sélectionnez votre package d’extension à charger de manière indépendante.
Cliquez sur OK.
Accédez à la edge://extensions page et vérifiez que votre extension est répertoriée.
Copiez la clé de microsoft_catalog_extension_id (ID) à partir de la liste des extensions sur la page.

Lorsque vous êtes prêt à distribuer votre extension aux utilisateurs, publiez-la sur le site web des modules complémentaires Microsoft Edge. L’ID d’extension de l’extension publiée peut différer de l’ID utilisé lors du chargement indépendant de votre extension. Si l’ID a changé, mettez à jour allowed_origins dans le fichier manifeste de l’hôte de messagerie native avec l’ID de votre extension publiée.

Étape 3 : Copier le fichier manifeste de l’hôte de messagerie native sur votre système

La dernière étape consiste à copier le fichier manifeste de l’hôte de messagerie native sur votre ordinateur et à vérifier que ce fichier manifeste est correctement configuré. Pour vous assurer que votre fichier manifeste d’hôte de messagerie natif est placé à l’emplacement attendu, procédez comme suit. L’emplacement varie selon la plateforme.

Sur Linux et macOS :

Veillez à fournir des autorisations de lecture sur le fichier manifeste de l’hôte de messagerie native.
Veillez à fournir des autorisations d’exécution sur le runtime hôte.

Le fichier manifeste de l’hôte de messagerie native peut se trouver n’importe où dans le système de fichiers. Le programme d’installation de l’application doit créer une clé de Registre et définir la valeur par défaut de la clé sur le chemin d’accès complet du fichier manifeste de l’hôte de messagerie native.

Les emplacements suivants sont des exemples de clés de Registre :

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

Pour ajouter une clé de Registre au répertoire avec la clé de manifeste, effectuez l’une des opérations suivantes :

Exécutez une commande dans l’invite de commandes :

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

Vous pouvez également créer un .reg fichier et l’exécuter comme suit :
1. Copiez la commande suivante dans un .reg fichier :
```
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app]
@="C:\\path\\to\\nmh-manifest.json"
```
2. Exécutez le .reg fichier. Si vous exécutez votre fichier créé .reg dans le cadre d’un script de traitement par lots, veillez à l’exécuter à l’aide d’une invite de commandes administrateur.

Microsoft Edge interroge la HKEY_CURRENT_USER clé racine, suivie de HKEY_LOCAL_MACHINE. Dans les deux clés, le registre 32 bits fait d’abord l’objet d’une recherche, puis le registre 64 bits est recherché pour identifier les hôtes de messagerie natifs. La clé de Registre spécifie l’emplacement du fichier manifeste de l’hôte de messagerie native.

Si les entrées de Registre pour Microsoft Edge n’ont pas l’emplacement du fichier manifeste de l’hôte de messagerie native, les emplacements du Registre Chromium et Chrome sont utilisés comme options de secours.

Si Microsoft Edge trouve la clé de Registre à l’un des emplacements précédemment répertoriés, il n’interroge pas les emplacements répertoriés dans l’extrait de code suivant.

L’ordre de recherche pour les emplacements du Registre est le suivant :

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\

Nœud de Registre WOW6432Node

Le HKEY_CURRENT_USER\SOFTWARE\WOW6432Node nœud de Registre ne fait pas l’objet d’une recherche sur les machines 64 bits, en raison de la façon dont le Registre fonctionne sur ces ordinateurs. Pour plus d’informations, consultez Clés de Registre affectées par les installations Windows qui incluent Windows sur Windows (WOW) Prise en charge de plusieurs architectures de processeur.

ID d’extension requis pour les deux magasins

Si vous avez des extensions sur les modules complémentaires Microsoft Edge et le Chrome Web Store, vous devez ajouter les ID d’extension correspondant aux deux magasins dans le allowed_origins du fichier manifeste de l’hôte de messagerie native. Cela est nécessaire, car seul le fichier manifeste de l’hôte de messagerie native qui correspond au premier emplacement du Registre trouvé est lu.

Pour stocker le fichier manifeste de l’hôte de messagerie native :

Les hôtes de messagerie native à l’échelle du système, qui sont disponibles pour tous les utilisateurs, sont stockés dans un emplacement fixe. Par exemple, le fichier manifeste de l’hôte de messagerie native doit être stocké à l’emplacement suivant :
```
/Library/Microsoft/Edge/NativeMessagingHosts/com.my_company.my_app.json
```
Les hôtes de messagerie native spécifiques à l’utilisateur, qui sont disponibles uniquement pour l’utilisateur actuel, se trouvent dans le NativeMessagingHosts sous-répertoire du répertoire de données utilisateur. Par exemple, le fichier manifeste de l’hôte de messagerie native doit être stocké à l’emplacement suivant :
```
~/Library/Application Support/Microsoft Edge {Channel_Name}/NativeMessagingHosts/com.my_company.my_app.json
```
Le {Channel_Name} dans Microsoft Edge {Channel_Name} doit être l’une des valeurs suivantes :
- Canary
- Dev
- Beta
Lorsque vous utilisez le canal Stable, {Channel_Name} n’est pas obligatoire.

Pour stocker le fichier manifeste de l’hôte de messagerie native :

Les hôtes de messagerie native à l’échelle du système, qui sont disponibles pour tous les utilisateurs, sont stockés dans un emplacement fixe. Le fichier manifeste de l’hôte de messagerie native doit être stocké à l’emplacement suivant :
```
/etc/opt/edge/native-messaging-hosts
```
Les hôtes de messagerie native spécifiques à l’utilisateur, qui sont disponibles uniquement pour l’utilisateur actuel, se trouvent dans le NativeMessagingHosts sous-répertoire du répertoire de données utilisateur. Le fichier manifeste de l’hôte de messagerie native doit être stocké à l’emplacement suivant :
```
~/.config/microsoft-edge/NativeMessagingHosts
```

Protocole de messagerie natif

Microsoft Edge démarre chaque hôte de messagerie native dans un processus distinct et communique avec celui-ci à l’aide de l’entrée standard (stdin) et de la sortie standard (stdout). Le même format est utilisé pour envoyer des messages dans les deux sens ; chaque message est sérialisé à l’aide de JSON, encodé en UTF-8 et précédé d’une longueur de message de 32 bits dans l’ordre d’octet natif. La taille maximale d’un message provenant de l’hôte de messagerie native est de 1 Mo, principalement pour protéger Microsoft Edge contre le comportement incorrect des applications natives. La taille maximale du message 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é dans le allowed_origins manifeste de l’hôte de messagerie native. Consultez Étape 2 : Créer votre fichier manifeste d’hôte de messagerie native, ci-dessus.

Sur Windows, l’hôte de messagerie native est également passé à un argument de ligne de commande avec un handle à la fenêtre native de Microsoft Edge appelante : --parent-window=<decimal handle value>. Cela permet à l’hôte de messagerie native de créer des fenêtres d’interface utilisateur natives qui sont correctement parentées. Notez que cette valeur sera 0 si le contexte appelant est un worker de service.

Lorsqu’un port de messagerie est créé à l’aide runtime.connectNativede , Microsoft Edge démarre un processus hôte de messagerie natif 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 runtime.sendNativeMessagede , sans créer de port de messagerie, Microsoft Edge démarre un nouveau processus hôte de messagerie natif pour chaque message. Dans ce cas, le premier message généré par le processus hôte est géré en tant que réponse à la requête d’origine, et Microsoft Edge le transmet au rappel de réponse spécifié lors runtime.sendNativeMessage de l’appel. Tous les autres messages générés par l’hôte de messagerie native dans ce cas sont ignorés.

Connexion à une application native

L’envoi et la réception de messages vers et à partir d’une application native sont très similaires à la messagerie inter-extensions. La différence main est que runtime.connectNative est utilisé au lieu de runtime.connect, et runtime.sendNativeMessage est utilisé à la place de runtime.sendMessage.

Pour utiliser ces méthodes, l’autorisation doit être déclarée dans le nativeMessaging fichier manifeste de vos extensions. Consultez Étape 1 : Ajouter des autorisations au manifeste d’extension, ci-dessus.

Ces méthodes ne sont pas disponibles dans les scripts de contenu, mais uniquement dans les pages et le service Worker de votre extension. Si vous souhaitez communiquer à partir d’un script de contenu vers l’application native, envoyez le message à votre service Worker pour le transmettre à l’application native.

L’exemple suivant crée un runtime.Port objet connecté à l’hôte com.my_company.my_applicationde messagerie native , commence à écouter les messages à partir de ce port et envoie un message sortant :

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

Utilisez runtime.sendNativeMessage pour envoyer un message à l’application native sans créer de port ; par exemple :

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

Débogage de la messagerie native

Lorsque certains échecs de messagerie native se produisent, la sortie est écrite dans le journal des erreurs de Microsoft Edge. Cela inclut lorsque l’hôte de messagerie native ne parvient pas à démarrer, écrit stderr dans ou enfreint le protocole de communication. Sur Linux et macOS, ce journal est facilement accessible en démarrant Microsoft Edge à partir de la ligne de commande et en regardant sa sortie dans le terminal. Sur Windows, utilisez --enable-logging comme expliqué dans Comment activer la journalisation.

Voici quelques erreurs courantes et conseils pour les résoudre :

Échec du démarrage de l’hôte de messagerie native.

Vérifiez si vous disposez des autorisations suffisantes pour exécuter le fichier hôte de messagerie native.

Nom d’hôte de messagerie native non valide spécifié.

Vérifiez si le nom contient des caractères non valides. Seuls les caractères alphanumériques minuscules, les traits de soulignement et les points (points) sont autorisés. Un nom ne peut pas commencer ou se terminer par un point, et un point ne peut pas être suivi d’un autre point.

L’hôte natif s’est arrêté.

Le canal vers l’hôte de messagerie native a été interrompu avant que le message soit lu par Microsoft Edge. Cette opération est probablement lancée à partir de votre hôte de messagerie natif.

Hôte de messagerie natif spécifié introuvable.

Vérifiez les éléments suivants :

Le nom est-il correctement orthographié dans l’extension et dans le fichier manifeste ?
Le manifeste se trouve-t-il dans le bon répertoire et avec le nom correct ? Consultez Emplacement de l’hôte de messagerie native pour connaître les formats attendus.
Le fichier manifeste est-il au format correct ? En particulier, le JSON est-il valide et bien formé, et les valeurs correspondent-elles à la définition d’un manifeste d’hôte de messagerie native, conformément à l’Étape 2 : Créer votre fichier manifeste d’hôte de messagerie natif ci-dessus ?
Le fichier spécifié dans path existe-t-il ? Sur Windows, les chemins d’accès peuvent être relatifs, mais sur macOS et Linux, les chemins doivent être absolus.

Le nom d’hôte de messagerie native n’est pas inscrit. (Windows uniquement)

L’hôte de messagerie natif est introuvable dans le Registre Windows. Double case activée en utilisant regedit si la clé a été réellement créée et correspond au format requis, comme indiqué à l’emplacement de l’hôte de messagerie native.

L’accès à l’hôte de messagerie native spécifié est interdit.

L’origine de l’extension est-elle répertoriée dans allowed_origins?

Erreur lors de la communication avec l’hôte de messagerie native.

Cela indique une implémentation incorrecte du protocole de communication dans l’hôte de messagerie native.

Assurez-vous que toutes les sorties dans stdout respectent le protocole de messagerie native. Si vous souhaitez imprimer des données à des fins de débogage, écrivez dans stderr.
Vérifiez que la longueur du message 32 bits est au format entier natif de la plateforme (little-endian ou big-endian).
La longueur du message ne doit pas dépasser 1024*1024.
La taille du message doit être égale au nombre d’octets dans le message. Cela peut différer de la « longueur » d’une chaîne, car les caractères peuvent être représentés par plusieurs octets.
Windows uniquement : Assurez-vous que le mode d’E/S du programme est défini sur O_BINARY. Par défaut, le mode E/S est O_TEXT, ce qui endommage le format du message, car les sauts de ligne (0A = \n) sont remplacés par des fins de ligne de style Windows ().\r\n = 0D 0A Le mode d’E/S peut être défini à l’aide de __setmode.

Remarque

Les parties de cette page sont des modifications basées sur le travail créé et partagé par Google et utilisées conformément aux termes décrits dans la licence internationale Creative Commons Attribution 4.0. La page d’origine se trouve ici.

Cette œuvre est concédée sous licence creative commons attribution 4.0 international.

Partage via