Virtual Channel API

SetupVirtualChannel

When a client extension and a server extension want to exchange data, they can setup a virtual channel between each other.

Both parties will issue a SetupVirtualChannelRequest message and both will wait for a VirtualChannelReadyEvent message. The synchronous response contains the name of the relay (named pipe on Windows, abstract UNIX domain socket on Linux and UNIX domain socket on macOS) over which the extensions will exchange data with NICE DCV and an authentication token used by NICE DCV to validate the process that is connecting to the relay endpoint.

• The caller must establish the communication with DCV.

  For Windows, open the client side of the named pipe.

  For Linux, open the abstract UNIX domain socket.

  For macOS, open the UNIX domain socket.

• Send the authentication token to the data channel.

• Wait for the asynchronous event on the control channel before writing any other data to it.

The caller must specify the ID of the process that will open the client side of the relay, NICE DCV will reject any attempt to connect to the relay from another process. Should the extension use the virtual channel from another process (e.g. a daemon process crashes and it is re-spawned), it will need to undergo a new virtual channel setup procedure.

The maximum number of open virtual channels (established or pending) for one extension is four, further setup requests will fail.

Request message:

SetupVirtualChannelRequest
+ string virtual_channel_name
+ int64 relay_client_process_id
			

• virtual_channel_name: Specific name of the virtual channel, the namespace is taken from the manifest.

• relay_client_process_id: Pid of the process that will open the client side of the relay.

Response message:

SetupVirtualChannelResponse
+ string virtual_channel_name
+ string relay_path
+ int64 relay_client_process_id
+ bytes virtual_channel_auth_token
			

• virtual_channel_name: Specific name of the virtual channel to be set up. The namespace is taken from the manifest.

• relay_path: Full path of the relay to the virtual channel. On Windows, it is the name of a named pipe. On Linux, it is the name of the abstract UNIX domain socket. On macOS, it is the name of the UNIX domain socket.

  For example:\\.\pipe\dcvextensions_random

• relay_client_process_id: The pid of the process that runs the server side of the relay client: the NICE DCV viewer on clients, the NICE DCV server process on servers.

• virtual_channel_auth_token: An authentication token the process has to send on the relay channel. DCV will use it to validate the connecting process.

Event message:

VirtualChannelReadyEvent
+ string virtual_channel_name
			

• virtual_channel_name: Specific name of the virtual channel, the namespace is taken from the manifest.

CloseVirtualChannel

One party (either the client extension or the server extension) can initiate the closure of a virtual channel with a CloseVirtualChannelRequest, the other party will be notified with a VirtualChannelClosedEvent.

Request message:

CloseVirtualChannelRequest
+ string virtual_channel_name
			

• Request message:virtual_channel_name: Specific name of the virtual channel, the namespace is taken from the manifest.

Response message:

CloseVirtualChannelResponse
+ string virtual_channel_name
			

• virtual_channel_name: Specific name of the virtual channel to be set up, the namespace is taken from the manifest.

Event message:

VirtualChannelClosedEvent
+ string virtual_channel_name
			

• virtual_channel_name: Specific name of the virtual channel, the namespace is taken from the manifest.