Core API - PCoIP Client SDK for Linux

Rate this Article
Average: 1 (1 vote)

February 2, 2021

Last modified: 09/03/2023, 6:06 pm

Knowledge Base Article Tutorial API/SDK HP Anyware

Core API Change Log

This section outlines API call updates and changes for the Core API from the different versions of the PCoIP Client SDK for Linux.

 

20.10

PcoipClientInitData

  • PcoipClientInitData structure has been changed for licensing related data. The following fields have been added:

    • proxyServer
    • proxyPort
    • numberOfActivationCodes
    • activationCodes

pcoip_core_api.h

  • pcoip_core_api.h structure change: struct LicenseInfo has changed to the following:

 

struct LicenseInfo
{
    enum PCoIPLicensingResult resultCode;   ///< the result code as reported by the licensing module
    bool hasExpiry;  ///< license has a valid expiry time
    time_t expiryTime;  ///< time that license expires expressed as UNIX time
};


The change to this struct affects the pcoip_client_get_licensing_info() API function. Replaced the int32_t daysRemaining with time_t expiryTime and added field bool hasExpiry.

 

  • New api: pcoip_client_log_level_get(). Returns the current event level defines as PCOIP_EVENT_LEVEL_* constants.

 

20.07

pcoip_core_api.h

  • PcoipClientinitData structure change: trustCenterUrl renamed to licServerURL.
  • New api: pcoip_core_aws_allowed(). Returns whether connections to Amazon WorkSpaces are allowed.
  • New api: pcoip_core_api_vmware_allowed(). Returns whether connections to VMware Horizon are allowed.
  • New api: pcoip_core_api_pcoip_allowed(). Returns whether PCoIP connections are allowed.

 

20.04

pcoip_core_api.h

  • pcoip_client_init() signature change: Uses new PcoipClientInitData structure. It includes data needed for licensing in future releases. The new data members should be left empty. Unused parameters were removed.

  • Deprecated api: pcoip_client_connection_callback_register()

  • New api: pcoip_client_connection_callback_register(). Callback signature changed to include PCoIPAuth state for licensing in future releases.
  • New api: pcoip_client_usb_set_local_termination_blacklist(). Sets devices that should be locally terminated.

pcoip_disconnect_types.h

  • Added value to enum ePCOIP_DISCONNECT_CAUSE. Will be used for licensing in future releases.

certificate_store.h

  • certificate_store set_store_location() removed. Location can now only be set during construction of certificate_store.

 

20.01

  • No updates or changes.

 

19.11

  • Relative Mouse Feature.

 

19.08

  • No updates or changes.

 

PCoIP Core Library Integration

The core library allows an application developer to integrate a PCoIP session directly into an application. The core library facilitates connection to a remote host, decoding PCoIP image data directly into an application supplied frame buffer as well as remoting audio, keyboard and mouse events and supported USB devices. The application is responsible for all of the interactions with the window manager and the local operating system. The following diagram shows how an application would integrate the core library and broker library into a custom application.

 

PCoIP Core API

This method uses the PCoIP Core API to integrate the PCoIP protocol into a custom application. This method is necessary if you want custom features in the client beyond that which is possible using the Session Client API.

PCoIP Core API

This diagram shows the architecture with a custom application integrating the core library.

rtl

 

*Partner Virtual Channel Plugins can be developed using the Virtual Channel SDK, to enable this you can combine the PCoIP Client SDK with the PCoIP Virtual Channel SDK.

 

PCoIP Core API and Application Functionality

Using the Core API the application developer has more control over the client application than the PCoIP Session API but the developer must implement the integration between the local OS and the core library.

Broker Interactions

The core library does not implement any of the broker protocol interactions. The application is responsible for obtaining the PCoIP agent address, port number and session tag, using the Broker Client API or some other brokering method, and passing these to the core library.

Session Establishment

The application must provide the PCoIP agent address, port number and session tag to the core library in order to establish a PCoIP session.

Display Topology

The application is responsible for deciding what displays to present to the user. The application may specify up to four displays with resolutions up to 4096x4096. The application must determine the correct display position and the rotations (if any).

Keyboard Events

The application is responsible for handling local keyboard events, and providing the core library with scan codes to send to the remote host.

Mouse Events

The application must provide the mouse events, with either absolute or relative coordinates, for the core library to send to the remote host.

Touch Events

If the application supports touch events, the core library can forward these to the remote host.

Cursor Handling

Local cursor handling is critical for providing the most responsive user experience possible. The application is responsible for updating the local cursor shape and position on call-back from the core library.

USB Redirection

The application is responsible for determining if any USB devices should be connected to the remote session. The core library will disconnect the USB devices from the local system and redirect the device to the remote system. →

Session Reconnection

The core library supports reconnecting a session (for up to 20 minutes) in the event of a network disruption. The application is notified when a network disruption occurs and provides a method for terminating reconnection attempts.

Session Termination

The core library provides a method for the application to terminate the session.

 

Setting Up the Development Environment

Once you have successfully established a session between a PCoIP Software Client and a PCoIP host, you can start developing your own PCoIP client. To begin, set up your client development environment, as discussed next.

To set up your client development environment:

Refer to the SDK package for the dependencies and libraries required to set-up the development environment. The CMake modules provided automatically detects the system libraries at CMake configuration time.

  1. Install the .deb SDK installer. All nescessary files will be saved to the corresponding system directories.
  2. At this point, the SDK is installed on the system. For build instructions, see Building the SDK for Linux.

 

Building the SDK for Linux

This section includes instructions for building a custom client application by utilizing the SDK.

  1. As a reference, follow the CMakeLists.txt of the minimal_client to understand the build steps using the cmake tool. It is located at /usr/lib/x86_64-linux-gnu/pcoip-client/examples/minimal_client/CMakeLists.txt
  2. Run the CMake configure and verify it configures without any errors.
  3. Run make to build the application.
  4. The find_package() command of CMake automatically finds the libraries installed by the SDK.

 

Setting Up a PCoIP Agent Test Environment

Before developing your custom client, you should set up a working PCoIP system. HP Anyware recommends establishing a small proof-of-concept system for custom client testing, consisting of a host machine with an installed PCoIP Agent.

Before using your test environment, you must install a PCoIP Agent development license on the host machine. You received a license when you subscribed to a HP Anyware All Access solution, specifically HP Anyware or HP Anyware Plus. If you do not have a license, obtain one from HP Anyware before proceeding.

To establish a working proof-of-concept test system:
 

  1. Establish your host virtual machine and determine the PCoIP agent that best fits your actual PCoIP environment.

  2. Install the PCoIP agent on the host machine. For PCoIP agent installation instructions, refer to the appropriate administrators' guide:

  3. Install your agent license on the host machine. For license installation instructions, see the Administrators' Guide for your host machines PCoIP Agent.

     

    Connecting To Your PCoIP Agent

    Once your test system is set up, you can establish PCoIP connections to it using HP Anyware PCoIP Software Clients. For environment testing and troubleshooting purposes, the HP Anyware PCoIP Software Client is available here: https://www.teradici.com/web-help/pcoip_client/linux/21.01/support/contacting_support/