Fonction NtCreateSectionEx (ntifs.h)

Article
08/07/2023

NtCreateSectionEx crée un objet de section** et ouvre un handle à l’objet avec l’accès souhaité spécifié. Il s’agit d’une version étendue de NtCreateSection qui crée un objet de section en spécifiant pour indiquer qu’il s’agit en fait d’une section AWE (Address Windowing Extensions).

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateSectionEx(
  [out]          PHANDLE                 SectionHandle,
  [out]          ACCESS_MASK             DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES      ObjectAttributes,
  [in, optional] PLARGE_INTEGER          MaximumSize,
  [in]           ULONG                   SectionPageProtection,
  [in]           ULONG                   AllocationAttributes,
  [in, optional] HANDLE                  FileHandle,
  [in/out]       PMEM_EXTENDED_PARAMETER ExtendedParameters,
                 ULONG                   ExtendedParameterCount
);

Paramètres

[out] SectionHandle

Pointeur vers une variable HANDLE qui reçoit un handle pour l’objet section.

[out] DesiredAccess

Spécifie une valeur ACCESS_MASK qui détermine l’accès demandé à l’objet . En plus des droits d’accès définis pour tous les types d’objets, l’appelant peut spécifier l’un des droits d’accès suivants, qui sont spécifiques aux objets de section :

Indicateur DesiredAccess	Permet à l’appelant d’effectuer cette opération
SECTION_EXTEND_SIZE	Étendez dynamiquement la taille de la section.
SECTION_MAP_EXECUTE	Exécutez les vues de la section.
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	Tous les indicateurs précédents combinés avec STANDARD_RIGHTS_REQUIRED.

[in, optional] ObjectAttributes

Pointeur vers une structure OBJECT_ATTRIBUTES qui spécifie le nom de l’objet et d’autres attributs. Utilisez InitializeObjectAttributes pour initialiser cette structure. Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit définir l’attribut OBJ_KERNEL_HANDLE lorsqu’il appelle InitializeObjectAttributes.

[in, optional] MaximumSize

Spécifie la taille maximale, en octets, de la section. NtCreateSection arrondit cette valeur au multiple le plus proche de PAGE_SIZE. Si la section est sauvegardée par le fichier de pagination, MaximumSize spécifie la taille réelle de la section. Si la section est sauvegardée par un fichier ordinaire, MaximumSize spécifie la taille maximale à laquelle le fichier peut être étendu ou mappé.

[in] SectionPageProtection

Spécifie la protection à placer sur chaque page de la section . Utilisez l’une des quatre valeurs suivantes : PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE ou PAGE_WRITECOPY. Pour obtenir une description de ces valeurs, consultez CreateFileMapping.

[in] AllocationAttributes

Spécifie un masque de bits d’indicateurs SEC_XXX qui détermine les attributs d’allocation de la section. Pour obtenir une description de ces indicateurs, consultez CreateFileMapping.

[in, optional] FileHandle

Spécifie éventuellement un handle pour un objet de fichier ouvert. Si la valeur de FileHandle est NULL, la section est sauvegardée par le fichier de pagination. Sinon, la section est sauvegardée par le fichier spécifié.

[in/out] ExtendedParameters

Pointeur vers un tableau de MEM_EXTENDED_PARAMETER structure le contient les paramètres étendus pour créer la section.

ExtendedParameterCount

Taille du tableau vers lequel extendedParameters pointe.

Valeur retournée

NtCreateSectionEx retourne STATUS_SUCCESS en cas de réussite, ou le code d’erreur NTSTATUS approprié en cas d’échec. Les codes status d’erreur possibles sont les suivants :

Code de retour	Description
STATUS_FILE_LOCK_CONFLICT	Le fichier spécifié par le paramètre FileHandle est verrouillé.
STATUS_INVALID_FILE_FOR_SECTION	Le fichier spécifié par FileHandle ne prend pas en charge les sections.
STATUS_INVALID_PAGE_PROTECTION	La valeur spécifiée pour le paramètre SectionPageProtection n’est pas valide.
STATUS_MAPPED_FILE_SIZE_ZERO	La taille du fichier spécifié par FileHandle est égale à zéro et MaximumSize à zéro.
STATUS_SECTION_TOO_BIG	La valeur de MaximumSize est trop grande. Cela se produit lorsque MaximumSize est supérieur à la valeur maximale définie par le système pour les sections, ou si MaximumSize est supérieur au fichier spécifié et que la section n’est pas accessible en écriture.

Remarques

Une fois que le handle pointé par SectionHandle n’est plus utilisé, le pilote doit appeler NtClose pour le fermer.

Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit s’assurer que tous les handles qu’il crée sont des handles privés. Sinon, le handle est accessible par le processus dans le contexte dans lequel le pilote est en cours d’exécution. Pour plus d’informations, consultez Handles d’objet.

Pour plus d’informations sur la configuration des sections mappées et des vues de la mémoire, consultez Sections et vues.

Notes

Si l’appel à cette fonction se produit en mode utilisateur, vous devez utiliser le nom « NtCreateSectionEx » au lieu de « ZwCreateSectionEx ».

Pour les appels provenant de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

ExtendedParameters est un paramètre étendu basé sur la pile si le nœud NUMA préféré a été spécifié.

Une seule instance d’un paramètre étendu peut être spécifiée.

Convertissez en un numéro de nœud numa basé sur 1 qui est attendu en aval de cette API.