Funzione FltCreateFileEx2 (fltkernel.h)

Articolo
03/08/2023

I driver minifilter chiamano FltCreateFileEx2 per creare un nuovo file o aprire un file esistente. Questa routine include un parametro di contesto di creazione facoltativo (ECP).

Sintassi

NTSTATUS FLTAPI FltCreateFileEx2(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ACCESS_MASK               DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional]  PLARGE_INTEGER            AllocationSize,
  [in]            ULONG                     FileAttributes,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in, optional]  PVOID                     EaBuffer,
  [in]            ULONG                     EaLength,
  [in]            ULONG                     Flags,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parametri

[in] Filter

Puntatore di filtro opaco per il chiamante.

[in, optional] Instance

Puntatore di istanza opaco per l'istanza del driver minifilter a cui deve essere inviata la richiesta di creazione. L'istanza deve essere collegata al volume in cui risiede il file o la directory. Questo parametro è facoltativo e può essere NULL. Se questo parametro è NULL, la richiesta viene inviata all'oggetto dispositivo nella parte superiore dello stack di driver del file system per il volume. Se questo parametro non è NULL, la richiesta viene inviata solo alle istanze del driver minifilter associate sotto l'istanza specificata.

[out] FileHandle

Puntatore a una variabile allocata dal chiamante che riceve l'handle di file se la chiamata a FltCreateFileEx2 ha esito positivo.

[out, optional] FileObject

Puntatore a una variabile allocata dal chiamante che riceve il puntatore dell'oggetto file se la chiamata a FltCreateFileEx2 ha esito positivo. Questo parametro è facoltativo e può essere NULL.

[in] DesiredAccess

Maschera di bit dei flag che specificano il tipo di accesso al file o alla directory che il chiamante richiede. Per altre informazioni su questo parametro e per l'elenco dei valori del flag, vedere il parametro DesiredAccess di IoCreateFileEx .

[in] ObjectAttributes

Puntatore a una struttura OBJECT_ATTRIBUTES opaca già inizializzata con InitializeObjectAttributes. Per altre informazioni, vedere il parametro ObjectAttributes di IoCreateFileEx e per una descrizione di ogni membro della struttura.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e le informazioni sull'operazione richiesta. Per altre informazioni su questo parametro, vedere il parametro IoStatusBlock di IoCreateFileEx .

[in, optional] AllocationSize

Facoltativamente, specifica le dimensioni iniziali di allocazione, in byte, per il flusso di file. Un valore diverso da zero non ha alcun effetto a meno che il file non venga creato, sovrascritto o sostituito.

[in] FileAttributes

Specifica uno o più flag FILE_ATTRIBUTE_XXX , che rappresentano gli attributi di file da impostare se si creano, sostituiscono o sovrascriveno un file. Per altre informazioni, vedere il parametro FileAttributes di IoCreateFileEx e per l'elenco di flag.

[in] ShareAccess

Specifica il tipo di accesso di condivisione al file richiesto dal chiamante, come zero o uno o una combinazione dei flag. Per altre informazioni, vedere il parametro ShareAccess di IoCreateFileEx e per l'elenco di flag.

[in] CreateDisposition

Specifica un valore che determina l'azione da eseguire, a seconda che il file esista già. Per l'elenco dei valori possibili, vedere il parametro Disposition di IoCreateFileEx .

[in] CreateOptions

Specifica le opzioni da applicare durante la creazione o l'apertura del file. Questo parametro è una combinazione compatibile dei flag elencati e descritti nel parametro CreateOptions di IoCreateFileEx.

[in, optional] EaBuffer

Puntatore a un buffer fornito dal chiamante FILE_FULL_EA_INFORMATION che contiene informazioni sull'attributo esteso (EA) da applicare al file.

[in] EaLength

Lunghezza, in byte, di EaBuffer.

[in] Flags

Specifica le opzioni da usare durante la creazione della richiesta di creazione. Per l'elenco delle opzioni possibili, vedere il parametro Opzioni di IoCreateFileEx .

[in, optional] DriverContext

Puntatore facoltativo a una struttura IO_DRIVER_CREATE_CONTEXT già inizializzata da IoInitializeDriverCreateContext.

Valore restituito

FltCreateFileEx2 restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato. Per un elenco di possibili codici restituiti, vedere la sezione Valore restituito di IoCreateFileEx .

Nota

FltCreateFileEx2 potrebbe restituire STATUS_FILE_LOCK_CONFLICT come valore restituito o nel membro Status della struttura IO_STATUS_BLOCK a cui punta il parametro IoStatusBlock. Ciò si verifica solo se il file di log NTFS è completo e si verifica un errore mentre FltCreateFileEx2 tenta di gestire questa situazione.

Commenti

FltCreateFileEx2 è simile a FltCreateFile e FltCreateFileEx, ad eccezione del fatto che supporta il parametro di input DriverContext.

Per specificare un ECP come parte di un'operazione di creazione, inizializzare il membro ExtraCreateParameter della struttura di IO_DRIVER_CREATE_CONTEXT con la routine FltAllocateExtraCreateParameterList . Se gli ECP vengono usati, devono essere creati, modificati e liberati usando le routine appropriate.

I driver di filtro sotto il chiamante di FltCreateFileEx2 non devono aggiungere o eliminare gli ECP nel chiamante. Di conseguenza, al ritorno dalla chiamata a FltCreateFileEx2, l'elenco ECP deve essere invariato e può essere passato a chiamate aggiuntive di FltCreateFileEx2 per altre operazioni di creazione. Si noti che il sistema operativo non dealloca automaticamente la struttura dell'elenco ECP: il chiamante di FltCreateFileEx2 deve deallocare questa struttura chiamando la routine FltFreeExtraCreateParameterList .

Per creare/aprire un file nel contesto di una transazione, impostare il membro TxnParameters della struttura IO_DRIVER_CREATE_CONTEXT sul valore restituito dalla routine IoGetTransactionParameterBlock .

FltCreateFileEx2 invia la richiesta di creazione solo alle istanze associate sotto l'istanza del driver minifilter specificata e al file system. L'istanza specificata e le istanze associate sopra non ricevono la richiesta di creazione. Se non viene specificata alcuna istanza, la richiesta passa alla parte superiore dello stack e viene ricevuta da tutte le istanze e dal file system.

Esistono due modi alternativi per specificare il nome del file da creare o aprire con FltCreateFileEx2:

Come nome percorso completo, fornito nel membro ObjectName dell'oggetto ObjectAttributes.
Come nome percorso relativo al file di directory rappresentato dall'handle nel membro RootDirectorydell'oggetto ObjectAttributes di input.

Qualsiasi FileHandle ottenuto da FltCreateFileEx2 deve essere rilasciato chiamando FltClose. Inoltre, qualsiasi puntatore FileObject restituito deve essere dereferenziato quando non è più necessario chiamando ObDereferenceObject.

Le routine del driver che non vengono eseguite nel contesto del processo di sistema devono impostare l'attributo OBJ_KERNEL_HANDLE per il parametro ObjectAttributes di FltCreateFileEx2. L'impostazione di questo attributo limita l'uso dell'handle restituito da FltCreateFileEx2 per i processi in esecuzione in modalità kernel. In caso contrario, l'handle può essere accessibile dal processo nel cui contesto è in esecuzione il driver.

Nota

Non chiamare questa routine con un valore IRP di primo livello diverso da NULL, in quanto può causare un deadlock di sistema.

Alcuni flag e combinazioni di flag DesiredAccess hanno gli effetti seguenti:

Per consentire a un chiamante di sincronizzare un completamento di I/O in attesa che il fileHandle restituito sia impostato sullo stato segnalato, il flag SYNC deve essere impostato.
Se vengono impostati solo i flag FILE_APPEND_DATA e SYNC, il chiamante può scrivere solo alla fine del file e tutte le informazioni di offset relative alle richieste di scrittura al file vengono ignorate. Tuttavia, il file viene esteso automaticamente in base alle esigenze per questo tipo di operazione di scrittura.
L'impostazione del flag di FILE_WRITE_DATA per un file consente anche di scrivere richieste oltre la fine del file. Il file viene esteso automaticamente per questo tipo di richiesta di scrittura, nonché.
Se vengono impostati solo i flag FILE_EXECUTE e SYNC, il chiamante non può usare l'handle restituito nel parametro FileHandle per leggere o scrivere direttamente dati da o verso il file. Vale a dire, tutte le operazioni sul file devono usare il paging di sistema di I/O per leggere o scrivere dati di file.

Il parametro ShareAccess determina se i thread separati possono accedere contemporaneamente allo stesso file. Se entrambi i file aperti hanno il privilegio di accedere a un file in modo specificato, il file può essere aperto e condiviso correttamente. Se il chiamante originale di FltCreateFileEx2 non specifica FILE_SHARE_READ, FILE_SHARE_WRITE o FILE_SHARE_DELETE, non è possibile eseguire altre operazioni aperte nel file perché il chiamante originale ha l'accesso esclusivo al file.

Per aprire correttamente un file condiviso, è necessario che il file DesiredAccess richiesto sia compatibile con le specifiche DesiredAccess e ShareAccess di tutte le richieste aperte precedenti non ancora rilasciate con FltClose. Vale a dire, il parametro DesiredAccess specificato in FltCreateFileEx2 per un determinato file non deve essere in conflitto con gli accessi che altri opener del file non sono consentiti.

Nota

Se IO_IGNORE_SHARE_ACCESS_CHECK è specificato nel parametro Flags , gestione I/O ignora il parametro ShareAccess . Tuttavia, il file system potrebbe comunque eseguire controlli di accesso. È quindi importante specificare la modalità di condivisione desiderata per il parametro ShareAccess, anche quando si usa il flag di IO_IGNORE_SHARE_ACCESS_CHECK. Si noti inoltre che quando viene specificato IO_IGNORE_SHARE_ACCESS_CHECK, il file system non tiene traccia dell'accesso desiderato o dell'accesso condiviso dell'apertura corrente. A causa di questo, le chiamate aperte successive sullo stesso file possono avere esito positivo.

Il valore CreateDisposition FILE_SUPERSEDE richiede che il chiamante disponga dell'accesso DELETE a un oggetto file esistente. In tal caso, viene eliminata in modo efficace una chiamata a FltCreateFileEx2 con FILE_SUPERSEDE in un file esistente e quindi la ricrea. Ciò implica che se il file è già stato aperto da un altro thread, ha aperto il file specificando un parametro ShareAccesscon il set di flag FILE_SHARE_DELETE. Si noti che questo tipo di eliminazione è coerente con lo stile POSIX dei file sovrascrivere.

I valori CreateDisposition FILE_OVERWRITE_IF e FILE_SUPERSEDE sono simili. Se FltCreateFileEx2 viene chiamato con un file esistente e uno di questi valori CreateDisposition , il file viene sostituito.

La sovrascrittura di un file è semanticamente equivalente a un'operazione di sostituzione, ad eccezione del seguente:

Il chiamante deve avere accesso in scrittura al file anziché eliminare l'accesso. Ciò implica che, se il file è già stato aperto da un altro thread, ha aperto il file con il flag FILE_SHARE_WRITE impostato nel parametro ShareAccess di input.
Gli attributi di file specificati vengono combinati con gli attributi già applicati al file usando un'operazione OR bit per bit. Ciò implica che se il file è già stato aperto da un altro thread, un chiamante successivo di FltCreateFileEx2 non può disabilitare i flag FileAttributes esistenti, ma può abilitare flag aggiuntivi per lo stesso file. Si noti che questo stile di sovrascrizione dei file è coerente con MS-DOS, Windows 3.1 e OS/2.

Il valore CreateOptions FILE_DIRECTORY_FILE specifica che il file da creare o aprire è un file di directory. Quando viene creato un file di directory, il file system crea una struttura appropriata sul disco per rappresentare una directory vuota per la struttura su disco di tale particolare file system. Se questa opzione è stata specificata e il file specificato da aprire non è un file di directory o se il chiamante ha specificato un valore CreateOptions o CreateDisposition incoerente, la chiamata a FltCreateFileEx2 ha esito negativo.

Il flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING impedisce al file system di eseguire qualsiasi buffering intermedio per conto del chiamante. Se si specifica questo valore, vengono applicate determinate restrizioni ai parametri del chiamante ad altri flt.. Routine di file o Zw.. Routine di file , tra cui le seguenti:

Qualsiasi valore di offset di byte passato al parametro ByteOffset di FltReadFile, ZwReadFile, FltWriteFile o ZwWriteFile deve essere un multiplo delle dimensioni del settore.
Il parametro Length passato a FltReadFile, ZwReadFile, FltWriteFile o ZwWriteFile deve essere un multiplo delle dimensioni del settore. Si noti che la specifica di un'operazione di lettura in un buffer la cui lunghezza è esattamente la dimensione del settore potrebbe comportare il trasferimento di meno byte significativi a tale buffer se la fine del file è stata raggiunta durante il trasferimento.
I buffer devono essere allineati in base al requisito di allineamento del dispositivo di archiviazione sottostante. Queste informazioni possono essere ottenute chiamando FltCreateFileEx2 per ottenere un handle per l'oggetto file che rappresenta il dispositivo fisico e quindi chiamando ZwQueryInformationFile con tale handle, specificando FileAlignmentInformation come valore per il parametro FileInformationClass . Per altre informazioni sui valori di sistema FILE_XXX_ALIGNMENT, definiti in Ntifs.h, vedere DEVICE_OBJECT e Inizializzazione di un oggetto Device.
Le chiamate a FltSetInformationFile o ZwSetInformationFile con il parametro FileInformationClass impostato su FilePositionInformation devono specificare un offset che corrisponde a un multiplo delle dimensioni del settore.

I flag CreateOptions FILE_SYNCHRONOUS_IO_ALERT e FILE_SYNCHRONOUS_IO_NONALERT, che si escludono a vicenda come suggerisce i nomi, specificano che il file viene aperto per operazioni di I/O sincrone. Ciò significa che tutte le operazioni di I/O sul file devono essere sincrone purché si verifichino tramite l'oggetto file a cui fa riferimento FileHandle restituito. Tutte le operazioni di I/O in un file di questo tipo vengono serializzate in tutti i thread usando l'handle restituito. Con uno di questi flag CreateOptions impostati, Gestione I/O mantiene l'offset di posizione del file corrente nel campo CurrentByteOffset dell'oggetto file. Questo offset può essere usato nelle chiamate a ZwReadFile e ZwWriteFile. Può anche essere sottoposto a query o impostato chiamando ZwQueryInformationFile o ZwSetInformationFile.

Se il flag CreateOptions FILE_OPEN_REPARSE_POINT non è specificato e FltCreateFileEx2 tenta di aprire un file con un punto di correzione, viene eseguita la normale elaborazione dei punti di analisi per il file. Se, d'altra parte, viene specificato il flag di FILE_OPEN_REPARSE_POINT, la normale elaborazione del reparse non viene eseguita e FltCreateFileEx2 tenta di aprire direttamente il file di reparse point. In entrambi i casi, se l'operazione di apertura ha avuto esito positivo, FltCreateFileEx2 restituisce STATUS_SUCCESS; in caso contrario, la routine restituisce un codice di errore NTSTATUS. FltCreateFileEx2 non restituisce mai STATUS_REPARSE.

Il flag CreateOptions FILE_OPEN_REQUIRING_OPLOCK elimina il tempo tra l'apertura del file e la richiesta di un oplock che potrebbe consentire a terze parti di aprire il file e ottenere una violazione di condivisione. Un'applicazione può usare il flag FILE_OPEN_REQUIRING_OPLOCK in FltCreateFileEx2 e quindi richiedere qualsiasi oplock. Ciò garantisce che un proprietario di oplock riceverà una notifica di qualsiasi richiesta aperta successiva che causa una violazione di condivisione.

In Windows 7, se esistono altri handle nel file quando un'applicazione usa il flag FILE_OPEN_REQUIRING_OPLOCK, l'operazione di creazione avrà esito negativo con STATUS_OPLOCK_NOT_GRANTED. Questa restrizione non esiste più a partire da Windows 8.

Se questa operazione di creazione interrompe un oplock già esistente nel file, l'impostazione del flag di FILE_OPEN_REQUIRING_OPLOCK causerà l'esito negativo dell'operazione di creazione con STATUS_CANNOT_BREAK_OPLOCK. L'oplock esistente non verrà interrotto da questa operazione di creazione.

Un'applicazione che usa questo flag deve richiedere un oplock dopo l'esito positivo di questa chiamata oppure tutti i tentativi successivi di aprire il file verranno bloccati senza il vantaggio dell'elaborazione tipica di oplock. Analogamente, se la chiamata ha esito positivo ma la richiesta oplock successiva ha esito negativo, un'applicazione che usa questo flag deve chiudere il relativo handle dopo aver rilevato che la richiesta di oplock non è riuscita.

Nota

Il flag FILE_OPEN_REQUIRING_OPLOCK è disponibile nei sistemi operativi Windows 7, Windows Server 2008 R2 e versioni successive. I file system Microsoft che implementano questo flag in Windows 7 sono NTFS, FAT ed exFAT.

Il flag CreateOptions FILE_RESERVE_OPFILTER consente a un'applicazione di richiedere un oplock di livello 1, batch o filtro per impedire ad altre applicazioni di ricevere violazioni di condivisione. Tuttavia, FILE_RESERVE_OPFILTER è praticamente utile solo per i oplock di filtro. Per usarlo, è necessario completare i passaggi seguenti:

Eseguire una richiesta di creazione con CreateOptions di FILE_RESERVE_OPFILTER, DesiredAccess di esattamente FILE_READ_ATTRIBUTES e ShareAccess di esattamente FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Se sono già presenti handle aperti, la richiesta di creazione ha esito negativo con STATUS_OPLOCK_NOT_GRANTED e anche il successivo oplock richiesto ha esito negativo.
- Se si apre con più accesso o meno condivisione, si verificherà anche un errore di STATUS_OPLOCK_NOT_GRANTED.
Se la richiesta di creazione ha esito positivo, richiedere un oplock.
Aprire un altro handle per il file per eseguire operazioni di I/O.

Il passaggio 3 rende questo pratico solo per gli oplock di filtro. L'handle aperto nel passaggio 3 può avere un oggetto DesiredAccess che contiene un massimo di FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL e non interrompe ancora un oplock di filtro. Tuttavia, qualsiasi desiredAccess maggiore di FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE interromperà un oplock di livello 1 o batch e rende il flag FILE_RESERVE_OPFILTER inutile per tali tipi di oplock.

NTFS è l'unico file system Microsoft che implementa FILE_RESERVE_OPFILTER.

I driver minifilter devono usare FltSetInformationFile, non ZwSetInformationFile, per rinominare un file.

Nota

Se si tenta di aprire un volume ma specificare solo una combinazione dei flag seguenti per il parametro DesiredAccess , FltCreateFileEx2 aprirà un handle, indipendentemente dal file system, che ha accesso diretto al dispositivo di archiviazione per il volume.

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

Non è necessario usare FltCreateFileEx2 per aprire un handle con accesso diretto al dispositivo di archiviazione per il volume oppure si perderanno le risorse di sistema. Se si vuole aprire un handle con accesso diretto a un dispositivo di archiviazione, chiamare invece la funzione IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint o ZwCreateFile .

Quando un chiamante di FltCreateFileEx2 desidera abilitare il reparsing per una destinazione del volume, un FLT_CREATEFILE_TARGET_ECP_CONTEXT può essere incluso come ECP nell'elenco ECP nel parametro DriverContext . Se questo ECP è presente, FltCreateFileEx2 regola il dispositivo di destinazione per l'operazione di creazione e tenta di trovare un'istanza filtrata di un volume appropriato per le informazioni sul file specificate. L'uso di questo ECP è disponibile a partire da Windows 8.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows Vista.
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (include FltKernel.h)
Libreria	Fltmgr.lib
IRQL	PASSIVE_LEVEL