Fonction NtCreateNamedPipeFile
Crée et ouvre le handle de fin serveur de la première instance d’un canal nommé spécifique ou d’une autre instance d’un canal nommé existant. La fonction retourne un handle qui peut être utilisé pour accéder au canal.
Syntaxe
NTSTATUS NtCreateNamedPipeFile(
[out] PHANDLE FileHandle,
[in] ULONG DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG ShareAccess,
[in] ULONG CreateDisposition,
[in] ULONG CreateOptions,
[in] ULONG NamedPipeType,
[in] ULONG ReadMode,
[in] ULONG CompletionMode,
[in] ULONG MaximumInstances,
[in] ULONG InboundQuota,
[in] ULONG OutboundQuota,
[in, optional] PLARGE_INTEGER DefaultTimeout
);
Paramètres
FileHandle [out]
Pointeur vers une variable qui reçoit le handle de fichier si l’appel réussit.
DesiredAccess [in]
Masque de bits d’indicateurs spécifiant le type d’accès au fichier ou au répertoire requis par l’appelant. Cet ensemble d’indicateurs DesiredAccess définis par le système détermine les droits d’accès spécifiques suivants pour les objets de fichier.
| Indicateur | Description |
|---|---|
| Suppression | Le fichier peut être supprimé. |
| FILE_READ_DATA | Les données peuvent être lues à partir du fichier. |
| FILE_READ_ATTRIBUTES | Les indicateurs FileAttributes, décrits ci-dessous, peuvent être lus. |
| FILE_READ_EA | Les attributs étendus (EA) associés au fichier peuvent être lus. |
| READ_CONTROL | La liste de contrôle d’accès (ACL) et les informations de propriété associées au fichier peuvent être lues. |
| FILE_WRITE_DATA | Les données peuvent être écrites dans le fichier. |
| FILE_WRITE_ATTRIBUTES | Les indicateurs FileAttributes peuvent être écrits. |
| FILE_WRITE_EA | Les EA associées au fichier peuvent être écrites. |
| FILE_APPEND_DATA | Les données peuvent être ajoutées au fichier. |
| WRITE_DAC | La liste de contrôle d’accès discrétionnaire (DACL) associée au fichier peut être écrite. |
| WRITE_OWNER | Les informations de propriété associées au fichier peuvent être écrites. |
| SYNCHRONIZE | L’appelant peut synchroniser l’achèvement d’une opération d’E/S en attendant que l’état FileHandle retourné soit défini sur l’état Signaled. Cet indicateur doit être défini si l’indicateur CreateOptionsFILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT l’indicateur est défini. |
| FILE_EXECUTE | Les données peuvent être lues en mémoire à partir du fichier à l’aide d’E/S de pagination système. |
Vous pouvez également spécifier un ou plusieurs des indicateurs de ACCESS_MASK génériques suivants pour tout objet de fichier qui ne représente pas de répertoire. Les indicateurs STANDARD_RIGHTS_XXX sont des valeurs système prédéfinies utilisées pour appliquer la sécurité sur les objets système. Vous pouvez également combiner ces indicateurs génériques avec des indicateurs supplémentaires du tableau précédent.
| Accès souhaité aux valeurs de fichier | Mappe aux indicateurs DesiredAccess |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNCHRONIZE. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNCHRONIZE. |
| GENERIC_EXECUTE | STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, FILE_READ_ATTRIBUTES, FILE_EXECUTE. |
Pour les répertoires (l’indicateur FILE_DIRECTORY_FILECreateOptions est défini), vous pouvez spécifier un ou plusieurs des indicateurs de ACCESS_MASK suivants, que vous pouvez également combiner avec tous les indicateurs compatibles décrits précédemment.
| Accès souhaité aux valeurs d’annuaire | Description |
|---|---|
| FILE_LIST_DIRECTORY | Les fichiers du répertoire peuvent être répertoriés. |
| FILE_TRAVERSE | Le répertoire peut être parcouru ; autrement dit, il peut faire partie du chemin d’accès d’un fichier. |
Les FILE_READ_DATAindicateurs , FILE_WRITE_DATA, FILE_EXECUTEet FILE_APPEND_DATADesiredAccess ne sont pas compatibles avec la création ou l’ouverture d’un fichier de répertoire.
ObjectAttributes [in]
Pointeur vers une OBJECT_ATTRIBUTES structure déjà initialisée par la routine InitializeObjectAttributes . Si l’appelant s’exécute dans le contexte du processus système, ce paramètre peut être NULL. Sinon, l’appelant doit définir l’attribut OBJ_KERNEL_HANDLE dans l’appel sur InitializeObjectAttributes.
Les membres de cette structure pour un objet de fichier sont les suivants :
| Membre | Valeur |
|---|---|
| Longueur ULONG | Nombre d’octets des données ObjectAttributes fournies. Cette valeur doit être au moins sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Pointeur vers une chaîne Unicode mise en mémoire tampon qui contient le nom du fichier à créer ou à ouvrir. Cette valeur doit être une spécification de fichier complète, sauf s’il s’agit du nom d’un fichier relatif au répertoire spécifié par RootDirectory. Par exemple, « \Device\Floppy1\myfile.dat » ou « ?? \B:\myfile.dat » peut être la spécification de fichier complète, tant que le pilote de lecteur de disquette et le système de fichiers qui se superpose sont déjà chargés. (Remarque : « ? » remplace « \DosDevices » comme nom de l’espace de noms de l’objet Win32. « \DosDevices » fonctionne toujours, mais « ? » est traduit plus rapidement par le gestionnaire d’objets.) |
| HANDLE RootDirectory | Handle facultatif pour un répertoire qui a été obtenu par un appel précédent à NtCreateNamedPipeFile. Si cette valeur a la valeur NULL, le membre ObjectName doit être une spécification de fichier complète qui inclut le chemin d’accès complet au fichier cible. Si cette valeur n’est pas NULL, le membre ObjectName spécifie un nom de fichier relatif à ce répertoire. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Descripteur de sécurité facultatif à appliquer à un fichier. Les listes de contrôle d’accès spécifiées par ce descripteur de sécurité ne sont appliquées au fichier qu’au moment de sa création. Si la valeur est NULL lors de la création d’un fichier, la liste de contrôle d’accès placée sur le fichier dépend du système de fichiers ; la plupart des systèmes de fichiers propagent une partie de cette ACL à partir du fichier de répertoire parent associé à la liste de contrôle d’accès par défaut de l’appelant. |
| Attributs ULONG | Ensemble d’indicateurs qui contrôle les attributs de l’objet de fichier. Si l’appelant s’exécute dans le contexte du processus système, ce paramètre peut être égal à zéro. Sinon, l’appelant doit définir l’indicateur OBJ_KERNEL_HANDLE . L’appelant peut également éventuellement définir l’indicateur OBJ_CASE_INSENSITIVE , ce qui indique que le code de recherche de nom doit ignorer le cas de ObjectName au lieu d’effectuer une recherche de correspondance exacte. |
IoStatusBlock [out]
Pointeur vers une variable de type IO_STATUS_BLOCK qui reçoit l’état d’achèvement final et des informations sur l’opération demandée. Au retour de NtCreateNamedPipeFile, le membre Information de la variable contient l’une des valeurs suivantes :
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
ShareAccess [in]
Spécifie le type d’accès de partage au fichier souhaité par l’appelant, comme zéro ou un, ou une combinaison des indicateurs suivants. Pour demander l’accès exclusif, définissez ce paramètre sur zéro. Pour éviter les erreurs de violation de partage, spécifiez tous les indicateurs d’accès de partage suivants.
| Indicateurs ShareAccess | Description |
|---|---|
| FILE_SHARE_READ | Le fichier peut être ouvert pour l’accès en lecture par les appels de création de fichier d’autres threads. |
| FILE_SHARE_WRITE | Le fichier peut être ouvert pour l’accès en écriture par les appels de création de fichier d’autres threads. |
| FILE_SHARE_DELETE | Le fichier peut être ouvert pour supprimer l’accès par les appels de création de fichier d’autres threads. |
Les pilotes de périphérique et les pilotes intermédiaires définissent généralement ShareAccess sur zéro, ce qui donne à l’appelant un accès exclusif au fichier ouvert.
CreateDisposition [in]
Valeur qui détermine la façon dont le fichier doit être géré lorsque le fichier existe déjà. CreateDisposition peut être l’un des éléments suivants :
| Valeur | Description |
|---|---|
| FILE_SUPERSEDE | Si le fichier existe déjà, remplacez-le par le fichier donné. S’il n’existe pas, créez le fichier donné. |
| FILE_CREATE | Si le fichier existe déjà, échouez la demande et ne créez pas ou n’ouvrez pas le fichier donné. S’il n’existe pas, créez le fichier donné. |
| FILE_OPEN | Si le fichier existe déjà, ouvrez-le au lieu de créer un fichier. S’il n’existe pas, échouez la demande et ne créez pas de fichier. |
| FILE_OPEN_IF | Si le fichier existe déjà, ouvrez-le. S’il n’existe pas, créez le fichier donné. |
| FILE_OVERWRITE | Si le fichier existe déjà, ouvrez-le et remplacez-le. S’il n’existe pas, la demande échoue. |
| FILE_OVERWRITE_IF | Si le fichier existe déjà, ouvrez-le et remplacez-le. S’il n’existe pas, créez le fichier donné. |
CreateOptions [in]
Spécifie les options à appliquer lors de la création ou de l’ouverture du fichier, en tant que combinaison compatible des indicateurs suivants.
| Indicateur CreateOptions | Description |
|---|---|
| FILE_DIRECTORY_FILE (0x00000001) | Le fichier en cours de création ou d’ouverture est un fichier de répertoire. Avec cet indicateur, le paramètre Disposition doit être défini sur , FILE_CREATEFILE_OPENou FILE_OPEN_IF.
Les indicateurs CreateOptions qui sont compatibles avec cet indicateur sont les suivants : FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENTet FILE_OPEN_BY_FILE_ID. |
| FILE_WRITE_THROUGH (0x00000002) | Les services système, les systèmes de fichiers et les pilotes qui écrivent des données dans le fichier doivent effectivement transférer les données dans le fichier avant que toute opération d’écriture demandée soit considérée comme terminée. |
| FILE_SEQUENTIAL_ONLY (0x00000004) | Tous les accès au fichier seront séquentiels. |
| FILE_NO_INTERMEDIATE_BUFFERING (0x00000008) | Le fichier ne peut pas être mis en cache ou mis en mémoire tampon dans les mémoires tampons internes d’un pilote. Cet indicateur n’est pas compatible avec l’indicateur DesiredAccessFILE_APPEND_DATA . |
| FILE_SYNCHRONOUS_IO_ALERT (0x00000010) | Toutes les opérations sur le fichier sont effectuées de manière synchrone. Toute attente de la part de l’appelant est sujette à l’arrêt prématuré des alertes. Cet indicateur permet également au système d’E/S de conserver le contexte de position du fichier. Si cet indicateur est défini, l’indicateur DesiredAccessSYNCHRONIZE doit également être défini afin que le Gestionnaire d’E/S utilise l’objet file comme objet de synchronisation. |
| FILE_SYNCHRONOUS_IO_NONALERT (0x00000020) | Toutes les opérations sur le fichier sont effectuées de manière synchrone. Les attentes dans le système pour synchroniser la file d’attente d’E/S et l’achèvement ne sont pas soumises à des alertes. Cet indicateur permet également au système d’E/S de conserver le contexte de position du fichier. Si cet indicateur est défini, l’indicateur DesiredAccessSYNCHRONIZE doit également être défini afin que le Gestionnaire d’E/S utilise l’objet file comme objet de synchronisation. |
| FILE_NON_DIRECTORY_FILE (0x00000040) | Le fichier en cours d’ouverture ne doit pas être un fichier de répertoire, sinon cet appel échoue. L’objet file en cours d’ouverture peut représenter un fichier de données ; un appareil logique, virtuel ou physique ; ou un volume. |
| FILE_CREATE_TREE_CONNECTION (0x00000080) | Créez une connexion d’arborescence pour ce fichier afin de l’ouvrir sur le réseau. |
| FILE_COMPLETE_IF_OPLOCKED (0x00000100) | Effectuez cette opération immédiatement avec un autre code de réussite si le fichier cible est verrouillé, au lieu de bloquer le thread de l’appelant. Si le fichier est bloqué, un autre appelant a déjà accès au fichier sur le réseau. |
| FILE_NO_EA_KNOWLEDGE (0x00000200) | Si les attributs étendus d’un fichier existant en cours d’ouverture indiquent que l’appelant doit comprendre les attributs étendus pour interpréter correctement le fichier, cette demande échoue, car l’appelant ne comprend pas comment traiter les attributs étendus. |
| FILE_OPEN_REMOTE_INSTANCE (0x00000400) | Réservé à l’utilisation du système ; n’utilisez pas. |
| FILE_RANDOM_ACCESS (0x00000800) | Les accès au fichier peuvent être aléatoires. Par conséquent, aucune opération de lecture anticipée séquentielle ne doit être effectuée sur le fichier par les systèmes de fichiers ou le système d’exploitation. |
| FILE_DELETE_ON_CLOSE (0x00001000) | Supprimez le fichier lorsque le dernier handle est passé à FltClose. |
| FILE_OPEN_BY_FILE_ID (0x00002000) | Le fichier est ouvert par ID. Le nom de fichier contient le nom d’un appareil et un ID 64 bits à utiliser pour ouvrir le fichier. |
| FILE_OPEN_FOR_BACKUP_INTENT (0x000004000) | Le fichier est ouvert pour l’intention de sauvegarde ; Par conséquent, le système doit vérifier certains droits d’accès et accorder à l’appelant les accès appropriés au fichier avant de vérifier l’entrée DesiredAccess par rapport au descripteur de sécurité du fichier. |
| FILE_NO_COMPRESSION (0x00008000) | Supprimez l’héritage de FILE_ATTRIBUTE_COMPRESSED à partir du répertoire parent. Cela permet de créer un fichier non compressé dans un répertoire marqué compressé. |
| FILE_OPEN_REQUIRING_OPLOCK (0x00010000) | Le fichier est ouvert et un verrou opportuniste (oplock) sur le fichier est demandé en tant qu’opération atomique unique. Le système de fichiers recherche les oplocks avant d’effectuer l’opération de création, et l’opération de création échoue avec un code de retour si l’opération de STATUS_CANNOT_BREAK_OPLOCK création interrompt un blocage d’opération existant. Cet indicateur est disponible dans les systèmes d’exploitation Windows 7, Windows Server 2008 R2 et ultérieur. |
| FILE_DISALLOW_EXCLUSIVE (0x00020000) | Lors de l’ouverture d’un fichier existant, si FILE_SHARE_READ n’est pas spécifié et que les vérifications d’accès au système de fichiers n’accordent pas à l’appelant l’accès en écriture au fichier, faites échouer cette ouverture avec STATUS_ACCESS_DENIED. Il s’agissait d’un comportement par défaut antérieur à Windows 7. |
| FILE_SESSION_AWARE (0x00040000) | Le fichier ou l’appareil est ouvert avec la reconnaissance de session. Si cet indicateur n’est pas spécifié, les appareils par session (par exemple, un appareil utilisant la redirection USB RemoteFX) ne peuvent pas être ouverts par les processus exécutés dans la session 0. Cet indicateur n’a aucun effet pour les appelants qui ne sont pas dans la session 0. Cet indicateur est pris en charge uniquement sur les éditions serveur de Windows. Cet indicateur n’est pas pris en charge avant Windows Server 2012. |
| FILE_RESERVE_OPFILTER (0x00100000) | Cet indicateur permet à une application de demander un verrou opportuniste de filtre (oplock) pour empêcher d’autres applications d’obtenir des violations de partage. S’il existe déjà des handles ouverts, la demande de création échoue avec STATUS_OPLOCK_NOT_GRANTED. |
| FILE_OPEN_REPARSE_POINT (0x00200000) | Ouvrez un fichier avec un point d’analyse et ignorez le traitement normal du point d’analyse pour le fichier. Pour plus d'informations, consultez la section Notes qui suit. |
| FILE_OPEN_NO_RECALL (0x00400000) | Indique à tous les filtres qui effectuent un stockage ou une virtualisation hors connexion de ne pas rappeler le contenu du fichier à la suite de cette ouverture. |
| FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000) | Cet indicateur indique au système de fichiers de capturer l’utilisateur associé au thread appelant. Tous les appels ultérieurs à FltQueryVolumeInformation ou ZwQueryVolumeInformationFile à l’aide du handle retourné supposent que l’utilisateur capturé, plutôt que l’utilisateur appelant à l’époque, afin de calculer l’espace libre disponible pour l’appelant. Cela s’applique aux valeurs FsInformationClass suivantes : FileFsSizeInformation, FileFsFullSizeInformationet FileFsFullSizeInformationEx. |
NamedPipeType [in]
Type de canal nommé à créer (byte-type ou message-type).
ReadMode [in]
Mode de lecture du canal (byte-type ou message-type).
CompletionMode [in]
Spécifie la façon dont l’opération doit être effectuée.
MaximumInstances [in]
Nombre maximal d’instances simultanées du canal nommé.
InboundQuota [in]
Spécifie le quota de pool réservé aux écritures dans le côté entrant du canal nommé.
OutboundQuota [in]
Spécifie le quota de pool réservé aux écritures dans le côté entrant du canal nommé.
DefaultTimeout [in, facultatif]
Pointeur facultatif vers une valeur de délai d’expiration utilisée si aucune valeur de délai d’expiration n’est spécifiée lors de l’attente d’une instance d’un canal nommé.
Retours
La valeur de la fonction est l’état final de l’opération de création/ouverture.
Remarques
Pour créer une instance d’un canal nommé, 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 d’instances 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 la 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é 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 de l’instance du canal nommé est fermé.
Configuration requise
| Condition requise | Valeur |
|---|---|
| En-tête | ntioapi.h |
| Bibliothèque | ntdll.lib |