Fonction FltCreateSectionForDataScan (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 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 |