Skip to content

The Broker Client API Example

The included sample broker client demonstrates how the APIs can be used to customize and control the pre-session and session phases of the connection. The Broker Client API is a two-step procedure, where as a first step, the Broker Client Example is built. The second step consists of running either a prebuilt PCoIP binary, or a prebuilt AWS binary.

Code is an API Demonstration Only

The sample session client, described in the following sections, demonstrates a simple connection scenario using the supplied broker_client_library. The example unrealistically assumes that all requests and calls succeed as expected, and performs only basic error handling. An actual client implementation is likely to be far more complex; for example, you will need to handle failed broker certificate verification, account for other authentication steps beyond a simple user ID and password combination, and any other circumstances dictated by your system requirements.

The Broker Client API Example Sequence

This section describes how the broker client API example implements the PCoIP session sequence. It also provides an overview of invoking and using the executable session client.

Custom Broker Client Library Implementations

PCoIP clients interact with PCoIP-compatible brokers and PCoIP agents using an abstraction layer called a broker client library. The following example uses the supplied broker client library. You may, however, choose to write your own broker client library to meet specific requirements, or use a thirdparty broker library which does not use the PCoIP Broker Protocol. Refer to the PCoIP® Connection Broker Protocol Specification for details on how to design and implement your own connection broker.

Building the Broker Client Example

!!! Note "Custom Broker Client Library Implementations" After you complete step 6, the build/ directory will contain the built examples as .exe files, which you can launch from the command line or double click, depending on what you have built.

  1. Install the latest PCoIP Software Client. For more information see the topic "Installing the PCoIP Software Client for Windows" in the Administrators Guide.
  2. Download the latest Windows SDK.
  3. To install the SDK, extract the contents of the PCoIPSoftClientSDK folder to a location of your preference.
  4. From the PCoIPSoftClientSDK folder, use the cd command to change the directory to broker_client_example.
  5. Create a directory called build/ inside the broker_client_example folder by running the following command: mkdir build
  6. Change the directory to build/ by using the cd command.
  7. Configure the SDK example by running the following command: cmake -G Xcode ..
  8. Build the example by running the following command: cmake --build
  9. Ensure that the CMakeLists.txt file present inside the directory has the path to the SDK directory appended to CMAKE_PREFIX_PATH so that the installed version of cmake on the system is able to locate the cmake modules for finding the dependencies:

   list(APPEND CMAKE_PREFIX_PATH "localpath/to/sdk/")

   find_package(PCoIPSoftClientSDK REQUIRED)
10. Link your application to the core library using the CMake command:

target_link_libraries(your_application PRIVATE PCoIPSoftClientSDK:pcoip_core)
11. To link other libraries, append them to the above command in step 7.

Running the Prebuilt PCoIP Client Binary

This example uses the supplied credentials to first establish a PCoIP session and then launch the PCoIP Software Client. The PCoIP Software Client thus launched, then connects to the remote agent.

Location of the login_info File

The login_info.txt file is available in the following location: /PCoIPSoftClientSDK/Examples/broker_client_example.

  1. Install the latest PCoIP Software Client. For more information see the topic "Installing the PCoIP Software Client for Windows" in the Administrators Guide.
  2. Download the latest Windows SDK.
  3. To install the SDK, extract the contents of the PCoIPSoftClientSDK folder to a location of your preference.
  4. Open the login_info.txt file.
  5. Add the remote PCoIP agent credentials in the format "FQDN domain username password hostname", where,
  • `FQDN`: The address of an HP Anyware broker.
  • `domain`: The domain that the host machine is on.
  • `username`: The username of the account you are connecting to.
  • `password`: The plain text password of the account you are connecting to. The password cannot contain spaces.

Example:

  desktop.example.com adomain.local foouser barpassword bazmacpro01
  1. Launch the example from a Terminal session: 
        cd ~/Documents/PCoIPSoftClientSDK/Examples/broker_client_example/bin/broker_client_example.app/Contents/MacOS

    killall PCoIPClient

    ./broker_client_example -l -i ~/Documents/PCoIPSoftClientSDK/Examples/broker_client_example/bin/login_info.txt

Running the Prebuilt AWS Example Binary

This topics contains instructions for running the AWS example binary that is packaged along with the Client SDK. The example uses credentials that you provide to first establish a PCoIP session and then launch the PCoIP Software Client. The PCoIP Software Client thus launched, then connects to the remote agent.

Location of the login_info_aws File

The login_info_aws.txt file can be found in the following location: /PCoIPSoftClientSDK/Examples/broker_client_example.

  1. Install the latest PCoIP Software Client. For more information see the topic "Installing the PCoIP Software Client for Windows" in the Administrators Guide.
  2. Download the latest Windows SDK.
  3. To install the SDK, extract the contents of the PCoIPSoftClientSDK folder to a location of your preference.
  4. Open the login_info_aws.txt file.
  5. Add the remote Amazon WorkSpace credentials in the format "aws_registration_code domain username password token_or_password resource_name", where,
  • `aws_registration_code`: The registration code for Amazon WorkSpace.
  • `domain`: The domain that the host machine is on.
  • `username`: The username of the account you are connecting to.
  • `password`: The plain text password of the account you are connecting to. The password cannot contain spaces.
  • `token_or_password`: The authentication token or password.
  • `resource_name`: The name of the resource to connect to.

Example:

 eNgrTX$xa adomain.local foouser barpassword 75539285075371469148082720109113041434163396974558736008282251461494906419802726 aws57864x1
  1. Launch the example from a Terminal session: 
        cd ~/Documents/PCoIPSoftClientSDK/Examples/broker_client_example/bin/broker_client_example_aws.app/Contents/MacOS

    killall PCoIPClient

    ./broker_client_example_aws -l -i ~/Documents/PCoIPSoftClientSDK/Examples/broker_client_example/bin/login_info_aws.txt