WTSVirtualChannelQuery-Funktion (wtsapi32.h)

Gibt Informationen zu einem angegebenen virtuellen Kanal zurück.

Syntax

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

Parameter

[in] hChannelHandle

Handle mit einem virtuellen Kanal, der von der FUNKTION WTSVirtualChannelOpen geöffnet wird.

unnamedParam2

[out] ppBuffer

Zeiger auf einen Puffer, der die angeforderten Informationen empfängt.

[out] pBytesReturned

Zeiger auf eine Variable, die die Anzahl von Bytes empfängt, die im ppBuffer-Parameter zurückgegeben werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Nichtzero-Wert. Rufen Sie die WTSFreeMemory-Funktion mit dem wert auf, der im ppBuffer-Parameter zurückgegeben wird, um den von WTSVirtualChannelQuery zugewiesenen temporären Arbeitsspeicher freizugeben.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Das folgende Beispiel zeigt, wie Sie Zugriff auf ein Dateihandle für virtuelle Kanäle erhalten, das für asynchrone E/A-Vorgänge verwendet werden kann. Zunächst öffnet der Code mithilfe eines Aufrufs der Funktion WTSVirtualChannelOpen einen virtuellen Kanal. Anschließend ruft der Code die FUNKTION WTSVirtualChannelQuery auf, wobei der virtuelle Klassentyp WTSVirtualFileHandle angegeben wird. WTSVirtualChannelQuery gibt ein Dateihandle zurück, mit dem Sie asynchrone (überlappende) Lese- und Schreibvorgänge ausführen können. Schließlich gibt der Code den von WTSVirtualChannelQuery zugewiesenen Arbeitsspeicher mit einem Aufruf der WTSFreeMemory-Funktion frei und schließt den virtuellen Kanal mit einem Aufruf der FUNKTION WTSVirtualChannelClose .

Beachten Sie, dass Sie das Durch Aufrufen von WTSVirtualChannelQuery abgerufene Dateihandle nicht explizit schließen sollten. Dies liegt daran , dass WTSVirtualChannelClose das Dateihandle schließt.

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

Weitere Informationen zum überlappenden Modus finden Sie unter Synchronisierung und überlappende Eingabe und Ausgabe.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	wtsapi32.h
Bibliothek	Wtsapi32.lib
DLL	Wtsapi32.dll
APIs	ext-ms-win-session-wtsapi32-l1-1-0 (eingeführt in Windows 8)

Weitere Informationen

WTSVirtualChannelOpen

WTS_VIRTUAL_CLASS