Fonction FltCreateMailslotFile (fltkernel.h)
Les pilotes de minifiltre appellent FltCreateMailslotFile pour créer un nouveau canal ou ouvrir un maillot existant.
Syntaxe
NTSTATUS FLTAPI FltCreateMailslotFile(
[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 CreateOptions,
[in] ULONG MailslotQuota,
[in] ULONG MaximumMessageSize,
[in] PLARGE_INTEGER ReadTimeout,
[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 maillot. 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 à FltCreateMailslotFile 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 à FltCreateMailslotFile 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.
| Indicateur DesiredAccess | Signification |
|---|---|
| FILE_READ_DATA | Les données peuvent être lues à partir du maillot 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 listes de contrôle d’accès et les informations de propriété associées au maillot peuvent être lues. |
| FILE_WRITE_DATA | Les données peuvent être écrites dans le maillot. |
| FILE_WRITE_ATTRIBUTES | Les indicateurs FileAttributes peuvent être écrits. |
| FILE_APPEND_DATA | Les données peuvent être ajoutées au maillot. |
| WRITE_DAC | La liste DE contrôle d’accès discrétionnaire associée au maillot peut être écrite. |
| WRITE_OWNER | Les informations de propriété associées au maillot peuvent être écrites. |
| ACCESS_SYSTEM_SECURITY | L’appelant aura un accès en écriture à la SACL du maillot. |
| 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 maillot à 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\Mailslot\myslot » ou « ?? \mailslot\myslot » 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 dans un répertoire, obtenu par un appel précédent à FltCreateFileEx2. Si cette valeur est NULL, le membre ObjectName doit être une spécification de fichier complète qui inclut le chemin d’accès complet au maillot cible. Si cette valeur n’est pas NULL, le membre ObjectName spécifie un nom de maillot relatif à ce répertoire. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Facultatif SECURITY_DESCRIPTOR à appliquer à un maillot. Les listes de contrôle d’accès spécifiées par ce descripteur de sécurité ne sont appliquées au maillot qu’au moment de sa création. Si la valeur est NULL lors de la création d’un maillot, la liste de contrôle d’accès placée sur le maillot dépend du système de fichiers mailslot et peut autoriser un client disposant d’un accès quelconque à créer un instance. |
| 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 la casse de ObjectName plutôt que d’effectuer une recherche de correspondance exacte. |
[out] IoStatusBlock
Pointeur vers une structure IO_STATUS_BLOCK qui reçoit l’achèvement final status et des informations sur l’opération demandée. En retour de FltCreateMailslotFile, le membre Information de la variable contient l’une des valeurs suivantes :
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
Options à appliquer lors de la création ou de l’ouverture du maillot, en tant que combinaison compatible des indicateurs suivants.
| Indicateurs | Signification |
|---|---|
| FILE_WRITE_THROUGH | Les services système, les systèmes de fichiers et les pilotes qui écrivent des données dans le maillot doivent effectivement transférer les données dans le maillot 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 maillot 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 maintenir le contexte de position du maillot. 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 maillot 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 de 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] MailslotQuota
Taille, en octets, de la mémoire tampon pour les écritures dans le maillot.
[in] MaximumMessageSize
Taille maximale, en octets, d’un message à écrire dans le maillot. Un message de toute taille est spécifié par la valeur 0.
[in] ReadTimeout
Heure à laquelle une opération de lecture attend qu’un message soit disponible dans le maillot. Le délai d’expiration par défaut est exprimé par incréments de 100 nanosecondes sous la forme d’un entier négatif. Par exemple, 250 millisecondes sont spécifiées en tant que –10*1000*250. En outre, les valeurs suivantes ont des significations spéciales.
| Valeur | Signification |
|---|---|
| 0 | Retourne immédiatement si aucun message n’est présent. |
| -1 | Attend toujours un message. |
[in, optional] DriverContext
Pointeur facultatif vers une structure IO_DRIVER_CREATE_CONTEXT déjà initialisée par IoInitializeDriverCreateContext.
Valeur retournée
FltCreateMailslotFile retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, telle que l’une des valeurs suivantes.
| Code de retour | Description |
|---|---|
| STATUS_FLT_DELETING_OBJECT | 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. |
| STATUS_OBJECT_PATH_SYNTAX_BAD | 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 FltCreateMailslotFile permet aux pilotes minifilter de créer ou d’ouvrir des instances de maillot. Cela est utile pour créer des mailslots virtuels ou pour créer un groupe maillot qui distribue à plusieurs autres mailslots.
Le paramètre Instance est NULL ou est précédemment défini en l’attachant au volume maillot. Un pointeur de volume est obtenu en passant « \Device\Mailslot » comme nom de 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 FltCreateMailslotFile, la liste ECP est inchangée et peut être passée à des appels supplémentaires de FltCreateMailslotFile pour d’autres opérations de création. La structure de liste ECP n’est pas automatiquement désallouée. L’appelant de FltCreateMailslotFile doit libérer cette structure en appelant la routine FltFreeExtraCreateParameterList .
Si Instance n’a pas la valeur NULL, la demande de création à partir de FltCreateMailslotFile est envoyée uniquement aux instances jointes sous le pilote minifilter spécifié instance et au système de fichiers maillot. 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 maillot.
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