Plugin-API
Das GRT besitzt eine dynamische Plugin-Schnittstelle zur Nachrüstung von Zusatzfunktionen.
Was sind GRT-Plugins?
GRT-Plugins sind eigenständige, ausführbare Programme oder Scripte. Beim Start werden alle aktivierten Plugins aus dem Plugin-Ordner in das Hauptprogramm eingebunden.
Hierzu wird zwischen dem GRT und jedem Plugin ein Kommunikationskanal über IPC (Inter Process Communication) aufgebaut. IPC ist eine gängige Verbindungsform zwischen verschiedenen Programmen auf einem System. Es ist keine Internetverbindung für Plugins oder das GRT dafür notwendig. Bei IPC läuft die Verbindung ausschließlich begrenzt auf den lokalen Rechner.
Die Plugins sind an das GRT also nur lose durch einen Kommunikationskanal angebunden. Wenn ein Plugin-Autor es wünscht, kann er sein Plugin daher auch so auslegen, dass es unabhängig vom GRT benutzt werden kann.
Wo werden die Plugins gespeichert/installiert?
Das Unterverzeichnis in dem sich die GRT-Plugins befinden müssen, damit sie erkannt werden lautet: “plugins”. Die Plugins befinden sich demnach also z.B. in
- C:/Programme/GordonsReloadingTool/plugins/
Welche Voraussetzungen braucht ein Plugin?
- Das Plugin muss ausführbar sein. D.h. es muss eigenständig als Programm oder Script ablaufen können.
- Das Plugin muss die beim Start angegebenen Kommandozeilenparameter erkennen und verarbeiten können.
- Das Plugin muss für die Kommunikation mit dem GRT eine Socket-Verbindung aufbauen können.
- unter Linux: ein Unix-Domain-Socket
- unter Windows: TCP-Socket
Da unter Windows keine Unix-Domain-Sockets existieren, kommt ein normaler TCP-Socket zum Einsatz. Das GRT öffnet hierzu einen speziell konfigurierten TCP-Socket, welcher keine Internetverbindungen zulässt und daher auch keine Firewall-Warnung provoziert.
Verzeichnisstruktur eines Plugins
Jedes Plugin befindet sich in einem eigenständigen Ordner. Der Name des Ordners sollte eindeutig sein um Konflikte mit anderen Plugins zu vermeiden, nimmt aber sonst keine Bedeutung ein.
Ein Pluginverzeichnis hat üblicherweise folgende Dateien und Ordner:
- /media
Unterverzeichnis für Mediendateien wie z.B. Icons oder Bilder (optional, Name ist eine Empfehlung)
- com.grt.plugin.xml
Diese Datei ist das sog. Manifest des Plugins. Der Name dieser Datei ist eine Vorgabe und immer gleich. Das Plugin-Manifest enthält die Spezifikation des Plugins. Es enthält auch die Definition von z.B. Menüs und Toolbar-Icons die im GRT für das Plugin automatisch bereitgestellt werden sollen.
- plugin.exe
Das Plugin selbst als ausführbare Datei (Name frei wählbar), hier für Windows. Ein Plugin kann auch mehrere Platformen unterstützen und der Ort der ausführbaren Dateien wird im Plugin-Manifest definiert. Wo die ausführbaren Plugindateien innerhalb des Plugin-Ordners gespeichert sind, ist demnach frei wählbar.
Einbindung der Plugins ins GRT
Sobald sich ein Plugin im GRT-Pluginordner befindet, wird beim Start vom GRT das Plugin-Manifest aller Plugins eingelesen. Je nach Konfiguration im Plugin-Manifest werden dann alle definierten und gewünschten Verhaltensweisen, Menüpunkte und Toolbar-Icons vom GRT für das Plugin erzeugt/angelegt bzw. konfiguriert.
Menüs die vom Plugin definiert wurden erscheinen im GRT im Menü “Plugins” mit dem Namen des Plugins und als Untermenüs alle vom Plugin definierten Menüpunkte. Die vom Plugin definierten Menüs können beliebig tief verschachtelt werden.
Anschließend wird je nach Betriebssystem die im Plugin-Manifest definierte, ausführbare Datei mit einem Kommandozeilenparameter gestartet. Mit den in der Kommandozeile angegebenen Verbindungsparametern muss sich das Plugin dann durch einen Socket-Connect mit dem GRT Verbinden. Im Plugin-Manifest kann ein Timeout festgelegt werden, wodurch der Verbindungsversuch seitens des GRT im Fehlerfall abgebrochen wird.
Siehe: Das Plugin-Manifest
Kommandozeilenparameter für Plugin-Start
GRT startet das Plugin mit folgenden Kommandozeilenparametern:
Windows
plugin.exe --ipcport <portnummer>
Unter Windows der Port für den TCP-Socket. Wird z.B. die Portnummer 49771 angegeben, lautet die Verbindungsadresse zum GRT: localhost:49771 bzw. 127.0.0.1:49771.
Linux
plugin --ipcfile <filepath>
Unter Linux der Pfad des Connectionfile für den Unix-Domain-Socket.
Verbindungsarten
Ein Plugin kann so konfiguriert werden, dass es entweder dauerhaft mit dem GRT in Verbindung bleibt, oder nur bei einer Benutzerinteraktion gestartet wird. Bei Plugins die dauerhaft mit dem GRT in Verbindung stehen, werden Toolbar-Icons deaktiviert (grau) wenn ein Plugin die Verbindung beendet und Menüpunkte des Plugins sind Funktionslos.
Solange das GRT läuft, kann sich das Plugin nach einem Verbindungsverlust mit den zuletzt angegebenen Verbindungsinformationen selbstständig wieder mit dem GRT verbinden. Toolbar-Icons und Menüs werden dann automatisch wieder aktiviert.
Kommunikation (API)
Die Kommunikation zwischen den Plugins und dem GRT erfolgt über Datenpakete die über eine Socketverbindung ausgetauscht werden. Die Datenkapselung erfolgt im Klartext über JSON-Notation mit entsprechenden Vorgaben zur Struktur.
- Zahlenwerte werden dezimal angegeben
- Zeichenketten werden im Klartext im UTF8-Format angegeben. Sie dürfen falls notwendig zusätzlich URL-Kodiert sein.
Wichtig
Es kann vorkommen, dass durch technische Umstände ein Paket verlorengeht. D.h. das Plugin muss dafür sorge tragen, dass die Antwortpakete vom GRT auf ein vom Plugin versendetes Kommando auch ausgewertet werden. Sollte keine Antwort eintreffen, kann das Plugin das damit erkennen und das Kommando erneut absetzen.
Fehlerhafte Pakete
Das GRT meldet als fehlerhaft erkannte Pakete mit einer Fehlermeldung und Beschreibung dem Plugin zurück.
Events & Funktionen
Das GRT versendet alle im Plugin-Manifest aktivierten Ereignisse (Events) an das Plugin. D.h. hat das Plugin das Event für Tabwechsel aktiviert (Reiter vom Benutzer angeklickt/gewechselt), wird dem Plugin automatisch eine Event-Nachricht zugeschickt, sobald der Benutzer im GRT einen Reiter angeklickt hat.
Liste der Events
Die Events (Ereignisse) erwarten keine Bestätigung durch das Plugin. Für Events ist also keine Antwortnachricht notwendig. Bei Auftreten eines Events wird es an alle Plugins versendet, welche das Event in ihrem Manifest aktiviert haben.
Hinweis: “Tab” bezeichnet den Reiter bzw. die zugehörige Ladungsdatei im GRT.
- Event_Attached - Plugin eingebunden
- Event_ColorPresetChange - Farbeinstellung/Preset wurde geändert
- Event_MenuAction - Menüpunkt angeklickt
- Event_ToolbarAction - Toolbar-Icon angeklickt
- Event_TabClosed - Tab wurde vom Benutzer geschlossen
- Event_TabComputed - Simulation neu berechnet
- Event_TabDataChange - Daten eines Tabs geändert
- Event_TabSwitch - der Benutzer hat auf einen (anderen) Tab geklickt
- Event_TabUnitChange - eine Maßeinheit wurde geändert
- Event_WindowActivate - ein GRT-Hauptfenster (das mit Tabs) wurde aktiviert/in den Vordergrund gesetzt
- Event_WindowClosed - ein GRT-Hauptfenster wurde geschlossen
- Event_WindowDeactivate - ein GRT-Hauptfenster wurde in den Hintergrund gesetzt
- Event_WindowMaximize - ein GRT-Hauptfenster wurde maximiert
- Event_WindowMinimize - ein GRT-Hauptfenster wurde minimiert
- Event_WindowMoved - ein GRT-Hauptfenster wurde verschoben
- Event_WindowResized - ein GRT-Hauptfenster wurde in der Größe geändert
- Event_WindowRestore - ein GRT-Hauptfenster wurde nach dem Maximieren/Minimieren wiederhergestellt
Liste der Funktionen (Kommandos)
Load
- Load_File - Datei laden (grtload)
Close
- Close_ChunkStream - Datenstrom freigeben
Get
- Get_Chunk - Teil eines Datenstroms lesen
- Get_ColorPresets - Liste der Farbschemen lesen.
- Get_ColorPreset - Farbschema lesen.
- Get_Tab - Eigenschaften eines bestimmten Tab/Reiter lesen.
- Get_TabList - Liste aller Tabs/Reiter inkl. Eigenschaften lesen.
- Get_TabOnTop - Eigenschaften des aktuellen (aktiven) Tab/Reiter lesen.
- Get_TabResults - Simulationsdaten eines bestimmten Tab/Reiter lesen.