USB Session Example

The usb session example demonstrates how the usb enumeration facilities provided as part of the PCoIPCore framework can be leveraged to setup a callback to notify the caller when usb devices are (un)plugged into a client. Furthermore, it illustrates how to use the PCoIPCore API to claim/release a device connected to the client.

Unlike the usb example, the usb session example leverages the SDK's BrokerClient api to provision a host with which to connect. As such this example works out of the box.

When you run the usb session example a PCoIP session between your client and the agent (whose credentials you have entered in the login_info.txt file) will be established. Note that this PCoIP session will not be accompanied by an associated window in which the agent's pixels are streamed. Once the session is established you will be presented with an interactive menu in terminal which will dislay the list of usb devices connected to the client which can be claimed or released.

Entitlements

As of version 23.01 the macOS PCoIP Soft Client SDK USB solution now leverages the IOUSBHost under the hood to claim and release usb devices. Any macOS application which uses this API to capture/release usb devices may do so only if it is running with root privileges or if the app is granted the special "com.apple.vm.device-access" entitlement.

As a result, if your application does not run with root privileges it must be granted this entitlement by Apple in order for it to leverage the USB functionality provided by this macOS Soft Client SDK.

You will have to contact Apple directly in order to be granted this entitlement.

Setting up The Provisioning Profile

1. Contact Apple to have them grant your organization the "com.apple.vm.device-access" entitlement.

2. In your Apple Developper account create an App identifier for this example app. E.g: com.myorganization.usbsessionexample

3. Create a "Development" provisioning profile with the "com.apple.vm.device-access" additional capability enabled which is associated to the app identifier you created in step 1. You can name the provisioning profile something like: com.myorganization.usb-session-example

Building the example

1. Install the SDK by opening the .dmg and dragging the PCoIPSoftClientSDK folder to your Documents folder (or other location).

2. Navigate to the example directory

    cd ~/Documents/PCoIPSoftClientSDK/Examples/usb_session_example

3. In the CMake file ~/Documents/PCoIPSoftClientSDK/Examples/usb_session_example/CMakeLists.txt update:

   i. The value of _bundle_ID to the bundle ID you specified during step 1. of Setting up a Provisioning Profile

   ii. The value of XCODE_ATTRIBUTE_DEVELOPMENT_TEAM to your team's developer ID.

   iii. The value XCODE_ATTRIBUTE_PROVISIONING_PROFILE_SPECIFIER to the provisioning profile specifier of the provisioning profile you created in step 3. of Setting up a Provisioning Profile iv. The value XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY to the signing identity associated to the provisioning profile you created in step 3. of Setting up a Provisioning Profile. For example, if you have created a development profile set the valu to "Apple Development".

4. Create a build directory and navigate there

    mkdir build && cd build

5. Configure the build using cmake.

    cmake -G Xcode ..

6. Update the login_info.txt file (~/Documents/PCoIPSoftClientSDK/Examples/usb_session_example/login_info.txt) with the credentials of a remote PCoIP agent.

7. Build the example

    cmake --build . --config RelWithDebInfo

Running the example

1. Run the example

    ./RelWithDebInfo/usb_session_example.app/Contents/MacOS/usb_session_example