Using The Broker Client Example¶

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

Finding the Latest Information

While we make every attempt to keep this topic current, the README file available along with the Broker Client example contains the latest information.

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 sample broker client implements the PCoIP session sequence. It also provides an overview of invoking and using the executable session client.

Custom Broker Client Library Implementations

Anyware clients interact with PCoIP-compatible brokers and Anyware 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 third-party 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.

Installing the Client SDK¶

Install the latest Anyware Software Client. For more information see the topic "Installing the Anyware Software Client for Mac" in the Administrators' Guide.
Download the latest SDK.
To install the SDK, open the .dmg file, and drag the PCoIPSoftClientSDK folder to your Documents folder (or another location of your preference).

Running the Prebuilt Anyware Client Binary¶

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

Location of the login_info File

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

Open the login_info.txt file.
Add the remote Anyware 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
```

Run 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

A status message will be displayed indicating whether the connection was successful. The following is an example of the status message:

Connected Successfully.
Desktop ID : sal-w7p64-sa15.autolab.local
ip_addr : 10.64.60.147
port : 4172
connect_tag:
SCS1fw0Zbk+Eu7q2iz0/M7mxfEE52au/3Jedtgp16L/rA8iB00+Er+YJd0yIL0xd9M
v5V0CDLSDmUNkOCwyyV1+u3w1aA7hXxEWmzhAA
session_id : 2305843009213693954
sni : SAL-W7P64-SA15
URI: "teradici-pcoip://10.64.60.147:4172?sessionid=
2305843009213693954&sni=SAL-W7P64-SA15", PARAMETERS: "connect-tag=SCS1fw0Zbk%2bEu7q2iz0%2fM7mxfEE52au%2f3Jedtgp16L%2frA8iB00%2bE
r%2bYJd0yIL0xd9Mv5V0CDLSDmUNkOCwyyV1%2bu3w1aA7hXxEWmzhAA"

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 AWS Anyware Software Client. The Anyware Software Client thus launched, 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: ~/Documents/PCoIPSoftClientSDK/Examples/broker_client_example/bin

Open the login_info_aws.txt file.
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
```

Run 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

A status message will be displayed indicating whether the connection was successful.

Building the Broker Client Example¶

From the root folder inside PCoIPSoftClientSDK, use the cd command to change the directory to the src folder of the Broker Client example:
```
cd ~/Documents/PCoIPSoftClientSDK/Examples/broker_client_example/src
```
Create a build directory by running the following command:
```
mkdir build
```
Change the directory to build by running the following command:
```
cd build
```
Configure the Broker Client example by running the following command:
```
cmake -G Xcode ..
```
Build the example by running the following command:
```
cmake --build . --config RelWithDebInfo
```

Custom Broker Client Library Implementations

This procedure creates broker_client_example and broker_client_example_aws executables.