Type de canal nommé, lecture et modes d’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 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é en tant que flux d’octets ou en tant que flux de messages. Le serveur de canal spécifie le type de canal lors de l’appel de CreateNamedPipe pour créer une instance d’un canal nommé. Les modes de type doivent être identiques 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 la 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 sur le canal comme unité de message. Le système effectue toujours des opérations d’écriture sur des canaux de type message comme si le mode é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 CreateNamedPipe. Les données peuvent être lues en mode lecture octet ou en mode lecture de message. Un handle vers un canal de type octet peut être en mode lecture octet uniquement. Un handle vers un canal de type message peut être en mode lecture octet ou lecture de message. Pour un canal de type message, le mode de lecture peut être différent pour les handles de serveur et de client avec la même instance de canal.

Pour créer le handle de canal en mode lecture octet, spécifiez PIPE_READMODE_BYTE ou utilisez la valeur par défaut. Les données sont lues à partir du canal sous la forme d’un flux d’octets. Une opération de lecture est effectuée avec succès 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 sous forme de flux de messages. Une opération de lecture est effectuée correctement uniquement lorsque l’intégralité du message est lue. Si le nombre spécifié d’octets à lire est inférieur à la taille du message suivant, la fonction lit autant que possible le message avant de retourner 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 octet 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 disposer du droit d’accès FILE_WRITE_ATTRIBUTES.

Mode d’attente

Le mode d’attente d’un handle de canal détermine comment les fonctions ReadFile, WriteFileet ConnectNamedPipe gèrent de longues opérations. En mode blocage-attente, les fonctions attendent indéfiniment un processus à l’autre extrémité du canal pour effectuer une opération. En mode non bloquant, les fonctions retournent immédiatement dans des situations qui nécessiteraient sinon une attente indéfinie.

Une opération de ReadFile est affectée par le mode d’attente d’un handle de canal lorsque le canal est vide. Avec un handle d’attente bloquant, l’opération n’est pas terminée correctement tant que les données ne sont pas disponibles à partir d’un thread écrit à l’autre extrémité du canal. À l’aide d’un handle d’attente non bloquant, la fonction retourne zéro immédiatement, 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 y a un espace insuffisant 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 une lecture de thread à partir de 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 qu’il attend de se connecter à l’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 à l’instance de canal en appelant la fonctionCreateFileou Fonction CallNamedPipe. Avec un handle d’attente non bloquant, l’opération de connexion retourne zéro immédiatement, 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 non bloquant, 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.