WTSVirtualChannelQuery, fonction (wtsapi32.h)

Article
03/04/2024

Retourne des informations sur un canal virtuel spécifié.

Syntaxe

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

Paramètres

[in] hChannelHandle

Gérez vers un canal virtuel ouvert par la fonction WTSVirtualChannelOpen .

unnamedParam2

[out] ppBuffer

Pointeur vers une mémoire tampon qui reçoit les informations demandées.

[out] pBytesReturned

Pointeur vers une variable qui reçoit le nombre d’octets retournés dans le paramètre ppBuffer .

Valeur retournée

Si la fonction réussit, la valeur de retour est une valeur différente de zéro. Appelez la fonction WTSFreeMemory avec la valeur retournée dans le paramètre ppBuffer pour libérer la mémoire temporaire allouée par WTSVirtualChannelQuery.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

L’exemple suivant montre comment accéder à un handle de fichier de canal virtuel qui peut être utilisé pour les E/S asynchrones. Tout d’abord, le code ouvre un canal virtuel à l’aide d’un appel à la fonction WTSVirtualChannelOpen . Ensuite, le code appelle la fonction WTSVirtualChannelQuery , en spécifiant le type de classe virtuelle WTSVirtualFileHandle. WTSVirtualChannelQuery retourne un handle de fichier que vous pouvez utiliser pour effectuer des opérations de lecture et d’écriture asynchrones (superposées). Enfin, le code libère la mémoire allouée par WTSVirtualChannelQuery avec un appel à la fonction WTSFreeMemory et ferme le canal virtuel avec un appel à la fonction WTSVirtualChannelClose .

Notez que vous ne devez pas fermer explicitement le handle de fichier obtenu en appelant WTSVirtualChannelQuery. Cela est dû au fait que WTSVirtualChannelClose ferme le handle de fichier.

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

Pour plus d’informations sur le mode chevauché, consultez Synchronisation et Entrée et sortie superposées.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	wtsapi32.h
Bibliothèque	Wtsapi32.lib
DLL	Wtsapi32.dll
Ensemble d’API	ext-ms-win-session-wtsapi32-l1-1-0 (introduit dans Windows 8)

Voir aussi

WTSVirtualChannelOpen

WTS_VIRTUAL_CLASS

Partager via