Fonction ConnectNamedPipe (namedpipeapi.h)

Article
08/25/2023

Permet à un processus de serveur de canal nommé d’attendre qu’un processus client se connecte à un instance d’un canal nommé. Un processus client se connecte en appelant la fonction CreateFile ou CallNamedPipe .

Syntaxe

BOOL ConnectNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Paramètres

[in] hNamedPipe

Handle vers l’extrémité du serveur d’un canal nommé instance. Ce handle est retourné par la fonction CreateNamedPipe .

[in, out, optional] lpOverlapped

Pointeur vers une structure OVERLAPPED.

Si hNamedPipe a été ouvert avec FILE_FLAG_OVERLAPPED, le paramètre lpOverlapped ne doit pas avoir la valeur NULL. Il doit pointer vers une structure CHEVAUCHEMENT VALIDE . Si hNamedPipe a été ouvert avec FILE_FLAG_OVERLAPPED et que lpOverlapped a la valeur NULL, la fonction peut signaler à tort que l’opération de connexion est terminée.

Si hNamedPipe a été créé avec FILE_FLAG_OVERLAPPED et que lpOverlapped n’a pas la valeur NULL, la structure OVERLAPPED doit contenir un handle pour un objet d’événement de réinitialisation manuelle (que le serveur peut créer à l’aide de la fonction CreateEvent ).

Si hNamedPipe n’a pas été ouvert avec FILE_FLAG_OVERLAPPED, la fonction ne retourne pas tant qu’un client n’est pas connecté ou qu’une erreur ne se produit pas. Les opérations synchrones réussies entraînent le retour d’une valeur différente de zéro si un client se connecte après l’appel de la fonction.

Valeur retournée

Si l’opération est synchrone, ConnectNamedPipe ne retourne pas tant que l’opération n’est pas terminée. Si la fonction réussit, la valeur de retour est différente de zéro. Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Si l’opération est asynchrone, ConnectNamedPipe retourne immédiatement. Si l’opération est toujours en attente, la valeur de retour est zéro et GetLastError retourne ERROR_IO_PENDING. (Vous pouvez utiliser la macro HasOverlappedIoCompleted pour déterminer quand l’opération est terminée.) Si la fonction échoue, la valeur de retour est zéro et GetLastError retourne une valeur autre que ERROR_IO_PENDING ou ERROR_PIPE_CONNECTED.

Si un client se connecte avant l’appel de la fonction, la fonction retourne zéro et GetLastError retourne ERROR_PIPE_CONNECTED. Cela peut se produire si un client se connecte dans l’intervalle entre l’appel à CreateNamedPipe et l’appel à ConnectNamedPipe. Dans ce cas, il existe une bonne connexion entre le client et le serveur, même si la fonction retourne zéro.

Remarques

Un processus de serveur de canal nommé peut utiliser ConnectNamedPipe avec un instance de canal nouvellement créé. Il peut également être utilisé avec un instance qui était précédemment connecté à un autre processus client ; dans ce cas, le processus serveur doit d’abord appeler la fonction DisconnectNamedPipe pour déconnecter le handle du client précédent avant que le handle puisse être reconnecté à un nouveau client. Sinon, ConnectNamedPipe retourne zéro et GetLastError retourne ERROR_NO_DATA si le client précédent a fermé son handle ou ERROR_PIPE_CONNECTED s’il n’a pas fermé son handle.

Le comportement de ConnectNamedPipe dépend de deux conditions : si le mode d’attente du handle de canal est défini sur bloquant ou non bloquant et si la fonction est définie pour s’exécuter de manière synchrone ou en mode chevauchement. Un serveur spécifie initialement le mode d’attente d’un handle de canal dans la fonction CreateNamedPipe , et il peut être modifié à l’aide de la fonction SetNamedPipeHandleState .

Le processus serveur peut utiliser l’une des fonctions d’attente ou SleepEx pour déterminer quand l’état de l’objet d’événement est signalé, et il peut ensuite utiliser la macro HasOverlappedIoCompleted pour déterminer quand l’opération ConnectNamedPipe se termine.

Si le handle de canal spécifié est en mode non bloquant, ConnectNamedPipe retourne toujours immédiatement. En mode sans blocage, ConnectNamedPipe retourne une valeur différente de zéro la première fois qu’il est appelé pour un canal instance déconnecté d’un client précédent. Cela indique que le canal est désormais disponible pour être connecté à un nouveau processus client. Dans toutes les autres situations où le handle de canal est en mode non bloquant, ConnectNamedPipe retourne zéro. Dans ces situations, GetLastError retourne ERROR_PIPE_LISTENING si aucun client n’est connecté, ERROR_PIPE_CONNECTED si un client est connecté et ERROR_NO_DATA si un client précédent a fermé son handle de canal, mais que le serveur n’a pas été déconnecté. Notez qu’une bonne connexion entre le client et le serveur n’existe qu’après la réception de l’erreur ERROR_PIPE_CONNECTED.

Note Le mode sans blocage est pris en charge pour la compatibilité avec Microsoft LAN Manager version 2.0, et il ne doit pas être utilisé pour obtenir une entrée et une sortie asynchrones (E/S) avec des canaux nommés.

Windows 10, version 1709 : les canaux ne sont pris en charge que dans un conteneur d’application, c’est-à-dire d’un processus UWP vers un autre processus UWP faisant partie de la même application. En outre, les canaux nommés doivent utiliser la syntaxe « \\.\pipe\LOCAL\ » pour le nom du canal.

Exemples

Pour obtenir un exemple, consultez Multithreaded Pipe Server.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	namedpipeapi.h
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll