WTSVirtualChannelRead function

Reads data from the server end of a virtual channel.

WTSVirtualChannelRead reads the data written by a VirtualChannelWrite call at the client end of the virtual channel.


BOOL WTSVirtualChannelRead(
  _In_  HANDLE hChannelHandle,
  _In_  ULONG  TimeOut,
  _Out_ PCHAR  Buffer,
  _In_  ULONG  BufferSize,
  _Out_ PULONG pBytesRead


hChannelHandle [in]

Handle to a virtual channel opened by the WTSVirtualChannelOpen function.

TimeOut [in]

Specifies the time-out, in milliseconds. If TimeOut is zero, WTSVirtualChannelRead returns immediately if there is no data to read. If TimeOut is INFINITE (defined in Winbase.h), the function waits indefinitely until there is data to read.

Buffer [out]

Pointer to a buffer that receives a chunk of data read from the server end of the virtual channel. The maximum amount of data that the server can receive in a single WTSVirtualChannelRead call is CHANNEL_CHUNK_LENGTH bytes. If the client's VirtualChannelWrite call writes a larger block of data, the server must make multiple WTSVirtualChannelRead calls.

In certain cases, Remote Desktop Services places a CHANNEL_PDU_HEADER structure at the beginning of each chunk of data read by the WTSVirtualChannelRead function. This will occur if the client DLL sets the CHANNEL_OPTION_SHOW_PROTOCOL option when it calls the VirtualChannelInit function to initialize the virtual channel. This will also occur if the channel is a dynamic virtual channel written to by using the IWTSVirtualChannel::Write method. Otherwise, the buffer receives only the data written in the VirtualChannelWrite call.

BufferSize [in]

Specifies the size, in bytes, of Buffer. If the chunk of data in Buffer will be preceded by a CHANNEL_PDU_HEADER structure, the value of this parameter should be at least CHANNEL_PDU_LENGTH. Otherwise, the value of this parameter should be at least CHANNEL_CHUNK_LENGTH.

pBytesRead [out]

Pointer to a variable that receives the number of bytes read.

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.


Note  WTSVirtualChannelRead is not thread safe. To access a virtual channel from multiple threads, or to do asynchronous IO through a virtual channel, use WTSVirtualChannelQuery with WTSVirtualFileHandle.


Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2008







See also