Fungsi WTSVirtualChannelQuery (wtsapi32.h)

Artikel
08/28/2023

Mengembalikan informasi tentang saluran virtual tertentu.

Sintaks

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

Parameter

[in] hChannelHandle

Tangani ke saluran virtual yang dibuka oleh fungsi WTSVirtualChannelOpen .

unnamedParam2

[out] ppBuffer

Penunjuk ke buffer yang menerima informasi yang diminta.

[out] pBytesReturned

Penunjuk ke variabel yang menerima jumlah byte yang dikembalikan dalam parameter ppBuffer .

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah nilai bukan nol. Panggil fungsi WTSFreeMemory dengan nilai yang dikembalikan dalam parameter ppBuffer untuk membebaskan memori sementara yang dialokasikan oleh WTSVirtualChannelQuery.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Contoh berikut menunjukkan cara mendapatkan akses ke handel file saluran virtual yang dapat digunakan untuk I/O asinkron. Pertama kode membuka saluran virtual dengan menggunakan panggilan ke fungsi WTSVirtualChannelOpen . Kemudian kode memanggil fungsi WTSVirtualChannelQuery , menentukan jenis kelas virtual WTSVirtualFileHandle. WTSVirtualChannelQuery mengembalikan handel file yang dapat Anda gunakan untuk melakukan operasi baca dan tulis asinkron (tumpang tindih). Akhirnya, kode membebaskan memori yang dialokasikan oleh WTSVirtualChannelQuery dengan panggilan ke fungsi WTSFreeMemory , dan menutup saluran virtual dengan panggilan ke fungsi WTSVirtualChannelClose .

Perhatikan bahwa Anda tidak boleh secara eksplisit menutup handel file yang diperoleh dengan memanggil WTSVirtualChannelQuery. Ini karena WTSVirtualChannelClose menutup handel file.

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

Untuk informasi selengkapnya tentang mode tumpang tindih, lihat Sinkronisasi dan Input dan Output yang Tumpang Tindih.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Server minimum yang didukung	Windows Server 2008
Target Platform	Windows
Header	wtsapi32.h
Pustaka	Wtsapi32.lib
DLL	Wtsapi32.dll
Set API	ext-ms-win-session-wtsapi32-l1-1-0 (diperkenalkan dalam Windows 8)

Lihat juga

WTSVirtualChannelBuka

WTS_VIRTUAL_CLASS

Bagikan melalui