estructura FLT_CALLBACK_DATA (fltkernel.h)

Artículo
08/07/2023

La estructura FLT_CALLBACK_DATA representa una operación de E/S. El Administrador de filtros y los minifiltros usan esta estructura para iniciar y procesar operaciones de E/S.

Sintaxis

typedef struct _FLT_CALLBACK_DATA {
  FLT_CALLBACK_DATA_FLAGS     Flags;
  PETHREAD                    Thread;
  PFLT_IO_PARAMETER_BLOCK     Iopb;
  IO_STATUS_BLOCK             IoStatus;
  struct _FLT_TAG_DATA_BUFFER *TagData;
  union {
    struct {
      LIST_ENTRY QueueLinks;
      PVOID      QueueContext[2];
    };
    PVOID FilterContext[4];
  };
  KPROCESSOR_MODE             RequestorMode;
} FLT_CALLBACK_DATA, *PFLT_CALLBACK_DATA;

Miembros

Flags

Máscara de bits de marcas que describen la operación de E/S.

Los minifiltros pueden establecer la marca siguiente.

Marca	Significado
FLTFL_CALLBACK_DATA_DIRTY	Un minifiltro establece esta marca (llamando a FltSetCallbackDataDirty) para indicar que ha modificado el contenido de la estructura de datos de devolución de llamada. (Para obtener más información, vea la siguiente sección Comentarios).

Nota

Solo el Administrador de filtros puede establecer las marcas siguientes.

Cuando el Administrador de filtros inicializa la estructura de datos de devolución de llamada, establece una de las marcas siguientes para especificar el tipo de operación de E/S que representa la estructura de datos de devolución de llamada.

Marca	Significado
FLTFL_CALLBACK_DATA_FAST_IO_OPERATION	La estructura de datos de devolución de llamada representa una operación de E/S rápida.
FLTFL_CALLBACK_DATA_FS_FILTER_OPERATION	La estructura de datos de devolución de llamada representa una operación de devolución de llamada de minifiltro del sistema de archivos.
FLTFL_CALLBACK_DATA_IRP_OPERATION	La estructura de datos de devolución de llamada representa una operación basada en paquetes de solicitud de E/S (IRP).

Nota

Solo el Administrador de filtros puede establecer las marcas siguientes.

Cuando el Administrador de filtros inicializa la estructura de datos de devolución de llamada, también puede establecer las marcas siguientes.

Marca	Significado
FLTFL_CALLBACK_DATA_GENERATED_IO	La estructura de datos de devolución de llamada representa una operación de E/S generada por un minifiltro. Esta marca solo es válida para las operaciones basadas en IRP.
FLTFL_CALLBACK_DATA_REISSUED_IO	La estructura de datos de devolución de llamada representa una operación de E/S que se vuelve a emitir mediante un minifiltro. (Para volver a emitir una operación de E/S, un minifiltro llama a FltReissueSynchronousIo). Esta marca solo es válida para las operaciones basadas en IRP.
FLTFL_CALLBACK_DATA_SYSTEM_BUFFER	El búfer de la operación de E/S se asignó desde un grupo no paginado. Esta marca se puede establecer para cualquier tipo de operación de E/S. Los minifiltros nunca deben establecer esta marca.

Nota

Solo el Administrador de filtros puede establecer las marcas siguientes.

Cuando el Administrador de filtros realiza el procesamiento de finalización de la operación de E/S que representa la estructura de datos de devolución de llamada, establece una o ambas marcas siguientes.

Marca	Significado
FLTFL_CALLBACK_DATA_DRAINING_IO	El Administrador de filtros establece esta marca para indicar que actualmente está purgando el nodo de finalización de la operación de E/S. Esta marca solo es válida durante la finalización de E/S.
FLTFL_CALLBACK_DATA_POST_OPERATION	El Administrador de filtros establece esta marca para indicar que actualmente llama a rutinas de devolución de llamada posteriores a la operación registradas (PFLT_POST_OPERATION_CALLBACK) para la operación. Esta marca solo es válida durante la finalización de E/S.

Thread

Puntero al subproceso que inició la operación de E/S. Este campo puede ser NULL.

Iopb

Puntero a una estructura de FLT_IO_PARAMETER_BLOCK que contiene los parámetros de la operación de E/S.

IoStatus

Estructura IO_STATUS_BLOCK que contiene el estado y la información de la operación de E/S. Un minifiltro puede modificar el contenido de esta estructura solo en una rutina de devolución de llamada previa a la operación (PFLT_PRE_OPERATION_CALLBACK) desde la que está a punto de devolver FLT_PREOP_COMPLETE o en una rutina de devolución de llamada posterior a la operación (PFLT_POST_OPERATION_CALLBACK) desde la que está a punto de devolver FLT_POSTOP_FINISHED_PROCESSING. De lo contrario, el Administrador de filtros establece normalmente el contenido de esta estructura.

TagData

Puntero a una estructura de FLT_TAG_DATA_BUFFER que contiene datos de punto de reanálisis para la operación de E/S. Este puntero solo es válido en la ruta de acceso posterior a la creación. Por lo tanto, solo la rutina de devolución de llamada posterior a la operación de un minifiltro puede cambiar el valor de este miembro. La rutina de devolución de llamada posterior a la creación de un minifiltro puede cambiar este miembro para que apunte a una estructura de FLT_TAG_DATA_BUFFER diferente. Sin embargo, si cambia el miembro para que apunte a una estructura diferente, primero debe llamar a ExFreePool para liberar la estructura existente para evitar una pérdida de memoria del grupo.

QueueLinks

Vínculos de cola que un minifiltro puede usar cuando se usa la cola de datos de devolución de llamada del Administrador de filtros para escribir la operación de E/S.

QueueContext[2]

Matriz de punteros de información de contexto que un minifiltro puede usar cuando se usa la cola del Administrador de filtros para escribir la operación de E/S.

FilterContext[4]

Matriz de punteros de información de contexto que un minifiltro puede usar cuando se usa una cola distinta de la cola del Administrador de filtros para escribir la operación de E/S.

RequestorMode

Indica el modo de ejecución del proceso que inició la operación de E/S, ya sea KernelMode o UserMode.

Comentarios

Un minifiltro registra rutinas de devolución de llamada (PFLT_PRE_OPERATION_CALLBACK) y posteriores a la operación (PFLT_POST_OPERATION_CALLBACK) para uno o varios tipos de operaciones de E/S. Cuando el Administrador de filtros llama a una de estas rutinas de devolución de llamada, pasa una estructura de datos de devolución de llamada (FLT_CALLBACK_DATA) como primer parámetro. Esta estructura representa la operación de E/S.

La rutina de devolución de llamada previa o posterior a la operación de un minifiltro puede modificar el contenido de la estructura de datos de devolución de llamada, excepto para los miembros Thread y RequestorMode . Si lo hace, debe llamar a FltSetCallbackDataDirty, a menos que también haya modificado el contenido del miembro IoStatus . De lo contrario, se omiten los valores modificados.

Un minifiltro puede iniciar una operación de E/S llamando a una rutina de soporte técnico como FltReadFile o llamando a FltAllocateCallbackData para asignar una estructura de datos de devolución de llamada; inicializando los parámetros de E/S de la estructura y pasando la estructura a FltPerformSynchronousIo o FltPerformAsynchronousIo.

Una operación de E/S iniciada por minifiltro solo se envía a las instancias de minifiltro adjuntas debajo de la instancia de llamada y al sistema de archivos. Los minifiltros adjuntos encima de la instancia especificada no reciben la operación de E/S.

Los minifiltros 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).