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

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.

*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 Software Client. To begin, set up your client development environment, as discussed next.

To set up your PCoIP Software Client development environment:

Currently OpenSSL and Boost are required as third party libraries. Download and install the third party libraries to your system. The CMake modules provided automatically detects the system libraries at CMake configure time.
 

1. Unzip the SDK tar file.
2. Copy the files from usr/bin, usr/include/ and usr/lib to the corresponding system directories, /usr/bin/, /usr/include and /usr/lib.
3. Copy the ClientSession.app into /Applications/ClientSession.app if you like to use the ClientSession.app from the system Applications directory. You can also copy the .dylibs from the ClientSession.app to the directory where you are building your custom application.
4. At this point the SDK is installed on the system. For information on how to link the SDK libraries with your custom client application, see Linking the SDK for macOS.

macOS Build Prerequisites

The following must be installed to build the PCoIP Client SDK on macOS:

• Xcode 10 https://developer.apple.com/xcode/downloads/

• Boost 1.71

• OpenSSL 1.1.1

• CMake 3.17.2 or above: Download
  
  The PCoIP Client SDK does not support versions of CMake higher than 3.17.2.
  
   

  Linking the SDK for macOS

  This section includes instructions for linking the SDK libraries with your custom client application:

• Open a Terminal window and change directory to the root of the mounted SDK disk image.

• Copy the SDK files to desired location for SDK development, refered to as <sdk_location> below. The CMake modules for finding the libraries within the package are located inside the SDK framework /<sdk_location>/PCoIPSoftClientSDK.framework/Resources/CMake. The required libraries are namespaced by PCoIPSoftClientSDK.
   

• To use the core APIs use the following commands on your applications CMake file for linking your application to the libraries that are needed from the SDK.

  list(APPEND_CMAKE_PREFIX_PATH " /<sdk_location>/PCoIPSoftClientSDK.framework/Resources/CMake")
  
  find_package(PCoIPSoftClientSDK REQUIRED)
  

• Use the following command to link your application to the core library using the CMake command, replacing <your_application> with your own application name:

  target_link_libraries(<your_application> PRIVATE PCoIPSoftClientSDK::pcoip_core )
  

  You can link to any other required libraries similarly by appending it to the above command.
  
   

  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:
   

• Establish your host virtual machine and determine the PCoIP Agent that best fits your actual PCoIP environment.

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

  • PCoIP Standard Agent for Windows Guide
  • PCoIP Graphics Agent for Windows Guide
  • PCoIP Standard Agent for Linux Guide
  • PCoIP Graphics Agent for Linux Guide

• 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/mac/21.01/support/contacting_support/