FsRtlCreateSectionForDataScan, fonction (ntifs.h)

La routine FsRtlCreateSectionForDataScan crée un objet de section. Utilisez cette routine avec une prudence extrême. (Consultez 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 vers l’objet section.

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

[in] FileObject

Objet fichier pour 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] DesiredAccess

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

indicateur DesiredAccess	Autorise l’appelant à
SECTION_MAP_READ	Lire les vues de la section.
SECTION_MAP_WRITE	Écrivez des vues de la section.
SECTION_QUERY	Interrogez l’objet de section pour plus d’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 celle définie 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é à une utilisation ultérieure.

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

Drapeau	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 différencie l’accès en lecture seule et l’accès à l’exécution, une tentative d’exécution de code dans la région validée entraîne une violation d’accès.
PAGE_READWRITE	Permet l’accès en lecture et en écriture à la région validée des pages.

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

Drapeau	Signification
SEC_COMMIT	Alloue un 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é à une utilisation ultérieure.

Valeur de retour

FsRtlCreateSectionForDataScan retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, comme l’une des opérations suivantes :

Retourner le code	Description
STATUS_END_OF_FILE	La taille du fichier spécifié 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’a 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 vers 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 de fichier ou peut obtenir un handle à l’objet de 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 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

Exigence	Valeur
client minimum 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 minimum pris en charge	Microsoft Windows Server 2003 SP1
plateforme cible	Universel
d’en-tête	ntifs.h (include Ntifs.h)
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL

Voir aussi

ACCESS_MASK

ccPurgeCacheSection

mmFlushImageSection

mmForceSectionClosed

ZwCreateSection