Touch Portal Plugin API Client for C++ and Qt

A simple TCP/IP network client for use in Touch Portal plugins which wish to utilize the Qt C++ library/framework.

---

Features

• Handles bi-directional network transfer and JSON encode/decode of Touch Portal messages.
• Uses Qt signals to deliver messages from Touch Portal and inform of connection status changes.
• Send messages to Touch Portal using Qt slots and/or direct client method invocations.
• Optimized for maximum throughput, no unnecessary data processing is performed (eg. assumes plugin author validates their own data before sending).
• Includes some optional convenience methods for working with incoming action/connector data (eg. convert JSON array of objects to a QMap with the data IDs as keys).
• Asynchronous socket operations, fully reentrant methods, and can be run in a separate thread if needed (with queued signals/slots communication).
• Supports Touch Portal plugin API up to v6 (latest released version). Will be updated for future versions as they are released.

---

Requirements

• Depends on the QtCore and QtNetwork libraries/modules.
• Requires a Qt event loop to process data (uses asynchronous socket operations).
  • Typically this would be provided by Q[Core|Gui]Application::exec(), but could also be wrapped in a custom class with own event loop for use outside of Qt applications (for example).
• The client should work on any platform supported by QtNetwork library.

Tested with Qt versions 5.12.12, 5.15.7, 6.4.1 on Windows 10/11, MacOS (Big Sur and later), and Linux (Debian 9 (buster) / Ubuntu 18.04 (bionic)).

---

Using

The client consists of a single class -- TPClientQt. The simplest way to use it in a project is to just include the source code files directly in the plugin build.

It can also be built/used as a shared or static library. The included CMake project file can be used to build this. By default it builds a shared library (DLL), but setting the BUILD_SHARED_LIBS variable to 'OFF/FALSE' will build the static version instead.

In either case, just #include "TPClientQt.h" somewhere in your plugin code and you're good to go.

---

Documentation

API documentation generated from source comments is published at: https://mpaperno.github.io/TouchPortal-CPP-API/annotated.html

---

Example

A working plugin using this client can be found at https://github.com/mpaperno/DSEP4TP

I will add a simpler example to this repository ASAP.

---

Credits

This project is written, tested, and documented by myself, Maxim (Max) Paperno.
https://github.com/mpaperno/

Documentation generated with Doxygen and styled with the most excellent Doxygen Awesome.

---

Copyright, License, and Disclaimer

TouchPortal-CPP-API Project
COPYRIGHT: Maxim Paperno; All Rights Reserved.

Dual licensed under the terms of either the GNU General Public License (GPL) or the GNU Lesser General Public License (LGPL), as published by the Free Software Foundation, either version 3 of the Licenses, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Copies of the GNU GPL and LGPL are included with this project and are available at http://www.gnu.org/licenses/.

Except as contained in this copyright notice, the names of the authors or their institutions shall not be used in advertising or otherwise to promote the sale, use, or other dealings in, any product using this Software, or any derivative of this Software, without prior written authorization from the authors.

This project may also use 3rd-party Open Source software under the terms of their respective licenses. The copyright notice above does not apply to any 3rd-party components used within.