Función FltAllocateExtraCreateParameter (fltkernel.h)

Artículo
02/29/2024

La rutina FltAllocateExtraCreateParameter asigna un grupo de memoria paginada para una estructura de contexto de parámetro de creación adicional (ECP) definida por el usuario y genera un puntero a esa estructura.

Sintaxis

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
);

Parámetros

[in] Filter

Puntero de filtro opaco para el controlador de minifiltro. Este puntero identifica de forma única el controlador de minifiltro y permanece constante siempre que se cargue el controlador de minifiltro.

[in] EcpType

Puntero a un GUID definido por el usuario que indica el tipo de la estructura de contexto ECP. Consulte Uso de GUID en Controladores para obtener más información.

[in] SizeOfContext

Tamaño, en bytes, de la estructura de contexto definida por el usuario.

[in] Flags

Define las opciones de asignación del grupo. A continuación se describe cómo se asignará el grupo cuando uno o varios de los valores de marca enumerados se combinen con el parámetro Flags mediante una operación OR bit a bit:

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL: se asignará un grupo no paginado. Si no se usa este valor de marca, se asignará el grupo paginado.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA: todos los grupos asignados por esta rutina se cobrarán con respecto a la cuota de memoria del proceso actual.

Si se usa más de una marca, se producirán todos los efectos asociados a los valores de marca utilizados.

[in, optional] CleanupCallback

Puntero opcional a una rutina de devolución de llamada de limpieza definida por minifiltro de tipo PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. Se llama a la rutina de devolución de llamada de limpieza cuando se elimina la estructura ECP (creada por la rutina FltAllocateExtraCreateParameter ). Establezca este parámetro en NULL si no se aplica una rutina de devolución de llamada de limpieza.

[in] PoolTag

Especifica la etiqueta de grupo para la memoria asignada. Para obtener más información, vea el parámetro Tag de ExAllocatePoolWithTag.

[out] EcpContext

Recibe un puntero a la estructura de contexto ECP asignada. Si la rutina no pudo asignar suficiente grupo, *EcpContext será NULL y la rutina devolverá el código de estado STATUS_INSUFFICIENT_RESOURCES.

Valor devuelto

FltAllocateExtraCreateParameter puede devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameter no pudo asignar memoria suficiente para una estructura ECP. En este caso, EcpContext será NULL.
STATUS_SUCCESS	La estructura ECP se asignó correctamente. En este caso, se devuelve un puntero a la estructura asignada en el parámetro EcpContext .

Comentarios

De forma predeterminada, la rutina FltAllocateExtraCreateParameter asigna un grupo de memoria paginada para una estructura de contexto ECP definida por el usuario. Si la máscara de bits FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL se usa como se ha descrito anteriormente, se asigna un grupo de memoria no paginado. Una vez que se ha asignado este grupo y se ha inicializado la estructura del contexto ECP, la rutina FltInsertExtraCreateParameter se usa para insertar la estructura de contexto ECP (elemento de lista ECP) en una estructura de lista ecP (lista ECP).

El sistema operativo no libera automáticamente el grupo de memoria asignado por la rutina FltAllocateExtraCreateParameter . Este grupo de memoria debe liberarse finalmente mediante uno de los métodos siguientes:

Llame a la rutina FltRemoveExtraCreateParameter para quitar la estructura de contexto ECP de la lista ECP y, a continuación, llame a la rutina FltFreeExtraCreateParameter para liberar la propia estructura de contexto ECP. La lista ECP permanece en existencia.
Llame a la rutina FltFreeExtraCreateParameterList : libera la lista ECP, incluidos los elementos de lista (estructuras de contexto ECP). La lista ECP se destruye.

Sin embargo, si un sistema de archivos o un controlador de filtro del sistema de archivos adjunta un ECP a un ECP_LIST existente o recién creado mientras procesa una solicitud de IRP_MJ_CREATE, este ECP se limpia automáticamente cuando se completa el IRP. Como resultado, un controlador de filtro no tiene que limpiar las ECP que se agregan dinámicamente. Esto permite que el ECP de un controlador de filtro se propague correctamente en los puntos de reanálisis, un proceso que puede requerir que se generen varias solicitudes de IRP_MJ_CREATE.