Fonction FsRtlCreateSectionForDataScan (ntifs.h)

Article
02/26/2024

La routine FsRtlCreateSectionForDataScan crée un objet section. Utilisez cette routine avec une extrême prudence. (Voir la section Remarques suivante.)

Syntaxe

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

Paramètres

[out] SectionHandle

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

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

[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 être NULL.

[in] DesiredAccess

Spécifie l’accès souhaité pour l’objet de section en tant qu’un ou plusieurs des indicateurs de ACCESS_MASK suivants.

Indicateur DesiredAccess	Autorise l’appelant à
SECTION_MAP_READ	Affichages en lecture de la section.
SECTION_MAP_WRITE	Écrire des vues de la section.
SECTION_QUERY	Interrogez l’objet 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 STANDARD_RIGHTS_REQUIRED. (Pour plus d’informations sur STANDARD_RIGHTS_REQUIRED, consultez ACCESS_MASK.)

[in, optional] ObjectAttributes

Pointeur vers une structure OBJECT_ATTRIBUTES qui spécifie le nom de l’objet et d’autres attributs. Utilisez la macro InitializeObjectAttributes pour initialiser cette structure. Étant donné que FsRtlCreateSectionForDataScan insère cet objet dans la table de handle de processus, l’appelant doit spécifier l’attribut OBJ_KERNEL_HANDLE lorsqu’il appelle InitializeObjectAttributes.

[in, optional] MaximumSize

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

[in] SectionPageProtection

Spécifie la 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 masque 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 du 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.

Valeur retournée

FsRtlCreateSectionForDataScan retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :

Code de retour	Description
STATUS_END_OF_FILE	La taille du fichier spécifiée par le paramètre FileObject est égale à zéro. Il s’agit d’un code d’erreur.
STATUS_FILE_LOCK_CONFLICT	Le fichier spécifié par le paramètre FileObject est verrouillé. Il s’agit d’un code d’erreur.
STATUS_INSUFFICIENT_RESOURCES	FsRtlCreateSectionForDataScan a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_FILE_FOR_SECTION	Le fichier spécifié par le paramètre FileObject ne prend pas en charge les sections. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER_8	La valeur spécifiée pour le paramètre SectionPageProtection n’est pas valide. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER_9	L’appelant a spécifié une valeur non valide pour le paramètre AllocationAttributes. Il s’agit d’un code d’erreur.
STATUS_PRIVILEGE_NOT_HELD	L’appelant n’avait pas le privilège requis pour créer un objet de section avec l’accès spécifié dans le paramètre DesiredAccess. Il s’agit d’un code d’erreur.

Remarques

Important La routine FsRtlCreateSectionForDataScan ne doit être utilisée que dans les cas où un handle de l’objet de fichier spécifié dans le paramètre FileObject n’a pas encore été créé (généralement lors du traitement d’une opération post-création). Si le pilote a un handle pour l’objet fichier ou peut obtenir un handle pour l’objet fichier, le pilote doit utiliser la routine ZwCreateSection à la place.

Une fois que 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 à déréférencer 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 Microsoft Windows SDK.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Correctif cumulatif pour Windows 2000 Service Pack 4 (SP4) ; Correctif cumulatif du Gestionnaire de filtres pour Windows XP Service Pack 2 (SP2).
Serveur minimal pris en charge	Microsoft Windows Server 2003 SP1
Plateforme cible	Universal
En-tête	ntifs.h (include Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL

Voir aussi