ru:doku:plugin-api

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 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.

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)
  • 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.

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: The plugin manifest

GRT starts the plugin with command line parameters as follows:

Windows
plugin.exe --ipcport <port number>

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 <filepath>

Under Linux the path of the connection file for the Unix domain socket.

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.

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 JSON-Notation with corresponding specifications to the structure.

  • Number values are specified decimal.
  • Strings are specified in plain text in UTF8-Format]. They may also be 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.

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.

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.

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.

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