Función FltCreateSectionForDataScan (fltkernel.h)

Artículo
08/07/2023

La rutina FltCreateSectionForDataScan crea un objeto de sección para un archivo. Opcionalmente, el administrador de filtros puede sincronizar la E/S con la sección creada.

Sintaxis

NTSTATUS FLTAPI FltCreateSectionForDataScan(
  [in]            PFLT_INSTANCE      Instance,
  [in]            PFILE_OBJECT       FileObject,
  [in]            PFLT_CONTEXT       SectionContext,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  PLARGE_INTEGER     MaximumSize,
  [in]            ULONG              SectionPageProtection,
  [in]            ULONG              AllocationAttributes,
  [in]            ULONG              Flags,
  [out]           PHANDLE            SectionHandle,
  [out]           PVOID              *SectionObject,
  [out, optional] PLARGE_INTEGER     SectionFileSize
);

Parámetros

[in] Instance

Puntero de instancia opaco para la instancia del controlador de minifiltro cuyo contexto se va a recuperar.

[in] FileObject

Objeto de archivo para un archivo abierto. El archivo especificado respaldará el objeto de sección. Este parámetro es obligatorio y no puede ser NULL.

[in] SectionContext

Puntero a un contexto de sección asignado previamente.

[in] DesiredAccess

Tipo de acceso para el objeto de sección como una o varias de las marcas de ACCESS_MASK siguientes.

Marca	Permite al autor de la llamada
SECTION_MAP_READ	Lee las vistas de la sección.
SECTION_MAP_WRITE	Escriba vistas de la sección.
SECTION_QUERY	Consulte el objeto de sección para obtener información sobre la sección. Los controladores deben establecer esta marca.
SECTION_ALL_ACCESS	Todas las acciones definidas por las marcas anteriores, así como las definidas por STANDARD_RIGHTS_REQUIRED. Para obtener más información sobre STANDARD_RIGHTS_REQUIRED, consulte ACCESS_MASK.

[in, optional] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES opcional que especifica el nombre del objeto y otros atributos. Use la macro InitializeObjectAttributes para inicializar esta estructura.

[in, optional] MaximumSize

Este parámetro se reserva para uso futuro.

[in] SectionPageProtection

Protección que se va a colocar en cada página de la sección. Especifique uno de los valores siguientes. Este parámetro es necesario y no puede ser cero.

Marca	Significado
PAGE_READONLY	Habilita el acceso de solo lectura a la región confirmada de las páginas. Un intento de escritura en la región confirmada produce una infracción de acceso. Si el sistema diferencia entre el acceso de solo lectura y el acceso de ejecución, un intento de ejecutar código en la región confirmada produce una infracción de acceso.
PAGE_READWRITE	Habilita el acceso de lectura y escritura a la región confirmada de las páginas.

[in] AllocationAttributes

Las máscaras de bits de las marcas SEC_XXX determinan los atributos de asignación de la sección. Especifique uno o varios de los valores siguientes. Este parámetro es necesario y no puede ser cero.

Marca	Significado
SEC_COMMIT	Asigna almacenamiento físico en memoria o en el archivo de paginación en disco para todas las páginas de una sección. Esta es la configuración predeterminada. Tenga en cuenta que esta marca es necesaria y no se puede omitir.
SEC_FILE	El archivo especificado por el parámetro FileObject es un archivo asignado.

[in] Flags

Este parámetro se reserva para uso futuro.

[out] SectionHandle

Puntero a una variable asignada por el autor de la llamada que recibe un identificador opaco en la sección. De forma predeterminada, el identificador de sección es un identificador de usuario. Si el autor de la llamada necesita un identificador de kernel, deben pasar un puntero a una estructura de OBJECT_ATTRIBUTES inicializada en el parámetro ObjectAttributes con la marca OBJ_KERNEL_HANDLE establecida.

[out] SectionObject

Puntero a una variable asignada por el autor de la llamada que recibe un puntero opaco al objeto de sección.

[out, optional] SectionFileSize

Puntero a una variable asignada por el autor de la llamada que recibe el tamaño, en bytes, del archivo en el momento en que se creó el objeto de sección. Este parámetro es opcional y puede ser NULL.

Valor devuelto

FltCreateSectionForDataScan devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes.

Código devuelto	Descripción
STATUS_END_OF_FILE	El tamaño del archivo especificado por el parámetro FileObject es cero.
STATUS_FILE_LOCK_CONFLICT	El archivo especificado por el parámetro FileObject está bloqueado.
STATUS_INSUFFICIENT_RESOURCES	FltCreateSectionForDataScan encontró un error de asignación de grupo.
STATUS_INVALID_FILE_FOR_SECTION	El archivo especificado por el parámetro FileObject no admite secciones.
STATUS_INVALID_PARAMETER	El minifiltro no está registrado.
STATUS_INVALID_PARAMETER_8	El valor especificado para el parámetro SectionPageProtection no es válido.
STATUS_INVALID_PARAMETER_9	El autor de la llamada especificó un valor no válido para el parámetro AllocationAttributes .
STATUS_NOT_SUPPORTED	El volumen asociado a esta instancia no admite contextos de sección.
STATUS_PRIVILEGE_NOT_HELD	El autor de la llamada no tenía los privilegios necesarios para crear un objeto de sección con el acceso especificado en el parámetro DesiredAccess .
STATUS_FILE_IS_A_DIRECTORY	El archivo especificado por el parámetro FileObject es un directorio.
STATUS_FLT_CONTEXT_ALREADY_DEFINED	La instancia de filtro especificada por Instance ya tiene una sección abierta para la secuencia. Solo se admite una sección por secuencia y, por tanto, por instancia.

Comentarios

Antes de llamar a FltCreateSectionForDataScan, un minifiltro debe registrar primero su volumen para el examen de datos llamando a FltRegisterForDataScan. Al igual que con otros elementos de contexto de filtro, SectionContext se asigna primero con FltAllocateContext.

FltCreateSectionForDataScan inserta el identificador en el objeto (SectionHandle) en la tabla de identificadores de proceso para el subproceso en el que se llama a FltCreateSectionForDataScan .

Los identificadores pueden ser identificadores de usuario o identificadores de kernel. Un identificador creado con OBJ_KERNEL_HANDLE establecido en la estructura de OBJECT_ATTRIBUTES a la que apunta ObjectAttributes es un identificador de kernel y solo se puede acceder desde el modo kernel. Un identificador creado sin la marca OBJ_KERNEL_HANDLE es un identificador de usuario, al que se puede acceder desde el modo de usuario o kernel. Un filtro puede crear un identificador de usuario y pasarlo a una aplicación en modo de usuario para su procesamiento. Por ejemplo, un motor de detección de virus puede vivir en una aplicación en modo de usuario y alimentarse de identificadores de usuario desde un filtro del sistema de archivos.

Algunas situaciones pueden producirse en las que mantener abierta una sección no es compatible con la E/S del archivo actual. En concreto, la E/S de archivos que desencadena una purga de caché puede provocar la incoherencia de caché si se impide la purga de caché debido a una sección abierta. Un minifiltro puede proporcionar una rutina de devolución de llamada opcional para las notificaciones de estos eventos. El controlador de minifiltro implementa un PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK para recibir estas notificaciones. Las notificaciones de conflicto se habilitan si el miembro SectionNotificationCallback de FLT_REGISTRATION se establece en esta rutina de devolución de llamada cuando se registra el minifiltro. Cuando se recibe una notificación, la sección se puede cerrar para permitir que la operación de E/S en conflicto continúe.

Nota

Es posible que se produzca una devolución de llamada de notificación de sección antes de que FltCreateSectionForDataScan devuelva. Un minifiltro debe poder recibir la devolución de llamada y controlar el caso en el que SectionHandle y SectionObject aún no son válidos.

Cuando el objeto de sección creado por esta rutina ya no es necesario, asegúrese de cerrar el identificador del objeto de sección (SectionHandle) llamando a la rutina ZwClose y desreferenciar el propio objeto de sección (SectionObject) llamando a la rutina ObDereferenceObject .

Para obtener información general sobre cómo crear secciones asignadas y vistas de memoria, vea Section Objects and Views. Consulte también la documentación de la rutina CreateFileMapping en el Microsoft Windows SDK.

Importante

Los minifiltros no deben eliminar explícitamente un contexto de sección pasado a FltCreateSectionForDataScan. No llame a FltDeleteContext después de pasar un contexto de sección a FltCreateSectionForDataScan. En este caso, se desasigna y quita un contexto de sección de una secuencia mediante una llamada a FltCloseSectionForDataScan .

En general, las secciones deben crearse como de solo lectura. En concreto, si un archivo de solo lectura está en una transacción y un minifiltro no crea una sección de solo lectura, se descarta una escritura en la sección y no se incluye como parte de la transacción.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8
Plataforma de destino	Universal
Encabezado	fltkernel.h (incluya Fltkernel.h)
Library	FltMgr.lib
IRQL	<= APC_LEVEL