Modes Type de canal nommé, Lecture et Attente

Le serveur de canal spécifie le mode de type de canal, le mode lecture et le mode d’attente dans le paramètre dwPipeMode de la fonction CreateNamedPipe . Les clients de canal peuvent spécifier ces modes de canal pour leurs poignées de canal à l’aide de la fonction CreateFile .

Type Mode

Le mode de type d’un canal détermine la façon dont les données sont écrites dans un canal nommé. Les données peuvent être transmises via un canal nommé sous la forme d’un flux d’octets ou d’un flux de messages. Le serveur de canal spécifie le type de canal lors de l’appel de CreateNamedPipe pour créer un instance d’un canal nommé. Les modes de type doivent être les mêmes pour toutes les instances d’un canal.

Pour créer un canal de type octet, spécifiez PIPE_TYPE_BYTE ou utilisez la valeur par défaut. Les données sont écrites dans le canal sous la forme d’un flux d’octets, et le système ne fait pas de distinction entre les octets écrits dans différentes opérations d’écriture.

Pour créer un canal de type message, spécifiez PIPE_TYPE_MESSAGE. Le système traite les octets écrits dans chaque opération d’écriture dans le canal comme une unité de message. Le système effectue toujours des opérations d’écriture sur les canaux de type message comme si le mode d’écriture directe était activé.

Mode lecture

Le mode de lecture d’un canal détermine la façon dont les données sont lues à partir d’un canal nommé. Le serveur de canal spécifie le mode de lecture initial d’un handle de canal lors de l’appel de CreateNamedPipe. Les données peuvent être lues en mode lecture d’octets ou en mode lecture de message. Un handle vers un canal de type octet peut être en mode lecture d’octets uniquement. Un handle vers un canal de type message peut être en mode lecture d’octets ou de lecture de message. Pour un canal de type message, le mode de lecture peut être différent pour les handles serveur et client vers le même canal instance.

Pour créer le handle de canal en mode lecture d’octets, spécifiez PIPE_READMODE_BYTE ou utilisez la valeur par défaut. Les données sont lues à partir du canal sous forme de flux d’octets. Une opération de lecture se termine correctement lorsque tous les octets disponibles dans le canal sont lus ou lorsque le nombre spécifié d’octets est lu.

Pour créer le handle de canal en mode lecture de message, spécifiez PIPE_READMODE_MESSAGE. Les données sont lues à partir du canal en tant que flux de messages. Une opération de lecture est terminée avec succès uniquement lorsque le message entier est lu. Si le nombre d’octets à lire spécifié est inférieur à la taille du message suivant, la fonction lit autant que possible le message avant de renvoyer zéro (la fonction GetLastError retourne ERROR_MORE_DATA). Le reste du message peut être lu à l’aide d’une autre opération de lecture.

Pour un client de canal, un handle de canal retourné par CreateFile est toujours en mode lecture d’octets initialement. Les clients de canal et les serveurs de canal peuvent utiliser la fonction SetNamedPipeHandleState pour modifier le mode de lecture d’un handle de canal. Le handle de canal doit avoir le droit d’accès FILE_WRITE_ATTRIBUTES.

Mode d’attente

Le mode d’attente d’un handle de canal détermine la façon dont les fonctions ReadFile, WriteFile et ConnectNamedPipe gèrent les opérations longues. En mode d’attente de blocage, les fonctions attendent indéfiniment qu’un processus à l’autre extrémité du canal termine une opération. En mode d’attente sans blocage, les fonctions retournent immédiatement dans des situations qui nécessiteraient sinon une attente indéfinie.

Une opération ReadFile est affectée par le mode d’attente d’une poignée de canal lorsque le canal est vide. Avec un handle d’attente de blocage, l’opération n’est pas terminée correctement tant que les données ne sont pas disponibles à partir d’un thread d’écriture à l’autre extrémité du canal. À l’aide d’un handle d’attente non bloquant, la fonction retourne immédiatement zéro et la fonction GetLastError retourne ERROR_NO_DATA.

Une opération WriteFile est affectée par le mode d’attente d’un handle de canal lorsqu’il n’y a pas suffisamment d’espace dans la mémoire tampon du canal. Avec un handle d’attente bloquant, l’opération d’écriture ne peut pas réussir tant que l’espace suffisant n’est pas créé dans la mémoire tampon par un thread lisant à l’autre extrémité du canal. Avec un handle d’attente non bloquant, l’opération d’écriture retourne immédiatement une valeur différente de zéro, sans écrire d’octets (pour un canal de type message) ou après avoir écrit autant d’octets que la mémoire tampon contient (pour un canal de type octet).

Une opération ConnectNamedPipe est affectée par le mode d’attente d’un handle de canal lorsqu’aucun client n’est connecté ou n’attend de se connecter au instance de canal. Avec un handle d’attente bloquant, l’opération de connexion ne réussit pas tant qu’un client de canal ne se connecte pas au canal instance en appelant la fonction CreateFile ou CallNamedPipe. Avec un handle d’attente non bloquant, l’opération de connexion retourne immédiatement zéro et la fonction GetLastError retourne ERROR_PIPE_LISTENING.

Par défaut, tous les handles de canal nommés retournés par la fonction CreateNamedPipe ou CreateFile sont créés avec le mode d’attente bloquant activé. Pour créer le canal en mode d’attente sans blocage, le serveur de canal spécifie PIPE_NOWAIT lors de l’appel de CreateNamedPipe.

Les clients de canal et les serveurs de canal peuvent modifier le mode d’attente d’un handle de canal en spécifiant PIPE_WAIT ou PIPE_NOWAIT dans un appel à la fonction SetNamedPipeHandleState .

Notes

Le mode d’attente sans blocage est pris en charge pour la compatibilité avec Microsoft LAN Manager version 2.0. Ce mode ne doit pas être utilisé pour obtenir des entrées et sorties (E/S) qui se chevauchent avec des canaux nommés. Les E/S qui se chevauchent doivent être utilisées à la place, car elles permettent aux opérations chronophages de s’exécuter en arrière-plan après le retour de la fonction. Pour plus d’informations sur les E/S qui se chevauchent, consultez Entrée et sortie synchrones et chevauchements.