DLL du client de canal virtuel

Le client d’une application de canaux virtuels est une DLL qui est chargée pendant l’initialisation des services Bureau à distance sur l’ordinateur client. La DLL doit être inscrite sur l’ordinateur client. Pour plus d’informations, consultez Inscription du client de canal virtuel.

La DLL cliente doit exporter une fonction VirtualChannelEntry , que les services Bureau à distance appellent pendant l’initialisation. Le point d’entrée VirtualChannelEntry reçoit un pointeur vers une structure CHANNEL_ENTRY_POINTS . Cette structure contient des pointeurs vers les fonctions que la DLL cliente appelle pour accéder aux canaux virtuels.

Fonction	Description
VirtualChannelInit	Enregistre les noms des canaux virtuels à utiliser par le client et fournit une fonction de rappel VirtualChannelInitEvent par le biais de laquelle les services Bureau à distance avertit le client des événements qui affectent la connexion du client.
VirtualChannelOpen	Ouvre la fin du client d’un canal virtuel spécifié et fournit une fonction de rappel VirtualChannelOpenEvent par le biais de laquelle les services Bureau à distance notifient le client des événements qui affectent le canal virtuel.
VirtualChannelWrite	Écrit des données dans un canal virtuel. Les services Bureau à distance envoient ces données à l’extrémité du serveur du canal virtuel. L’extrémité du serveur appelle la fonction WTSVirtualChannelRead pour lire les données.
VirtualChannelClose	Ferme un canal virtuel.

La fonction VirtualChannelEntry de votre DLL doit appeler la fonction VirtualChannelInit pour initialiser l’accès aux canaux virtuels. Lorsque vous appelez VirtualChannelInit, vous devez passer un pointeur vers la fonction de rappel VirtualChannelInitEvent . Les services Bureau à distance appellent cette fonction de rappel lorsque l’initialisation est terminée et à nouveau lorsqu’une connexion a été établie avec un serveur hôte de session Bureau à distance (hôte de session Bureau à distance).

Une fois la connexion établie, vous pouvez appeler la fonction VirtualChannelOpen pour ouvrir les canaux virtuels inscrits par l’appel VirtualChannelInit . L’appel VirtualChannelOpen spécifie un pointeur vers votre fonction de rappel VirtualChannelOpenEvent.

Une fois l’appel VirtualChannelOpen retourné, vous pouvez appeler la fonction VirtualChannelWrite pour écrire dans le canal virtuel. L’opération d’écriture étant asynchrone, vous ne devez pas libérer ou réutiliser la mémoire tampon passée à VirtualChannelWrite tant que les services Bureau à distance n’appellent pas votre fonction VirtualChannelOpenEvent pour indiquer que l’opération d’écriture a été effectuée. Lorsque vous appelez VirtualChannelWrite, vous pouvez passer un morceau de données utilisateur qui identifie l’opération d’écriture. Les services Bureau à distance renvoient ces données utilisateur lorsqu’ils appellent VirtualChannelOpenEvent pour vous informer que l’opération est terminée. À l’extrémité du serveur du canal virtuel, le complément serveur appelle la fonction WTSVirtualChannelRead pour lire les données.

Les services Bureau à distance appellent également votre fonction VirtualChannelOpenEvent lorsque les données sont écrites dans le canal virtuel par le module serveur. Le module serveur appelle la fonction WTSVirtualChannelWrite pour écrire des données à l’extrémité du serveur du canal virtuel.

Les modules client et serveur peuvent écrire des blocs de données de n’importe quelle taille dans le canal virtuel. Toutefois, avant d’envoyer les données, les services Bureau à distance segmentent les données en blocs de CHANNEL_CHUNK_LENGTH octets. Les services Bureau à distance appellent votre fonction VirtualChannelOpenEvent une fois pour chaque bloc de données, au lieu de reconstruire les données dans un bloc de la taille d’origine. Chaque appel à VirtualChannelOpenEvent indique la taille du bloc, la taille totale écrite par le serveur et si les données constituent le début, le milieu ou la fin d’un bloc écrit par le serveur.

Vous pouvez appeler la fonction VirtualChannelClose pour fermer un canal. Toutefois, il n’est pas nécessaire de l’appeler, car les services Bureau à distance ferment automatiquement tous les canaux lorsque le client se déconnecte du serveur.