======Plugin-API====== The GRT has a dynamic plug-in interface for add-on functions. ===What are GRT plugins?=== GRT plugins are standalone, executable programs or scripts. At startup, all activated plugins from the plugin folder are integrated into the main program. For this purpose a communication channel between the GRT and each plugin is established via [[https://en.wikipedia.org/wiki/Inter-process_communication|IPC]] (Inter Process Communication). IPC is a common type of connection between different programs on a system. It does not require an Internet connection for plug-ins or the GRT. With IPC, the connection is limited to the local computer. The plug-ins are therefore only loosely connected to the GRT via a communication channel. If a plugin author so wishes, he can also design his plugin so that it can be used independently of the GRT. ===Where are the plugins stored/installed?=== The //subdirectory// in which the GRT plugins must be located to be recognized: **//"plugins"//**. So the plugins are located e.g. in * //C:/Applications/GordonsReloadingTool/plugins/// ===What requirements does a plugin need?=== * The plugin must be executable. I.e. it must be able to run independently as a program or script. * The plugin must be able to recognize and process the **command line parameters** specified at startup. * The plugin must be able to establish a **Socket connection** for the communication with the GRT. * **under Linux:** a Unix domain socket * **under Windows:** TCP-Socket\\ Because there are no Unix domain sockets under Windows, a normal TCP socket is used. The GRT opens a specially configured TCP socket, which does not allow Internet connections and therefore does not provoke a firewall warning. ====Directory structure of a plugin==== Each plugin is located in a separate folder. The name of the folder should be unique to avoid conflicts with other plugins, but it has no other meaning. A plugin directory usually has the following files and folders: * **///media//**\\ Subdirectory for media files like icons or images (optional, name is a recommendation) * **//[[en:doku:plugin-api-manifest|com.grt.plugin.xml]]//**\\ This file is the so called **//Manifest//** of the plugin. **The name of this file is a default and always the same.** The plugin manifest contains the specification of the plugin. It also contains the definition of e.g. menus and toolbar icons which should be provided automatically in the GRT for the plugin. * **//plugin.exe//**\\ The plugin itself as an executable file (any name), here for Windows. A plugin can also support multiple platforms and the location of the executable files is defined in the plugin manifest. Where the executable plugin files are stored within the plugin folder is therefore freely selectable. =====Integration of plugins into the GRT===== When a plugin is stored in the GRT plugin folder, the //Plugin Manifest// of all plugins is read by the GRT at startup. Depending on the configuration in the plugin manifest, all defined and desired behaviors, menu items and toolbar icons will be created or configured by the GRT for the plugin. Menus defined by the plugin appear in the GRT in the menu "Plugins" with the name of the plugin and as submenus all menu items defined by the plugin. The menus defined by the plugin can be nested as deep as desired. Then, depending on the operating system, the executable file defined in the plugin manifest is launched with a command line parameter. With the connection parameters specified in the command line, the plugin must then connect to the GRT with a **//Socket-Connect//**. A **Timeout** can be specified in the plugin manifest, which cancels the connection attempt on the part of the GRT in the event of an error. **See: [[en:doku:plugin-api-manifest|The plugin manifest]]** ====Command line parameter for plugin start==== GRT starts the plugin with command line parameters as follows: ==Windows== plugin.exe --ipcport Under Windows the port for the TCP socket. If, for example, the port number **49771** is specified, the connection address to the GRT is: **//localhost:49771//** or **//127.0.0.1:49771//**. == Linux == plugin --ipcfile Under Linux the path of the connection file for the Unix domain socket. ====Connection types==== A plugin can be configured so that it either remains **continuously** connected to the GRT, or is only started during **user interaction**. For plugins that are permanently connected to the GRT, toolbar icons **will be disabled** (gray) if a plugin terminates the connection and menu items of the plugin are functionless. As long as the GRT is running, the plugin can reconnect to the GRT automatically after a connection loss with the last specified connection information. Toolbar icons and menus are then automatically reactivated. =====Communication (API)===== The communication between the plugins and the GRT takes place via data packets which are exchanged via a socket connection. The data encapsulation is done in plain text via [[https://en.wikipedia.org/wiki/JSON|JSON-Notation]] with corresponding specifications to the structure. * **Number values** are specified **decimal**. * **Strings** are specified in plain text in [[https://en.wikipedia.org/wiki/UTF-8|UTF8-Format]]]. They may also be [[https://en.wikipedia.org/wiki/Percent-encoding|URL-encoded]] if necessary. ==Important== It may happen that a package is lost due to technical circumstances. This means that the plugin must ensure that the **response packets** are **evaluated** by the GRT for a command sent by the plugin. If no response is received, the plugin can recognize this and execute the command again. ==Failed packets== The GRT reports back to the plugin packets detected as faulty with an error message and description. =====Events & Functions===== The GRT sends all **events activated in the plugin manifest ** to the plugin. I.e. if the plugin has activated the event for tab change (tab clicked/changed by the user), an event message is automatically sent to the plugin as soon as the user has clicked a tab in the GRT. ====List of Events==== **The events** do **not** expect any confirmation from the plugin. No response message is necessary for events. When an event occurs, it is sent to all plugins that have activated the event in their manifest. Note: "Tab" denotes the tab or the corresponding load file in the GRT. * [[en:doku:plugin-api-event-attached|Event_Attached]] - Plugin integrated * [[en:doku:plugin-api-event-colorpresetchange|Event_ColorPresetChange]] - color scheme changed * [[en:doku:plugin-api-event-menuaction|Event_MenuAction]] - Menu item clicked * [[en:doku:plugin-api-event-toolbaraction|Event_ToolbarAction]] - Toolbar icon clicked on * [[en:doku:plugin-api-event-tabclosed|Event_TabClosed]] - Tab was closed by user * [[en:doku:plugin-api-event-tabcomputed|Event_TabComputed]] - Simulation recalculated * [[en:doku:plugin-api-event-tabdatachange|Event_TabDataChange]] - Data of a tab changed * [[en:doku:plugin-api-event-tabswitch|Event_TabSwitch]] - the user has clicked on a (different) tab * [[en:doku:plugin-api-event-tabunitchange|Event_TabUnitChange]] - a unit of measurement has been changed * [[en:doku:plugin-api-event-windowactivate|Event_WindowActivate]] - a GRT main window (the one with tabs) has been activated/put in the foreground * [[en:doku:plugin-api-event-windowclosed|Event_WindowClosed]] - a GRT main window was closed * [[en:doku:plugin-api-event-windowdeactivate|Event_WindowDeactivate]] - a GRT main window was placed in the background * [[en:doku:plugin-api-event-windowmaximize|Event_WindowMaximize]] - a GRT main window was maximized * [[en:doku:plugin-api-event-windowminimize|Event_WindowMinimize]] - a GRT main window was minimized * [[en:doku:plugin-api-event-windowmoved|Event_WindowMoved]] - a GRT main window was moved * [[en:doku:plugin-api-event-windowresized|Event_WindowResized]] - a GRT main window has been resized * [[en:doku:plugin-api-event-windowrestore|Event_WindowRestore]] - a GRT main window was restored after maximizing/minimizing ====List of functions (commands)==== ===Close=== * [[en:doku:plugin-api-cmd-close_chunkstream|Close_ChunkStream]] - close data stream ===Get=== * [[en:doku:plugin-api-cmd-get_chunk|Get_Chunk]] - read part of a data stream * [[en:doku:plugin-api-cmd-get_colorpresets|Get_ColorPresets]] - list of all color schemes * [[en:doku:plugin-api-cmd-get_colorpreset|Get_ColorPreset]] - read color scheme * [[en:doku:plugin-api-cmd-get_tab|Get_Tab]] - read properties of a specific tab * [[en:doku:plugin-api-cmd-get_tablist|Get_TabList]] - read list with properties of all tabs * [[en:doku:plugin-api-cmd-get_tabontop|Get_TabOnTop]] - read properties of the active (focus) tab * [[en:doku:plugin-api-cmd-get_tabresults|Get_TabResults]] - read simulation results of a specific tab