de:doku:plugin-api

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.

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.

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.

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.

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.

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.

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.

Load

Close

Get

This website uses only functional necessary cookies.

By clicking on OK, you agree with storing that cookies on your computer for the time of your session.
If you do not agree please leave the website.

Show information about the used cookies.

Show our policies.

  • de/doku/plugin-api.txt
  • Last modified: 2021/05/30 03:33
  • (external edit)