Virtual Channel Client
The client component of a virtual channels application is a dynamic-link library (DLL) 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 client DLL exports a VirtualChannelEntry function, which Terminal Services calls during initialization. The VirtualChannelEntry entry point receives a pointer to a CHANNEL_ENTRY_POINTS 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. |
| 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. |
| 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. |
| VirtualChannelClose | Closes a virtual channel. |
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
Last updated on Saturday, April 10, 2004
© 1992-2003 Microsoft Corporation. All rights reserved.