Funzione IoCancelFileOpen (ntddk.h)

Articolo
02/26/2024

La routine IoCancelFileOpen può essere usata da un driver di filtro del file system per chiudere un file aperto da un driver del file system nello stack di dispositivi del driver di filtro.

Sintassi

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

Parametri

[in] DeviceObject

Puntatore alla parte superiore dello stack di dispositivi immediatamente sotto l'oggetto dispositivo del driver di filtro.

[in] FileObject

Puntatore all'oggetto file per la chiusura del file.

Valore restituito

nessuno

Osservazioni

Se un driver di filtro del file system determina che una richiesta di creazione file aperta o file deve avere esito negativo dopo che i driver di livello inferiore hanno già completato la richiesta con STATUS_SUCCESS, può usare IoCancelFileOpen per chiudere il file aperto dai driver di livello inferiore.

Anche se STATUS_REPARSE è un valore NTSTATUS riuscito, non è necessario chiamare IoCancelFileOpen per un'operazione di creazione completata con STATUS_REPARSE, perché questo valore di stato indica che il file non è stato aperto correttamente.

Una chiamata riuscita a IoCancelFileOpen ha l'effetto seguente: per minifiltri e filtri legacy che sono sopra il chiamante nello stack del file system, la richiesta di creazione appare non riuscita. A quelli che sono sotto il chiamante, il file sembra essere stato aperto (o creato) e quindi chiuso.

Si noti che IoCancelFileOpen non annulla alcuna modifica al file. Ad esempio, IoCancelFileOpen non elimina un file appena creato o ripristina un file sovrascritto o sostituito allo stato precedente.

Un esempio tipico è il seguente:

Esiste un driver di filtro tra un driver di filtro di livello superiore e un driver di file system di livello inferiore.
Il driver di filtro passa una richiesta IRP_MJ_CREATE lo stack di dispositivi al driver del file system e il driver del file system completa la richiesta di IRP_MJ_CREATE con stato STATUS_SUCCESS.
Prima che il driver di filtro completi la richiesta di creazione, determina che il file deve essere chiuso.
Il driver di filtro usa IoCancelFileOpen per chiudere il file aperto dal driver del file system.

Dopo aver chiamato IoCancelFileOpen, il driver di filtro deve completare la richiesta di creazione con un codice di errore appropriato, ad esempio STATUS_UNSUCCESSFUL o STATUS_ACCESS_DENIED. Inoltre, deve impostare il campo Irp-IoStatus.Information> su zero.

IoCancelFileOpen deve essere chiamato prima che vengano creati gli handle per il file. I chiamanti possono controllare il membro Flag della struttura FILE_OBJECT a cui punta il parametro FileObject . Se il flag FO_HANDLE_CREATED è impostato, ciò significa che uno o più handle sono stati creati per il file, quindi non è sicuro chiamare IoCancelFileOpen.

IoCancelFileOpen imposta il flag di FO_FILE_OPEN_CANCELLED nel membro Flag dell'oggetto file a cui punta FileObject . Questo flag indica che la richiesta di IRP_MJ_CREATE è stata annullata e verrà rilasciata una richiesta di IRP_MJ_CLOSE per questo oggetto file. Una volta annullata l'operazione di creazione, non può essere ristampata, ovvero STATUS_REPARSE non può essere restituita dal driver di filtro legacy se ha chiamato la routine IoCreateFileOpen .

I minifilter devono usare FltCancelFileOpen anziché IoCancelFileOpen.

Requisiti

Requisito	Valore
Client minimo supportato	Questa routine è disponibile in Microsoft Windows 2000 e versioni successive.
Piattaforma di destinazione	Universale
Intestazione	ntddk.h (include Ntddk.h, Ntifs.h, Fltkernel.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL