WTSVirtualChannelQuery 函式 (wtsapi32.h)

傳回指定之虛擬通道的相關信息。

語法

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

參數

[in] hChannelHandle

WTSVirtualChannelOpen 函式所開啟之虛擬通道的句柄。

unnamedParam2

[out] ppBuffer

接收所要求信息的緩衝區指標。

[out] pBytesReturned

接收 ppBuffer 參數中傳回之位元組數目的變數指標。

傳回值

如果函式成功，則傳回值是非零值。 使用 ppBuffer 參數中傳回的值呼叫 WTSFreeMemory 函式，以釋放由 WTSVirtualChannelQuery 配置的暫存記憶體。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

下列範例示範如何存取可用於異步 I/O 的虛擬通道檔案句柄。 首先，程式代碼會使用 對 WTSVirtualChannelOpen 函式的呼叫來開啟虛擬通道。 然後程式代碼會呼叫 WTSVirtualChannelQuery 函 式，並指定 WTSVirtualFileHandle 虛擬類別類型。 WTSVirtualChannelQuery 會傳回可用來執行異步 (重疊) 讀取和寫入作業的檔案句柄。 最後，程式代碼會釋放 WTSVirtualChannelQuery 所配置的記憶體，並呼叫 WTSFreeMemory 函式，並使用 WTSVirtualChannelClose 函式的呼叫來關閉虛擬通道。

請注意，您不應該明確關閉呼叫 WTSVirtualChannelQuery 取得的檔案句柄。 這是因為 WTSVirtualChannelClose 會關閉檔句柄。

    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;
    }

如需重疊模式的詳細資訊，請參閱 同步處理和重疊的輸入和輸出。

規格需求

需求	值
最低支援的用戶端	Windows Vista
最低支援的伺服器	Windows Server 2008
目標平台	Windows
標頭	wtsapi32.h
程式庫	Wtsapi32.lib
Dll	Wtsapi32.dll
API 集合	ext-ms-win-session-wtsapi32-l1-1-0 (於 Windows 8)

另請參閱

WTSVirtualChannelOpen

WTS_VIRTUAL_CLASS