SetNamedPipeHandleState, fonction (namedpipeapi.h)

Article
03/08/2023

Définit le mode lecture et le mode de blocage du canal nommé spécifié. Si le handle spécifié se trouve à l’extrémité cliente d’un canal nommé et si le processus serveur de canal nommé se trouve sur un ordinateur distant, la fonction peut également être utilisée pour contrôler la mise en mémoire tampon locale.

Syntaxe

BOOL SetNamedPipeHandleState(
  [in]           HANDLE  hNamedPipe,
  [in, optional] LPDWORD lpMode,
  [in, optional] LPDWORD lpMaxCollectionCount,
  [in, optional] LPDWORD lpCollectDataTimeout
);

Paramètres

[in] hNamedPipe

Handle du canal nommé instance. Ce paramètre peut être un handle à l’extrémité du serveur du canal, comme retourné par la fonction CreateNamedPipe , ou à l’extrémité cliente du canal, comme retourné par la fonction CreateFile . Le handle doit avoir GENERIC_WRITE accès au canal nommé pour un canal en écriture seule ou en lecture/écriture, ou il doit disposer d’un accès GENERIC_READ et FILE_WRITE_ATTRIBUTES pour un canal en lecture seule.

Ce paramètre peut également être un handle vers un canal anonyme, tel que retourné par la fonction CreatePipe .

[in, optional] lpMode

Nouveau mode de canal. Le mode est une combinaison d’un indicateur de mode lecture et d’un indicateur de mode d’attente. Ce paramètre peut être NULL si le mode n’est pas défini. Spécifiez l’un des modes suivants.

Mode	Signification
PIPE_READMODE_BYTE 0x00000000	Les données sont lues à partir du canal sous la forme d’un flux d’octets. Ce mode est la valeur par défaut si aucun indicateur de mode lecture n’est spécifié.
PIPE_READMODE_MESSAGE 0x00000002	Les données sont lues à partir du canal sous forme de flux de messages. La fonction échoue si cet indicateur est spécifié pour un canal de type octet.

L’un des modes d’attente suivants peut être spécifié.

Mode	Signification
PIPE_WAIT 0x00000000	Le mode de blocage est activé. Ce mode est le mode par défaut si aucun indicateur de mode d’attente n’est spécifié. Lorsqu’un handle de canal en mode bloquant est spécifié dans la fonction ReadFile, WriteFile ou ConnectNamedPipe , les opérations ne sont pas terminées tant qu’il n’y a pas de données à lire, que toutes les données sont écrites ou qu’un client est connecté. L’utilisation de ce mode peut signifier attendre indéfiniment, dans certaines situations, qu’un processus client effectue une action.
PIPE_NOWAIT 0x00000001	Le mode sans blocage est activé. Dans ce mode, ReadFile, WriteFile et ConnectNamedPipe retournent toujours immédiatement. Notez que le mode sans blocage est pris en charge pour la compatibilité avec Microsoft LAN Manager version 2.0 et ne doit pas être utilisé pour obtenir des entrées et sorties asynchrones (E/S) avec des canaux nommés.

Mode

Signification

PIPE_WAIT
0x00000000

Le mode de blocage est activé. Ce mode est le mode par défaut si aucun indicateur de mode d’attente n’est spécifié. Lorsqu’un handle de canal en mode bloquant est spécifié dans la fonction ReadFile, WriteFile ou ConnectNamedPipe , les opérations ne sont pas terminées tant qu’il n’y a pas de données à lire, que toutes les données sont écrites ou qu’un client est connecté. L’utilisation de ce mode peut signifier attendre indéfiniment, dans certaines situations, qu’un processus client effectue une action.

PIPE_NOWAIT
0x00000001

Le mode sans blocage est activé. Dans ce mode, ReadFile, WriteFile et ConnectNamedPipe retournent toujours immédiatement. Notez que le mode sans blocage est pris en charge pour la compatibilité avec Microsoft LAN Manager version 2.0 et ne doit pas être utilisé pour obtenir des entrées et sorties asynchrones (E/S) avec des canaux nommés.

[in, optional] lpMaxCollectionCount

Nombre maximal d’octets collectés sur l’ordinateur client avant la transmission au serveur. Ce paramètre doit avoir la valeur NULL si le handle de canal spécifié se trouve à l’extrémité du serveur d’un canal nommé ou si les processus client et serveur se trouvent sur la même machine. Ce paramètre est ignoré si le processus client spécifie l’indicateur FILE_FLAG_WRITE_THROUGH dans la fonction CreateFile lors de la création du handle. Ce paramètre peut être NULL si le nombre de collections n’est pas défini.

[in, optional] lpCollectDataTimeout

Durée maximale, en millisecondes, qui peut passer avant qu’un canal nommé distant transfère des informations sur le réseau. Ce paramètre doit être NULL si le handle de canal spécifié se trouve à l’extrémité du serveur d’un canal nommé ou si les processus client et serveur se trouvent sur le même ordinateur. Ce paramètre est ignoré si le processus client a spécifié l’indicateur FILE_FLAG_WRITE_THROUGH dans la fonction CreateFile lors de la création du handle. Ce paramètre peut être NULL si le nombre de collections n’est pas défini.

Valeur retourné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.

Remarques

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

Exemples

Pour obtenir un exemple, consultez Client de canal nommé.

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