Funzione IoCreateFileEx (ntddk.h)

Articolo
03/08/2023

La routine IoCreateFileEx causa la creazione di un nuovo file o una nuova directory oppure apre un file, un dispositivo, una directory o un volume esistente e fornisce al chiamante un handle per l'oggetto file. I driver di filtro del file system (driver di filtro legacy) chiamano questa routine.

Sintassi

NTSTATUS IoCreateFileEx(
  [out]          PHANDLE                   FileHandle,
  [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                     Disposition,
  [in]           ULONG                     CreateOptions,
  [in, optional] PVOID                     EaBuffer,
  [in]           ULONG                     EaLength,
  [in]           CREATE_FILE_TYPE          CreateFileType,
  [in, optional] PVOID                     InternalParameters,
  [in]           ULONG                     Options,
  [in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parametri

[out] FileHandle

Puntatore a una variabile che riceve l'handle di file se la chiamata ha esito positivo. Il driver deve chiudere l'handle con ZwClose non appena l'handle non viene più usato.

[in] DesiredAccess

Maschera di bit di flag (vedere ACCESS_MASK) che specifica il tipo di accesso richiesto dal chiamante al file o alla directory. Questo set di flag DesiredAccess definiti dal sistema determina i seguenti diritti di accesso specifici per gli oggetti file.

Flag DesiredAccess	Significato
DELETE	Il file può essere eliminato.
FILE_READ_DATA	I dati possono essere letti dal file.
FILE_READ_ATTRIBUTES	I flag FileAttributes , descritti di seguito, possono essere letti.
FILE_READ_EA	Gli attributi estesi (EAs) associati al file possono essere letti.
READ_CONTROL	È possibile leggere l'elenco di controllo di accesso (ACL) e le informazioni sulla proprietà associate al file.
FILE_WRITE_DATA	I dati possono essere scritti nel file.
FILE_WRITE_ATTRIBUTES	I flag FileAttributes possono essere scritti.
FILE_WRITE_EA	È possibile scrivere EA associati al file.
FILE_APPEND_DATA	I dati possono essere aggiunti al file.
WRITE_DAC	È possibile scrivere l'elenco di controllo degli accessi discrezionali (DACL) associato al file.
WRITE_OWNER	Le informazioni sulla proprietà associate al file possono essere scritte.
SYNCHRONIZE	Il chiamante può sincronizzare il completamento di un'operazione di I/O aspettando che il fileHandle restituito sia impostato sullo stato Segnalato. Questo flag deve essere impostato se è impostato il flag CreateOptions FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT.
FILE_EXECUTE	I dati possono essere letti in memoria dal file usando il paging di I/O del sistema.

In alternativa, per qualsiasi oggetto file che non rappresenta una directory, è possibile specificare uno o più flag generici ACCESS_MASK seguenti. I flag di STANDARD_RIGHTS_XXX sono valori di sistema predefiniti usati per applicare la sicurezza agli oggetti di sistema. È anche possibile combinare questi flag generici con flag aggiuntivi dalla tabella precedente.

Accesso desiderato ai valori di file	Esegue il mapping ai flag DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNC.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNC.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SYNC, FILE_READ_ATTRIBUTES, FILE_EXECUTE.

Per le directory (il flag CreateOptions FILE_DIRECTORY_FILE è impostato), è possibile specificare uno o più flag di ACCESS_MASK seguenti, che è anche possibile combinare con eventuali flag compatibili descritti in precedenza.

Accesso desiderato ai valori della directory	Significato
FILE_LIST_DIRECTORY	I file nella directory possono essere elencati.
FILE_TRAVERSE	La directory può essere attraversata; ovvero, può essere parte del nome percorso di un file.

I flag FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE e FILE_APPEND_DATA DesiredAccess non sono compatibili con la creazione o l'apertura di un file di directory.

[in] ObjectAttributes

Puntatore a una struttura OBJECT_ATTRIBUTES già inizializzata dalla routine InitializeObjectAttributes . Se il chiamante è in esecuzione nel contesto del processo di sistema, questo parametro può essere NULL. In caso contrario, il chiamante deve impostare l'attributo OBJ_KERNEL_HANDLE nella chiamata a InitializeObjectAttributes. I membri di questa struttura per un oggetto file includono quanto segue.

Membro	Valore
Lunghezza ULONG	Numero di byte dei dati ObjectAttributes forniti. Questo valore deve essere almeno `sizeof(OBJECT_ATTRIBUTES)`.
PUNICODE_STRING ObjectName	Puntatore a una stringa Unicode con buffer contenente il nome del file da creare o aprire. Questo valore deve essere una specifica di file completa, a meno che non sia il nome di un file relativo alla directory specificata da RootDirectory. Ad esempio, "\Device\Floppy1\myfile.dat" o "?? \B:\myfile.dat" potrebbe essere la specifica di file completa, purché il driver dell'unità disco floppy e il file system sovraseggera siano già caricati. Nota: "??" sostituisce "\DosDevices" come nome dello spazio dei nomi dell'oggetto Win32. "\DosDevices" funziona ancora, ma "??" viene tradotto più velocemente dal gestore oggetti.
HANDLE RootDirectory	Handle facoltativo in una directory ottenuta da una chiamata precedente a IoCreateFileEx. Se questo valore è NULL, il membro ObjectName deve essere una specifica di file completa che include il percorso completo del file di destinazione. Se questo valore non è NULL, il membro ObjectName specifica un nome file relativo a questa directory.
PSECURITY_DESCRIPTOR SecurityDescriptor	Descrittore di sicurezza facoltativo da applicare a un file. Gli ACL specificati da tale descrittore di sicurezza vengono applicati solo al file quando viene creato. Se il valore è NULL quando viene creato un file, l'ACL inserito nel file è dipendente dal file system; la maggior parte dei file system propaga una parte di tale ACL dal file di directory padre combinata con l'ACL predefinito del chiamante.
Attributi ULONG	Set di flag che controllano gli attributi dell'oggetto file. Se il chiamante è in esecuzione nel contesto del processo di sistema, questo parametro può essere zero. In caso contrario, il chiamante deve impostare il flag di OBJ_KERNEL_HANDLE . Il chiamante può anche impostare facoltativamente il flag OBJ_CASE_INSENSITIVE , che indica che il codice di ricerca dei nomi deve ignorare il caso di ObjectName anziché eseguire una ricerca esatta di corrispondenza.

[out] IoStatusBlock

Puntatore a una variabile di tipo IO_STATUS_BLOCK che riceve lo stato di completamento finale e informazioni sull'operazione richiesta. In caso di ritorno da IoCreateFileEx, il membro Information della variabile contiene uno dei valori seguenti:

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

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

[in] FileAttributes

Gli attributi specificati in modo esplicito vengono applicati solo quando il file viene creato, sostituito o, in alcuni casi, sovrascritto. Per impostazione predefinita, questo valore è FILE_ATTRIBUTE_NORMAL, che può essere sottoposto a override da qualsiasi altro flag o da una combinazione (tramite un'operazione OR bit per bit) di flag compatibili. I flag FileAttributes possibili includono quanto segue.

Flag Di FileAttributes	Significato
FILE_ATTRIBUTE_NORMAL	È necessario creare un file con attributi standard.
FILE_ATTRIBUTE_READONLY	Deve essere creato un file di sola lettura.
FILE_ATTRIBUTE_HIDDEN	Deve essere creato un file nascosto.
FILE_ATTRIBUTE_SYSTEM	È necessario creare un file di sistema.
FILE_ATTRIBUTE_ARCHIVE	Il file deve essere contrassegnato in modo che venga archiviato.
FILE_ATTRIBUTE_TEMPORARY	Deve essere creato un file temporaneo.

[in] ShareAccess

Specifica il tipo di accesso di condivisione al file che il chiamante vuole, come zero o uno o una combinazione dei flag seguenti. Per richiedere l'accesso esclusivo, impostare questo parametro su zero. Se il flag di IO_IGNORE_SHARE_ACCESS_CHECK viene specificato nel parametro Opzioni , 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 questo parametro, anche quando si usa il flag di IO_IGNORE_SHARE_ACCESS_CHECK. Per evitare errori di violazione di condivisione, specificare tutti i flag di accesso di condivisione seguenti.

Flag shareAccess	Significato
FILE_SHARE_READ	Il file può essere aperto per l'accesso in lettura tramite le chiamate di creazione di file di altri thread.
FILE_SHARE_WRITE	Il file può essere aperto per l'accesso in scrittura tramite le chiamate create da altri thread.
FILE_SHARE_DELETE	Il file può essere aperto per eliminare l'accesso tramite le chiamate create da altri thread.

I driver di dispositivo e i driver intermedi in genere impostano ShareAccess su zero, che consente al chiamante l'accesso esclusivo al file aperto.

[in] Disposition

Valore che determina la modalità di gestione del file quando il file esiste già. L'eliminazione può essere una delle seguenti.

Valore	Significato
FILE_SUPERSEDE	Se il file esiste già, sostituirlo con il file specificato. Se non esiste, creare il file specificato.
FILE_CREATE	Se il file esiste già, non eseguire la richiesta e non creare o aprire il file specificato. Se non esiste, creare il file specificato.
FILE_OPEN	Se il file esiste già, aprirlo anziché crearne uno nuovo. Se non esiste, non è possibile eseguire la richiesta e non creare un nuovo file.
FILE_OPEN_IF	Se il file esiste già, aprirlo. Se non esiste, creare il file specificato.
FILE_OVERWRITE	Se il file esiste già, aprirlo e sovrascriverlo. Se non esiste, non è possibile eseguire la richiesta.
FILE_OVERWRITE_IF	Se il file esiste già, aprirlo e sovrascriverlo. Se non esiste, creare il file specificato.

[in] CreateOptions

Specifica le opzioni da applicare durante la creazione o l'apertura del file, come combinazione compatibile dei flag seguenti.

Flag CreateOptions	Significato
FILE_DIRECTORY_FILE (0x00000001)	Il file creato o aperto è un file di directory. Con questo flag, il parametro Disposition deve essere impostato su uno dei FILE_CREATE, FILE_OPEN o FILE_OPEN_IF. I flag CreateOptions compatibili con questo flag sono i seguenti: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT e FILE_OPEN_BY_FILE_ID.
FILE_WRITE_THROUGH (0x00000002)	I servizi di sistema, i file system e i driver che scrivono dati nel file devono effettivamente trasferire i dati nel file prima che venga considerata completa qualsiasi operazione di scrittura richiesta.
FILE_SEQUENTIAL_ONLY (0x00000004)	Tutti gli accessi al file saranno sequenziali.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	Il file non può essere memorizzato nella cache o nel buffer interno di un driver. Questo flag non è compatibile con il flag DesiredAccessFILE_APPEND_DATA.
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Tutte le operazioni sul file vengono eseguite in modo sincrono. Qualsiasi attesa per conto del chiamante è soggetta alla terminazione prematura dagli avvisi. Questo flag causa anche il mantenimento del contesto di posizione del file dal sistema di I/O. Se questo flag è impostato, il flag DesiredAccess SYNC deve essere impostato anche in modo che gestione I/O usi l'oggetto file come oggetto di sincronizzazione.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Tutte le operazioni sul file vengono eseguite in modo sincrono. Le attese nel sistema per sincronizzare l'accodamento di I/O e il completamento non sono soggetti agli avvisi. Questo flag causa anche il mantenimento del contesto di posizione del file dal sistema di I/O. Se questo flag è impostato, il flag DesiredAccess SYNC deve essere impostato anche in modo che gestione I/O usi l'oggetto file come oggetto di sincronizzazione.
FILE_NON_DIRECTORY_FILE (0x00000040)	Il file aperto non deve essere un file di directory o questa chiamata non riesce. L'oggetto file aperto può rappresentare un file di dati; un dispositivo logico, virtuale o fisico; o un volume.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Creare una connessione ad albero per questo file per aprirla tramite la rete.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Completare immediatamente questa operazione con un codice di esito positivo alternativo se il file di destinazione viene oplockato anziché bloccare il thread del chiamante. Se il file è oplocked, un altro chiamante ha già accesso al file tramite la rete.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Se gli attributi estesi in un file esistente che viene aperto indicano che il chiamante deve comprendere gli attributi estesi per interpretare correttamente il file, non riuscire a eseguire questa richiesta perché il chiamante non capisce come gestire gli attributi estesi.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Riservato per l'uso del sistema; non usare.
FILE_RANDOM_ACCESS (0x00000800)	Gli accessi al file possono essere casuali, quindi non è necessario eseguire operazioni di lettura sequenziale sul file da file system o dal sistema operativo.
FILE_DELETE_ON_CLOSE (0x00001000)	Eliminare il file quando l'ultimo handle viene passato a FltClose.
FILE_OPEN_BY_FILE_ID (0x00002000)	Il file viene aperto in base all'ID. Il nome del file contiene il nome di un dispositivo e un ID a 64 bit da usare per aprire il file.
FILE_OPEN_FOR_BACKUP_INTENT (0x000004000)	Il file viene aperto per la finalità di backup; pertanto, il sistema deve controllare determinati diritti di accesso e concedere al chiamante gli accessi appropriati al file prima di controllare l'input DesiredAccess con il descrittore di sicurezza del file.
FILE_NO_COMPRESSION (0x00008000)	Eliminare l'ereditarietà di FILE_ATTRIBUTE_COMPRESSED dalla directory padre. Ciò consente la creazione di un file non compresso in una directory contrassegnata come compressa.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	Il file viene aperto e viene richiesto un blocco opportunistico (oplock) nel file come singola operazione atomica. Il file system verifica gli oplock prima di eseguire l'operazione di creazione e l'operazione di creazione avrà esito negativo con un codice restituito di STATUS_CANNOT_BREAK_OPLOCK se l'operazione di creazione interromperebbe un oplock esistente. Questo flag è disponibile in Windows 7, Windows Server 2008 R2 e versioni successive dei sistemi operativi Windows.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Quando si apre un file esistente, se FILE_SHARE_READ non è specificato e i controlli di accesso al file system non concedono al chiamante l'accesso in scrittura al file, non è possibile aprire con STATUS_ACCESS_DENIED. Questo comportamento è stato predefinito prima di Windows 7.
FILE_SESSION_AWARE (0x00040000)	Il file o il dispositivo viene aperto con la consapevolezza della sessione. Se questo flag non è specificato, i dispositivi per sessione (ad esempio un dispositivo che usa il reindirizzamento USB RemoteFX) non possono essere aperti dai processi in esecuzione nella sessione 0. Questo flag non ha alcun effetto per i chiamanti non nella sessione 0. Questo flag è supportato solo nelle edizioni server di Windows. Questo flag non è supportato prima di Windows Server 2012.
FILE_RESERVE_OPFILTER (0x00100000)	Questo flag consente a un'applicazione di richiedere un blocco opportunistico di filtro (oplock) per impedire ad altre applicazioni di ottenere violazioni di condivisione. Se sono già disponibili handle aperti, la richiesta di creazione avrà esito negativo con STATUS_OPLOCK_NOT_GRANTED. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
FILE_OPEN_REPARSE_POINT (0x00200000)	Aprire un file con un punto di correzione e ignorare l'elaborazione normale del punto di ripristino per il file. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
FILE_OPEN_NO_RECALL (0x00400000)	Indica a tutti i filtri che eseguono l'archiviazione offline o la virtualizzazione per non ricordare il contenuto del file in seguito a questa apertura.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	Questo flag indica al file system di acquisire l'utente associato al thread chiamante. Tutte le chiamate successive a FltQueryVolumeInformation o ZwQueryVolumeInformationFile usando l'handle restituito presuppongono l'utente acquisito, anziché l'utente chiamante al momento, a scopo di calcolare lo spazio disponibile per il chiamante. Questo vale per i valori FsInformationClass seguenti: FileFsSizeInformation, FileFsFullSizeInformation e FileFsFullSizeInformationEx.

[in, optional] EaBuffer

Puntatore a una variabile fornita dal chiamante di tipo FILE_FULL_EA_INFORMATION che contiene informazioni sull'attributo esteso (EA) da applicare al file. Per i driver di dispositivo e intermedio, questo parametro deve essere NULL.

[in] EaLength

Lunghezza, in byte, di EaBuffer. Per i driver di dispositivo e i driver intermedi, questo parametro deve essere zero.

[in] CreateFileType

I driver devono impostare questo parametro su CreateFileTypeNone.

[in, optional] InternalParameters

I driver devono impostare questo parametro su NULL.

[in] Options

Specifica le opzioni da usare durante la generazione della richiesta di creazione. È possibile usare zero o più valori di flag di bit seguenti.

Flag opzioni	Significato
IO_FORCE_ACCESS_CHECK	La gestione I/O deve controllare la richiesta di creazione rispetto al descrittore di sicurezza del file. Per altre informazioni, vedere la sezione Osservazioni.
IO_IGNORE_SHARE_ACCESS_CHECK	La gestione I/O non deve eseguire controlli di accesso condiviso sull'oggetto file dopo la creazione. Tuttavia, il file system potrebbe comunque eseguire questi controlli.
IO_STOP_ON_SYMLINK	Se viene rilevato un collegamento simbolico, un collegamento simbolico o un punto di ripristino globale durante l'apertura o la creazione del file, la gestione I/O restituirà STATUS_STOPPED_ON_SYMLINK. Inoltre, una struttura REPARSE_DATA_BUFFER verrà restituita in IoStatusBlock-Information>. Il chiamante è responsabile della liberazione della struttura REPARSE_DATA_BUFFER .
IO_OPEN_TARGET_DIRECTORY	Aprire la directory padre del file.

[in, optional] DriverContext

Puntatore facoltativo a una struttura IO_DRIVER_CREATE_CONTEXT inizializzata in precedenza dalla routine IoInitializeDriverCreateContext . La struttura IO_DRIVER_CREATE_CONTEXT può essere usata per passare parametri aggiuntivi alle routine IoCreateFileEx e FltCreateFileEx2 . Per altre informazioni, vedere la sezione Osservazioni seguenti.

Valore restituito

IoCreateFileEx restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti.

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	IoCreateFileEx restituisce questo valore di stato se il parametro DriverContext non è NULL e se l'oggetto dispositivo specificato non è collegato allo stack di driver del file system per il volume specificato nel nome del file o della directory. Questo oggetto dispositivo viene specificato dal membro DeviceObjectHint della struttura IO_DRIVER_CREATE_CONTEXT. Per altre informazioni, vedere IO_DRIVER_CREATE_CONTEXT.
STATUS_MOUNT_POINT_NOT_RESOLVED	IoCreateFileEx restituisce questo valore di stato se il parametro DriverContext non è NULL e se il file o il nome della directory contiene un punto di montaggio che si risolve in un volume diverso da quello a cui è collegato l'oggetto dispositivo specificato. Questo oggetto dispositivo viene specificato dal membro DeviceObjectHint della struttura IO_DRIVER_CREATE_CONTEXT. Per altre informazioni, vedere IO_DRIVER_CREATE_CONTEXT.
STATUS_OBJECT_PATH_SYNTAX_BAD	IoCreateFileEx restituisce questo valore di stato se il parametro ObjectAttributes non contiene un membro RootDirectory , ma il membro ObjectName nella struttura OBJECT_ATTRIBUTES è una stringa vuota o non contiene un carattere OBJECT_NAME_PATH_SEPARATOR. Questo indica una sintassi errata per il percorso dell'oggetto.
STATUS_STOPPED_ON_SYMLINK	IoCreateFileEx restituisce questo valore di stato se il flag dei parametri OpzioniIO_STOP_ON_SYMLINK è impostato e viene rilevato un collegamento simbolico durante l'apertura o la creazione del file.

Se la routine IoCreateFileEx restituisce uno stato di errore, il chiamante può trovare informazioni aggiuntive sulla causa dell'errore controllando il parametro IoStatusBlock .

IoCreateFileEx 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 IoCreateFileEx tenta di gestire questa situazione.

Commenti

La routine IoCreateFileEx è simile alla routine IoCreateFile e alla routine IoCreateFileSpecifyDeviceObjectHint, ma offre funzionalità aggiuntive, tra cui l'accesso a parametri di creazione aggiuntivi (ECPs), hint di oggetti dispositivo e informazioni sulle transazioni tramite il parametro DriverContext della routine IoCreateFileEx. Per altre informazioni su questi parametri basati sulla struttura, vedere IO_DRIVER_CREATE_CONTEXT.

I driver di filtro del file system chiamano IoCreateFileEx per inviare una richiesta di creazione solo a un oggetto dispositivo specificato, i filtri collegati sotto di esso e il file system. I filtri collegati sopra l'oggetto dispositivo specificato nello stack di driver non ricevono la richiesta di creazione. Tuttavia, se il membro DeviceObjectHint della struttura IO_DRIVER_CREATE_CONTEXT (passato tramite il parametro DriverContext ) è NULL, la richiesta passa all'inizio dello stack e viene ricevuta da tutti i filtri e dal file system.

Se la richiesta di I/O non passa all'inizio dello stack di driver, ovvero se il parametro DriverContext non è NULL e un oggetto dispositivo valido viene specificato dal membro DeviceObjectHint della struttura IO_DRIVER_CREATE_CONTEXT, si applica la restrizione seguente:

Se il percorso del nome file passato alla routine IoCreateFileEx contiene un punto di montaggio, il punto di montaggio deve essere risolto nello stesso volume in cui risiede il file o la directory.

L'handle ottenuto da IoCreateFileEx può essere usato dalle chiamate successive per modificare i dati all'interno del file o lo stato o gli attributi dell'oggetto file. Qualsiasi handle ottenuto da IoCreateFileEx deve essere rilasciato chiamando ZwClose.

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

Come nome percorso completo, fornito nel membro ObjectName del parametro ObjectAttributes di input.
Come nome percorso relativo all'handle nel membro RootDirectory del parametro ObjectAttributes di input. Questo handle può rappresentare un file di directory.

Le routine del driver eseguite in un contesto di processo diverso da quello del processo di sistema devono impostare l'attributo OBJ_KERNEL_HANDLE per il parametro ObjectAttributes di IoCreateFileEx. Ciò limita l'uso dell'handle restituito da IoCreateFileEx ai processi in esecuzione in modalità kernel. In caso contrario, l'handle può essere accessibile dal processo nel cui contesto è in esecuzione il driver. I driver possono chiamare InitializeObjectAttributes per impostare l'attributo OBJ_KERNEL_HANDLE.

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. In caso contrario, un chiamante che è un dispositivo o un driver intermedio deve sincronizzare un completamento di I/O usando un oggetto evento.
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 scritture nel file vengono ignorate. Tuttavia, il file verrà 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 oltre la fine del file. Il file viene esteso automaticamente anche per questo tipo di scrittura.
Se vengono impostati solo i flag FILE_EXECUTE e SYNC, il chiamante non può leggere o scrivere direttamente dati nel file usando fileHandle restituito: ovvero tutte le operazioni sul file si verificano tramite il pager del sistema in risposta alle istruzioni e agli accessi ai dati. I driver di dispositivo e intermedio non devono impostare il flag di FILE_EXECUTE in DesiredAccess.

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

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

Se IO_IGNORE_SHARE_ACCESS_CHECK viene specificato nel parametro Opzioni , la 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.

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

I valori Di eliminazione FILE_OVERWRITE_IF e FILE_SUPERSEDE sono simili. Se IoCreateFileEx viene chiamato con un file esistente e uno di questi valori di eliminazione , il file verrà 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 nell'input ShareAccess.
Gli attributi di file specificati sono logicamente ORed con quelli già presenti nel file. Ciò implica che se il file è già stato aperto da un altro thread, un chiamante successivo di IoCreateFileEx 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 con 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 Eliminazione incoerente, la chiamata a IoCreateFileEx avrà esito negativo.

Il flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING impedisce al file system di eseguire qualsiasi buffer intermedio per conto del chiamante. Se si specifica questo valore, vengono applicate determinate restrizioni ai parametri del chiamante a Zw.. Routine di file , inclusi i seguenti:

Qualsiasi byteOffset facoltativo passato a ZwReadFile o ZwWriteFile deve essere un intero (intero multiplo) della dimensione del settore.
La lunghezza passata a ZwReadFile o ZwWriteFile deve essere un integrale delle dimensioni del settore. Si noti che specificando un'operazione di lettura in un buffer la cui lunghezza è esattamente la dimensione del settore potrebbe causare un numero minore di byte significativi trasferiti 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 sottostante. Queste informazioni possono essere ottenute chiamando IoCreateFileEx per ottenere un handle per l'oggetto file che rappresenta il dispositivo fisico e quindi chiamando ZwQueryInformationFile con tale handle. Per un elenco dei valori FILE_XXX del sistema_ALIGNMENT, vedere DEVICE_OBJECT.
Le chiamate a ZwSetInformationFile con il parametro FileInformationClass impostate su FilePositionInformation devono specificare un offset integrale delle dimensioni del settore.

I flag CreateOptions, FILE_SYNCHRONOUS_IO_ALERT e FILE_SYNCHRONOUS_IO_NONALERT a vicenda, specificano che tutte le operazioni di I/O sul file devono essere sincrone purché si verifichino tramite l'oggetto file denominato dal file restituito FileHandle. Tutti gli I/O in un file di questo tipo vengono serializzati in tutti i thread usando l'handle restituito. Con uno di questi valori CreateOptions , il flag DesiredAccess SYNC deve essere impostato in modo che gestione I/O userà l'oggetto file come oggetto di sincronizzazione. Con uno di questi valori CreateOptions impostati, Gestione I/O mantiene il contesto di "posizione file" per l'oggetto file, un offset di posizione del file interno e corrente. Questo offset può essere usato nelle chiamate a ZwReadFile e ZwWriteFile. La sua posizione può essere eseguita anche chiamando ZwQueryInformationFile o impostando la chiamata di ZwSetInformationFile.

Se il flag CreateOptions FILE_OPEN_REPARSE_POINT non è specificato e IoCreateFileEx tenta di aprire un file con un punto di reparse, l'elaborazione normale del punto di ripristino si verifica per il file. Se, invece, viene specificato il flag di FILE_OPEN_REPARSE_POINT, l'elaborazione di riparse normale non si verifica e IoCreateFileEx tenta di aprire direttamente il file del punto di ripristino. In entrambi i casi, se l'operazione aperta ha avuto esito positivo, IoCreateFileEx restituisce STATUS_SUCCESS; in caso contrario, la routine restituisce un codice di errore NTSTATUS. IoCreateFileEx 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 potenzialmente consentire a una terza parte di aprire il file e ottenere una violazione di condivisione. Un'applicazione può usare il flag di FILE_OPEN_REQUIRING_OPLOCK in IoCreateFileEx e quindi richiedere qualsiasi oplock. Ciò garantisce che un proprietario di oplock riceverà una notifica a qualsiasi richiesta aperta successiva che causa una violazione della condivisione.

In Windows 7, se esistono altri handle nel file quando un'applicazione usa il flag di 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à presente 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 che questa chiamata ha esito positivo o tutti i tentativi successivi di aprire il file verranno bloccati senza il vantaggio dell'elaborazione tipica del blocco operativo. Analogamente, se questa chiamata ha esito positivo, ma la richiesta di 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.

Il flag FILE_OPEN_REQUIRING_OPLOCK è disponibile in Windows 7, Windows Server 2008 R2 e versioni successive dei sistemi operativi Windows. I file system Microsoft che implementano questo flag sono NTFS, FAT e 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 ottenere violazioni di condivisione. Tuttavia, FILE_RESERVE_OPFILTER è praticamente utile solo per gli oplock di filtro. Per usarlo, è necessario seguire questa procedura:

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 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 tre rende questa pratica 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 | SYNC | READ_CONTROL e ancora non interrompere un blocco di filtri. Tuttavia, qualsiasi desiredAccess maggiore di FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNC interromperà un blocco di livello 1 o batch e renderà inutile il flag di FILE_RESERVE_OPFILTER per tali tipi di oplock.

Per creare richieste di origine in modalità utente, se il driver imposta IO_FORCE_ACCESS_CHECK nel parametro Opzioni di IoCreateFileEx , deve anche impostare OBJ_FORCE_ACCESS_CHECK nel parametro ObjectAttributes . Per informazioni su questo flag, vedere il membro Attributi di OBJECT_ATTRIBUTES.

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

È possibile usare IoCreateFileEx per ottenere un handle in un volume.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	ntddk.h (include Ntddk.h, Ntifs.h, FltKernel.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL