ConnectNamedPipe, fonction (namedpipeapi.h)

Article
11/20/2024

Permet à un processus de serveur de canal nommé d’attendre qu’un processus client se connecte à une 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 la fin du serveur d’une instance de canal nommé. Ce handle est retourné par la fonction CreateNamedPipe.

[in, out, optional] lpOverlapped

Pointeur vers une structure SUPERPOSÉE.

Si hNamedPipe a été ouvert avec FILE_FLAG_OVERLAPPED, le paramètre lpOverlapped ne doit pas être NULL. Il doit pointer vers une structure de QUI SE CHEVAUCHE. Si hNamedPipe a été ouvert avec FILE_FLAG_OVERLAPPED et lpOverlapped est NULL, la fonction peut signaler de manière incorrecte que l’opération de connexion est terminée.

Si hNamedPipe a été créé avec FILE_FLAG_OVERLAPPED et lpOverlapped n’est pas NULL, la structure SE CHEVAUCHER doit contenir un handle vers 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 se produit. 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 de retour

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’erreur étendues, 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 égale à zéro et GetLastError retourne ERROR_IO_PENDING. (Vous pouvez utiliser la macro HasOverlappedIoCompleted pour déterminer quand l’opération a terminé.) Si la fonction échoue, la valeur de retour est égale à 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 une instance de canal nouvellement créée. Il peut également être utilisé avec une instance qui a été précédemment connectée à 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 le blocage ou le non-blocage et si la fonction est définie pour s’exécuter de manière synchrone ou en mode superposé. 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 SleepExpour 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 non bloquant, ConnectNamedPipe retourne une valeur différente de zéro la première fois qu’elle est appelée pour une instance de canal déconnectée 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é sa poignée de canal, mais que le serveur n’a pas déconnecté. Notez qu’une bonne connexion entre le client et le serveur existe uniquement après la réception de l’erreur ERROR_PIPE_CONNECTED.

Remarque mode Non-blocking est pris en charge pour la compatibilité avec Microsoft LAN Manager version 2.0, et il ne doit pas être utilisé pour obtenir des entrées et sorties asynchrones (E/S) avec des canaux nommés.

Windows 10, version 1709 et ultérieures : canaux ne peuvent pas être utilisés pour communiquer entre les conteneurs d’applications ; Par exemple, d’un processus UWP à un autre processus UWP qui ne fait pas partie de la même application. En outre, les canaux nommés dans les conteneurs d’applications doivent utiliser la syntaxe « \\.\pipe\LOCAL\' pour le nom du canal.

Exemples

Pour obtenir un exemple, consultez Multithreaded Pipe Server .

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	namedpipeapi.h
bibliothèque	Kernel32.lib
DLL	Kernel32.dll