Funzione NtCreateFile (ntifs.h)

Articolo
05/24/2024

La routine NtCreateFile crea un nuovo file o apre un file esistente.

Sintassi

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateFile(
  [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              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Parametri

[out] FileHandle

Puntatore a una variabile HANDLE che riceve un handle per il file.

[in] DesiredAccess

Specifica un valore ACCESS_MASK che determina l'accesso richiesto all'oggetto.

Oltre al standard diritti di accesso definiti per tutti i tipi di oggetti, il chiamante può specificare uno dei seguenti diritti di accesso specifici; vale a dire diritti specifici per i file.

flag ACCESS_MASK	Consente al chiamante di eseguire questa operazione
FILE_READ_DATA	Legge i dati dal file.
FILE_READ_ATTRIBUTES	Leggere gli attributi del file. Per altre informazioni, vedere la descrizione del parametro FileAttributes.
FILE_READ_EA	Leggere gli attributi estesi (EA) del file. Questo flag è irrilevante per i driver intermedi e del dispositivo.
FILE_WRITE_DATA	Scrivere dati nel file.
FILE_WRITE_ATTRIBUTES	Scrivere gli attributi del file. Per altre informazioni, vedere la descrizione del parametro FileAttributes.
FILE_WRITE_EA	Modificare gli attributi estesi (EA) del file. Questo flag è irrilevante per i driver intermedi e del dispositivo.
FILE_APPEND_DATA	Aggiungere dati al file.
FILE_EXECUTE	Usare l'I/O di paging di sistema per leggere i dati dal file in memoria. Questo flag è irrilevante per i driver intermedi e del dispositivo.

Nota

Non specificare FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA o FILE_EXECUTE quando si crea o si apre una directory.

Il chiamante può anche specificare i seguenti diritti di accesso generici (diritti applicabili a tutti i tipi di oggetto, in cui il significato di ogni diritto di accesso generico è specifico del tipo di oggetto). I diritti di accesso generici per gli oggetti file corrispondono a diritti di accesso specifici, come illustrato nella tabella seguente. Si noti che "correspond" indica "esegue il mapping a" e non significa che il valore del diritto generico è "uguale a" il valore dell'OR bit per bit del mapping dei diritti specifico. Il gestore di I/O definisce il mapping effettivo.

Diritto di accesso generico	Esegue il mapping a questi diritti di accesso specifici
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA e SYNCHRONIZE
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA e SYNCHRONIZE
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, FILE_EXECUTE, FILE_READ_ATTRIBUTES e SYNCHRONIZE. Questo valore è irrilevante per i driver intermedi e del dispositivo.
GENERIC_ALL	FILE_ALL_ACCESS

Nota

diritti di accesso generici possono essere specificati solo per un file; non possono essere specificati per una directory.

Alcuni flag di CreateOptions richiedono che determinati flag di accesso siano impostati in DesiredAccess quando viene chiamato NtCreateFile. Per informazioni dettagliate, vedere il parametro CreateOptions .

Ad esempio, se si specifica GENERIC_READ per un oggetto file, la routine esegue il mapping di questo valore alla maschera di bit FILE_GENERIC_READ di diritti di accesso specifici. Nella tabella precedente i diritti di accesso specifici elencati per GENERIC_READ corrispondono (ma non sono uguali) ai flag di accesso contenuti nella maschera di bit FILE_GENERIC_READ.

Se il file è effettivamente una directory, il chiamante può anche specificare i diritti di accesso generici seguenti.

flag di DesiredAccess	Consente al chiamante di eseguire questa operazione
FILE_LIST_DIRECTORY	Elencare i file nella directory.
FILE_TRAVERSE	Attraversare la directory, in altre parole, includere la directory nel percorso di un file.

Per altre informazioni sui diritti di accesso, vedere ACCESS_MASK e Access Rights.

[in] ObjectAttributes

Puntatore a una struttura OBJECT_ATTRIBUTES che specifica il nome dell'oggetto e altri attributi. Usare InitializeObjectAttributes per inizializzare questa struttura. Se il chiamante non è in esecuzione in un contesto di thread di sistema, deve impostare l'attributo OBJ_KERNEL_HANDLE quando chiama InitializeObjectAttributes.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e altre informazioni sull'operazione richiesta. In particolare, il membro Information riceve uno dei valori seguenti:

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Puntatore a un LARGE_INTEGER contenente le dimensioni di allocazione iniziali, in byte, per un file creato o sovrascritto. Se AllocationSize è NULL, non viene specificata alcuna dimensione di allocazione. Se non viene creato o sovrascritto alcun file, AllocationSize viene ignorato.

[in] FileAttributes

Specifica uno o più flag FILE_ATTRIBUTE_XXX che rappresentano gli attributi di file da impostare se si crea o si sovrascrive un file. Il chiamante specifica in genere FILE_ATTRIBUTE_NORMAL, che imposta gli attributi predefiniti. Per un elenco dei flag di XXX validi FILE_ATTRIBUTE_, vedere la routine CreateFile nella documentazione di Microsoft Windows SDK. Se non viene creato o sovrascritto alcun file, FileAttributes viene ignorato.

[in] ShareAccess

Tipo di accesso alla condivisione, specificato come zero o qualsiasi combinazione dei flag seguenti.

flag di ShareAccess	Consente ad altri thread di eseguire questa operazione
FILE_SHARE_READ	Leggere il file
FILE_SHARE_WRITE	Scrivere il file
FILE_SHARE_DELETE	Eliminare il file

I driver intermedi e del dispositivo in genere impostano ShareAccess su zero, che consente al chiamante di accedere esclusivamente al file aperto.

[in] CreateDisposition

Specifica l'azione da eseguire se il file non esiste o non esiste. CreateDisposition può essere uno dei valori nella tabella seguente.

Valore di CreateDisposition	Azione se il file esiste	Azione se il file non esiste
FILE_SUPERSEDE	Sostituire il file.	Creare il file.
FILE_CREATE	Restituisce un errore.	Creare il file.
FILE_OPEN	Aprire il file.	Restituisce un errore.
FILE_OPEN_IF	Aprire il file.	Creare il file.
FILE_OVERWRITE	Aprire il file e sovrascriverlo.	Restituisce un errore.
FILE_OVERWRITE_IF	Aprire il file e sovrascriverlo.	Creare il file.

[in] CreateOptions

Specifica le opzioni da applicare quando il driver crea o apre il file. Usare uno o più flag nella tabella seguente.

Flag CreateOptions	Significato
FILE_DIRECTORY_FILE (0x00000001)	Il file è una directory. I flag di CreateOptions compatibili sono FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT e FILE_OPEN_BY_FILE_ID. Il parametro CreateDisposition deve essere impostato su FILE_CREATE, FILE_OPEN o FILE_OPEN_IF.
FILE_WRITE_THROUGH (0x00000002)	I servizi di sistema, i driver del file system e i driver che scrivono dati nel file devono effettivamente trasferire i dati al file prima che qualsiasi operazione di scrittura richiesta venga considerata completa.
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 memorizzato nel buffer interno di un driver. Questo flag non è compatibile con il flag di FILE_APPEND_DATA DesiredAccess.
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Tutte le operazioni sul file vengono eseguite in modo sincrono. Qualsiasi attesa per conto del chiamante è soggetta a terminazione prematura dagli avvisi. Questo flag fa anche in modo che il sistema di I/O mantenga il puntatore alla posizione del file. Se questo flag è impostato, il flag SYNCHRONIZE deve essere impostato nel parametro DesiredAccess.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Tutte le operazioni sul file vengono eseguite in modo sincrono. Le attese nel sistema che sincronizzano l'accodamento e il completamento di I/O non sono soggetti ad avvisi. Questo flag fa anche in modo che il sistema di I/O mantenga il contesto di posizione del file. Se questo flag è impostato, il flag SYNCHRONIZE deve essere impostato nel parametro DesiredAccess.
FILE_NON_DIRECTORY_FILE (0x00000040)	Il file non è una directory. L'oggetto file da aprire può rappresentare un file di dati; un dispositivo logico, virtuale o fisico; o un volume. A partire da Windows 11 versione 24H2, NTFS ora rispetta questo flag quando si apre un attributo $INDEX_ALLOCATION.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Creare una connessione ad albero per questo file per aprirlo in rete. Questo flag non viene usato dai driver intermedi e del dispositivo.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Completare immediatamente questa operazione con un codice di esito positivo alternativo di STATUS_OPLOCK_BREAK_IN_PROGRESS se il file di destinazione è bloccato, anziché bloccare il thread del chiamante. Se il file è bloccato, un altro chiamante ha già accesso al file. Questo flag non viene usato dai driver intermedi e del dispositivo.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Se gli attributi estesi (EA) per un file esistente aperto indicano che il chiamante deve comprendere che EAs deve interpretare correttamente il file, NtCreateFile deve restituire un errore. Questo flag è irrilevante per i driver intermedi e del dispositivo.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Riservato per l'uso del sistema; non usare.
FILE_RANDOM_ACCESS (0x00000800)	L'accesso al file può essere casuale, quindi non deve essere eseguita alcuna operazione di read-ahead sequenziale dai driver del file system o dal sistema.
FILE_DELETE_ON_CLOSE (0x00001000)	Il sistema elimina il file quando l'ultimo handle al file viene passato a NtClose. Se questo flag è impostato, il flag DELETE deve essere impostato nel parametro desiredAccess .
FILE_OPEN_BY_FILE_ID (0x00002000)	Il nome file specificato dal parametro ObjectAttributes include un numero di riferimento file binario a 8 byte o un ID oggetto a 16 byte per il file, a seconda del file system. Facoltativamente, un nome di dispositivo seguito da un carattere barra rovesciata può procedere con questi valori binari. Per altri dettagli e un esempio, vedere La sezione Osservazioni.
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000)	Il file viene aperto per finalità di backup. Pertanto, il sistema deve verificare la presenza di determinati diritti di accesso e concedere al chiamante l'accesso appropriato al file, prima di controllare il parametro DesiredAccess rispetto al descrittore di sicurezza del file. Questo flag non viene usato dai driver intermedi e del dispositivo.
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 la presenza di oplock prima di eseguire l'operazione di creazione e non riuscirà a creare con un codice restituito di STATUS_CANNOT_BREAK_OPLOCK se il risultato sarebbe interrompere un oplock esistente. Questo flag è disponibile a partire da Windows 7 e Windows Server 2008 R2.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Quando si apre un file esistente, se non viene specificato FILE_SHARE_READ e i controlli di accesso al file system non concedono al chiamante l'accesso in scrittura al file, non eseguire questa operazione con STATUS_ACCESS_DENIED. Questo comportamento è stato predefinito prima di Windows 7. Questo flag è disponibile a partire da Windows 7 e Windows Server 2008 R2.
FILE_SESSION_AWARE (0x00040000)	Il client che apre il file o il dispositivo è in grado di essere compatibile con la sessione e, se necessario, l'accesso alla sessione viene convalidato. Questo flag è disponibile a partire da Windows 8.
FILE_RESERVE_OPFILTER (0x00100000)	Questo flag consente a un'applicazione di richiedere un blocco opportunistico filtro (oplock) per impedire ad altre applicazioni di ricevere violazioni di condivisione. Se sono già presenti handle aperti, la richiesta di creazione avrà esito negativo con STATUS_OPLOCK_NOT_GRANTED. Per altre informazioni, vedere la sezione Osservazioni seguente.
FILE_OPEN_REPARSE_POINT (0x00200000)	Aprire un file con un punto reparse e ignorare l'elaborazione normale del punto di analisi per il file. Per altre informazioni, vedere la sezione Osservazioni seguente.
FILE_OPEN_NO_RECALL (0x00400000)	Indica a tutti i filtri che eseguono l'archiviazione offline o la virtualizzazione di non richiamare il contenuto del file in seguito all'apertura.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	Questo flag indica al file system di acquisire l'utente associato al thread chiamante. Eventuali chiamate successive a FltQueryVolumeInformation o ZwQueryVolumeInformationFile usando l'handle restituito presuppongono l'utente acquisito, anziché l'utente chiamante al momento, ai fini del calcolo dello spazio disponibile per il chiamante. Questo vale per i valori FsInformationClass seguenti: FileFsSizeInformation, FileFsFullSizeInformation e FileFsFullSizeInformationEx.
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000)	Interpretare il parametro EaBuffer come istanza di EXTENDED_CREATE_INFORMATION. Questo flag è disponibile a partire da Windows 11 versione 22H2.

[in, optional] EaBuffer

Per i driver intermedi e di dispositivo, questo parametro deve essere un puntatore NULL.

[in] EaLength

Per i driver intermedi e del dispositivo, questo parametro deve essere zero.

Valore restituito

ntCreateFile restituisce STATUS_SUCCESS in caso di esito positivo o di codice di errore NTSTATUS appropriato in caso di errore. In quest'ultimo caso, il chiamante può determinare la causa dell'errore controllando il parametro IoStatusBlock .

Nota

NtCreateFile 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 è pieno e si verifica un errore mentre NtCreateFile tenta di gestire questa situazione.

Osservazioni

NtCreateFile fornisce un handle che il chiamante può usare per modificare i dati di un file o lo stato e gli attributi dell'oggetto file. Per altre informazioni, vedere Using Files in a Driver.

Quando l'handle a cui punta FileHandle non è più in uso, il driver deve chiamare NtClose per chiuderlo.

Se il chiamante non è in esecuzione in un contesto di thread di sistema, deve assicurarsi che gli handle creati siano handle privati. In caso contrario, l'handle può essere accessibile dal processo nel cui contesto è in esecuzione il driver. Per altre informazioni, vedere Handle di oggetti .

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

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

L'impostazione di determinati flag nel parametro DesiredAccess produce gli effetti seguenti:

Affinché un chiamante sincronizzi un completamento di I/O attendendo che venga restituito FileHandle, è necessario impostare il flag SYNCHRONIZE. In caso contrario, un chiamante che è un dispositivo o un driver intermedio deve sincronizzare un completamento di I/O usando un oggetto evento.
Se il chiamante imposta solo i flag FILE_APPEND_DATA e SYNCHRONIZE, può scrivere solo alla fine del file e le informazioni sull'offset relative alle operazioni di scrittura nel file vengono ignorate. Il file verrà esteso automaticamente in base alle esigenze per questo tipo di operazione.
L'impostazione del flag FILE_WRITE_DATA per un file consente anche al chiamante di scrivere oltre la fine del file. Anche in questo caso, il file viene esteso automaticamente in base alle esigenze.
Se il chiamante imposta solo i flag FILE_EXECUTE e SYNCHRONIZE, non può leggere o scrivere direttamente dati nel file utilizzando il FileHandle restituito. Ovvero, tutte le operazioni sul file vengono eseguite tramite il cercapersone di sistema in risposta alle operazioni di istruzione e accesso ai dati. I driver intermedi e del dispositivo non devono impostare il flag di FILE_EXECUTE.

Il parametro ShareAccess determina se i thread separati possono accedere allo stesso file, possibilmente contemporaneamente. A condizione che entrambi i chiamanti dispongano dei privilegi di accesso appropriati, il file può essere aperto e condiviso correttamente. Se il chiamante originale di NtCreateFile non specifica FILE_SHARE_READ, FILE_SHARE_WRITE o FILE_SHARE_DELETE, nessun altro chiamante può aprire il file, ovvero al chiamante originale viene concesso l'accesso esclusivo.

Per aprire correttamente un file condiviso, i flag di DesiredAccess devono essere compatibili con i flag DesiredAccess e ShareAccess di tutte le operazioni aperte precedenti non ancora rilasciate tramite . Ovvero, il DesiredAccess specificato per NtCreateFile per un determinato file non deve essere in conflitto con gli accessi non consentiti da altri opener del file.

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

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

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

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 NtCreateFile non può disabilitare i flag FileAttributes esistenti ma può abilitare flag aggiuntivi per lo stesso file. Si noti che questo stile di sovrascrittura dei file è coerente con MS-DOS, Microsoft Windows 3.1 e OS/2.

Il valore FILE_DIRECTORY_FILE CreateOptions specifica che il file da creare o aprire è una 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 quel 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 incoerente CreateOptions o createDisposition valore, la chiamata a NtCreateFile avrà esito negativo.

Il flag FILE_NO_INTERMEDIATE_BUFFERING CreateOptions impedisce al file system di eseguire qualsiasi buffering intermedio per conto del chiamante. Se si specifica questo flag, le restrizioni seguenti sui parametri del chiamante vengono applicate ad altre routine di ZwXxxFile.

Qualsiasi ByteOffset facoltativo passato a NtReadFile o NtWriteFile deve essere un multiplo delle dimensioni del settore.
Il Length passato a NtReadFile o NtWriteFile deve essere un integrale 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 può comportare il trasferimento di un numero minore di 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 sottostante. Per ottenere queste informazioni, chiamare NtCreateFile per ottenere un handle per l'oggetto file che rappresenta il dispositivo fisico e passare tale handle a NtQueryInformationFile. Per un elenco dei valori_ALIGNMENT FILE_XXX del sistema, vedere DEVICE_OBJECT.
Le chiamate a NtSetInformationFile con il parametro FileInformationClass impostato su FilePositionInformation devono specificare un offset multiplo delle dimensioni del settore.

I flag FILE_SYNCHRONOUS_IO_ALERT e FILE_SYNCHRONOUS_IO_NONALERT CreateOptions (che si escludono a vicenda) specificano che tutte le operazioni di I/O nel file saranno sincrone, purché le operazioni si verifichino tramite l'oggetto file a cui fa riferimento l'oggetto file restituito FileHandle. Tutte le operazioni di I/O in un file di questo tipo vengono serializzate in tutti i thread usando l'handle restituito. Se uno di questi flag CreateOptions è impostato, è necessario impostare anche il flag SYNCHRONIZE DesiredAccess per costringere il gestore di I/O a usare l'oggetto file come oggetto di sincronizzazione. In questi casi, il gestore di I/O tiene traccia dell'offset di posizione del file corrente, che è possibile passare a NtReadFile e NtWriteFile. Chiama NtQueryInformationFile o ntSetInformationFile per ottenere o impostare questa posizione.

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

Il flag FILE_OPEN_REQUIRING_OPLOCK CreateOptions 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 NtCreateFile e quindi richiedere qualsiasi oplock. In questo modo, un proprietario di oplock riceverà una notifica di qualsiasi richiesta aperta successiva che causa una violazione della condivisione.

In Windows 7, se nel file esistono altri handle 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 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 il flag FILE_OPEN_REQUIRING_OPLOCK deve richiedere un oplock dopo che la chiamata ha esito positivo oppure tutti i tentativi successivi di aprire il file verranno bloccati senza il vantaggio della normale elaborazione di oplock. Analogamente, se questa 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. L'applicazione non deve eseguire altre operazioni del file system sul file prima di richiedere l'oplock (oltre a chiudere l'handle di file), altrimenti potrebbe verificarsi un deadlock.

Nota

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

Il FILE_RESERVE_OPFILTER flag createoptions consente a un'applicazione di richiedere un oplock di livello 1, batch o filtro per impedire che altre applicazioni ottengano violazioni di condivisione. Tuttavia, FILE_RESERVE_OPFILTER è praticamente utile solo per gli 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 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 interrompere ancora un oplock di filtro. Tuttavia, qualsiasi DesiredAccess maggiore di FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE interrompe un oplock di livello 1 o Batch e rende il flag di FILE_RESERVE_OPFILTER inutilizzabile per tali tipi di oplock.

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

Per il flag FILE_OPEN_BY_FILE_ID CreateOptions , un nome di dispositivo di esempio avrà il formato:

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

dove FileID è di 8 byte e ObjectID è di 16 byte:

In NTFS, può essere un numero di riferimento a 8 byte o a 16 byte o UN ID oggetto. Un numero di riferimento a 16 byte è uguale a un numero a 8 byte riempito con zeri.
In ReFS, può essere un numero di riferimento a 8 byte o a 16 byte. Un numero a 16 byte non è correlato a un numero a 8 byte. Gli ID oggetto non sono supportati.
I file system FAT, ExFAT, UDFS e CDFS non supportano il flag FILE_OPEN_BY_FILE_ID.

Questo numero viene assegnato da e specifico al file system specifico. Poiché il campo filename conterrà parzialmente un BLOB binario, non è corretto presupporre che si tratti di una stringa Unicode valida e, soprattutto, potrebbe non essere una stringa con terminazione Null.

I chiamanti di NtCreateFile devono essere in esecuzione in IRQL = PASSIVE_LEVEL e con API kernel speciali abilitate.

Nota

Se la chiamata a questa funzione viene eseguita in modalità utente, è necessario usare il nome "NtCreateFile" anziché "ZwCreateFile".

Per le chiamate da driver in modalità kernel, le NtXxx e ZwXxx versioni di una routine di Windows Native System Services possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000
piattaforma di destinazione	Universale
intestazione	ntifs.h (include Wdm.h, Ntddk.h, Ntifs.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)
regole di conformità DDI	HwStorPortProhibitedDDIs, PowerIrpDDis