Функция WTSVirtualChannelQuery (wtsapi32.h)

Статья
08/28/2023

Возвращает сведения об указанном виртуальном канале.

Синтаксис

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

Параметры

[in] hChannelHandle

Обработка виртуального канала, открытого функцией WTSVirtualChannelOpen .

unnamedParam2

[out] ppBuffer

Указатель на буфер, который получает запрошенные сведения.

[out] pBytesReturned

Указатель на переменную, которая получает количество байтов, возвращаемых в параметре ppBuffer .

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет ненулевым. Вызовите функцию WTSFreeMemory со значением, возвращенным в параметре ppBuffer , чтобы освободить временную память, выделенную WTSVirtualChannelQuery.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

В следующем примере показано, как получить доступ к дескриптором файла виртуального канала, который можно использовать для асинхронного ввода-вывода. Сначала код открывает виртуальный канал с помощью вызова функции 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
Header	wtsapi32.h
Библиотека	Wtsapi32.lib
DLL	Wtsapi32.dll
Набор API	ext-ms-win-session-wtsapi32-l1-1-0 (представлено в Windows 8)

См. также раздел

WTSVirtualChannelOpen

WTS_VIRTUAL_CLASS