Función FltCreateSectionForDataScan (fltkernel.h)
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 |