FLT_IO_PARAMETER_BLOCK structure (fltkernel.h)

Article
05/31/2024

La structure FLT_IO_PARAMETER_BLOCK contient les paramètres de l’opération d’E/S représentée par une structure de données de rappel FLT_CALLBACK_DATA .

Syntaxe

typedef struct _FLT_IO_PARAMETER_BLOCK {
  ULONG          IrpFlags;
  UCHAR          MajorFunction;
  UCHAR          MinorFunction;
  UCHAR          OperationFlags;
  UCHAR          Reserved;
  PFILE_OBJECT   TargetFileObject;
  PFLT_INSTANCE  TargetInstance;
  FLT_PARAMETERS Parameters;
} FLT_IO_PARAMETER_BLOCK, *PFLT_IO_PARAMETER_BLOCK;

Membres

IrpFlags

Masque de bits d’indicateurs qui spécifient différents aspects de l’opération d’E/S. Ces indicateurs sont utilisés uniquement pour les opérations basées sur IRP. Le tableau suivant présente les valeurs d’indicateur.

Valeur	Signification
IRP_BUFFERED_IO	L’opération est une opération d’E/S mise en mémoire tampon.
IRP_CLOSE_OPERATION	L’opération est une opération de nettoyage ou de fermeture.
IRP_DEALLOCATE_BUFFER	Le gestionnaire d’E/S libère la mémoire tampon pendant la phase d’achèvement de l’IRP.
IRP_INPUT_OPERATION	L’opération est une opération d’entrée.
IRP_NOCACHE	L’opération est une opération d’E/S non mise en cache.
IRP_PAGING_IO	L’opération est une opération d’E/S de pagination.
IRP_SYNCHRONOUS_API	L’opération d’E/S est synchrone.
IRP_SYNCHRONOUS_PAGING_IO	L’opération est une opération d’E/S de pagination synchrone.
IRP_MOUNT_COMPLETION	Un montage de volume est terminé pour l’opération.
IRP_CREATE_OPERATION	L’opération est une opération de création ou d’ouverture.
IRP_READ_OPERATION	L’opération d’E/S est destinée à la lecture.
IRP_WRITE_OPERATION	L’opération d’E/S est destinée à l’écriture.
IRP_DEFER_IO_COMPLETION	L’achèvement des E/S de l’opération est différé.
IRP_ASSOCIATED_IRP	L’opération est associée à un IRP principal.
IRP_OB_QUERY_NAME	L’opération est une requête de nom asynchrone.
IRP_HOLD_DEVICE_QUEUE	Réservé.
IRP_UM_DRIVER_INITIATED_IO	L’opération provient d’un pilote en mode utilisateur.

MajorFunction

Code de fonction principal pour l’opération d’E/S. Les codes de fonction principaux sont utilisés pour les opérations basées sur IRP, les opérations d’E/S rapides et les opérations de rappel de système de fichiers (FSFilter). Pour plus d’informations sur les opérations supplémentaires, consultez FLT_PARAMETERS.

MinorFunction

Code de fonction secondaire pour l’opération d’E/S. Ce membre est facultatif et peut être NULL. La valeur du membre MajorFunction détermine les valeurs possibles. Pour plus d’informations sur les codes de fonction secondaires, consultez FLT_PARAMETERS.

OperationFlags

Masque de bits d’indicateurs qui spécifient différents aspects de l’opération d’E/S. Ces indicateurs sont utilisés uniquement pour les opérations basées sur IRP. Le Gestionnaire de filtres copie ces indicateurs à partir du membre Flags de la structure IO_STACK_LOCATION qui est associée à l’IRP. Le tableau suivant présente les valeurs d’indicateur les plus couramment utilisées.

Valeur	Signification
SL_CASE_SENSITIVE	Utilisé pour IRP_MJ_CREATE. Si cet indicateur est défini, les comparaisons de noms de fichiers doivent respecter la casse.
SL_EXCLUSIVE_LOCK	Utilisé pour IRP_MJ_LOCK_CONTROL. Si cet indicateur est défini, un verrou exclusif de plage d’octets est demandé. Sinon, un verrou partagé est demandé.
SL_FAIL_IMMEDIATELY	Utilisé pour IRP_MJ_LOCK_CONTROL. Si cet indicateur est défini, la demande de verrouillage doit échouer si elle ne peut pas être accordée immédiatement.
SL_FORCE_ACCESS_CHECK	Utilisé pour IRP_MJ_CREATE. Si cet indicateur est défini, des vérifications d’accès doivent être effectuées même si la valeur du membre RequestorMode de l’IRP est KernelMode.
SL_FORCE_DIRECT_WRITE	Utilisé pour IRP_MJ_WRITE et IOCTL_DISK_COPY_DATA. Si cet indicateur est défini, les pilotes en mode noyau peuvent écrire dans des zones de volume qu’ils ne peuvent normalement pas écrire pour des raisons de sécurité. Cet indicateur est vérifié à la fois au niveau de la couche du système de fichiers et de la couche de pile de stockage. L’indicateur SL_FORCE_DIRECT_WRITE est disponible dans Windows Vista et les versions ultérieures de Windows.
SL_INDEX_SPECIFIED	Utilisé pour IRP_MJ_DIRECTORY_CONTROL, IRP_MJ_QUERY_EA et IRP_MJ_SET_QUOTA. Si cet indicateur est défini, l’analyse des informations d’annuaire, de quota ou d’attribut étendu doit commencer à l’entrée dans la liste dont l’index est spécifié.
SL_OPEN_PAGING_FILE	Utilisé pour IRP_MJ_CREATE. Si cet indicateur est défini, le fichier est un fichier de pagination.
SL_OPEN_TARGET_DIRECTORY	Utilisé pour IRP_MJ_CREATE. Si cet indicateur est défini, le répertoire parent du fichier doit être ouvert.
SL_OVERRIDE_VERIFY_VOLUME	Utilisé pour IRP_MJ_DIRECTORY_CONTROL, IRP_MJ_READ et IRP_MJ_WRITE. Si cet indicateur est défini, l’opération d’E/S doit être effectuée même si l’indicateur DO_VERIFY_VOLUME est défini sur l’objet d’appareil du volume.
SL_RESTART_SCAN	Utilisé pour IRP_MJ_DIRECTORY_CONTROL, IRP_MJ_QUERY_EA et IRP_MJ_SET_QUOTA. Si cet indicateur est défini, l’analyse des informations d’annuaire, de quota ou d’attribut étendu doit commencer à la première entrée du répertoire ou de la liste. Sinon, l’analyse doit reprendre à partir de l’analyse précédente.
SL_RETURN_SINGLE_ENTRY	Utilisé pour IRP_MJ_DIRECTORY_CONTROL, IRP_MJ_QUERY_EA et IRP_MJ_SET_QUOTA. Si cet indicateur est défini, l’analyse des informations d’annuaire, de quota ou d’attribut étendu doit retourner uniquement la première entrée trouvée.
SL_WATCH_TREE	Utilisé pour IRP_MJ_DIRECTORY_CONTROL. Si cet indicateur est défini, tous les sous-répertoires de ce répertoire doivent également être surveillés. Sinon, seul le répertoire lui-même doit être surveillé.
SL_WRITE_THROUGH	Utilisé pour IRP_MJ_WRITE. Si cet indicateur est défini, les données du fichier doivent être écrites dans le stockage persistant, pas seulement dans le cache.

Reserved

Réservé pour le système. Ne pas utiliser.

TargetFileObject

Pointeur d’objet fichier pour le fichier ou le répertoire qui est la cible pour cette opération d’E/S.

TargetInstance

Pointeur d’instance opaque pour le minifiltre qui est la cible de cette opération d’E/S.

Parameters

Une structure FLT_PARAMETERS qui contient les paramètres de l’opération d’E/S spécifiées par les membres MajorFunction et MinorFunction .

Remarques

La structure FLT_IO_PARAMETER_BLOCK contient les paramètres de l’opération d’E/S représentée par une structure de données de rappel (FLT_CALLBACK_DATA). La structure de données de rappel contient un pointeur vers la structure FLT_IO_PARAMETER_BLOCK dans son membre Iopb .

Un minifilter reçoit un pointeur vers la structure de données de rappel en tant que paramètre d’entrée Data ou CallbackData vers les types de routine de rappel suivants :

Les routines de rappel de préopération et de post-opération d’un minifiltre peuvent modifier le contenu de la structure FLT_IO_PARAMETER_BLOCK pour l’opération d’E/S, à l’exception des membres MajorFunction et Reserved . Si c’est le cas, il doit appeler FltSetCallbackDataDirty, sauf s’il a également modifié le membre IoStatus de la structure de données de rappel pour l’opération. Sinon, les valeurs modifiées sont ignorées.

Lorsque le Gestionnaire de filtres émet un rappel de préopération ou de post-opération à un minifiltre, FltObjects-FileObject> et TargetFileObject (CallbackData-Iopb-TargetFileObject>>) sont initialement identiques. Si un minifiltre modifie TargetFileObject ou TargetInstance, son appel ultérieur à FltSetCallbackDataDirty à partir d’un rappel de préopération entraîne le remplacement de FltObjects-FileObjects> et FltObjects-Instance> avant d’envoyer l’opération à des filtres inférieurs.

Si la routine de rappel de préopération d’un minifiltre modifie les paramètres d’une opération d’E/S, tous les minifiltres en dessous dans la pile d’instances de minifiltre reçoivent les paramètres modifiés dans leurs routines de rappel de préopération et de postopération.

Les paramètres modifiés ne sont pas reçus par la routine de rappel de post-opération du minifilter ou par les minifiltres au-dessus de ce minifiltre dans la pile d’instances du minifilter. Dans tous les cas, les routines de rappel de préopération et de post-opération d’un minifilter reçoivent les mêmes valeurs de paramètre d’entrée.

Si un minifilter modifie la valeur du membre TargetInstance , la nouvelle valeur doit être un pointeur vers une instance du même minifiltre à la même altitude sur un volume différent. En outre, l’objet d’appareil du nouveau volume doit avoir une taille de pile supérieure ou égale à celle de l’objet appareil du volume d’origine.

Pour obtenir la taille de pile d’un objet de périphérique de volume, avec un pointeur d’instance opaque pour une instance attachée au volume, procédez comme suit :

Appelez FltGetVolumeFromInstance pour obtenir le pointeur de volume.
Appelez FltGetDeviceObject pour obtenir un pointeur vers l’objet de périphérique de volume. Ce pointeur est retourné dans le paramètre DeviceObject . La taille de la pile de l’objet d’appareil se trouve dans DeviceObject-StackSize>.
Lorsque le pointeur de volume n’est plus nécessaire, appelez FltObjectDereference pour décrémenter son nombre de références.
Lorsque le pointeur d’objet de périphérique de volume n’est plus nécessaire, appelez ObDereferenceObject pour décrémenter son nombre de références.

Un minifilter peut modifier la valeur du membre TargetFileObject . Toutefois, la nouvelle valeur doit être un pointeur vers un objet file pour un fichier qui réside sur le même volume que l’instance spécifiée par le membre TargetInstance .

Un minifilter ne peut pas modifier en toute sécurité la valeur du membre MajorFunction . Au lieu de cela, il doit lancer une nouvelle opération d’E/S.

Un minifiltre peut lancer une opération d’E/S en appelant une routine de support comme FltReadFile ou en appelant FltAllocateCallbackData pour allouer une structure de données de rappel ; initialisation des paramètres d’E/S dans la structure FLT_IO_PARAMETER_BLOCK et transmission de la structure de données de rappel à FltPerformSynchronousIo ou FltPerformAsynchronousIo.

Notes

Utilisez des routines de support dans la mesure du possible lors du lancement d’opérations d’E/S. Un minifiltre doit allouer ses propres données de rappel uniquement s’il n’existe aucune fonction de prise en charge pour une opération d’E/S particulière.