struttura CREATEFILE2_EXTENDED_PARAMETERS (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;
Membri
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 essere il valore predefinito più comune per i file.
Questo parametro può includere qualsiasi combinazione degli attributi del 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 descritti in dettaglio 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 essere aperti. Per altre informazioni, vedere la sezione
Per l'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, ciò significa che tutti i dati nel file vengono crittografati. Per una directory, significa che la crittografia è l'impostazione predefinita per i file e le sottodirectory appena creati. Per altre informazioni, vedere File Encryption.
Questo flag non ha alcun effetto se viene 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 e le sottodirectory appena creati, a meno che il chiamante non specifichi diversamente.
Questo flag è supportato solo nel file system ReFS. |
|
Il file non dispone di 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 gerarchica delle risorse di archiviazione. Le applicazioni non devono modificare arbitrariamente questo attributo. |
|
Il file è di sola lettura. Le applicazioni possono leggere il file, ma non possono scriverlo o eliminarlo. |
|
Il file fa parte o viene utilizzato esclusivamente da un sistema operativo. |
|
Il file viene usato per l'archiviazione temporanea.
Per altre informazioni, vedere la sezione comportamento di memorizzazione nella cache |
dwFileFlags
Questo parametro può contenere combinazioni di flag (FILE_FLAG_*) per il controllo del comportamento di memorizzazione nella cache dei file o dei dispositivi, delle modalità di accesso e di altri flag speciali.
| Bandiera | Significato |
|---|---|
|
Il file viene aperto o creato per un'operazione di backup o ripristino. Il sistema garantisce che il processo chiamante sostituisa i controlli di 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 su una directory. Un handle di directory può essere passato ad 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, che include l'handle specificato e qualsiasi altro handle aperto o duplicato.
Se sono presenti handle aperti esistenti in un file, la chiamata ha esito negativo a meno che non siano state tutte aperte 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 per la risoluzione dei nomi DOS. Esistono mappe dei dispositivi separate per ogni utente del sistema e gli utenti possono gestire le proprie mappe dei dispositivi. In genere, durante la rappresentazione, verrà usata la mappa del dispositivo dell'utente rappresentato. Tuttavia, quando questo flag è impostato, viene usata 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 di FILE_FLAG_NO_BUFFERING, per informazioni dettagliate, vedere File Buffering. |
|
I dati del file vengono richiesti, ma devono continuare a trovarsi nell'archiviazione remota. Non deve essere trasportato nuovamente nella risorsa di archiviazione locale. Questo flag è destinato all'uso da parte di sistemi di archiviazione remoti. |
|
Non si verificherà normale punto di analisi; CreateFile2 tenterà di aprire il reparse point. Quando un file viene aperto, viene restituito un handle di file, indipendentemente dal fatto che il filtro che controlla il punto di analisi sia operativo.
Questo flag non può essere utilizzato 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 |
|
Il file o il dispositivo viene aperto o creato per l'I/O asincrono.
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 l'uso di 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 windows a MS-DOS o a 16 bit. |
|
L'accesso deve essere casuale. Il sistema può usarlo come suggerimento per ottimizzare la memorizzazione nella cache dei file.
Questo flag non ha alcun 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 |
|
Il file o il dispositivo viene aperto con consapevolezza della sessione. Se questo flag non viene specificato, i dispositivi per sessione (ad esempio un dispositivo che usa il reindirizzamento USB RemoteFX) non possono essere aperti dai processi in esecuzione nella sessione 0. Questo flag non ha alcun effetto per i chiamanti non nella sessione 0. Questo flag è supportato solo nelle edizioni server di Windows.
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ò usarlo come suggerimento per ottimizzare la memorizzazione nella cache dei file.
Questo flag non deve essere usato se verrà usato read-behind (ovvero le analisi all'indietro). Questo flag non ha alcun 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 |
|
Le operazioni di scrittura non passeranno attraverso alcuna cache intermedia, verranno passate direttamente al disco.
Per altre informazioni, vedere la sezione |
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 alcun processo figlio che l'applicazione può creare e il file o il dispositivo associato all'handle restituito ottiene un descrittore di sicurezza predefinito.
Il lpSecurityDescriptor membro 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.
Il bInheritHandle membro 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.
Osservazioni
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 dwFileFlags membro vengono usati per controllare o influire sul modo in cui i dati associati all'handle vengono memorizzati nella cache dal sistema. Sono:
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Se nessuno di questi flag è 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 di 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 ignorano in avanti su intervalli di byte di piccole dimensioni. Se un'applicazione sposta il puntatore al file per l'accesso casuale, le prestazioni di memorizzazione nella cache ottimali probabilmente non si verificheranno. 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 attiva, i dati vengono scritti nella cache di sistema ma scaricati su disco senza ritardi.
Se FILE_FLAG_WRITE_THROUGH e FILE_FLAG_NO_BUFFERING vengono specificati entrambi, in modo che la memorizzazione nella cache del sistema non sia attiva, i dati vengono scaricati immediatamente su disco senza passare attraverso la cache di sistema di Windows. Il sistema operativo richiede inoltre un write-through della cache hardware locale del disco rigido a supporti persistenti.
Nota
Non tutti gli hardware del disco rigido supportano questa funzionalità di scrittura.
L'uso corretto del flag di FILE_FLAG_NO_BUFFERING richiede considerazioni speciali sull'applicazione. Per altre informazioni, vedere file buffering.
Una richiesta write-through tramite FILE_FLAG_WRITE_THROUGH fa anche in modo che NTFS scarichi tutte le modifiche ai metadati, ad esempio un aggiornamento timestamp o un'operazione di ridenominazione, risultante dall'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 inutili sanzioni per le prestazioni. L'uso di questi flag insieme evita 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 della memoria. Tuttavia, alcune operazioni di I/O richiedono più tempo, perché i dati non vengono mantenuti nella cache. Inoltre, i metadati del file possono essere ancora memorizzati nella cache, ad esempio durante la creazione di un file vuoto. Per assicurarsi che i metadati vengano scaricati su disco, usare la funzione
Se si specifica l'attributo FILE_ATTRIBUTE_TEMPORARY, i file system evitano di scrivere i dati nell'archiviazione di massa se è disponibile memoria cache sufficiente, perché un'applicazione elimina un file 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 asincroni
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 che usano tale handle vengano bloccate fino al completamento, mentre un handle di file asincrono consente al sistema di restituire immediatamente dalle chiamate di funzione di I/O, indipendentemente dal fatto che abbiano completato o meno l'operazione di I/O. Come indicato in precedenza, questo comportamento sincrono e asincrono viene determinato specificando FILE_FLAG_OVERLAPPED all'interno del dwFileFlags membro della struttura CREATEFILE2_EXTENDED_PARAMETERS passata nel parametro pCreateExParams. Esistono diverse complessità e potenziali insidie quando si usa l'I/O asincrona; Per altre informazioni, vedere I/O sincrona e asincrona .
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 8 [app desktop | App UWP] |
| server minimo supportato | Windows Server 2012 [app desktop | App UWP] |
| intestazione |
fileapi.h (include Windows.h) |