CREATEFILE2_EXTENDED_PARAMETERS struttura (fileapi.h)
Contiene parametri estesi facoltativi per CreateFile2.
Sintassi
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
Members
dwSize
Contiene le dimensioni di questa struttura, sizeof(CREATEFILE2_EXTENDED_PARAMETERS).
dwFileAttributes
Gli attributi e i flag del file o del dispositivo FILE_ATTRIBUTE_NORMAL il valore predefinito più comune per i file.
Questo parametro può includere qualsiasi combinazione degli attributi di file disponibili (FILE_ATTRIBUTE_*). Tutti gli altri attributi di file sostituiscono FILE_ATTRIBUTE_NORMAL.
Nota
Quando CreateFile2 apre un file esistente, in genere combina i flag di file con gli attributi di file del file esistente e ignora gli attributi di file forniti come parte di dwFlagsAndAttributes. I casi speciali sono dettagliati in Creazione e apertura di file.
Alcuni degli attributi e dei flag di file seguenti possono essere applicati solo ai file e non necessariamente a tutti gli altri tipi di dispositivi che CreateFile2 possono aprire. Per altre informazioni, vedere la sezione Osservazioni della pagina di CreateFile2 riferimento e creazione e apertura di file.
Per un accesso più avanzato agli attributi di file, vedere SetFileAttributes. Per un elenco completo di tutti gli attributi di file con i relativi valori e descrizioni, vedere Costanti attributo file.
| Attributo | Significato |
|---|---|
|
Il file deve essere archiviato. Le applicazioni usano questo attributo per contrassegnare i file per il backup o la rimozione. |
|
Il file o la directory è crittografato. Per un file, questo significa che tutti i dati del file sono crittografati. Per una directory, ciò significa che la crittografia è l'impostazione predefinita per i file appena creati e le sottodirectory. Per altre informazioni, vedere Crittografia file.
Questo flag non ha alcun effetto se è specificato anche FILE_ATTRIBUTE_SYSTEM . Questo flag non è supportato nelle edizioni Home, Home Premium, Starter o ARM di Windows. Questo flag non è supportato quando viene chiamato da un'app di Windows Store. |
|
Il file è nascosto. Non includerlo in un elenco di directory normale. |
|
File o directory configurati con integrità. Per un file, tutti i flussi di dati nel file hanno integrità. Per una directory, l'integrità è l'impostazione predefinita per i file appena creati e le sottodirectory, a meno che il chiamante non specifichi altrimenti.
Questo flag è supportato solo nel file system ReFS. |
|
Il file non ha altri attributi impostati. Questo attributo è valido solo se usato da solo. |
|
I dati di un file non sono immediatamente disponibili. Questo attributo indica che i dati dei file vengono spostati fisicamente nell'archiviazione offline. Questo attributo viene usato da Archiviazione remota, il software di gestione dell'archiviazione gerarchica. Le applicazioni non devono modificare arbitrariamente questo attributo. |
|
Il file è di sola lettura. Le applicazioni possono leggere il file, ma non possono scrivere o eliminarle. |
|
Il file fa parte o viene usato esclusivamente da un sistema operativo. |
|
Il file viene usato per l'archiviazione temporanea.
Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento. |
dwFileFlags
Questo parametro può contenere combinazioni di flag (FILE_FLAG_*) per il controllo del comportamento del file o della memorizzazione nella cache dei dispositivi, delle modalità di accesso e di altri flag a scopo speciale.
| Flag | Significato |
|---|---|
|
Il file viene aperto o creato per un'operazione di backup o ripristino. Il sistema garantisce che il processo chiamante esegue l'override della sicurezza dei file quando il processo ha SE_BACKUP_NAME e SE_RESTORE_NAME privilegi. Per altre informazioni, vedere Modifica dei privilegi in un token.
È necessario impostare questo flag per ottenere un handle in una directory. Un handle di directory può essere passato a alcune funzioni anziché a un handle di file. Per altre informazioni, vedere la sezione Osservazioni. |
|
Il file deve essere eliminato immediatamente dopo la chiusura di tutti i relativi handle, inclusi l'handle specificato ed eventuali altri handle aperti o duplicati.
Se sono presenti handle aperti esistenti in un file, la chiamata non riesce a meno che non siano state aperte tutte con la modalità di condivisione FILE_SHARE_DELETE . Le successive richieste aperte per il file hanno esito negativo a meno che non venga specificata la modalità di condivisione FILE_SHARE_DELETE. |
|
Una mappa dei dispositivi è un mapping tra i nomi dei dispositivi DOS e i dispositivi nel sistema e viene usato durante la risoluzione dei nomi DOS. Le mappe dei dispositivi separate esistono per ogni utente nel sistema e gli utenti possono gestire le proprie mappe dei dispositivi. In genere durante la rappresentazione, verrà usata la mappa del dispositivo dell'utente rappresentata. Tuttavia, quando questo flag è impostato, viene usata invece la mappa del dispositivo dell'utente del processo. |
|
Il file o il dispositivo viene aperto senza memorizzazione nella cache del sistema per le letture e le scritture dei dati. Questo flag non influisce sulla memorizzazione nella cache del disco rigido o sui file mappati alla memoria.
Esistono requisiti rigorosi per l'uso corretto dei file aperti con CreateFile2 usando il flag FILE_FLAG_NO_BUFFERING , per informazioni dettagliate, vedere Buffering file. |
|
I dati del file vengono richiesti, ma devono continuare a trovarsi nell'archiviazione remota. Non deve essere trasportato nuovamente all'archiviazione locale. Questo flag è usato dai sistemi di archiviazione remoti. |
|
L'elaborazione normale del punto di ripristino non si verificherà; CreateFile2 tenterà di aprire il punto di ripristino. Quando viene aperto un file, viene restituito un handle di file, indipendentemente dal fatto che il filtro che controlla il punto di ripristino sia operativo.
Questo flag non può essere usato con il flag CREATE_ALWAYS . Se il file non è un reparse point, questo flag viene ignorato. Per altre informazioni, vedere la sezione Osservazioni. |
|
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 ultimo codice di errore di ERROR_CANNOT_BREAK_OPLOCK se il risultato sarebbe interrompere un oplock esistente.
Se si usa questo flag e la chiamata alla funzione CreateFile2 viene restituita correttamente, la prima operazione da eseguire sull'handle di file consiste nel richiedere un oplock chiamando la funzione DeviceIOControl e quindi passare FSCTL_REQUEST_OPLOCK o una delle altre operazioni di blocco opportunistiche. Se si eseguono altre operazioni del file system con l'handle di file prima di richiedere un oplock, potrebbe verificarsi un deadlock. Nota È possibile chiamare in modo sicuro la funzione CloseHandle sull'handle di file senza prima richiedere un oplock.
|
|
Il file o il dispositivo viene aperto o creato per le operazioni di I/O asincrone.
Quando vengono completate le operazioni di I/O successive su questo handle, l'evento specificato nella struttura OVERLAPPED verrà impostato sullo stato segnalato. Se questo flag viene specificato, il file può essere usato per operazioni di lettura e scrittura simultanee. Se questo flag non viene specificato, le operazioni di I/O vengono serializzate, anche se le chiamate alle funzioni di lettura e scrittura specificano una struttura OVERLAPPED . Per informazioni sulle considerazioni relative all'uso di un handle di file creato con questo flag, vedere la sezione Handle di I/O sincroni e asincroni di questo argomento. |
|
L'accesso verrà eseguito in base alle regole POSIX. Ciò include la possibilità di usare più file con nomi diversi solo nel caso, per i file system che supportano tale denominazione. Prestare attenzione quando si usa questa opzione, perché i file creati con questo flag potrebbero non essere accessibili dalle applicazioni scritte per MS-DOS o Windows a 16 bit. |
|
L'accesso deve essere casuale. Il sistema può interpretare questa situazione come hint per l'ottimizzazione della memorizzazione del file nella cache.
Questo flag non ha effetto se il file system non supporta le operazioni di I/O memorizzate nella cache e FILE_FLAG_NO_BUFFERING. Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento. |
|
Il file o il dispositivo viene aperto con consapevolezza della sessione. Se questo flag non viene specificato, non è possibile aprire i dispositivi per sessione, ad esempio un dispositivo che usa il reindirizzamento USB RemoteFX, tramite 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.
Windows Server 2008 R2 e Windows Server 2008: Questo flag non è supportato prima di Windows Server 2012. |
|
L'accesso deve essere sequenziale dall'inizio alla fine. Il sistema può interpretare questa situazione come hint per l'ottimizzazione della memorizzazione del file nella cache.
Questo flag non deve essere usato se verrà usato read-behind (ovvero le analisi all'indietro). Questo flag non ha effetto se il file system non supporta le operazioni di I/O memorizzate nella cache e FILE_FLAG_NO_BUFFERING. Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento. |
|
Le operazioni di scrittura non passeranno attraverso alcuna cache intermedia, che passeranno direttamente al disco.
Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento. |
dwSecurityQosFlags
Il parametro dwSecurityQosFlags specifica le informazioni SQOS. Per altre informazioni, vedere Livelli di rappresentazione.
lpSecurityAttributes
Puntatore a una struttura SECURITY_ATTRIBUTES che contiene due membri dati separati ma correlati: un descrittore di sicurezza facoltativo e un valore booleano che determina se l'handle restituito può essere ereditato dai processi figlio.
Questo parametro può essere NULL.
Se questo parametro è NULL, l'handle restituito da CreateFile2 non può essere ereditato da eventuali processi figlio che l'applicazione può creare e il file o il dispositivo associato all'handle restituito ottiene un descrittore di sicurezza predefinito.
Il membro lpSecurityDescriptor della struttura specifica un SECURITY_DESCRIPTOR per un file o un dispositivo. Se questo membro è NULL, al file o al dispositivo associato all'handle restituito viene assegnato un descrittore di sicurezza predefinito.
CreateFile2 ignora il membro lpSecurityDescriptor quando si apre un file o un dispositivo esistente, ma continua a usare il membro bInheritHandle .
Il membro bInheritHandle della struttura specifica se l'handle restituito può essere ereditato.
Per altre informazioni, vedere la sezione Osservazioni dell'argomento CreateFile2 .
hTemplateFile
Handle valido per un file modello con il diritto di accesso GENERIC_READ . Il file modello fornisce attributi di file e attributi estesi per il file in fase di creazione.
Questo parametro può essere NULL.
Quando si apre un file esistente, CreateFile2 ignora questo parametro.
Quando si apre un nuovo file crittografato, il file eredita l'elenco di controllo di accesso discrezionale dalla directory padre. Per altre informazioni, vedere Crittografia file.
Commenti
Per compilare un'applicazione che usa la struttura CREATEFILE2_EXTENDED_PARAMETERS , definire la macro _WIN32_WINNT come 0x0602 o versione successiva. Per altre informazioni, vedere Uso delle intestazioni di Windows.
Comportamento di memorizzazione nella cache
Diversi valori possibili per il membro dwFileFlags vengono usati per controllare o influire sulla modalità di memorizzazione dei dati associati all'handle dal sistema. ovvero:
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Se nessuno di questi flag viene specificato, il sistema usa uno schema di memorizzazione nella cache per utilizzo generico predefinito. In caso contrario, la memorizzazione nella cache del sistema si comporta come specificato per ogni flag.
Alcuni di questi flag non devono essere combinati. Ad esempio, la combinazione di FILE_FLAG_RANDOM_ACCESS con FILE_FLAG_SEQUENTIAL_SCAN è auto-sconfitta.
La specifica del flag FILE_FLAG_SEQUENTIAL_SCAN può migliorare le prestazioni per le applicazioni che leggono file di grandi dimensioni usando l'accesso sequenziale. I miglioramenti delle prestazioni possono essere ancora più evidenti per le applicazioni che leggono file di grandi dimensioni principalmente in sequenza, ma occasionalmente saltano avanti su intervalli ridotti di byte. Se un'applicazione sposta il puntatore di file per l'accesso casuale, è probabile che non si verifichino prestazioni ottimali di memorizzazione nella cache. Tuttavia, l'operazione corretta è comunque garantita.
I flag FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING sono indipendenti e possono essere combinati.
Se FILE_FLAG_WRITE_THROUGH viene usato ma non viene specificato FILE_FLAG_NO_BUFFERING, in modo che la memorizzazione nella cache del sistema sia effettiva, i dati vengono scritti nella cache di sistema ma vengono scaricati su disco senza ritardo.
Se FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING sono entrambi specificati, in modo che la memorizzazione nella cache del sistema non sia effettiva, i dati vengono immediatamente scaricati su disco senza passare dalla cache del sistema Windows. Il sistema operativo richiede anche un write-through della cache hardware locale del disco rigido per supporti persistenti.
Nota
Non tutti gli hardware del disco rigido supportano questa funzionalità di scrittura.
L'uso appropriato del flag di FILE_FLAG_NO_BUFFERING richiede considerazioni speciali sull'applicazione. Per altre informazioni, vedere Buffering file.
Una richiesta di scrittura tramite FILE_FLAG_WRITE_THROUGH causa anche lo scaricamento di eventuali modifiche ai metadati, ad esempio un aggiornamento del timestamp o un'operazione di ridenominazione, che comporta l'elaborazione della richiesta. Per questo motivo, il flag di FILE_FLAG_WRITE_THROUGH viene spesso usato con il flag FILE_FLAG_NO_BUFFERING come sostituzione per chiamare la funzione FlushFileBuffers dopo ogni scrittura, che può causare penali per le prestazioni non necessarie. L'uso di questi flag consente di evitare tali sanzioni. Per informazioni generali sulla memorizzazione nella cache dei file e dei metadati, vedere Memorizzazione nella cache dei file.
Quando FILE_FLAG_NO_BUFFERING viene combinato con FILE_FLAG_OVERLAPPED, i flag offrono prestazioni asincrone massime, perché l'I/O non si basa sulle operazioni sincrone della gestione memoria. Tuttavia, alcune operazioni di I/O richiedono più tempo, perché i dati non vengono mantenuti nella cache. Inoltre, i metadati dei file possono comunque essere memorizzati nella cache, ad esempio durante la creazione di un file vuoto. Per assicurarsi che i metadati vengano scaricati su disco, usare la funzione FlushFileBuffers .
Se è disponibile una memoria di cache sufficiente, l'attributo FILE_ATTRIBUTE_TEMPORARY causa l'eliminazione di un file system temporaneo dopo la chiusura di un handle. In tal caso, il sistema può evitare completamente di scrivere i dati. Anche se non controlla direttamente la memorizzazione nella cache dei dati nello stesso modo dei flag menzionati in precedenza, l'attributo FILE_ATTRIBUTE_TEMPORARY indica al sistema di conservare il più possibile nella cache di sistema senza scrivere e pertanto può essere di preoccupazione per determinate applicazioni.
Handle di I/O sincroni e sincroni
CreateFile2 fornisce la creazione di un handle di file o dispositivo sincrono o asincrono. Un handle sincrono si comporta in modo che le chiamate di funzione di I/O usando tale handle vengano bloccate fino al completamento, mentre un handle di file asincrono consente al sistema di restituire immediatamente dalle chiamate di funzione I/O, indipendentemente dal completamento dell'operazione di I/O o. Come indicato in precedenza, questo comportamento sincrono o asincrono viene determinato specificando FILE_FLAG_OVERLAPPED all'interno del membro dwFileFlags della struttura CREATEFILE2_EXTENDED_PARAMETERS passata nel parametro pCreateExParams . Esistono diverse complessità e potenziali insodenze durante l'uso di I/O asincrone; per altre informazioni, vedere I/O sincrona e asincrona.
Requisiti
| Client minimo supportato | Windows 8 [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2012 [app desktop | App UWP] |
| Intestazione | fileapi.h (includere Windows.h) |