Función IoCancelFileOpen (ntddk.h)

Artículo
08/07/2023

Una rutina de filtro del sistema de archivos puede usar la rutina IoCancelFileOpen para cerrar un archivo abierto por un controlador del sistema de archivos en la pila de dispositivos del controlador de filtro.

Sintaxis

void IoCancelFileOpen(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PFILE_OBJECT   FileObject
);

Parámetros

[in] DeviceObject

Puntero a la parte superior de la pila de dispositivos inmediatamente debajo del objeto de dispositivo del controlador de filtro.

[in] FileObject

Puntero al objeto de archivo para que se cierre el archivo.

Valor devuelto

None

Observaciones

Si un controlador de filtro del sistema de archivos determina que una solicitud de archivo abierta o de creación de archivos debe producir un error después de que los controladores de nivel inferior ya hayan completado la solicitud con STATUS_SUCCESS, puede usar IoCancelFileOpen para cerrar el archivo abierto por los controladores de nivel inferior.

Aunque STATUS_REPARSE es un valor NTSTATUS correcto, no es necesario llamar a IoCancelFileOpen para una operación de creación que se completó con STATUS_REPARSE, ya que este valor de estado indica que el archivo no se abrió correctamente.

Una llamada correcta a IoCancelFileOpen tiene el siguiente efecto: Para minifiltros y filtros heredados que están por encima del autor de la llamada en la pila del sistema de archivos, parece que se ha producido un error en la solicitud de creación. A los que están debajo del autor de la llamada, parece que el archivo se ha abierto (o creado) y, a continuación, se ha cerrado.

Tenga en cuenta que IoCancelFileOpen no deshace ninguna modificación en el archivo. Por ejemplo, IoCancelFileOpen no elimina un archivo recién creado ni restaura un archivo sobrescrito o reemplazado por su estado anterior.

Un ejemplo típico es el siguiente:

Existe un controlador de filtro entre un controlador de filtro de nivel superior y un controlador de sistema de archivos de nivel inferior.
El controlador de filtro pasa una solicitud de IRP_MJ_CREATE a la pila del dispositivo al controlador del sistema de archivos y el controlador del sistema de archivos completa la solicitud de IRP_MJ_CREATE con el estado STATUS_SUCCESS.
Antes de que el controlador de filtro complete la solicitud de creación, determina que se debe cerrar el archivo.
El controlador de filtro usa IoCancelFileOpen para cerrar el archivo que abrió el controlador del sistema de archivos.

Después de llamar a IoCancelFileOpen, el controlador de filtro debe completar la solicitud de creación con un código de error adecuado, como STATUS_UNSUCCESSFUL o STATUS_ACCESS_DENIED. Además, debe establecer el campo Irp-IoStatus.Information> en cero.

Se debe llamar a IoCancelFileOpen antes de crear los identificadores para el archivo. Los autores de llamadas pueden comprobar el miembro Flags de la estructura FILE_OBJECT a la que apunta el parámetro FileObject . Si se establece la marca FO_HANDLE_CREATED, esto significa que se han creado uno o varios identificadores para el archivo, por lo que no es seguro llamar a IoCancelFileOpen.

IoCancelFileOpen establece la marca FO_FILE_OPEN_CANCELLED en el miembro Flags del objeto de archivo al que apunta FileObject . Esta marca indica que se ha cancelado la solicitud de IRP_MJ_CREATE y se emitirá una solicitud de IRP_MJ_CLOSE para este objeto de archivo. Una vez cancelada la operación de creación, no se puede volver a emitir; es decir, el controlador de filtro heredado no puede devolver STATUS_REPARSE si ha llamado a la rutina IoCreateFileOpen .

Los minifiltros deben usar FltCancelFileOpen en lugar de IoCancelFileOpen.

Requisitos

Requisito	Value
Cliente mínimo compatible	Esta rutina está disponible en Microsoft Windows 2000 y versiones posteriores.
Plataforma de destino	Universal
Encabezado	ntddk.h (incluya Ntddk.h, Ntifs.h, Fltkernel.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL