Funzione WTSVirtualChannelQuery (wtsapi32.h)

Articolo
08/28/2023

Restituisce informazioni su un canale virtuale specificato.

Sintassi

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

Parametri

[in] hChannelHandle

Gestire in un canale virtuale aperto dalla funzione WTSVirtualChannelOpen .

unnamedParam2

[out] ppBuffer

Puntatore a un buffer che riceve le informazioni richieste.

[out] pBytesReturned

Puntatore a una variabile che riceve il numero di byte restituiti nel parametro ppBuffer .

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un valore diverso da zero. Chiamare la funzione WTSFreeMemory con il valore restituito nel parametro ppBuffer per liberare la memoria temporanea allocata da WTSVirtualChannelQuery.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

L'esempio seguente illustra come ottenere l'accesso a un handle di file del canale virtuale che può essere usato per le operazioni di I/O asincrone. Per prima cosa, il codice apre un canale virtuale usando una chiamata alla funzione WTSVirtualChannelOpen . Il codice chiama quindi la funzione WTSVirtualChannelQuery , specificando il tipo di classe virtuale WTSVirtualFileHandle. WTSVirtualChannelQuery restituisce un handle di file che è possibile usare per eseguire operazioni di lettura e scrittura asincrone (sovrapposte). Infine, il codice libera la memoria allocata da WTSVirtualChannelQuery con una chiamata alla funzione WTSFreeMemory e chiude il canale virtuale con una chiamata alla funzione WTSVirtualChannelClose .

Si noti che non è consigliabile chiudere in modo esplicito l'handle di file ottenuto chiamando WTSVirtualChannelQuery. Il motivo è che WTSVirtualChannelClose chiude l'handle di 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;
    }

Per altre informazioni sulla modalità sovrapposta, vedere Sincronizzazione e input e output sovrapposti.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	wtsapi32.h
Libreria	Wtsapi32.lib
DLL	Wtsapi32.dll
Set di API	ext-ms-win-session-wtsapi32-l1-1-0 (introdotto in Windows 8)

Vedi anche

WTSVirtualChannelOpen

WTS_VIRTUAL_CLASS

Condividi tramite