Função WTSVirtualChannelQuery (wtsapi32.h)

Retorna informações sobre um canal virtual especificado.

Sintaxe

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

Parâmetros

[in] hChannelHandle

Manipule para um canal virtual aberto pela função WTSVirtualChannelOpen .

unnamedParam2

[out] ppBuffer

Ponteiro para um buffer que recebe as informações solicitadas.

[out] pBytesReturned

Ponteiro para uma variável que recebe o número de bytes retornados no parâmetro ppBuffer .

Retornar valor

Se a função for bem-sucedida, o valor retornado será um valor diferente de zero. Chame a função WTSFreeMemory com o valor retornado no parâmetro ppBuffer para liberar a memória temporária alocada por WTSVirtualChannelQuery.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

O exemplo a seguir mostra como obter acesso a um identificador de arquivo de canal virtual que pode ser usado para E/S assíncrona. Primeiro, o código abre um canal virtual usando uma chamada para a função WTSVirtualChannelOpen . Em seguida, o código chama a função WTSVirtualChannelQuery , especificando o tipo de classe virtual WTSVirtualFileHandle. WTSVirtualChannelQuery retorna um identificador de arquivo que você pode usar para executar operações de leitura e gravação assíncronas (sobrepostas). Por fim, o código libera a memória alocada por WTSVirtualChannelQuery com uma chamada para a função WTSFreeMemory e fecha o canal virtual com uma chamada para a função WTSVirtualChannelClose .

Observe que você não deve fechar explicitamente o identificador de arquivo obtido chamando WTSVirtualChannelQuery. Isso ocorre porque o WTSVirtualChannelClose fecha o identificador de arquivo.

    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 obter mais informações sobre o modo sobreposto, consulte Sincronização e Entrada e Saída Sobrepostas.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	wtsapi32.h
Biblioteca	Wtsapi32.lib
DLL	Wtsapi32.dll
Conjunto de APIs	ext-ms-win-session-wtsapi32-l1-1-0 (introduzido em Windows 8)

Confira também

WTSVirtualChannelOpen

WTS_VIRTUAL_CLASS