Fonction ConnectNamedPipe (namedpipeapi.h)
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.
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 |