FltCreateSectionForDataScan, fonction (fltkernel.h)

La routine FltCreateSectionForDataScan crée un objet de section pour un fichier. Le gestionnaire de filtres peut éventuellement synchroniser les E/S avec la section créée.

Syntaxe

NTSTATUS FLTAPI FltCreateSectionForDataScan(
  [in]            PFLT_INSTANCE      Instance,
  [in]            PFILE_OBJECT       FileObject,
  [in]            PFLT_CONTEXT       SectionContext,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  PLARGE_INTEGER     MaximumSize,
  [in]            ULONG              SectionPageProtection,
  [in]            ULONG              AllocationAttributes,
  [in]            ULONG              Flags,
  [out]           PHANDLE            SectionHandle,
  [out]           PVOID              *SectionObject,
  [out, optional] PLARGE_INTEGER     SectionFileSize
);

Paramètres

[in] Instance

Pointeur d’instance opaque pour l’instance de pilote minifilter dont le contexte doit être récupéré.

[in] FileObject

Objet fichier d’un fichier ouvert. L’objet section est soutenu par le fichier spécifié. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] SectionContext

Pointeur vers un contexte de section précédemment alloué.

[in] DesiredAccess

Type d’accès pour l’objet de section sous la forme d’un ou plusieurs indicateurs de ACCESS_MASK suivants.

[in, optional] ObjectAttributes

Pointeur vers une structure OBJECT_ATTRIBUTES facultative qui spécifie le nom de l’objet et d’autres attributs. Utilisez la macro InitializeObjectAttributes pour initialiser cette structure.

[in, optional] MaximumSize

Ce paramètre est réservé à une utilisation ultérieure.

[in] SectionPageProtection

Protection à placer sur chaque page de la section. Spécifiez l’une des valeurs suivantes. Ce paramètre est obligatoire et ne peut pas être égal à zéro.

[in] AllocationAttributes

Les masques de bits des indicateurs de SEC_XXX déterminent les attributs d’allocation de la section. Spécifiez une ou plusieurs des valeurs suivantes. Ce paramètre est obligatoire et ne peut pas être égal à zéro.

[in] Flags

Ce paramètre est réservé à une utilisation ultérieure.

[out] SectionHandle

Pointeur vers une variable allouée par l’appelant qui reçoit un handle opaque à la section. Par défaut, le handle de section est un handle d’utilisateur. Si l’appelant a besoin d’un handle de noyau, il doit passer un pointeur vers une structure de OBJECT_ATTRIBUTES initialisée dans le paramètre ObjectAttributes avec l’indicateur de OBJ_KERNEL_HANDLE défini.

[out] SectionObject

Pointeur vers une variable allouée par l’appelant qui reçoit un pointeur opaque vers l’objet de section.

[out, optional] SectionFileSize

Pointeur vers une variable allouée par l’appelant qui reçoit la taille, en octets, du fichier au moment de la création de l’objet de section. Ce paramètre est facultatif et peut être NULL.

Valeur de retour

FltCreateSectionForDataScan retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple l’une des valeurs suivantes.

Remarques

Avant d’appeler FltCreateSectionForDataScan, un minifilter doit d’abord inscrire son volume pour l’analyse des données en appelant FltRegisterForDataScan. Comme avec d’autres éléments de contexte de filtre, SectionContext est d’abord alloué avec FltAllocateContext.

FltCreateSectionForDataScan insère le handle dans l’objet (SectionHandle) dans la table de handle de processus du thread sur lequel FltCreateSectionForDataScan est appelée.

Les handles peuvent être des handles utilisateur ou des handles de noyau. Un handle créé avec OBJ_KERNEL_HANDLE défini dans la structure OBJECT_ATTRIBUTES qui ObjectAttributes points est un handle de noyau et est accessible uniquement à partir du mode noyau. Un handle créé sans l’indicateur de OBJ_KERNEL_HANDLE est un handle d’utilisateur accessible à partir du mode utilisateur ou noyau. Un filtre peut créer un handle utilisateur, puis le transmettre à une application en mode utilisateur pour le traitement. Par exemple, un moteur d’analyse antivirus peut vivre dans une application en mode utilisateur et être alimenté par des handles utilisateur à partir d’un filtre de système de fichiers.

Certaines situations peuvent se produire lorsque la conservation d’une section ouverte n’est pas compatible avec les E/S de fichier actuelles. En particulier, les E/S de fichier qui déclenchent une purge du cache peuvent entraîner une incohérence du cache si le vidage du cache est empêché en raison d’une section ouverte. Un minifilter peut fournir une routine de rappel facultative pour les notifications de ces événements. Le pilote minifilter implémente un PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK pour recevoir ces notifications. Les notifications de conflit sont activées si l'SectionNotificationCallback membre de FLT_REGISTRATION est défini sur cette routine de rappel lorsque le minifilter est inscrit. Lorsqu’une notification est reçue, la section peut être fermée pour permettre à l’opération d’E/S en conflit de continuer.

Lorsque l’objet de section créé par cette routine n’est plus nécessaire, veillez à fermer le handle de l’objet section (SectionHandle) en appelant la routine ZwClose et en déréférencez l’objet section lui-même (SectionObject) en appelant la routine ObDereferenceObject.

Pour plus d’informations sur la création de sections mappées et de vues de mémoire, consultez Objets et vues de section. Consultez également la documentation relative à la routine CreateFileMapping dans le Kit de développement logiciel (SDK) Microsoft Windows.

Exigences

Voir aussi

ACCESS_MASK

CcPurgeCacheSection

FLT_REGISTRATION

FltAllocateContext

FltCloseSectionForDataScan

FltRegisterForDataScan

ObDereferenceObject

PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK

ZwClose

ZwCreateSection