Función WTSVirtualChannelQuery (wtsapi32.h)

Devuelve información sobre un canal virtual especificado.

Sintaxis

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

Parámetros

[in] hChannelHandle

Controle a un canal virtual abierto por la función WTSVirtualChannelOpen .

unnamedParam2

[out] ppBuffer

Puntero a un búfer que recibe la información solicitada.

[out] pBytesReturned

Puntero a una variable que recibe el número de bytes devueltos en el parámetro ppBuffer .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un valor distinto de cero. Llame a la función WTSFreeMemory con el valor devuelto en el parámetro ppBuffer para liberar la memoria temporal asignada por WTSVirtualChannelQuery.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

En el ejemplo siguiente se muestra cómo obtener acceso a un identificador de archivo de canal virtual que se puede usar para E/S asincrónica. En primer lugar, el código abre un canal virtual mediante una llamada a la función WTSVirtualChannelOpen . A continuación, el código llama a la función WTSVirtualChannelQuery , especificando el tipo de clase virtual WTSVirtualFileHandle. WTSVirtualChannelQuery devuelve un identificador de archivo que puede usar para realizar operaciones asincrónicas (superpuestas) de lectura y escritura. Por último, el código libera la memoria asignada por WTSVirtualChannelQuery con una llamada a la función WTSFreeMemory y cierra el canal virtual con una llamada a la función WTSVirtualChannelClose .

Tenga en cuenta que no debe cerrar explícitamente el identificador de archivo obtenido llamando a WTSVirtualChannelQuery. Esto se debe a que WTSVirtualChannelClose cierra el identificador de archivo.

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

Para obtener más información sobre el modo superpuesto, vea Sincronización y entrada y salida superpuestas.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	wtsapi32.h
Library	Wtsapi32.lib
Archivo DLL	Wtsapi32.dll
Conjunto de API	ext-ms-win-session-wtsapi32-l1-1-0 (introducido en Windows 8)

Consulte también

WTSVirtualChannelOpen

WTS_VIRTUAL_CLASS