Función FltAllocateContext (fltkernel.h)

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:

[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.

[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:

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.

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.

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.

Requisitos

Consulte también

FLT_CONTEXT_REGISTRATION

FltCloseSectionForDataScan

FltCreateSectionForDataScan

FltDeleteContext

FltDeleteFileContext

FltDeleteInstanceContext

FltDeleteStreamContext

FltDeleteStreamHandleContext

FltDeleteTransactionContext

FltDeleteVolumeContext

FltGetContexts

FltGetFileContext

FltGetInstanceContext

FltGetSectionContext

FltGetStreamContext

FltGetStreamHandleContext

FltGetTransactionContext

FltGetVolumeContext

FltReferenceContext

FltRegisterFilter

FltReleaseContext

FltSetFileContext

FltSetInstanceContext

FltSetStreamContext

FltSetStreamHandleContext

FltSetTransactionContext

FltSetVolumeContext