Función FltAllocateCallbackData (fltkernel.h)

2024-02-26

FltAllocateCallbackData asigna una estructura de datos de devolución de llamada que un controlador de minifiltro puede usar para iniciar una solicitud de E/S.

Sintaxis

NTSTATUS FLTAPI FltAllocateCallbackData(
  [in]           PFLT_INSTANCE      Instance,
  [in, optional] PFILE_OBJECT       FileObject,
  [out]          PFLT_CALLBACK_DATA *RetNewCallbackData
);

Parámetros

[in] Instance

Puntero de instancia opaco para la instancia del controlador de minifiltro que está iniciando la operación de E/S. Este parámetro es obligatorio y no puede ser NULL.

[in, optional] FileObject

Puntero de objeto de archivo que se va a usar en la operación de E/S. Este parámetro es opcional y puede ser NULL.

[out] RetNewCallbackData

Puntero a una variable asignada por el autor de la llamada que recibe la dirección de la estructura de datos de devolución de llamada (FLT_CALLBACK_DATA) recién asignada.

Valor devuelto

FltAllocateCallbackData devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como el siguiente:

Código devuelto	Descripción
STATUS_INSUFFICIENT_RESOURCES	FltAllocateCallbackData encontró un error de asignación de grupo al intentar asignar la estructura de datos de devolución de llamada. Se trata de un código de error.

Comentarios

Un controlador de minifiltro puede llamar a FltAllocateCallbackData para asignar una estructura de datos de devolución de llamada (FLT_CALLBACK_DATA) para una operación de E/S iniciada por el controlador minifiltro.

Nota La rutina FltAllocateCallbackData no asigna toda la memoria que podría requerir una solicitud de E/S posterior. Si una solicitud de E/S, como FltPerformSynchronousIo o FltPerformAsynchronousIo, requiere memoria adicional para alguna estructura, la solicitud podría encontrar una asignación de memoria. La rutina FltAllocateCallbackDataEx se puede usar para evitar este posible problema mediante la asignación previa de la memoria para las estructuras adicionales que se usarán en una solicitud de E/S. Si hay un problema de asignación de memoria para la estructura RetNewCallbackData o estructuras necesarias adicionales, se puede tratar en el punto de asignación de datos de devolución de llamada.

Las estructuras de datos de devolución de llamada se asignan desde un grupo no paginado.

Después de inicializar los parámetros de la estructura de datos de devolución de llamada devuelta por FltAllocateCallbackData, el llamador inicia la operación de E/S pasando la estructura a FltPerformSynchronousIo o FltPerformAsynchronousIo. Estas rutinas envían la operación de E/S solo a las instancias del controlador de minifiltro adjuntas debajo de la instancia de inicio (especificada en el parámetro Instance ) y al sistema de archivos. Los controladores de minifiltro conectados encima de la instancia especificada no reciben la operación de E/S.

Los controladores de minifiltro solo pueden iniciar operaciones de E/S basadas en IRP. No pueden iniciar operaciones de devolución de llamada de E/S rápidas o de filtro del sistema de archivos (FSFilter).

Los controladores de minifiltro deben usar FltAllocateCallbackData, FltPerformAsynchronousIo y FltPerformSynchronousIo solo para las operaciones de E/S para las que no se pueden usar rutinas como las siguientes:

FltClose

FltCreateFile

FltQueryVolumeInformation

FltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

Cuando ya no se necesita la estructura de datos de devolución de llamada asignada por FltAllocateCallbackData , el autor de la llamada es responsable de liberarla llamando a FltFreeCallbackData.