Virtual Channel Client (Windows CE 5.0)
The client component of a virtual channels application is a dynamic-link library (DLL) that is loaded during Terminal Services initialization on the client computer. The DLL must be registered on the client computer. For more information, see Virtual Channel Client Registration.
The following list shows the function that the client DLL exports:
- When RDP is running in Microsoft® ActiveX® Control, the client DLL exports a VirtualChannelEntry function.
- When RDP is running in Graphics, Windowing, and Events Subsystem (GWES), the client DLL exports a VirtualChannelEntryEx function.
Terminal Services calls this function during initialization. The function entry point receives a pointer to a CHANNEL_ENTRY_POINTS or CHANNEL_ENTRY_POINTS_EX structure. This structure contains pointers to the following functions the client DLL calls to access virtual channels.
| Function | Description |
|---|---|
| VirtualChannelInit | Registers the names of the virtual channels to be used by the client and provides a VirtualChannelInitEvent callback through which Terminal Services notifies the client about events that affect the client connection. |
| VirtualChannelInitEx | Registers the names of the virtual channels to be used by the client and provides a VirtualChannelInitEvent callback through which Terminal Services notifies the client about events that affect the client connection.
This function is a virtual extension that protects virtual channels when RDP is running in GWES and multiple sessions are used. |
| VirtualChannelOpen | Opens the client end of a specified virtual channel and provides a VirtualChannelOpenEvent callback through which Terminal Services notifies the client about events that affect the virtual channel. |
| VirtualChannelOpenEx | Opens the client end of a specified virtual channel and provides a VirtualChannelOpenEvent callback through which Terminal Services notifies the client about events that affect the virtual channel.
This function is a virtual extension that protects virtual channels when RDP is running in GWES and multiple sessions are used. |
| VirtualChannelWrite | Writes data to a virtual channel. Terminal Services sends this data to the server end of the virtual channel. The server end calls WTSVirtualChannelRead to read the data. |
| VirtualChannelWriteEx | Writes data to a virtual channel. Terminal Server sends this data to the server end of the virtual channel.
This function is a virtual extension that protects virtual channels when RDP is running in GWES and multiple sessions are used. |
| VirtualChannelClose | Closes a virtual channel. |
| VirtualChannelCloseEx | Closes a virtual channel.
This function is a virtual extension that protects virtual channels when RDP is running in GWES and multiple sessions are used. |
**Note **The following explanation assumes that RDP is running in Microsoft ActiveX Control, and not running in GWES. If RDP is running in GWES, you would use the *Ex functions instead.
The VirtualChannelEntry function must call the VirtualChannelInit function to initialize virtual-channel access. When calling VirtualChannelInit you must pass a pointer to the VirtualChannelInitEvent callback function. Terminal Services calls this function when initialization has been completed, and again when a connection has been established with a Terminal Server.
After the connection is established, you can call the VirtualChannelOpen function to open the virtual channels registered by the VirtualChannelInit call. The VirtualChannelOpen call specifies a pointer to your VirtualChannelOpenEvent callback function.
After the VirtualChannelOpen call returns, you can call the VirtualChannelWrite function to write to the virtual channel. The write operation is asynchronous, so you must not release or reuse the buffer passed to VirtualChannelWrite until Terminal Services calls your VirtualChannelOpenEvent function to indicate the write operation has been completed.
When you call VirtualChannelWrite, you can pass a piece of user data that identifies the write operation. Terminal Services passes this user data back when it calls VirtualChannelOpenEvent to notify you that the operation has been completed. At the server end of the virtual channel, the server add-in calls the WTSVirtualChannelRead function to read the data.
Terminal Services also calls your VirtualChannelOpenEvent function when data is written to the virtual channel by the server component. The server component calls the WTSVirtualChannelWrite function to write data to the server end of the virtual channel.
The client and server components can write data blocks of any size to the virtual channel. Before sending the data, however, Terminal Services breaks the data into segments of CHANNEL_CHUNK_LENGTH bytes. Terminal Services calls your VirtualChannelOpenEvent function once for each data segment, rather than rebuilding the data into a block of the original size. Each call to VirtualChannelOpenEvent indicates the segment's size, the total size written by the server, and whether the data constitutes the beginning, middle, or end of a block written by the server.
VirtualChannelClose closes a channel. However, it is not necessary to explicitly call it, because Terminal Services automatically closes all channels when the client disconnects from the server.
See Also
Send Feedback on this topic to the authors