Fonction FsRtlAllocateExtraCreateParameter (ntifs.h)

Article
08/07/2023

La routine FsRtlAllocateExtraCreateParameter alloue de la mémoire pour une structure de contexte de paramètre de création supplémentaire (ECP) et génère un pointeur vers cette structure.

Syntaxe

NTSTATUS FsRtlAllocateExtraCreateParameter(
  [in]           LPCGUID                                        EcpType,
  [in]           ULONG                                          SizeOfContext,
  [in]           FSRTL_ALLOCATE_ECP_FLAGS                       Flags,
  [in, optional] PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK CleanupCallback,
  [in]           ULONG                                          PoolTag,
  [out]          PVOID                                          *EcpContext
);

Paramètres

[in] EcpType

Pointeur vers un GUID qui indique le type de la structure de contexte ECP. Pour plus d’informations, consultez Utilisation de GUID dans les pilotes .

[in] SizeOfContext

Taille, en octets, de la structure de contexte.

[in] Flags

Définit les options d’allocation de pool. L’article suivant décrit comment le pool est alloué lorsqu’une ou plusieurs des valeurs d’indicateur répertoriées sont combinées au paramètre Flags à l’aide d’une opération OR au niveau du bit :

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL : un pool non paginé sera alloué. Si cette valeur d’indicateur n’est pas utilisée, le pool paginé est alloué.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA : tous les pools alloués par FsRtlAllocateExtraCreateParameter seront facturés sur le quota de mémoire du processus actuel.

Si plusieurs indicateurs sont utilisés, tous les effets associés aux valeurs d’indicateur utilisées se produisent.

[in, optional] CleanupCallback

Pointeur facultatif vers une routine de rappel de nettoyage définie par filtre de type PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. La routine de rappel de nettoyage est appelée lorsque la structure ECP (créée par la routine FsRtlAllocateExtraCreateParameter ) est supprimée. Définissez ce paramètre sur NULL si une routine de rappel de nettoyage n’est pas applicable.

[in] PoolTag

Spécifie la balise de pool pour la mémoire allouée. Pour plus d’informations, consultez le paramètre Tagd’ExAllocatePoolWithTag.

[out] EcpContext

Reçoit un pointeur vers la structure de contexte ECP allouée. Si la routine n’a pas pu allouer un pool suffisant, la valeur indiquée par EcpContext est NULL et FsRtlAllocateExtraCreateParameter retourne status code STATUS_INSUFFICIENT_RESOURCES.

Valeur retournée

FltAllocateExtraCreateParameter retourne un code status tel que l’un des éléments suivants :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	FsRtlAllocateExtraCreateParameter n’a pas pu allouer suffisamment de mémoire pour une structure ECP. Dans ce cas, EcpContext a la valeur NULL.
STATUS_SUCCESS	La structure ECP a été correctement allouée. Dans ce cas, un pointeur vers la structure allouée est retourné dans le paramètre EcpContext .

Remarques

Par défaut, la routine FsRtlAllocateExtraCreateParameter alloue un pool de mémoire paginée pour une structure de contexte ECP. Si le masque de bits FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL est utilisé comme décrit dans le paramètre Flags , un pool de mémoire non paginé est alloué. Une fois ce pool alloué et la structure de contexte ECP initialisée, la routine FltInsertExtraCreateParameter est utilisée pour insérer la structure de contexte ECP (élément de liste ECP) dans une structure de liste ECP (ECP_LIST).

Si l’appelant alloue ECP_LIST et qu’un ou plusieurs ECPs sont utilisés dans un appel à IoCreateFileEx, la description précédente est correcte. Dans ce cas, le système ne libère aucun des ECPs, de sorte que l’appelant peut effectuer plusieurs appels à IoCreateFileEx avec le même ensemble d’ECP. Toutefois, si un pilote de filtre de système de fichiers ou de système de fichiers joint un fournisseur d’environnement à un ECP_LIST existant ou nouvellement créé lors du traitement d’une demande de IRP_MJ_CREATE, ce fournisseur d’environnement est automatiquement nettoyé à la fin de l’IRP. Par conséquent, un pilote de filtre n’a pas besoin d’propre les fournisseurs d’environnement qui sont ajoutés dynamiquement. Cela permet à l’ECP d’un pilote de filtre d’être correctement propagé sur les points d’analyse, un processus qui peut nécessiter la génération de plusieurs demandes IRP_MJ_CREATE.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	La routine FsRtlAllocateExtraCreateParameter est disponible à partir de Windows Vista.
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL