======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 [[https://de.wikipedia.org/wiki/Interprozesskommunikation|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) * **//[[de:doku:plugin-api-manifest|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: [[de:doku:plugin-api-manifest|Das Plugin-Manifest]]** ===Kommandozeilenparameter für Plugin-Start=== GRT startet das Plugin mit folgenden Kommandozeilenparametern: ==Windows== plugin.exe --ipcport 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 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 [[https://de.wikipedia.org/wiki/JavaScript_Object_Notation|JSON-Notation]] mit entsprechenden Vorgaben zur Struktur. * **Zahlenwerte** werden **dezimal** angegeben * **Zeichenketten** werden im Klartext im [[https://de.wikipedia.org/wiki/UTF-8|UTF8-Format]] angegeben. Sie dürfen falls notwendig zusätzlich [[https://de.wikipedia.org/wiki/URL-Encoding|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. * [[de:doku:plugin-api-event-attached|Event_Attached]] - Plugin eingebunden * [[de:doku:plugin-api-event-colorpresetchange|Event_ColorPresetChange]] - Farbeinstellung/Preset wurde geändert * [[de:doku:plugin-api-event-menuaction|Event_MenuAction]] - Menüpunkt angeklickt * [[de:doku:plugin-api-event-toolbaraction|Event_ToolbarAction]] - Toolbar-Icon angeklickt * [[de:doku:plugin-api-event-tabclosed|Event_TabClosed]] - Tab wurde vom Benutzer geschlossen * [[de:doku:plugin-api-event-tabcomputed|Event_TabComputed]] - Simulation neu berechnet * [[de:doku:plugin-api-event-tabdatachange|Event_TabDataChange]] - Daten eines Tabs geändert * [[de:doku:plugin-api-event-tabswitch|Event_TabSwitch]] - der Benutzer hat auf einen (anderen) Tab geklickt * [[de:doku:plugin-api-event-tabunitchange|Event_TabUnitChange]] - eine Maßeinheit wurde geändert * [[de:doku:plugin-api-event-windowactivate|Event_WindowActivate]] - ein GRT-Hauptfenster (das mit Tabs) wurde aktiviert/in den Vordergrund gesetzt * [[de:doku:plugin-api-event-windowclosed|Event_WindowClosed]] - ein GRT-Hauptfenster wurde geschlossen * [[de:doku:plugin-api-event-windowdeactivate|Event_WindowDeactivate]] - ein GRT-Hauptfenster wurde in den Hintergrund gesetzt * [[de:doku:plugin-api-event-windowmaximize|Event_WindowMaximize]] - ein GRT-Hauptfenster wurde maximiert * [[de:doku:plugin-api-event-windowminimize|Event_WindowMinimize]] - ein GRT-Hauptfenster wurde minimiert * [[de:doku:plugin-api-event-windowmoved|Event_WindowMoved]] - ein GRT-Hauptfenster wurde verschoben * [[de:doku:plugin-api-event-windowresized|Event_WindowResized]] - ein GRT-Hauptfenster wurde in der Größe geändert * [[de:doku:plugin-api-event-windowrestore|Event_WindowRestore]] - ein GRT-Hauptfenster wurde nach dem Maximieren/Minimieren wiederhergestellt ====Liste der Funktionen (Kommandos)==== ===Load=== * [[de:doku:plugin-api-cmd-load_file|Load_File]] - Datei laden (grtload) ===Close=== * [[de:doku:plugin-api-cmd-close_chunkstream|Close_ChunkStream]] - Datenstrom freigeben ===Get=== * [[de:doku:plugin-api-cmd-get_chunk|Get_Chunk]] - Teil eines Datenstroms lesen * [[de:doku:plugin-api-cmd-get_colorpresets|Get_ColorPresets]] - Liste der Farbschemen lesen. * [[de:doku:plugin-api-cmd-get_colorpreset|Get_ColorPreset]] - Farbschema lesen. * [[de:doku:plugin-api-cmd-get_tab|Get_Tab]] - Eigenschaften eines bestimmten Tab/Reiter lesen. * [[de:doku:plugin-api-cmd-get_tablist|Get_TabList]] - Liste aller Tabs/Reiter inkl. Eigenschaften lesen. * [[de:doku:plugin-api-cmd-get_tabontop|Get_TabOnTop]] - Eigenschaften des aktuellen (aktiven) Tab/Reiter lesen. * [[de:doku:plugin-api-cmd-get_tabresults|Get_TabResults]] - Simulationsdaten eines bestimmten Tab/Reiter lesen.