FltCreateMailslotFile, fonction (fltkernel.h)
Les pilotes minifilter appellent FltCreateMailslotFile pour créer un 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 d’instance opaque pour l’instance de pilote minifilter à laquelle la demande de création doit être envoyée. L’instance doit être attachée au volume du système de fichiers maillot. Ce paramètre est facultatif et peut être NULL. Si ce paramètre est NULL, la requête est envoyée à l’objet d’appareil en haut de la pile de pilotes du système de fichiers pour le volume. S’il n’est pasNULL, la requête est envoyée uniquement aux instances de pilote minifilter attachées sous l’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 d’objet de fichier si l’appel à FltCreateMailslotFile réussit. Ce paramètre est facultatif et peut être NULL.
[in] DesiredAccess
Masque de bits des indicateurs qui spécifient le type d’accès requis par l’appelant au fichier ou au répertoire. L’ensemble d’indicateurs de 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 contrôle d’accès liste 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 | indicateurs de 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 DACL 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 mail maillot. |
| SYNCHRONISER | L’appelant peut synchroniser l’achèvement d’une opération d’E/S en attendant que le 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 indicateurs génériques ACCESS_MASK suivants pour n’importe quel 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 aux indicateurs DesiredAccess |
|---|---|
| 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 |
|---|---|
| de 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 par rapport 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 vers 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 complet du maillot cible. Si cette valeur n’est pasnull, le membre ObjectName spécifie un nom de maillot relatif à ce répertoire. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | SECURITY_DESCRIPTOR facultatives à appliquer à un maillot. listes de contrôle d’accès spécifiées par un descripteur de sécurité ne sont appliquées qu’au maillot lors de sa création. Si la valeur est null lorsqu’un maillot est créé, la liste de contrôle d’accès placée sur le maillot dépend du système de fichiers maillot et peut autoriser un client disposant d’un accès quelconque à créer une instance. |
| attributs ULONG | Ensemble d’indicateurs qui contrôlent les attributs de l’objet de fichier. Si l’appelant est en cours d’exécution dans le contexte du processus système, ce paramètre peut être égal à zéro. Sinon, l’appelant doit définir l’indicateur de OBJ_KERNEL_HANDLE. L’appelant peut également définir l’indicateur de OBJ_CASE_INSENSITIVE, ce qui indique que le code de recherche de noms doit ignorer le cas de ObjectName plutôt que d’effectuer une recherche exacte-correspondance. |
[out] IoStatusBlock
Pointeur vers une structure IO_STATUS_BLOCK qui reçoit l’état d’achèvement final et les informations relatives à l’opération demandée. À partir 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.
| Drapeaux | 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 réellement 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 au nom de l’appelant est soumise à un arrêt prématuré des alertes. Cet indicateur entraîne également le maintien du contexte de position du courrier électronique. Si cet indicateur est défini, l’indicateur DesiredAccess SYNCHRONIZE doit également être défini afin que le Gestionnaire d’E/S utilise l’objet de fichier 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 mise en file d’attente d’E/S et la saisie semi-automatique ne sont pas soumises à des alertes. Cet indicateur entraîne également le maintien du contexte de position du fichier par le système d’E/S. Si cet indicateur est défini, l’indicateur DesiredAccess SYNCHRONIZE doit également être défini afin que le Gestionnaire d’E/S utilise l’objet de fichier 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é en 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 de retour
FltCreateMailslotFile retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple l’une des valeurs suivantes.
| Retourner le code | Description |
|---|---|
| STATUS_FLT_DELETING_OBJECT | Le filtre ou l’instance spécifié dans les paramètres Filter ou Instance est détruit. Ce code d’état peut être reçu si la requête ouverte traverse un point de montage de volume et que le paramètre instance de n’est pasNULL. 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 maillots virtuels ou pour créer un groupe de mailslots qui distribue à plusieurs autres mailslots.
Le paramètre de l’instance est NULL ou est précédemment défini en attachant le volume de mailslot. 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 PPE sont utilisées, elles doivent être allouées, initialisées et libérées à l’aide de leurs routines de support associées. Lors du retour de l’appel de FltCreateMailslotFile, la liste ECP n’est pas modifié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 désallouée automatiquement. L’appelant de FltCreateMailslotFile doit libérer cette structure en appelant la routine FltFreeExtraCreateParameterList.
Si instance n’est pas NULL, la demande de création de FltCreateMailslotFile est envoyée uniquement aux instances jointes sous l’instance de pilote minifilter spécifiée et au système de fichiers maillot. L’instance spécifiée et les instances jointes ci-dessus ne reçoivent pas la demande de création. Si aucune instance n’est spécifiée, la requête passe en haut de la pile et est reçue par toutes les instances et le système de fichiers maillot.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible dans Windows 8. |
| plateforme cible | Universel |
| d’en-tête | fltkernel.h (include FltKernel.h) |
| bibliothèque | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
Voir aussi
FltAllocateExtraCreateParameterList