Plugin-API

Le logiciel GRT dispose d'une interface plug-in dynamique pour l'ajout de fonctions supplémentaires.

Les plugins GRT sont des programmes ou des scripts autonomes et exécutables. Au démarrage, tous les plugins du dossier plugins sont intégrés dans le programme principal.

A cette fin, un canal de communication entre GRT et chaque plugin est établi viaIPC (Inter Process Communication). L'IPC est un type de connexion courant entre différents programmes sur un système. Il ne nécessite pas de connexion Internet pour les plug-ins ou GRT. Avec IPC, la connexion est limitée à l'ordinateur local.

Les plugins ne sont donc que reliés au GRT par un canal de communication. Si l'auteur d'un plugin le souhaite, il peut également concevoir son plugin de manière à ce qu'il puisse être utilisé indépendamment de GRT.

Le sous-répertoire dans lequel les plugins GRT doivent être situés est : “plugins” avec le chemin suivant :

• C:/Applications/GordonsReloadingTool/plugins/

• Le plugin doit être exécutable. C'est à dire qu'il doit être capable de fonctionner de façon indépendante comme un programme ou un script.
• Le plugin doit pouvoir reconnaître et traiter paramètres de ligne de commande les spécifiés au démarrage.
• Le plugin doit pouvoir établir une Connection socket pour la communication avec GRT.
  • sous Linux: a Unix domain socket
  • sous Windows: TCP-Socket
    Comme il n'existe pas de sockets Unix sous Windows, un socket TCP normal est utilisé. GRT ouvre un socket TCP spécialement configuré, qui n'autorise pas les connexions Internet et ne provoque donc pas d'avertissement du pare-feu.

Chaque plugin est situé dans un dossier distinct. Le nom du dossier doit être unique pour éviter les conflits avec d'autres plugins, mais il n'a aucune autre signification.

Un répertoire de plugins contient généralement les fichiers et dossiers suivants :

• /media
  Sous-répertoire pour les fichiers médias tels que les icônes ou les images (le nom est facultatif mais est recommandé)

• com.grt.plugin.xml
  Ce fichier est ce que l'on appelle Manifest “Manifeste” du plugin. Le nom de ce fichier est par défaut et toujours le même. Le manifeste du plugin contient les spécifications du plugin. Il contient également la définition des menus et des icônes de la barre d'outils, par exemple, qui doivent être fournis automatiquement dans GRT pour le plugin.

• plugin.exe
  Le plugin lui-même sous forme de fichier exécutable (n'importe quel nom), ici pour Windows. Un plugin peut également supporter plusieurs plateformes et l'emplacement des fichiers exécutables est défini dans le manifeste du plugin. L'endroit où les fichiers exécutables du plugin sont stockés dans le dossier du plugin peut donc être choisi librement.

Lorsqu'un plugin est stocké dans le dossier du plugin GRT, le Manifeste Plugin de tous les plugins est lu par GRT au démarrage. En fonction de la configuration dans le manifeste du plugin, tous les comportements, éléments de menu et icônes de la barre d'outils définis et souhaités seront créés ou configurés par GRT pour le plugin.

Les menus définis par le plugin apparaissent dans le GRT dans le menu “Plugins” avec le nom du plugin et comme sous-menus tous les éléments de menu définis par le plugin. Les menus définis par le plugin peuvent être imbriqués aussi profondément que souhaité.

Ensuite, en fonction du système d'exploitation, le fichier exécutable défini dans le manifeste du plugin est lancé avec une ligne de commande. Avec les paramètres de connexion spécifiés dans la ligne de commande, le plugin doit ensuite se connecter au GRT avec une commande Socket-Connect. Un Timeout peut être spécifié dans le manifeste du plugin, ce qui annule la tentative de connexion de la part de GRT en cas d'erreur.

Voir: Le manifeste du plugin

GRT démarre le plugin avec les lignes de commande comme suit :

plugin.exe --ipcport <port number>

Sous Windows le port pour le socket TCP. Par exemple, si le numéro de port 49771 est spécifié, l'adresse de connexion à GRT: localhost:49771 or 127.0.0.1:49771.

plugin --ipcfile <filepath>

Sous Linux, le chemin du fichier de connexion pour le socket de domaine Unix.

Un plugin peut être configuré de manière à rester connecté continuellement au GRT ou à n'être lancé que lors d'une action de l'utilisateur. Pour les plugins qui sont connectés en permanence, les icônes de la barre d'outils seront désactivées (grisées) si un plugin met fin à la connexion. Les éléments de menu du plugin ne seront plus fonctionnels.

Tant que GRT fonctionne, le plugin peut se reconnecter automatiquement après une perte de connexion avec les dernières informations de connexion. Les icônes de la barre d'outils et les menus sont alors automatiquement réactivés.

La communication entre les plugins et GRT s'effectue par le biais de paquets de données qui sont échangés via une connexion socket. L'encapsulation des données se fait en texte clair par le biais de JSON-Notation avec les spécifications correspondantes à la structure.

• Les valeurs numériques sont spécifiées en décimal.
• Les chaines de caractères sont spécifiées en texte suivant le codage UTF8-Format]. Elles peuvent aussi être codées URL-encoded si nécessaire.

Il peut arriver qu'un paquet de données soit perdu en raison de circonstances techniques. Le plugin doit s'assurer que GRT émet les paquet de réponse pour une commande envoyée par le plugin. Si aucune réponse n'est reçue, le plugin peut le reconnaître et exécuter à nouveau la commande.

Le logiciel GRT renvoie au plugin les paquets détectés comme défectueux avec un message d'erreur et une description de l'erreur.

Le GRT envoie tous les événements activés dans le manifeste du plugin au plugin. C'est-à-dire que si le plugin a activé l'événement pour le changement d'onglet (onglet cliqué/changé par l'utilisateur), un message d'événement est automatiquement envoyé au plugin dès que l'utilisateur a cliqué sur un onglet dans GRT.

Les évènements n'attendent aucune confirmation de la part du plugin. Aucun message de réponse n'est nécessaire pour les événements. Lorsqu'un événement se produit, il est envoyé à tous les plugins qui ont activé l'événement dans leur manifeste.

Note: “Tab” désigne l'onglet ou le fichier de chargement correspondant dans GRT.

• Event_Attached - Plugin intégré
• Event_ColorPresetChange - le schéma de couleurs a changé
• Event_MenuAction - On a cliqué sur un élément de menu
• Event_ToolbarAction - L'icône de la barre d'outils a été cliquée
• Event_TabClosed - L'utilisateur a fermé l'onglet
• Event_TabComputed - Simulation recalculée
• Event_TabDataChange - Les données d'un onglet ont été modifiées
• Event_TabSwitch - l'utilisateur a cliqué sur un onglet (différent)
• Event_TabUnitChange - une unité de mesure a été modifiée
• Event_WindowActivate - une fenêtre principale GRT (celle avec des onglets) a été activée/placée au premier plan
• Event_WindowClosed - une fenêtre principale de GRT a été fermée
• Event_WindowDeactivate - une fenêtre principale de GRT a été placée en arrière-plan
• Event_WindowMaximize - une fenêtre principale de GRT a été agrandie
• Event_WindowMinimize - Une fenêtre principale de GRT a été réduite
• Event_WindowMoved - Une fenêtre principale de GRT a été déplacée
• Event_WindowResized - une fenêtre principale de GRT a été redimensionnée
• Event_WindowRestore - une fenêtre principale de GRT a été restaurée après avoir été agrandie ou réduite

• Close_ChunkStream - ferme le flux de données

• Get_Chunk - lit une partie d'un flux de données
• Get_ColorPresets - Liste de tous les schémas de couleurs
• Get_ColorPreset - lecture du schéma de couleurs
• Get_Tab - Lecture des propriétés d'un onglet spécifique
• Get_TabList - Lit la liste des propriétés de tous les onglets
• Get_TabOnTop - Lecture des propriétés de l'onglet actif (focus)
• Get_TabResults - lecture des résultats de simulation d'un onglet spécifique