Export (0) Print
Expand All
Expand Minimize

WTSVirtualChannelQuery function

Returns information about a specified virtual channel.

Syntax


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

Parameters

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.

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

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Wtsapi32.h

Library

Wtsapi32.lib

DLL

Wtsapi32.dll

See also

WTSVirtualChannelOpen
WTS_VIRTUAL_CLASS

 

 

Show:
© 2014 Microsoft