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 ai diritti di accesso standard definiti per tutti i tipi di oggetti, il chiamante può specificare uno dei diritti di accesso specifici seguenti; 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 (EAs) 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 del file. Questo flag è irrilevante per i driver intermedi e del dispositivo.
FILE_APPEND_DATA	Aggiungere dati al file.
FILE_EXECUTE	Usare il paging di sistema di I/O 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 diritti di accesso generico seguenti (diritti applicabili a tutti i tipi di oggetto, in cui il significato di ogni diritto di accesso generico è specifico per il 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" significa "esegue il mapping a" e non significa che il valore del diritto generico è "uguale a" il valore dell'OR bit per bit del relativo mapping dei diritti specifici. 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

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

Alcuni flag CreateOptions richiedono che determinati flag di accesso siano impostati in DesiredAccess quando viene chiamato NtCreateFile . Per questi dettagli, 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ò specificare anche i diritti di accesso generici seguenti.

Flag 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 Diritti di accesso.

[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 sovrascrive un file. Il chiamante specifica in genere FILE_ATTRIBUTE_NORMAL, che imposta gli attributi predefiniti. Per un elenco di flag FILE_ATTRIBUTE_XXX validi, 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 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 impostano in genere 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 della tabella seguente.

Valore CreateDisposition	Azione se il file esiste	Azione se il file non esiste
FILE_SUPERSEDE	Sostituire il file.	Create il file.
FILE_CREATE	Restituisce un errore.	Create il file.
FILE_OPEN	Open the file.	Restituisce un errore.
FILE_OPEN_IF	Open the file.	Create il file.
FILE_OVERWRITE	Aprire il file e sovrascriverlo.	Restituisce un errore.
FILE_OVERWRITE_IF	Aprire il file e sovrascriverlo.	Create 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 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 venga considerata completata 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 di FILE_APPEND_DATA del parametro DesiredAccess .
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 determina anche che il sistema di I/O mantenga il puntatore alla posizione del file. Se questo flag è impostato, il flag SYNC 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 agli avvisi. Questo flag determina inoltre che il sistema di I/O mantenga il contesto di posizione file. Se questo flag è impostato, il flag SYNC 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)	Create una connessione ad albero per questo file per aprirla tramite la rete. Questo flag non viene usato dai driver di dispositivo e intermedi.
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 è oplockato, anziché bloccare il thread del chiamante. Se il file è oplocked, un altro chiamante ha già accesso al file. Questo flag non viene usato dai driver di dispositivo e intermedi.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Se gli attributi estesi (EAs) per un file esistente aperto indicano che il chiamante deve comprendere EAs per 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 è necessario eseguire operazioni di lettura sequenziale dai driver del file system o dal sistema.
FILE_DELETE_ON_CLOSE (0x00001000)	Il sistema elimina il file quando l'ultimo handle del 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 del file specificato dal parametro ObjectAttributes include un numero di riferimento file binario a 8 byte o a 16 byte o ID oggetto per il file, a seconda del file system. Facoltativamente, un nome del dispositivo seguito da un carattere barra rovesciata può procedere con questi valori binari. Vedere Osservazioni per altri dettagli e un esempio.
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000)	Il file viene aperto per la finalità di backup. Pertanto, il sistema deve controllare determinati diritti di accesso e concedere al chiamante l'accesso appropriato al file, prima di controllare il parametro DesiredAccess sul 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 le operazioni di oplock prima di eseguire l'operazione di creazione e avrà esito negativo 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 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. 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 è a conoscenza della sessione e per ogni accesso alla sessione viene convalidato se necessario. Questo flag è disponibile a partire da Windows 8.
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.
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 di dispositivo e intermedi, questo parametro deve essere un puntatore NULL .

[in] EaLength

Per i driver di dispositivo e intermedi, 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. Nel secondo 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.

Commenti

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 Uso di file in un 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 pathname completo, fornito nel membro ObjectName dell'oggetto ObjectAttributes di input.
Come pathname relativo al file di directory rappresentato dall'handle nel membro RootDirectory di input ObjectAttributes.

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

Affinché un chiamante sincronizzi un completamento di I/O in attesa del fileHandle restituito, è 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 tutte le informazioni di offset sulle 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 l'oggetto FileHandle restituito. Ovvero, tutte le operazioni sul file si verificano 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 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 DesiredAccess devono essere compatibili con i flag DesiredAccess e ShareAccess di tutte le operazioni aperte precedenti che non sono ancora state rilasciate tramite . Ovvero , l'oggetto 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 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, ha aperto il file specificando un parametro ShareAccess con il flag FILE_SHARE_DELETE impostato. Si noti che questo tipo di eliminazione è coerente con lo stile POSIX dei file sovrascrivendo.

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 valore CreateOptions o CreateDisposition incoerente, 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, vengono applicate le restrizioni seguenti ai parametri del chiamante in altre routine ZwXxxFile .

Qualsiasi ByteOffset facoltativo passato a NtReadFile o NtWriteFile deve essere un multiplo delle dimensioni del settore.
La lunghezza passata 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 potrebbe 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 FILE_XXX_ALIGNMENT del sistema, vedere DEVICE_OBJECT.
Le chiamate a NtSetInformationFile con il parametro FileInformationClass impostato su FilePositionInformation devono specificare un offset che corrisponde a più 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 FileHandle restituito. 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 CreateOptions FILE_OPEN_REPARSE_POINT non è specificato e NtCreateFile tenta di aprire un file con un punto di correzione, viene eseguita la normale elaborazione dei punti di reparse 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 NtCreateFile tenta di aprire direttamente il file del punto di analisi. 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 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 NtCreateFile 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 il flag FILE_OPEN_REQUIRING_OPLOCK 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 della normale elaborazione di oplock. Analogamente, se la 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.

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 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 i blocchi 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 renderà inutile il flag FILE_RESERVE_OPFILTER per tali tipi di oplock.

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

Per il flag CreateOptions FILE_OPEN_BY_FILE_ID, 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 corrisponde 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 per il file system specifico. Poiché il campo nome file conterrà in parte 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 si verifica in modalità utente, è necessario usare il nome "NtCreateFile" anziché "ZwCreateFile".

Per le chiamate dai driver in modalità kernel, le versioni NtXxx e ZwXxx 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 Uso di nt e zw versioni delle routine di Servizi di sistema nativo.

Requisiti

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