API Structure

Touch Portal allows to import plug-ins which can be used to control third-party software or supply services to the Touch Portal users. This documentation describes the full infrastructure of the Touch Portal API.

Static or Dynamic setup

Touch Portal plug-ins can be designed from two principles.

Static - This principle can be used when you create a plug-in that does not require communication back and forth to the plug-in software. Examples of when you would use this principle is when your plug-in will only have actions that will trigger an executable with a command line parameters or when you want to execute scripting code that is already present on the system. The general purpose of this principle is fire-and-forget. The API does not provide any means to trigger events or return states when using this principle.
Dynamic - This principle can be used if you want to create a plug-in that executes actions but also provide states and events to the Touch Portal user. This principle uses socket communication to send the user triggered actions from Touch Portal to the plug-in and listens for state changes and events which the users can act upon as they can with native Touch Portal events.

Plugin Structure of Static setup

Below is a diagram of the infrastructure of Touch Portal and how static plugins function within.

Image 1. Plugin structure for Static Plugins

The .tpp plugin file is a zip file that contains a Description file, an icon file and the plugin application files. The .tpp file is imported in Touch Portal and is processed. All files are placed in the Touch Portal data folder in a unique folder that belongs to this plug-in. When Touch Portal starts (or after importing the .tpp file) it will read the description file to create categories and actions that are defined in that file.

Defined actions will execute a commandline when used. There is no feedback and there are no states. These actions are fire-and-forget actions.

Plugin Structure of Dynamic setup

Below is a diagram of the infrastructure of Touch Portal and how plugins function within.

Image 1. Plugin structure for Dynamic Plugins

Touch Portal will then open a socket connection that listens to the pairing of plug-ins. The plug-in will then pair and starts sending state updates and events to Touch Portal. Touch Portal will interpreted these and will act accordingly.

Touch Portal processes all communication asynchronously. This means if you send two calls immediatly, the first might not be processed fully before the second is being processed.

It is important to understand these differences and limitations for each of the principles. Almost all plug-ins require the Dynamic principle so when in doubt use that principle.

Static and Dynamically linked Libraries (Important)

Touch Portal runs its own embedded Java runtime, which includes the JavaFX library. Both Java and JavaFX use dependencies required for their execution. Touch Portal launches all plugins from its own context, which means that the processes inherit the libraries loaded from this runtime. This can affect your plugin if it requires and uses any library that is also part of the runtime. If you do not explicitly reference (or bundle) your own libraries, the context of Touch Portal will be used first to locate and load libraries.

Why is this important? Well, if a library exists in Touch Portal's runtime (like msvcp140.dll, vcruntime140.dll, and vcruntime140_1.dll for MSVC, for example), it will be used and may not be the correct version compared to what your plugin requires, which can cause your plugin to crash. When using external libraries, be sure to add them to your plugin folder next to the executable or reference them properly so that the correct libraries are used instead of the embedded runtime versions.

General Info

The Plug-in File