Fonction FltCreateNamedPipeFile (fltkernel.h)
Les pilotes de minifiltre appellent FltCreateNamedPipeFile pour créer un nouveau canal ou ouvrir un canal existant.
Syntaxe
NTSTATUS FLTAPI FltCreateNamedPipeFile(
[in] PFLT_FILTER Filter,
[in, optional] PFLT_INSTANCE Instance,
[out] PHANDLE FileHandle,
[out, optional] PFILE_OBJECT *FileObject,
[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,
ULONG InboundQuota,
ULONG OutboundQuota,
[in, optional] PLARGE_INTEGER DefaultTimeout,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
Paramètres
[in] Filter
Pointeur de filtre opaque pour l’appelant.
[in, optional] Instance
Pointeur de instance opaque pour le pilote minifiltre instance à laquelle la demande de création doit être envoyée. Le instance doit être attaché au volume pour le système de fichiers de canal nommé. Ce paramètre est facultatif et peut être NULL. Si ce paramètre a la valeur NULL, la demande est envoyée à l’objet d’appareil situé en haut de la pile de pilotes de système de fichiers pour le volume. Si elle n’est pas NULL, la demande est envoyée uniquement aux instances de pilote de minifiltre attachées sous la instance spécifiée.
[out] FileHandle
Pointeur vers une variable allouée par l’appelant qui reçoit le handle de fichier si l’appel à FltCreateNamedPipeFile réussit.
[out, optional] FileObject
Pointeur vers une variable allouée par l’appelant qui reçoit le pointeur de l’objet fichier si l’appel à FltCreateNamedPipeFile réussit. Ce paramètre est facultatif et peut être NULL.
[in] DesiredAccess
Masque de bits d’indicateurs qui spécifient le type d’accès requis par l’appelant au fichier ou au répertoire. L’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.
| Indicateurs DesiredAccess | Signification |
|---|---|
| FILE_READ_DATA | Les données peuvent être lues à partir du canal nommé. |
| FILE_READ_ATTRIBUTES | Les indicateurs FileAttributes peuvent être lus. Pour plus d’informations, consultez la table des valeurs d’indicateur valides dans le paramètre FileAttributes de FltCreateFileEx2. |
| READ_CONTROL | La liste de contrôle d’accès (ACL) et les informations de propriété associées au canal nommé peuvent être lues. |
| FILE_WRITE_DATA | Les données peuvent être écrites dans le canal nommé. |
| FILE_WRITE_ATTRIBUTES | Les indicateurs FileAttributes peuvent être écrits. |
| 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 canal nommé peut être écrite. |
| WRITE_OWNER | Les informations de propriété associées au canal nommé peuvent être écrites. |
| ACCESS_SYSTEM_SECURITY | L’appelant aura un accès en écriture à la SACL du canal nommé |
| 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 CreateOptions FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT est défini. |
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.
| DesiredAccess to File Values | Mappe à DesiredAccess Flags |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA et SYNCHRONIZE. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA et SYNCHRONIZE. |
[in] ObjectAttributes
Pointeur vers une structure de OBJECT_ATTRIBUTES opaque déjà initialisée avec 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 répertoriés dans le tableau suivant.
| Membre | Valeur |
|---|---|
| Longueur ULONG | Nombre d’octets de données contenus dans la structure pointée par ObjectAttributes. Cette valeur doit être au moins sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Pointeur vers une structure UNICODE_STRING qui contient le nom du canal à créer ou à ouvrir. Ce nom doit être une spécification de fichier complète ou le nom d’un objet d’appareil, sauf s’il s’agit du nom d’un fichier relatif au répertoire spécifié par RootDirectory. Par exemple, « \Device\NamedPipe\mypipe » ou « \ ?? \pipe\mypipe » peut être des spécifications de fichier valides. (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, obtenu par un appel précédent à FltCreateFileEx2. Si cette valeur a la valeur NULL, le membre ObjectNamedoit être une spécification de fichier complète qui inclut le chemin d’accès complet au canal cible. Si cette valeur n’est pas NULL, le membre ObjectName spécifie un nom de canal relatif à ce répertoire. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Descripteur de sécurité facultatif (SECURITY_DESCRIPTOR) à appliquer à un canal. Les listes de contrôle d’accès spécifiées par ce descripteur de sécurité ne sont appliquées au canal qu’au moment de sa création. Si la valeur est NULL lors de la création d’un canal, la liste de contrôle d’accès placée sur le canal dépend du système de fichiers de canal nommé et peut autoriser un client disposant d’un accès quelconque à créer un instance. |
| AttributsULONG | 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 la casse de ObjectName plutôt que d’effectuer une recherche de correspondance exacte. |
[out] IoStatusBlock
Pointeur vers une structure de IO_STATUS_BLOCK qui reçoit le status d’achèvement final et des informations sur l’opération demandée. En retour de FltCreateNamedPipeFile, le membre Information de la variable contient l’une des valeurs suivantes :
FILE_CREATED
FILE_OPENED
[in] ShareAccess
Type d’accès de partage au fichier dont l’appelant a besoin en tant qu’un ou une combinaison des indicateurs suivants. Pour éviter les erreurs de violation de partage, spécifiez tous les indicateurs d’accès de partage suivants.
| Indicateurs ShareAccess | Signification |
|---|---|
| FILE_SHARE_READ | Le fichier peut être ouvert pour l’accès en lecture par les appels d’autres threads à FltCreateNamedPipeFile. |
| FILE_SHARE_WRITE | Le fichier peut être ouvert pour l’accès en écriture par les appels d’autres threads à FltCreateNamedPipeFile. |
[in] CreateDisposition
Valeur qui détermine l’action à entreprendre, selon que le fichier existe déjà. La valeur peut être l’une des valeurs décrites dans le tableau suivant.
| Valeurs CreateDisposition | Signification |
|---|---|
| FILE_CREATE | Si le fichier existe déjà, échouez la demande et ne créez ni n’ouvrez le fichier spécifié. Si ce n’est pas le cas, créez le fichier. |
| FILE_OPEN | Si le fichier existe déjà, ouvrez-le au lieu de créer un fichier. Si ce n’est pas le cas, échouez la demande et ne créez pas de fichier. |
| FILE_OPEN_IF | Si le fichier existe déjà, ouvrez-le. Si ce n’est pas le cas, créez le fichier . |
[in] CreateOptions
Options à appliquer lors de la création ou de l’ouverture du canal, en tant que combinaison compatible des indicateurs suivants.
| Indicateurs CreateOptions | Signification |
|---|---|
| FILE_WRITE_THROUGH | Les services système, les systèmes de canal et les pilotes qui écrivent des données dans le canal doivent effectivement transférer les données dans le canal avant que toute opération d’écriture demandée soit considérée comme terminée. Cet indicateur est automatiquement défini si l’indicateur CreateOptions FILE_NO_INTERMEDIATE_BUFFERING est défini. |
| FILE_SYNCHRONOUS_IO_ALERT | Toutes les opérations sur le canal 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 canal. Si cet indicateur est défini, l’indicateur DesiredAccess SYNCHRONIZE doit également être défini pour que le Gestionnaire d’E/S utilise l’objet file comme objet de synchronisation. |
| FILE_SYNCHRONOUS_IO_NONALERT | Toutes les opérations sur le canal 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 DesiredAccess SYNCHRONIZE doit également être défini pour que le Gestionnaire d’E/S utilise l’objet file comme objet de synchronisation. |
[in] NamedPipeType
Type de canal nommé à créer. Peut avoir l’une des valeurs suivantes :
[in] ReadMode
Mode à lire à partir du canal.
[in] CompletionMode
Mode d’achèvement pour les lectures et les écritures de canal.
[in] MaximumInstances
Nombre maximal d’instances autorisées pour ce canal nommé.
InboundQuota
Nombre d’octets à réserver pour la mémoire tampon d’entrée.
OutboundQuota
Nombre d’octets à réserver pour la mémoire tampon de sortie.
[in, optional] DefaultTimeout
Délai d’expiration par défaut par incréments de 100 nanosecondes. Cette valeur est exprimée sous la forme d’un entier négatif. Par exemple, 250 millisecondes sont spécifiées comme –10 * 1000 * 250.
[in, optional] DriverContext
Pointeur facultatif vers une structure IO_DRIVER_CREATE_CONTEXT déjà initialisée par IoInitializeDriverCreateContext.
Valeur retournée
FltCreateNamedPipeFile retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, comme l’une des valeurs suivantes.
| Code de retour | Description |
|---|---|
|
Le filtre ou instance spécifié dans les paramètres De filtre ou d’instance est en cours d’opération. Ce code status peut être reçu si la requête ouverte traverse un point de montage de volume et que le paramètre Instance n’est pas NULL. Il s’agit d’un code d’erreur. |
|
Le paramètre ObjectAttributes ne contenait pas de membre RootDirectory , mais le membre ObjectName dans la structure OBJECT_ATTRIBUTES était une chaîne vide ou ne contenait pas de caractère OBJECT_NAME_PATH_SEPARATOR. Ce code d’erreur indique une syntaxe incorrecte pour le chemin d’accès de l’objet. |
Remarques
La fonction FltCreateNamedPipeFile permet aux pilotes minifilter de créer ou d’ouvrir des instances de canal. Cela est utile pour créer des canaux virtuels ou pour créer des unions de canaux pour le multiplexage des E/S.
Le paramètre instance est NULL ou est précédemment défini en l’attachant au volume de canal nommé. Un pointeur de volume est obtenu en passant « \Device\NamedPipe » comme nom du volume à FltGetVolumeFromName.
Pour spécifier un paramètre de création supplémentaire (ECP) dans le cadre d’une opération de création, initialisez le membre ExtraCreateParameter de la structure IO_DRIVER_CREATE_CONTEXT avec la routine FltAllocateExtraCreateParameterList . Si les fournisseurs d’environnement d’environnement sont utilisés, ils doivent être alloués, initialisés et libérés à l’aide de leurs routines de support associées. Lors du retour de l’appel de FltCreateNamedPipeFile, la liste ECP est inchangée et peut être passée à des appels supplémentaires de FltCreateNamedPipeFile pour d’autres opérations de création. La structure de liste ECP n’est pas automatiquement désallouée. L’appelant de FltCreateNamedPipeFile doit libérer cette structure en appelant la routine FltFreeExtraCreateParameterList .
Si Instance n’a pas la valeur NULL, la demande de création de FltCreateNamedPipeFile est envoyée uniquement aux instances jointes sous le pilote minifilter spécifié instance et au système de fichiers de canal nommé. Le instance spécifié et les instances jointes ci-dessus ne reçoivent pas la demande de création. Si aucune instance n’est spécifiée, la demande va en haut de la pile et est reçue par toutes les instances et le système de fichiers de canal nommé.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible dans Windows 8. |
| Plateforme cible | Universal |
| En-tête | fltkernel.h (incluez FltKernel.h) |
| Bibliothèque | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
Voir aussi
FltAllocateExtraCreateParameterList