Architecture

A Citrix Independent Computing Architecture (ICA) virtual channel is a bidirectional, error-free connection for the exchange of generalized packet data between a server running Citrix Virtual Apps and Desktops, and a client device. You can use virtual channels to add functionality to clients. Uses for virtual channels include:

• Support for administrative functions
• New data streams (audio and video)
• New devices, such as scanners, card readers, and joysticks

Virtual channel overview

An ICA virtual channel is a bidirectional, error-free connection for the exchange of generalized packet data between a client and a server running Citrix Virtual Apps and Desktops. Each implementation of an ICA virtual channel consists of two components:

• Server-side portion on the computer running Citrix Virtual Apps and Desktops: The virtual channel on the server-side is a normal Win32 process. It can be an application or a Windows NT service.

• Client-side: The client-side custom virtual driver runs in the context of the client. You must implement the virtual driver by including a virtual channel SDK JavaScript file along with custom Virtual Channel code. When you configure Citrix Workspace app, Citrix Workspace app communicates with the Third-party custom Virtual Channel code by sending messages with the help of SDK and calls the appropriate call-backs provided at the time of registering the virtual channel.

Citrix Workspace app Virtual Channel SDK is responsible for de-multiplexing the virtual channel data from the ICA data stream and routing it to the correct call-back of the registered virtual channel. It is also responsible for sending the data using the appropriate object to the server in coordination with the Citrix Workspace app. Citrix Workspace app does not know any data package detail for each virtual channel and it only transfers all available data between the server and the client virtual driver.

The following is an overview of the client-server data exchange using a virtual channel:

• The client connects to the server running Citrix Virtual Apps and Desktops. The client passes information about the virtual channels that it supports to the server.

• The server-side application starts, obtains a handle to the virtual channel and optionally queries for additional information about the channel.

• Both the client-side virtual driver and server-side application can send data initiatively:

  • If the server application has data to send to the client, the data is sent to the client immediately. When the client receives the data, Citrix Workspace app de-multiplexes the virtual channel data from the ICA stream and passes it to the third-party code implementing the virtual channel. Virtual Channel SDK routes the data to the appropriate call-back of the registered object for that Virtual channel.

  • If the client virtual driver has data to send to the server, the data is also sent immediately.

• When the ICA session disconnects or something unexpected occurs, such as runtime exceptions or errors, the virtual channel closes and the client virtual driver (Third-party code) disconnects from Citrix Workspace app.

ICA and virtual channel data packets

Virtual channel data packets are encapsulated in the ICA stream between the client and the server. Because ICA is a presentation-level protocol and runs over several different transport layer protocols, the virtual channel API enables you to write your protocols without worrying about the underlying transport layer protocols. The data packet is preserved.

For example, if 100 bytes are sent to the server, the same 100 bytes is received by the server when the virtual channel is demultiplexed from the ICA data stream. The compiled code runs independently of the currently configured transport protocol. The ICA engine provides the following services to the virtual channel:

• Packet encapsulation
• Error correction

Packet encapsulation

ICA virtual channels are packet-based, meaning that if one side performs a write with a certain amount of data, the other side receives the entire block of data when it performs a read. This contrasts with TCP, for example, which is stream-based and requires a higher-level protocol to parse out packet boundaries. Stated another way, virtual channel packets are contained within the ICA stream, which is managed separately by the system software.

Error correction

ICA provides reliability mechanisms even when the underlying transport is unreliable. This guarantees that connections are error-free and that data is received in the order in which it is sent.

Workspace app and virtual driver interaction

In Citrix Workspace app, the custom virtual driver is implemented as a Third-party code and must be installed before an ICA session is launched. Third-party code needs to include the Virtual Channel SDK JavaScript file and register to the Virtual Channel by giving appropriate parameters. In addition, the Third-party code implementing the virtual channel and the name of the virtual channel have to be configured for Citrix Workspace app to bind. When you launch an ICA session, Citrix Workspace app queries each Virtual Channel by sending messages to the Third-party code. SDK calls the functions registered for different messages and the Third-party code needs to respond with the replies in the format defined. If the Third-party code is not installed or the Virtual Channel is not registered with the SDK or the Citrix Workspace app is not configured correctly, then the Virtual Channel is not initialized but the sessions would be launched.

The following process flow happens at the session start:

• On a session launch, using the configuration you can fetch the custom Virtual Channel information. This is used by the session for binding the Virtual Channel between the Third-party code and Citrix Workspace app session.

• Session sends a message when the virtual channel is initialized. The Virtual Channel SDK handles the message and calls the call-back set for the driverOpen during virtual channel registration by giving the session Id and the stream name. Call-back present in the third-party code must reply with the enable flag set to true or false along with the sessionId and the virtual channel name. If enable is set to true, further initialization of the virtual channel happens. Otherwise, the virtual channel is ignored. If the virtual channel is not registered with the SDK, then the virtual channel is ignored.

• On sending enable true, the session would send another message to collect the virtual channel information that must be sent to the server during initialization. SDK would get the message and call the call-back registered for driver info of the registered VC object. The call-back present in the third-party implementation must reply with the appropriate packet if applicable or reply with null.

• Session would send all the capabilities to the server and on successful initialization of virtual channel, any data sent by the server to Citrix Workspace app for HTML5 session is forwarded to the Virtual Channel SDK. Virtual Channel SDK calls the icaDataArrival call-back of the registered virtual channel object. Call-back should parse the packet and send the reply packet using the sendData method of the registered virtual channel object. Utils has been provided to make packet reading and construction of the reply packet easier.

• On disconnect of the session or the reload/crash/uninstall of the third-party code Virtual Channel SDK calls the driverClose call-back of the Third-party code with the appropriate session Id and stream name which can be used to handle any clean-up of the virtual channel for that session.

Virtual channel packets

ICA does not define the contents of a virtual channel packet. The contents are specific to the particular virtual channel and are not interpreted or managed by the ICA data stream manager. You must develop your protocol for the virtual channel data.

Because Citrix Workspace app and the Virtual Channel SDK are not aware of the details of the virtual channel package, they pass all available data in the ICA stream to the virtual driver by calling icaDataArrival. Packets received by the icaDataArrival function of the virtual channel are Uint8Arrays with appropriate details of offset and length. The virtual channel also needs to send the data to the server in the same format. The session creates the port connection and the data is sent/received over this port. The Maximum size of the data that can be sent/received depends on the implementation.