WTSVirtualChannelQuery function (wtsapi32.h)

Returns information about a specified virtual channel.

Syntax

BOOL WTSVirtualChannelQuery(
  [in]  HANDLE            hChannelHandle,
        WTS_VIRTUAL_CLASS unnamedParam2,
  [out] PVOID             *ppBuffer,
  [out] DWORD             *pBytesReturned
);

Parameters

[in] hChannelHandle

Handle to a virtual channel opened by the WTSVirtualChannelOpen function.

unnamedParam2

[out] ppBuffer

Pointer to a buffer that receives the requested information.

[out] pBytesReturned

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.

Remarks

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;
    DWORD result = ERROR_SUCCESS;
    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(
                            vcHandle,
                            WTSVirtualFileHandle,
                            &vcFileHandlePtr,
                            &len
                            )) 
        {
            result = GetLastError();
        }
    }

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

        //
        //  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) 
    {
        WTSVirtualChannelClose(vcHandle);
        vcFileHandle = NULL;
    }

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

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	wtsapi32.h
Library	Wtsapi32.lib
DLL	Wtsapi32.dll
API set	ext-ms-win-session-wtsapi32-l1-1-0 (introduced in Windows 8)

See also

WTSVirtualChannelOpen

WTS_VIRTUAL_CLASS