Fonction FltAllocateExtraCreateParameter (fltkernel.h)

Article
08/07/2023

La routine FltAllocateExtraCreateParameter alloue un pool de mémoire paginée à une structure de contexte ECP (Extra Create Parameter) définie par l’utilisateur et génère un pointeur vers cette structure.

Syntaxe

NTSTATUS FLTAPI FltAllocateExtraCreateParameter(
  [in]           PFLT_FILTER                                    Filter,
  [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] Filter

Pointeur de filtre opaque pour le pilote minifilter. Ce pointeur identifie de façon unique le pilote minifilter et reste constant tant que le pilote minifilter est chargé.

[in] EcpType

Pointeur vers un GUID défini par l’utilisateur indiquant 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 définie par l’utilisateur.

[in] Flags

Définit les options d’allocation de pool. L’exemple suivant décrit comment le pool est alloué lorsqu’une ou plusieurs des valeurs d’indicateur répertoriées sont combinées avec le 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 : tout le pool alloué par cette routine est facturé par rapport au 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 minifiltre 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 FltAllocateExtraCreateParameter ) 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 Tag de ExAllocatePoolWithTag.

[out] EcpContext

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

Valeur retournée

FltAllocateExtraCreateParameter peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameter n’a pas pu allouer suffisamment de mémoire pour une structure ECP. Dans ce cas, EcpContext aura 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 FltAllocateExtraCreateParameter alloue un pool de mémoire paginée pour une structure de contexte ECP définie par l’utilisateur. Si le masque de bits FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL est utilisé comme décrit ci-dessus, un pool de mémoire non paginé est alloué. Une fois que ce pool a été alloué et que la structure de contexte ECP a été 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 (liste ECP).

Le pool de mémoire alloué par la routine FltAllocateExtraCreateParameter n’est pas automatiquement libéré par le système d’exploitation. Ce pool de mémoire doit finalement être libéré à l’aide de l’une des méthodes suivantes :

Appelez la routine FltRemoveExtraCreateParameter pour supprimer la structure de contexte ECP de la liste ECP, puis appelez la routine FltFreeExtraCreateParameter pour libérer la structure de contexte ECP elle-même. La liste ECP existe toujours.
Appelez la routine FltFreeExtraCreateParameterList : cela libère la liste ECP, y compris tous les éléments de liste (structures de contexte ECP). La liste ECP est détruite.

Toutefois, si un pilote de système de fichiers ou de filtre de système de fichiers attache un ecP à 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, processus qui peut nécessiter la génération de plusieurs demandes de IRP_MJ_CREATE.