Función FltAllocateContext (fltkernel.h)

Artículo
03/15/2024

La rutina FltAllocateContext asigna una estructura de contexto para un tipo de contexto especificado.

Sintaxis

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

Parámetros

[in] Filter

Puntero de filtro opaco para el autor de la llamada. Este parámetro es obligatorio y no puede ser NULL.

[in] ContextType

Valor FLT_CONTEXT_TYPE que indica el tipo de contexto que se va a asignar. ContextType puede ser uno de los siguientes:

Valor	Significado
FLT_VOLUME_CONTEXT (0x0001)	Asigne un contexto de volumen.
FLT_INSTANCE_CONTEXT (0x0002)	Asigne un contexto de instancia.
FLT_FILE_CONTEXT (0x0004)	Asigne un contexto de archivo.
FLT_STREAM_CONTEXT (0x0008)	Asigne un contexto de secuencia.
FLT_STREAMHANDLE_CONTEXT (0x0010)	Asigne un contexto de identificador de flujo.
FLT_TRANSACTION_CONTEXT (0x0020)	Asigne un contexto de transacción.
FLT_SECTION_CONTEXT (0x0040)	Asigne un contexto de sección. Disponible a partir de Windows 8.

[in] ContextSize

Tamaño, en bytes, de la parte del contexto definido por el controlador de minifiltro. Debe ser mayor que cero y menor o igual que MAXUSHORT; para contextos de tamaño fijo, debe ser menor o igual que el tamaño especificado en la estructura FLT_CONTEXT_REGISTRATION . Un minifiltro usa esta parte del contexto para mantener la información de contexto específica para sí misma. FltMgr trata esta parte de la estructura de contexto como opaca. Este parámetro es obligatorio y no puede ser cero.

[in] PoolType

Tipo de grupo que se va a asignar. Este parámetro es obligatorio y debe ser uno de los siguientes. Consulte POOL_TYPE para obtener una descripción detallada de cada tipo. Vea Comentarios para obtener más información.

Valor	Significado
NonPagedPool	Memoria del sistema no paginable. PoolType debe ser NonPagedPool si ContextType es FLT_VOLUME_CONTEXT.
PagedPool	Memoria del sistema paginable.
NonPagedPoolNx	Grupo no paginado no ejecutado (NX).

[out] ReturnedContext

Puntero a una variable asignada por el autor de la llamada que recibe la dirección del contexto recién asignado. El autor de la llamada es responsable de llamar a FltReleaseContext para liberar este contexto cuando ya no es necesario.

Valor devuelto

FltAllocateContext devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes:

Código devuelto	Descripción
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	La información de asignación para el contexto del tipo especificado no se proporcionó en el momento del registro de filtro. O bien, para contextos de tamaño fijo, contextSize solicitado es mayor que el tamaño especificado en la estructura de FLT_CONTEXT_REGISTRATION para el contextType especificado.
STATUS_FLT_DELETING_OBJECT	El controlador de minifiltro que se especifica en el parámetro Filter se está descomponiéndose. Se trata de un código de error.
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext encontró un error de asignación de grupo. Se trata de un código de error.
STATUS_INVALID_BUFFER_SIZE	ContextSize no puede ser mayor que MAXUSHORT. Se trata de un código de error.
STATUS_INVALID_PARAMETER	Se especificó un valor no válido para contextType o el parámetro ContextSize . Se trata de un código de error.
STATUS_NOT_SUPPORTED	El sistema de archivos no admite contextos por secuencia. Se trata de un código de error.

Comentarios

Para obtener más información sobre los contextos, vea Acerca de los contextos de minifiltro.

FltAllocateContext asigna un contexto del tipo especificado del grupo especificado. A partir de Windows 11, si la memoria a la que ReturnedContext apunta a depende de la siguiente manera:

Se garantiza que la memoria se va a cero para los contextos de tamaño variable.
El contenido de memoria está definido por la implementación para contextos de tamaño fijo asignados por una función de devolución de llamada proporcionada por el autor de la llamada.
De lo contrario, no se puede suponer que la memoria está en cero para los contextos de tamaño fijo debido al comportamiento de la lista de aspecto. Es decir, una entrada devuelta de la lista lookaside podría no estar cero si es memoria que se liberó previamente a la lista de lookaside en lugar de una nueva asignación.

Antes de Windows 11, el contenido del contexto devuelto no está a cero.

Establecer PoolType en un valor no válido puede dar lugar a un comportamiento inesperado, como provocar que se omitan las listas de búsqueda, lo que da lugar a la pérdida de las ventajas de rendimiento de las listas de aspecto. En el caso de los contextos que tienen una función de devolución de llamada ContextAllocateCallback , el comportamiento debido a un PoolType no válido depende de la implementación.

Una vez asignado el contexto, se puede establecer en un objeto pasando el puntero ReturnedContext a la rutina set-context adecuada de la tabla siguiente.

Tipo de contexto	rutina de Set-Context
FLT_FILE_CONTEXT	FltSetFileContext (a partir de Windows Vista)
FLT_INSTANCE_CONTEXT	FltSetInstanceContext
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan (a partir de Windows 8)
FLT_STREAM_CONTEXT	FltSetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltSetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltSetTransactionContext (a partir de Windows Vista)
FLT_VOLUME_CONTEXT	FltSetVolumeContext

Cuando un controlador de minifiltro llama a FltRegisterFilter desde su rutina DriverEntry , debe registrar cada tipo de contexto que use. Para obtener más información, vea la entrada de referencia para la estructura de FLT_CONTEXT_REGISTRATION y El registro de tipos de contexto.

FltAllocateContext no inicializa el contenido de la parte de la estructura de contexto específica del controlador de minifiltro.

Para obtener el contexto de un objeto, llame a FltGetContexts o a la rutina get-context adecuada de la tabla siguiente.

Tipo de contexto	Rutina de Get-Context
FLT_FILE_CONTEXT	FltGetFileContext (a partir de Windows Vista)
FLT_INSTANCE_CONTEXT	FltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext (a partir de Windows 8)
FLT_STREAM_CONTEXT	FltGetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltGetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltGetTransactionContext (a partir de Windows Vista )
FLT_VOLUME_CONTEXT	FltGetVolumeContext

Los contextos son con recuento de referencias y, en una devolución correcta de FltAllocateContext, el contexto al que apunta ReturnedContext se ha inicializado para tener un recuento de referencias de 1. Un contexto se libera automáticamente cuando su recuento de referencias alcanza cero. Para incrementar el recuento de referencias en un contexto, llame a FltReferenceContext.

Para disminuir el recuento de referencias en un contexto, llame a FltReleaseContext.

Dado que los contextos son con recuento de referencias, normalmente no es necesario eliminarlos. Para eliminar un contexto explícitamente, llame a FltDeleteContext o a la rutina de contexto de eliminación adecuada de la tabla siguiente.

Tipo de contexto	Rutina de Delete-Context
FLT_FILE_CONTEXT	FltDeleteFileContext (a partir de Windows Vista)
FLT_INSTANCE_CONTEXT	FltDeleteInstanceContext
FLT_SECTION_CONTEXT	FltCloseSectionForDataScan (a partir de Windows 8)
FLT_STREAM_CONTEXT	FltDeleteStreamContext
FLT_STREAMHANDLE_CONTEXT	FltDeleteStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltDeleteTransactionContext (a partir de Windows Vista)
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext