CreateNamedPipeA, fonction (winbase.h)
Crée une 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 pour créer la première instance d’un canal nommé spécifique et établir ses attributs de base ou pour créer une 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 unique du canal. Cette chaîne doit avoir le formulaire suivant :
\\.\pipe\nom de canal
La partie pipename du nom peut inclure n’importe quel caractère autre qu’une barre oblique inverse, y compris les nombres et les caractères spéciaux. La chaîne de nom de canal entière peut comporter jusqu’à 256 caractères. Les noms de canal ne respectent pas la casse.
[in] dwOpenMode
Mode ouvert.
La fonction échoue si dwOpenMode spécifie quelque chose d’autre 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 par 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 l’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 de canal en appelant le GetNamedPipeInfo |
|
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 du 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 les modes d’écriture et de chevauchement. 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 de la première instance réussit, mais la création de l’instance suivante échoue avec ERROR_ACCESS_DENIED. |
|
Le mode Écriture directe est activé. Ce mode affecte uniquement les opérations d’écriture sur des canaux de type octet, puis, uniquement lorsque les processus client et serveur se trouvent sur différents ordinateurs. Si ce mode est activé, les fonctions qui écrivent dans un canal nommé ne retournent pas tant que les données écrites ne sont pas transmises sur le réseau et qu’elles se trouvent 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’accumulent ou jusqu’à ce qu’une durée maximale s’écoule. |
|
Le mode superposé 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 exécuté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 fastidieuse s’exécute en arrière-plan. Par exemple, en mode superposé, un thread peut gérer les 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 se chevauche n’est pas activé, les fonctions effectuant des opérations de lecture, d’écriture et de connexion sur le handle de canal ne retournent pas 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 ReadFile, WriteFile, ConnectNamedPipeet fonctions TransactNamedPipe peuvent s’exécuter de manière synchrone ou comme des opérations superposées. |
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 de contrôle d’accès (ACL) et accès SACL Right. |
[in] dwPipeMode
Mode canal.
La fonction échoue si dwPipeMode spécifie quelque chose d’autre 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 pendant différentes opérations d’écriture. |
|
Les données sont écrites dans le canal sous la forme d’un flux de messages. Le canal traite les octets écrits pendant chaque opération d’écriture en tant qu’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 le ReadFile, writeFileou fonction 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 soit connecté. L’utilisation de ce mode peut signifier attendre indéfiniment dans certaines situations pour qu’un processus client effectue une action. |
|
Le mode non bloquant est activé. Dans ce mode, ReadFile, WriteFileet ConnectNamedPipe retournent toujours immédiatement.
Notez que le mode non bloquant est pris en charge pour la compatibilité avec Microsoft LAN Manager version 2.0 et ne doit pas être utilisé pour obtenir des E/S asynchrones avec des canaux nommés. Pour plus d’informations sur les E/S de canal asynchrone, consultez d’entrée et de sortie synchrones et superposées. |
L’un des modes clients 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 pouvant ê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 d’autres instances du canal. Les valeurs acceptables sont comprises entre 1 et PIPE_UNLIMITED_INSTANCES (255).
Si ce paramètre est PIPE_UNLIMITED_INSTANCES, le nombre d’instances de canal pouvant ê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 mémoires tampons de canal nommées, 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 mémoires tampons de canal nommées, 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.
La valeur zéro entraîne un délai d’expiration par défaut de 50 millisecondes.
[in, optional] lpSecurityAttributes
Pointeur vers une structure 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 est 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 pour 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 de retour
Si la fonction réussit, la valeur de retour est un handle à la fin du serveur d’une instance de canal nommé.
Si la fonction échoue, la valeur de retour est INVALID_HANDLE_VALUE. Pour obtenir des informations d’erreur étendues, 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 créé, la liste de contrôle d’accès (ACL) à partir 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 type de message), l’accès au canal (duplex, entrant ou sortant), le nombre d’instances et la valeur de délai d’attente. Si différentes valeurs 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 de données, définissez également le côté client sur le mode message. Pour modifier le mode du canal, le client de canal doit ouvrir un canal en lecture seule avec GENERIC_READ et un accès FILE_WRITE_ATTRIBUTES.
Le serveur de canal ne doit pas effectuer d’opération de lecture bloquante tant que le client de canal n’a pas démarré. Sinon, une condition de concurrence peut se produire. Cela se produit généralement lors de l’initialisation du code, tel que le runtime 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 les objets tels que les threads et les 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 conseillées. La taille réelle de la mémoire tampon réservée pour chaque extrémité du canal nommé est soit la valeur par défaut du système, soit la taille minimale ou maximale du système, soit la taille spécifiée arrondie à la limite d’allocation suivante. La taille de la mémoire tampon spécifiée doit être suffisamment petite pour que votre processus ne s’exécute pas du pool non paginé, mais suffisamment grand pour prendre en charge les requêtes classiques.
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 du canal restant est suffisant pour répondre à la demande, l’opération d’écriture se termine immédiatement. Si le quota d’écriture du canal restant est trop petit pour répondre à la demande, le système tente de développer 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 bloque 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 votre taille de 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 va bloquer. Si l’opération se chevauche, un thread système est bloqué ; sinon, le thread d’application est bloqué.
Pour libérer des ressources utilisées par un canal nommé, l’application doit toujours fermer les handles lorsqu’elles ne sont plus nécessaires, ce qui est effectué soit en appelant la fonction CloseHandle, soit lorsque le processus associé aux handles d’instance se termine. Notez qu’une 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 vers l’instance du canal nommé est fermé.
Windows 10, version 1709 : les canaux ne sont pris en charge que dans un conteneur d’applications ; Par exemple, 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\ 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 | winbase.h (inclure Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |