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 パラメーターで返されるバイト数を受け取る変数へのポインター。

戻り値

関数が成功した場合、戻り値は 0 以外の値になります。 WTSVirtualChannelQuery によって割り当てられた一時メモリを解放するには、ppBuffer パラメーターで返される値を使用して WTSFreeMemory 関数を呼び出します。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

次の例では、非同期 I/O に使用できる仮想チャネル ファイル ハンドルにアクセスする方法を示します。 最初に、 WTSVirtualChannelOpen 関数の呼び出しを使用して仮想チャネルを開きます。 次に、 WTSVirtualFileHandle 仮想クラス型を指定して、WTSVirtualChannelQuery 関数を呼び出します。 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
Library	Wtsapi32.lib
[DLL]	Wtsapi32.dll
API セット	ext-ms-win-session-wtsapi32-l1-1-0 (Windows 8で導入)

こちらもご覧ください

WTSVirtualChannelOpen

WTS_VIRTUAL_CLASS