Export (0) Print
Expand All
Expand Minimize
2 out of 2 rated this helpful - Rate this topic

WTSVirtualChannelQuery function

Returns information about a specified virtual channel.


BOOL WTSVirtualChannelQuery(
  _In_   HANDLE hChannelHandle,
  _In_   WTS_VIRTUAL_CLASS WtsVirtualClass,
  _Out_  PVOID *ppBuffer,
  _Out_  DWORD *pBytesReturned


hChannelHandle [in]

Handle to a virtual channel opened by the WTSVirtualChannelOpen function.

WtsVirtualClass [in]

Specifies the type of information returned in the ppBuffer parameter. This parameter can be a value from the WTS_VIRTUAL_CLASS enumeration type.

ppBuffer [out]

Pointer to a buffer that receives the requested information.

pBytesReturned [out]

Pointer to a variable that receives the number of bytes returned in the ppBuffer parameter.

Return value

If the function succeeds, the return value is a nonzero value. Call the WTSFreeMemory function with the value returned in the ppBuffer parameter to free the temporary memory allocated by WTSVirtualChannelQuery.

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


The following example shows how to gain access to a virtual channel file handle that can be used for asynchronous I/O. First the code opens a virtual channel by using a call to the WTSVirtualChannelOpen function. Then the code calls the WTSVirtualChannelQuery function, specifying the WTSVirtualFileHandle virtual class type. WTSVirtualChannelQuery returns a file handle that you can use to perform asynchronous (overlapped) read and write operations. Finally, the code frees the memory allocated by WTSVirtualChannelQuery with a call to the WTSFreeMemory function, and closes the virtual channel with a call to the WTSVirtualChannelClose function.

Note that you should not explicitly close the file handle obtained by calling WTSVirtualChannelQuery. This is because WTSVirtualChannelClose closes the file handle.

    PVOID vcFileHandlePtr = NULL;
    DWORD len;
    HANDLE vcHandle = NULL;
    HANDLE vcFileHandle = NULL;

    //  Open a virtual channel.
    vcHandle = WTSVirtualChannelOpen(
                      WTS_CURRENT_SERVER_HANDLE, // Current TS Server
                      WTS_CURRENT_SESSION,       // Current TS Session
                      (LPSTR) "TSTCHNL"                 // Channel name

    if (vcHandle == NULL) 
        result = GetLastError();

    //  Gain access to the underlying file handle for 
    //   asynchronous I/O. 
    if (result == ERROR_SUCCESS) 
        if (!WTSVirtualChannelQuery(
            result = GetLastError();

    //  Copy the data and
    //   free the buffer allocated by WTSVirtualChannelQuery.
    if (result == ERROR_SUCCESS) 
        memcpy(&vcFileHandle, vcFileHandlePtr, sizeof(vcFileHandle));

        //  Use vcFileHandle for overlapped reads and writes here.

    //  Call WTSVirtualChannelClose to close the virtual channel. 
    //   Note: do not close the file handle.
    if (vcHandle != NULL) 
        vcFileHandle = NULL;

For more information about overlapped mode, see Synchronization and Overlapped Input and Output.


Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003







See also




Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
© 2014 Microsoft. All rights reserved.