Fonction CreateNamedPipeA (winbase.h)
Crée un instance d’un canal nommé et retourne un handle pour les opérations de canal suivantes. Un processus de serveur de canal nommé utilise cette fonction soit pour créer la première instance d’un canal nommé spécifique et établir ses attributs de base, soit pour créer une nouvelle instance d’un canal nommé existant.
Syntaxe
HANDLE CreateNamedPipeA(
[in] LPCSTR lpName,
[in] DWORD dwOpenMode,
[in] DWORD dwPipeMode,
[in] DWORD nMaxInstances,
[in] DWORD nOutBufferSize,
[in] DWORD nInBufferSize,
[in] DWORD nDefaultTimeOut,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);
Paramètres
[in] lpName
Nom de canal unique. Cette chaîne doit avoir la forme suivante :
\\.\pipe\pipename
La partie pipename du nom peut inclure n’importe quel caractère autre qu’une barre oblique inverse, y compris des nombres et des caractères spéciaux. La chaîne de nom de canal entière peut avoir jusqu’à 256 caractères. Les noms de canal ne respectent pas la casse.
[in] dwOpenMode
Mode ouvert.
La fonction échoue si dwOpenMode spécifie autre chose que 0 ou les indicateurs répertoriés dans les tableaux suivants.
Ce paramètre doit spécifier l’un des modes d’accès au canal suivants. Le même mode doit être spécifié pour chaque instance du canal.
| Mode | Signification |
|---|---|
|
Le canal est bidirectionnel ; Les processus serveur et client peuvent lire et écrire dans le canal. Ce mode donne au serveur l’équivalent de GENERIC_READ et GENERIC_WRITE accès au canal. Le client peut spécifier GENERIC_READ ou GENERIC_WRITE, ou les deux, lorsqu’il se connecte au canal à l’aide de la fonction CreateFile . |
|
Le flux de données dans le canal passe du client au serveur uniquement. Ce mode donne au serveur l’équivalent de GENERIC_READ accès au canal. Le client doit spécifier GENERIC_WRITE accès lors de la connexion au canal. Si le client doit lire les paramètres du canal en appelant les fonctions GetNamedPipeInfo ou GetNamedPipeHandleState , le client doit spécifier GENERIC_WRITE et FILE_READ_ATTRIBUTES accès lors de la connexion au canal. |
|
Le flux de données dans le canal passe du serveur au client uniquement. Ce mode donne au serveur l’équivalent de GENERIC_WRITE accès au canal. Le client doit spécifier GENERIC_READ accès lors de la connexion au canal. Si le client doit modifier les paramètres de canal en appelant la fonction SetNamedPipeHandleState , le client doit spécifier GENERIC_READ et FILE_WRITE_ATTRIBUTES accès lors de la connexion au canal. |
Ce paramètre peut également inclure un ou plusieurs des indicateurs suivants, qui activent l’écriture directe et les modes superposés. Ces modes peuvent être différents pour différentes instances du même canal.
| Mode | Signification |
|---|---|
|
Si vous tentez de créer plusieurs instances d’un canal avec cet indicateur, la création du premier instance réussit, mais la création du instance suivant échoue avec ERROR_ACCESS_DENIED. |
|
Le mode d’écriture directe est activé. Ce mode affecte uniquement les opérations d’écriture sur les canaux de type octet, puis uniquement lorsque les processus client et serveur se trouvent sur des ordinateurs différents. Si ce mode est activé, les fonctions qui écrivent dans un canal nommé ne retournent pas les données écrites tant que les données écrites ne sont pas transmises sur le réseau et se situent dans la mémoire tampon du canal sur l’ordinateur distant. Si ce mode n’est pas activé, le système améliore l’efficacité des opérations réseau en mettant en mémoire tampon les données jusqu’à ce qu’un nombre minimal d’octets s’accumule ou jusqu’à ce qu’un temps maximal s’écoule. |
|
Le mode chevauché est activé. Si ce mode est activé, les fonctions effectuant des opérations de lecture, d’écriture et de connexion qui peuvent prendre beaucoup de temps peuvent être retournées immédiatement. Ce mode permet au thread qui a démarré l’opération d’effectuer d’autres opérations pendant que l’opération chronophage s’exécute en arrière-plan. Par exemple, en mode chevauchant, un thread peut gérer des opérations d’entrée et de sortie simultanées (E/S) sur plusieurs instances d’un canal ou effectuer des opérations de lecture et d’écriture simultanées sur le même handle de canal. Si le mode superposé n’est pas activé, les fonctions effectuant des opérations de lecture, d’écriture et de connexion sur le handle de canal ne sont pas retournées tant que l’opération n’est pas terminée. Les fonctions ReadFileEx et WriteFileEx ne peuvent être utilisées qu’avec un handle de canal en mode superposé. Les fonctions ReadFile, WriteFile, ConnectNamedPipe et TransactNamedPipe peuvent s’exécuter de manière synchrone ou en tant qu’opérations qui se chevauchent. |
Ce paramètre peut inclure n’importe quelle combinaison des modes d’accès de sécurité suivants. Ces modes peuvent être différents pour différentes instances du même canal.
| Mode | Signification |
|---|---|
|
L’appelant aura un accès en écriture à la liste de contrôle d’accès discrétionnaire (ACL) du canal nommé. |
|
L’appelant aura un accès en écriture au propriétaire du canal nommé. |
|
L’appelant aura un accès en écriture à la SACL du canal nommé. Pour plus d’informations, consultez Access-Control Listes (ACL) et Droit d’accès SACL. |
[in] dwPipeMode
Mode canal.
La fonction échoue si dwPipeMode spécifie autre chose que 0 ou les indicateurs répertoriés dans les tableaux suivants.
L’un des modes de type suivants peut être spécifié. Le même mode de type doit être spécifié pour chaque instance du canal.
| Mode | Signification |
|---|---|
|
Les données sont écrites dans le canal sous la forme d’un flux d’octets. Ce mode ne peut pas être utilisé avec PIPE_READMODE_MESSAGE. Le canal ne distingue pas les octets écrits au cours des différentes opérations d’écriture. |
|
Les données sont écrites dans le canal sous forme de flux de messages. Le canal traite les octets écrits pendant chaque opération d’écriture comme une unité de message. La fonction GetLastError retourne ERROR_MORE_DATA lorsqu’un message n’est pas lu complètement. Ce mode peut être utilisé avec PIPE_READMODE_MESSAGE ou PIPE_READMODE_BYTE. |
L’un des modes de lecture suivants peut être spécifié. Différentes instances du même canal peuvent spécifier différents modes de lecture.
L’un des modes d’attente suivants peut être spécifié. Différentes instances du même canal peuvent spécifier différents modes d’attente.
| Mode | Signification |
|---|---|
|
Le mode de blocage est activé. Lorsque le handle de canal 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 n’est pas connecté. L’utilisation de ce mode peut signifier attendre indéfiniment, dans certaines situations, qu’un processus client effectue une action. |
|
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 effectuer des E/S asynchrones avec des canaux nommés. Pour plus d’informations sur les E/S de canal asynchrones, consultez Entrée et sortie synchrones et superposées. |
L’un des modes client distants suivants peut être spécifié. Différentes instances du même canal peuvent spécifier différents modes de client distant.
[in] nMaxInstances
Nombre maximal d’instances qui peuvent être créées pour ce canal. La première instance du canal peut spécifier cette valeur ; le même nombre doit être spécifié pour les autres instances du canal. Les valeurs acceptables se trouvent entre 1 et PIPE_UNLIMITED_INSTANCES (255).
Si ce paramètre est PIPE_UNLIMITED_INSTANCES, le nombre d’instances de canal qui peuvent être créées est limité uniquement par la disponibilité des ressources système. Si nMaxInstances est supérieur à PIPE_UNLIMITED_INSTANCES, la valeur de retour est INVALID_HANDLE_VALUE et GetLastError retourne ERROR_INVALID_PARAMETER.
[in] nOutBufferSize
Nombre d’octets à réserver pour la mémoire tampon de sortie. Pour une discussion sur le dimensionnement des tampons de canal nommés, consultez la section Remarques suivante.
[in] nInBufferSize
Nombre d’octets à réserver pour la mémoire tampon d’entrée. Pour une discussion sur le dimensionnement des tampons de canal nommés, consultez la section Remarques suivante.
[in] nDefaultTimeOut
Valeur de délai d’attente par défaut, en millisecondes, si la fonction WaitNamedPipe spécifie NMPWAIT_USE_DEFAULT_WAIT. Chaque instance d’un canal nommé doit spécifier la même valeur.
Une valeur de zéro entraîne un délai d’attente par défaut de 50 millisecondes.
[in, optional] lpSecurityAttributes
Pointeur vers une structure de SECURITY_ATTRIBUTES qui spécifie un descripteur de sécurité pour le nouveau canal nommé et détermine si les processus enfants peuvent hériter du handle retourné. Si lpSecurityAttributes a la valeur NULL, le canal nommé obtient un descripteur de sécurité par défaut et le handle ne peut pas être hérité. Les listes de contrôle d’accès dans le descripteur de sécurité par défaut d’un canal nommé accordent un contrôle total au compte LocalSystem, aux administrateurs et au propriétaire du créateur. Ils accordent également l’accès en lecture aux membres du groupe Tout le monde et au compte anonyme.
Valeur retournée
Si la fonction réussit, la valeur de retour est un handle à l’extrémité du serveur d’un canal nommé instance.
Si la fonction échoue, la valeur de retour est INVALID_HANDLE_VALUE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Remarques
Pour créer une instance d’un canal nommé à l’aide de CreateNamedPipe, l’utilisateur doit avoir FILE_CREATE_PIPE_INSTANCE accès à l’objet de canal nommé. Si un nouveau canal nommé est en cours de création, la liste de contrôle d’accès (ACL) du paramètre attributs de sécurité définit le contrôle d’accès discrétionnaire pour le canal nommé.
Toutes les instances d’un canal nommé doivent spécifier le même type de canal (type d’octet ou de message), l’accès au canal (duplex, entrant ou sortant), le même nombre de instance et la même valeur de délai d’attente. Si des valeurs différentes sont utilisées, cette fonction échoue et GetLastError retourne ERROR_ACCESS_DENIED.
Un processus client se connecte à un canal nommé à l’aide de la fonction CreateFile ou CallNamedPipe . Le côté client d’un canal nommé démarre en mode octet, même si le côté serveur est en mode message. Pour éviter les problèmes de réception des données, définissez également le mode message côté client. Pour modifier le mode du canal, le client de canal doit ouvrir un canal en lecture seule avec un accès GENERIC_READ et FILE_WRITE_ATTRIBUTES .
Le serveur de canal ne doit pas effectuer une opération de lecture bloquante tant que le client de canal n’a pas démarré. Sinon, une condition de race peut se produire. Cela se produit généralement lorsque le code d’initialisation, tel que l’exécution C, doit verrouiller et examiner les handles hérités.
Chaque fois qu’un canal nommé est créé, le système crée les mémoires tampons entrantes et/ou sortantes à l’aide d’un pool non paginé, qui est la mémoire physique utilisée par le noyau. Le nombre d’instances de canal (ainsi que d’objets tels que des threads et des processus) que vous pouvez créer est limité par le pool non paginé disponible. Chaque demande de lecture ou d’écriture nécessite de l’espace dans la mémoire tampon pour les données de lecture ou d’écriture, ainsi que de l’espace supplémentaire pour les structures de données internes.
Les tailles de mémoire tampon d’entrée et de sortie sont des conseils. La taille de mémoire tampon réelle réservée à chaque extrémité du canal nommé est soit la valeur par défaut du système, la valeur minimale ou maximale du système, soit la taille spécifiée arrondie à la limite d’allocation suivante. La taille de mémoire tampon spécifiée doit être suffisamment petite pour que votre processus ne soit pas à court de pool non paginé, mais suffisamment grande pour prendre en charge les demandes standard.
Chaque fois qu’une opération d’écriture de canal se produit, le système tente d’abord de charger la mémoire sur le quota d’écriture du canal. Si le quota d’écriture de canal restant est suffisant pour répondre à la demande, l’opération d’écriture se termine immédiatement. Si le quota d’écriture de canal restant est trop petit pour répondre à la demande, le système tente d’étendre les mémoires tampons pour prendre en charge les données à l’aide d’un pool non paginé réservé au processus. L’opération d’écriture est bloquée jusqu’à ce que les données soient lues à partir du canal afin que le quota de mémoire tampon supplémentaire puisse être libéré. Par conséquent, si la taille de la mémoire tampon spécifiée est trop petite, le système augmente la mémoire tampon en fonction des besoins, mais l’inconvénient est que l’opération se bloque. Si l’opération se chevauche, un thread système est bloqué ; sinon, le thread d’application est bloqué.
Pour libérer les ressources utilisées par un canal nommé, l’application doit toujours fermer les handles lorsqu’elles ne sont plus nécessaires, ce qui s’effectue soit en appelant la fonction CloseHandle, soit lorsque le processus associé à la instance handles se termine. Notez qu’un instance d’un canal nommé peut avoir plusieurs handles associés. Une instance d’un canal nommé est toujours supprimée lorsque le dernier handle du instance du canal nommé est fermé.
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\ du 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 | winbase.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |