Fonction FltCreateSectionForDataScan (fltkernel.h)

Article
08/07/2023

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 le pilote minifiltre instance dont le contexte doit être récupéré.

[in] FileObject

Objet file pour un fichier ouvert. L’objet section est sauvegardé par le fichier spécifié. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[in] SectionContext

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

[in] DesiredAccess

Type d’accès pour l’objet de section en tant qu’un ou plusieurs des indicateurs de ACCESS_MASK suivants.

Indicateur	Permet à l’appelant de
SECTION_MAP_READ	Lire les vues de la section.
SECTION_MAP_WRITE	Écrire des vues de la section.
SECTION_QUERY	Interrogez l’objet de section pour obtenir des informations sur la section. Les pilotes doivent définir cet indicateur.
SECTION_ALL_ACCESS	Toutes les actions définies par les indicateurs précédents ainsi que par ceux définis par STANDARD_RIGHTS_REQUIRED. Pour plus d’informations sur STANDARD_RIGHTS_REQUIRED, consultez ACCESS_MASK.

[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é à un usage futur.

[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.

Indicateur	Signification
PAGE_READONLY	Active l’accès en lecture seule à la région validée des pages. Une tentative d’écriture dans la région validée entraîne une violation d’accès. Si le système fait la différence entre l’accès en lecture seule et l’accès d’exécution, une tentative d’exécution de code dans la région validée entraîne une violation d’accès.
PAGE_READWRITE	Active l’accès en lecture et en écriture à la région validée des pages.

[in] AllocationAttributes

Les masques de bits des indicateurs 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.

Indicateur	Signification
SEC_COMMIT	Alloue le stockage physique en mémoire ou dans le fichier de pagination sur le disque pour toutes les pages d’une section. Il s'agit du paramètre par défaut. Notez que cet indicateur est obligatoire et ne peut pas être omis.
SEC_FILE	Le fichier spécifié par le paramètre FileObject est un fichier mappé.

[in] Flags

Ce paramètre est réservé à un usage futur.

[out] SectionHandle

Pointeur vers une variable allouée par l’appelant qui reçoit un handle opaque vers la section. Par défaut, le handle de section est un handle utilisateur. Si l’appelant a besoin d’un handle de noyau, il doit passer un pointeur vers une structure OBJECT_ATTRIBUTES initialisée dans le paramètre ObjectAttributes avec l’indicateur 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 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 retournée

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

Code de retour	Description
STATUS_END_OF_FILE	La taille du fichier spécifiée par le paramètre FileObject est égale à zéro.
STATUS_FILE_LOCK_CONFLICT	Le fichier spécifié par le paramètre FileObject est verrouillé.
STATUS_INSUFFICIENT_RESOURCES	FltCreateSectionForDataScan a rencontré un échec d’allocation de pool.
STATUS_INVALID_FILE_FOR_SECTION	Le fichier spécifié par le paramètre FileObject ne prend pas en charge les sections.
STATUS_INVALID_PARAMETER	Le minifiltre n’est pas inscrit.
STATUS_INVALID_PARAMETER_8	La valeur spécifiée pour le paramètre SectionPageProtection n’est pas valide.
STATUS_INVALID_PARAMETER_9	L’appelant a spécifié une valeur non valide pour le paramètre AllocationAttributes .
STATUS_NOT_SUPPORTED	Le volume attaché à cette instance ne prend pas en charge les contextes de section.
STATUS_PRIVILEGE_NOT_HELD	L’appelant ne disposait pas des privilèges requis pour créer un objet de section avec l’accès spécifié dans le paramètre DesiredAccess .
STATUS_FILE_IS_A_DIRECTORY	Le fichier spécifié par le paramètre FileObject est un répertoire.
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Le filtre instance spécifié par Instance a déjà une section ouverte pour le flux. Une seule section par flux, et par conséquent, par instance est prise en charge.

Remarques

Avant d’appeler FltCreateSectionForDataScan, un minifiltre 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 pour le thread sur lequel FltCreateSectionForDataScan est appelé.

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 vers laquelle ObjectAttributes pointe est un handle de noyau et est accessible uniquement à partir du mode noyau. Un handle créé sans l’indicateur OBJ_KERNEL_HANDLE est un handle utilisateur, accessible en mode utilisateur ou noyau. Un filtre peut créer un handle utilisateur, puis le passer à une application en mode utilisateur pour 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 le maintien d’une section ouverte est incompatible 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 la purge du cache est empêchée en raison d’une section ouverte. Un minifiltre peut fournir une routine de rappel facultative pour les notifications de ces événements. Le pilote minifiltre implémente une PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK pour recevoir ces notifications. Les notifications de conflit sont activées si le membre SectionNotificationCallback de FLT_REGISTRATION est défini sur cette routine de rappel lorsque le minifiltre 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.

Notes

Un rappel de notification de section peut se produire avant le retour de FltCreateSectionForDataScan . Un minifiltre doit être en mesure de recevoir le rappel et de gérer le cas où SectionHandle et SectionObject ne sont pas encore valides.

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

Pour obtenir des informations générales 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 Microsoft Windows SDK.

Important

Les minifiltres ne doivent pas supprimer explicitement un contexte de section passé à FltCreateSectionForDataScan. N’appelez pas FltDeleteContext après le passage d’un contexte de section à FltCreateSectionForDataScan. Un contexte de section est libéré et supprimé d’un flux en appelant FltCloseSectionForDataScan dans ce cas.

En général, les sections doivent être créées en lecture seule. En particulier, si un fichier en lecture seule se trouve dans une transaction et qu’un minifiltre ne crée pas de section en lecture seule, une écriture dans la section est ignorée et n’est pas incluse dans la transaction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8
Plateforme cible	Universal
En-tête	fltkernel.h (inclure Fltkernel.h)
Bibliothèque	FltMgr.lib
IRQL	<= APC_LEVEL