Funzione IoCreateFileSpecifyDeviceObjectHint (ntddk.h)

Articolo
03/08/2023

La routine IoCreateFileSpecifyDeviceObjectHint viene usata dai driver di filtro del file system per inviare una richiesta di creazione solo ai filtri seguenti di un oggetto dispositivo specificato e al file system.

Sintassi

NTSTATUS IoCreateFileSpecifyDeviceObjectHint(
  [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] PVOID              DeviceObject
);

Parametri

[out] FileHandle

Puntatore a una variabile che riceve un handle per l'oggetto file se questa chiamata ha esito positivo.

[in] DesiredAccess

Maschera di flag che specificano il tipo di accesso richiesto dal chiamante al file o alla directory. Il set di flag DesiredAccess definiti dal sistema determina i diritti di accesso specifici seguenti 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 in un secondo momento, possono essere letti.
FILE_READ_EA	Gli attributi estesi (EA) 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 attributi estesi 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.

I chiamanti di IoCreateFileSpecifyDeviceObjectHint possono specificare una o una combinazione delle seguenti, possibilmente ORed con flag compatibili aggiuntivi dall'elenco precedente di flagDesiredAccess , per qualsiasi oggetto file che non rappresenta un file di directory:

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

La STANDARD_RIGHTS_XXX sono valori di sistema predefiniti usati per applicare la sicurezza agli oggetti di sistema.

Se il flag FILE_DIRECTORY_FILE CreateOptions è impostato, i chiamanti di IoCreateFileSpecifyDeviceObjectHint possono specificare una o una combinazione dei flag seguenti, possibilmente ORed con uno o più flag compatibili dall'elenco precedente di flagDesiredAccess .

DesiredAccess 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 (ObjectAttributes) può essere NULL. In caso contrario, il chiamante deve impostare l'attributo OBJ_KERNEL_HANDLE nella chiamata alla routine InitializeObjectAttributes . I membri della struttura OBJECT_ATTRIBUTES per un oggetto file includono quanto segue.

Membro	Valore
ULONGLength	Specifica il 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 che denomina il 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, a condizione che il driver floppy e il file system overlying siano già caricati. Si noti che \?? sostituisce \DosDevices come nome dello spazio dei nomi dell'oggetto Win32. \DosDevices funzionerà ancora, ma \?? viene tradotto più velocemente dal gestore oggetti.
HANDLERootDirectory	Facoltativamente specifica un handle in una directory ottenuta da una chiamata precedente a IoCreateFileSpecifyDeviceObjectHint. 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	Facoltativamente, specifica un descrittore di sicurezza 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.
ULONGAttributes	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 di OBJ_CASE_INSENSITIVE, che indica che il codice di ricerca dei nomi deve ignorare il caso di ObjectName anziché eseguire una ricerca di corrispondenza esatta.

[out] IoStatusBlock

Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e informazioni sull'operazione richiesta. In ritorno da IoCreateFileSpecifyDeviceObjectHint, il membro Information 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 ORed 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	È necessario creare un file di sola lettura.
FILE_ATTRIBUTE_HIDDEN	È necessario creare 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	È necessario creare un file temporaneo.

[in] ShareAccess

Specifica il tipo di accesso alla condivisione al file che il chiamante desidera, come zero, o uno o una combinazione dei flag seguenti. Per richiedere l'accesso esclusivo, impostare questo parametro su zero. Se il flag IO_IGNORE_SHARE_ACCESS_CHECK viene specificato nel parametro Options , il gestore di I/O ignora questo parametro. 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 IO_IGNORE_SHARE_ACCESS_CHECK. Per la massima probabilità di 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 da altri thread.
FILE_SHARE_WRITE	Il file può essere aperto per l'accesso in scrittura da altri thread.
FILE_SHARE_DELETE	Il file può essere aperto per l'eliminazione dell'accesso da parte di altri thread.

[in] Disposition

Specifica un valore che determina l'azione da eseguire, a seconda che il file esista già. Il valore può essere uno di quelli descritti di seguito.

Valori di eliminazione	Significato
FILE_SUPERSEDE	Se il file esiste già, sostituirlo con il file specificato. In caso contrario, creare il file specificato.
FILE_CREATE	Se il file esiste già, non eseguire la richiesta e non creare o aprire il file specificato. In caso contrario, creare il file specificato.
FILE_OPEN	Se il file esiste già, aprirlo invece di creare un nuovo file. In caso contrario, la richiesta non riesce e non crea un nuovo file.
FILE_OPEN_IF	Se il file esiste già, aprirlo. In caso contrario, creare il file specificato.
FILE_OVERWRITE	Se il file esiste già, aprirlo e sovrascriverlo. In caso contrario, non eseguire la richiesta.
FILE_OVERWRITE_IF	Se il file esiste già, aprirlo e sovrascriverlo. In caso contrario, creare il file specificato.

[in] CreateOptions

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

Flag CreateOptions	Significato
FILE_DIRECTORY_FILE	Il file creato o aperto è un file di directory. Se questo flag è impostato, il parametro Disposition deve essere impostato su uno dei FILE_CREATE, FILE_OPEN o FILE_OPEN_IF. Questo flag è compatibile con i flag CreateOptions seguenti: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT e FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE	Il file da aprire non deve essere un file di directory o questa chiamata avrà esito negativo. L'oggetto file aperto deve rappresentare un file di dati.
FILE_WRITE_THROUGH	I servizi di sistema, gli FSD e i driver che scrivono dati nel file devono effettivamente trasferire i dati nel file prima che venga considerata completata qualsiasi operazione di scrittura richiesta.
FILE_SEQUENTIAL_ONLY	Tutti gli accessi al file saranno sequenziali.
FILE_RANDOM_ACCESS	Gli accessi al file possono essere casuali, quindi non devono essere eseguite operazioni di lettura-ahead sequenziali sul file da fsd o dal sistema.
FILE_NO_INTERMEDIATE_BUFFERING	Il file non può essere memorizzato nella cache o memorizzato nel buffer interno di un driver. Questo flag non è compatibile con il flag FILE_APPEND_DATA DesiredAccess .
FILE_SYNCHRONOUS_IO_ALERT	Tutte le operazioni sul file vengono eseguite in modo sincrono. Qualsiasi attesa per conto del chiamante è soggetta a terminazione prematura dagli avvisi. Questo flag determina anche che il sistema di I/O mantenga il contesto di posizione del file. Se questo flag è impostato, è necessario impostare anche il flag DesiredAccess SYNCHRONIZE.
FILE_SYNCHRONOUS_IO_NONALERT	Tutte le operazioni sul file vengono eseguite in modo sincrono. Le attese presenti nel sistema per sincronizzare l'accodamento e il completamento di I/O non sono soggetti ad avvisi. Questo flag determina anche che il sistema di I/O mantenga il contesto di posizione del file. Se questo flag è impostato, è necessario impostare anche il flag DesiredAccess SYNCHRONIZE.
FILE_CREATE_TREE_CONNECTION	Creare una connessione albero per questo file per aprirlo in rete.
FILE_COMPLETE_IF_OPLOCKED	Completare immediatamente questa operazione con un codice di esito positivo alternativo se il file di destinazione è bloccato, anziché bloccare il thread del chiamante. Se il file è bloccato, un altro chiamante ha già accesso al file in rete.
FILE_NO_EA_KNOWLEDGE	Se gli attributi estesi in un file esistente aperto indicano che il chiamante deve comprendere gli EA per interpretare correttamente il file, non eseguire questa richiesta perché il chiamante non riconosce come gestire gli EA.
FILE_OPEN_REPARSE_POINT	Aprire un file con un reparse point e ignorare la normale elaborazione dei punti di analisi per il file. Per altre informazioni, vedere la sezione Osservazioni di seguito.
FILE_DELETE_ON_CLOSE	Eliminare il file quando viene passato l'ultimo handle a ZwClose.
FILE_OPEN_BY_FILE_ID	Il nome file specificato nel parametro ObjectAttributes include il numero di riferimento del file a 8 byte per il file. Questo numero viene assegnato dal file system ed è specifico del file system. Se il file è un reparse point, il nome del file include anche il nome di un dispositivo. Nota: il file system FAT non supporta FILE_OPEN_BY_FILE_ID.
FILE_OPEN_FOR_BACKUP_INTENT	Il file viene aperto per finalità di backup, quindi il sistema deve verificare la presenza di determinati diritti di accesso e concedere al chiamante gli accessi appropriati al file prima di controllare l'input DesiredAccess nel descrittore di sicurezza del file.
FILE_OPEN_REQUIRING_OPLOCK	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 l'operazione di creazione ha esito negativo con un codice restituito di STATUS_CANNOT_BREAK_OPLOCK se la creazione interrompe un oplock esistente.
FILE_RESERVE_OPFILTER	Questo flag consente a un'applicazione di richiedere un blocco opportunistico del filtro (oplock) per impedire ad altre applicazioni di ricevere violazioni di condivisione. Se sono già presenti handle aperti, la richiesta di creazione ha esito negativo con STATUS_OPLOCK_NOT_GRANTED. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] EaBuffer

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

[in] EaLength

Lunghezza, in byte, di EaBuffer.

[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 utilizzare durante la creazione della richiesta di creazione. Nella tabella seguente sono elencate le opzioni disponibili.

Flag di opzioni	Significato
IO_FORCE_ACCESS_CHECK	Indica che il gestore di I/O deve controllare la richiesta di creazione rispetto al descrittore di sicurezza del file.
IO_IGNORE_SHARE_ACCESS_CHECK	Indica che il gestore di I/O non deve eseguire controlli di accesso alla condivisione sull'oggetto file dopo la creazione. Tuttavia, il file system potrebbe comunque eseguire questi controlli.

[in, optional] DeviceObject

Puntatore all'oggetto dispositivo a cui inviare la richiesta di creazione. L'oggetto dispositivo deve essere un oggetto dispositivo filtro o file system nello stack di driver del file system per il volume in cui risiede il file o la directory. Questo parametro è facoltativo e può essere NULL. Se questo parametro è NULL, la richiesta verrà inviata all'oggetto dispositivo nella parte superiore dello stack di driver.

Valore restituito

IoCreateFileSpecifyDeviceObjectHint restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	DeviceObject specificato non è collegato allo stack di driver del file system per il volume specificato nel nome del file o della directory. Questo errore può verificarsi anche se il nome contiene un punto reparse diverso da un punto di montaggio.
STATUS_MOUNT_POINT_NOT_RESOLVED	Il nome del file o della directory contiene un punto di montaggio che si risolve in un volume diverso da quello a cui è collegato l'oggetto DeviceObject specificato.
STATUS_OBJECT_PATH_SYNTAX_BAD

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

Commenti

Questa routine viene utilizzata dai driver di filtro del file system per inviare una richiesta di creazione solo ai filtri seguenti a un oggetto dispositivo specificato e al file system. I filtri collegati sopra l'oggetto dispositivo specificato nello stack di driver non ricevono la richiesta di creazione.

La routine Windows Vista IoCreateFileEx è simile alla routine IoCreateFileSpecifyDeviceObjectHint , ma offre una maggiore funzionalità rispetto alla routine IoCreateFileSpecifyDeviceObjectHint , incluso l'accesso a parametri di creazione aggiuntivi e informazioni sulle transazioni.

Se si usa la routine IoCreateFileEx anziché la routine IoCreateFileSpecifyDeviceObjectHint , si noti che il parametro DriverContext della routine IoCreateFileSpecifyDeviceObjectHint è stato spostato nel membro DeviceObjectHint della struttura IO_DRIVER_CREATE_CONTEXT . La struttura IO_DRIVER_CREATE_CONTEXT viene passata alla routine IoCreateFileEx tramite il relativo parametro DriverContext .

I driver di filtro del file system chiamano IoCreateFileSpecifyDeviceObjectHint per inviare una richiesta di creazione solo a un oggetto dispositivo specificato, ai filtri collegati sotto di esso e al file system. I filtri collegati sopra l'oggetto dispositivo specificato nello stack di driver non ricevono la richiesta di creazione. Lo stesso vale per tutte le richieste di pulizia o chiusura sull'oggetto file creato da IoCreateFileSpecifyDeviceObjectHint.

Esistono due modi alternativi per specificare il nome del file da creare o aprire usando IoCreateFileSpecifyDeviceObjectHint:

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

Qualsiasi handle ottenuto da IoCreateFileSpecifyDeviceObjectHint deve essere rilasciato chiamando ZwClose.

Le routine 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 IoCreateFileSpecifyDeviceObjectHint. Ciò limita l'uso dell'handle restituito da IoCreateFileSpecifyDeviceObjectHint ai processi in esecuzione in modalità kernel. In caso contrario, l'handle può essere accessibile dal processo nel cui contesto è in esecuzione il driver.

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

Affinché un chiamante sincronizzi un completamento di I/O attende che il fileHandle restituito venga impostato sullo stato Segnalato, è necessario impostare il flag SYNCHRONIZE.
Se vengono impostati solo i flag FILE_APPEND_DATA e SYNCHRONIZE, il chiamante può scrivere solo alla fine del file e tutte le informazioni di offset sulle 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 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 SYNCHRONIZE, il chiamante 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 istruzioni e agli accessi ai dati.

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

Affinché un file condiviso venga aperto correttamente, l'oggetto DesiredAccess richiesto al file deve essere compatibile con le specifiche DesiredAccess e ShareAccess di tutte le aperte precedenti che non sono ancora state rilasciate con ZwClose. Ovvero, desiredAccess specificato in IoCreateFileSpecifyDeviceObjectHint per un determinato file non deve essere in conflitto con gli accessi non consentiti da altri opener del file.

Se IO_IGNORE_SHARE_ACCESS_CHECK viene specificato nel parametro Options , il gestore di 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 IO_IGNORE_SHARE_ACCESS_CHECK.

Il valore Disposition FILE_SUPERSEDE richiede che il chiamante disponga dell'accesso DELETE a un oggetto file esistente. In tal caso, una chiamata a IoCreateFileSpecifyDeviceObjectHint con FILE_SUPERSEDE in un file esistente elimina effettivamente tale file e quindi la 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 Disposition FILE_OVERWRITE_IF e FILE_SUPERSEDE sono simili. Se IoCreateFileSpecifyDeviceObjectHint 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 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 IoCreateFileSpecifyDeviceObjectHint non può disabilitare i flag FileAttributes esistenti, ma può abilitare flag aggiuntivi per lo stesso file.

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 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 Disposition incoerente, la chiamata a IoCreateFileSpecifyDeviceObjectHint avrà 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 zw.. Routine di file , tra cui le seguenti:

Qualsiasi valore offset di byte passato a ZwReadFile o ZwWriteFile deve essere un multiplo delle dimensioni del settore del dispositivo sottostante.
La lunghezza passata a ZwReadFile 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 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. Queste informazioni possono essere ottenute chiamando IoCreateFileSpecifyDeviceObjectHint 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_ALIGNMENT di sistema, vedere DEVICE_OBJECT.
Le chiamate a ZwSetInformationFile con il parametro FileInformationClass impostato su FilePositionInformation devono specificare un offset che corrisponde a un multiplo delle dimensioni del settore.

L'opzione CreateOptions, FILE_SYNCHRONOUS_IO_ALERT e FILE_SYNCHRONOUS_IO_NONALERT che si escludono a vicenda, specificare che tutte le operazioni di I/O sul file devono essere sincrone purché 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. Con una di queste opzioni CreateOptions, il flag DesiredAccess SYNCHRONIZE deve essere impostato in modo che Gestione I/O usi l'oggetto file come oggetto di sincronizzazione. Con uno di questi set CreateOptions , Gestione I/O mantiene il "contesto di posizione file" per l'oggetto file, un offset interno e corrente della posizione del file. Questo offset può essere usato nelle chiamate a ZwReadFile e ZwWriteFile. La sua posizione può essere eseguita anche chiamando ZwQueryInformationFile o chiamando ZwSetInformationFile.

Se il flag CreateOptions FILE_OPEN_REPARSE_POINT non è specificato e IoCreateFileSpecifyDeviceObjectHint tenta di aprire un file con un punto di reparse, viene eseguita la normale elaborazione dei punti di analisi per il file. Se, d'altra parte, viene specificato il flag FILE_OPEN_REPARSE_POINT, la normale elaborazione del reparse non viene eseguita e IoCreateFileSpecifyDeviceObjectHint tenta di aprire direttamente il file di reparse point. In entrambi i casi, se l'operazione di apertura ha avuto esito positivo, IoCreateFileSpecifyDeviceObjectHint restituisce STATUS_SUCCESS; in caso contrario, la routine restituisce un codice di errore NTSTATUS. IoCreateFileSpecifyDeviceObjectHint 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 IoCreateFileSpecifyDeviceObjectHint 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 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 sistemi operativi Windows successivi. I file system Microsoft che implementano questo flag in Windows 7 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 completare la procedura seguente:

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à disponibili handle aperti, la richiesta di creazione avrà esito negativo con STATUS_OPLOCK_NOT_GRANTED e il successivo oplock richiesto avrà 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 contenente 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 oggetto 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.

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

Impossibile usare IoCreateFileSpecifyDeviceObjectHint per ottenere un handle in un volume.

Se il percorso del nome file passato a IoCreateFileSpecifyDeviceObjectHint contiene un punto reparse, il punto di ripristino deve essere risolto nello stesso volume in cui risiede il file o la directory. In caso contrario, viene restituito l'errore STATUS_INVALID_DEVICE_OBJECT_PARAMETER o STATUS_MOUNT_POINT_NOT_RESOLVED.

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