Funzione CreateFile2 (fileapi.h)
Crea o apre un file o un dispositivo di I/O. I dispositivi di I/O usati più comunemente sono i seguenti: file, flusso di file, directory, disco fisico, volume, buffer della console, unità nastro, risorsa di comunicazione, mailslot e pipe. La funzione restituisce un handle che può essere usato per accedere al file o al dispositivo per vari tipi di I/O a seconda del file o del dispositivo e dei flag e degli attributi specificati.
Quando viene chiamato da un'app di Windows Store, CreateFile2 è semplificato. È possibile aprire solo file o directory all'interno delle directory ApplicationData.LocalFolder o Package.InstalledLocation. Non è possibile aprire named pipe o mailslot o creare file crittografati (FILE_ATTRIBUTE_ENCRYPTED).
Sintassi
HANDLE CreateFile2(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in] DWORD dwCreationDisposition,
[in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);
Parametri
[in] lpFileName
Nome del file o del dispositivo da creare o aprire.
Per informazioni sui nomi speciali dei dispositivi, vedere Definizione di un nome di dispositivo MS-DOS.
Per creare un flusso di file, specificare il nome del file, i due punti e quindi il nome del flusso. Per altre informazioni, vedere flussi di file.
[in] dwDesiredAccess
Accesso richiesto al file o al dispositivo, che può essere riepilogato come lettura, scrittura, entrambi o nessuno zero).
I valori usati più comunemente sono GENERIC_READ, GENERIC_WRITEo entrambi (GENERIC_READ | GENERIC_WRITE). Per altre informazioni, vedere diritti di accesso generico, diritti di accesso e sicurezza dei file, costanti per i diritti di accesso ai filee ACCESS_MASK.
Se questo parametro è zero, l'applicazione può eseguire query su determinati metadati, ad esempio file, directory o attributi del dispositivo senza accedere a tale file o dispositivo, anche se GENERIC_READ accesso sarebbe stato negato.
Non è possibile richiedere una modalità di accesso in conflitto con la modalità di condivisione specificata dal parametro dwShareMode in una richiesta aperta che dispone già di un handle aperto.
Per altre informazioni, vedere la sezione Osservazioni di questo argomento e Creazione e apertura di file.
[in] dwShareMode
Modalità di condivisione richiesta del file o del dispositivo, che può essere letta, scritta, entrambe, eliminate, tutte queste o nessuna (vedere la tabella seguente). Le richieste di accesso agli attributi o agli attributi estesi non sono interessate da questo flag.
Se questo parametro è zero e CreateFile2 ha esito positivo, il file o il dispositivo non può essere condiviso e non può essere aperto di nuovo fino alla chiusura dell'handle al file o al dispositivo. Per altre informazioni, vedere la sezione Osservazioni.
Non è possibile richiedere una modalità di condivisione in conflitto con la modalità di accesso specificata in una richiesta esistente con un handle aperto.
Per consentire a un processo di condividere un file o un dispositivo mentre un altro processo ha il file o il dispositivo aperto, usare una combinazione compatibile di uno o più dei valori seguenti. Per altre informazioni sulle combinazioni valide di questo parametro con il parametro dwDesiredAccess
[in] dwCreationDisposition
Azione da eseguire su un file o un dispositivo esistente o non esistente.
Per i dispositivi diversi dai file, questo parametro viene in genere impostato su OPEN_EXISTING.
Per altre informazioni, vedere la sezione Osservazioni.
Questo parametro deve essere uno dei valori seguenti, che non possono essere combinati:
[in, optional] pCreateExParams
Puntatore a una struttura CREATEFILE2_EXTENDED_PARAMETERS facoltativa.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle aperto per il file, il dispositivo, la named pipe o lo slot di posta elettronica specificati.
Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per ottenere informazioni estese sull'errore, chiamare GetLastError.
Osservazioni
Per compilare un'applicazione che usa la funzione CreateFile2, definire la macro _WIN32_WINNT come 0x0602 o versione successiva. Per altre informazioni, vedere Uso delle intestazioni di Windows.
CreateFile2 supporta l'interazione tra file e la maggior parte degli altri tipi di dispositivi e meccanismi di I/O disponibili per gli sviluppatori Windows. Questa sezione tenta di trattare i vari problemi che gli sviluppatori possono riscontrare quando si usano CreateFile2 in contesti diversi e con tipi di I/O diversi. Il testo tenta di utilizzare la parola file solo quando si fa riferimento specificamente ai dati archiviati in un file system effettivo. Tuttavia, alcuni usi di file possono fare riferimento in genere a un oggetto I/O che supporta meccanismi simili a file. Questo uso liberale del termine file è particolarmente diffuso nei nomi costanti e nei nomi dei parametri a causa dei motivi cronologici menzionati in precedenza.
Al termine dell'utilizzo dell'handle dell'oggetto restituito da
Alcuni file system, ad esempio il file system NTFS, supportano la compressione o la crittografia per singoli file e directory. Nei volumi con un file system montato con questo supporto, un nuovo file eredita gli attributi di compressione e crittografia della relativa directory.
Non è possibile utilizzare CreateFile2 per controllare la compressione, la decompressione o la decrittografia in un file o in una directory. Per altre informazioni, vedere Creazione e apertura di file, compressione e decompressione di file e crittografia dei file .
Se il lpSecurityAttributes membro della struttura di CREATEFILE2_EXTENDED_PARAMETERS passato nel parametro pCreateExParams è NULL, l'handle restituito da CreateFile2 non può essere ereditato da alcun processo figlio che l'applicazione può creare. Si applicano anche le informazioni seguenti relative a questo membro:
- Se la variabile membro bInheritHandle
non è FALSE , ovvero qualsiasi valore diverso da zero, l'handle può essere ereditato. Pertanto, è fondamentale inizializzare correttamente questo membro della struttura per FALSE se non si intende ereditare l'handle. - Gli elenchi di controllo di accesso (ACL) nel descrittore di sicurezza predefinito per un file o una directory vengono ereditati dalla directory padre.
- Il file system di destinazione deve supportare la sicurezza su file e directory per il membro lpSecurityDescriptor, che può essere determinato usando GetVolumeInformation.
| Tecnologia | Sostenuto |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| SMB 3.0 Transparent Failover (TFO) | No |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | No |
| Cluster Shared Volume File System (CsvFS) | Sì |
| Resilient File System (ReFS) | Sì |
comportamento del collegamento simbolico
Se la chiamata a questa funzione crea un file, non viene apportata alcuna modifica al comportamento. Considerare inoltre le informazioni seguenti relative al flag di FILE_FLAG_OPEN_REPARSE_POINT per il dwFileFlags membro della struttura CREATEFILE2_EXTENDED_PARAMETERS passata nel parametro pCreateExParams:-
Se si specifica FILE_FLAG_OPEN_REPARSE_POINT:
- Se un file esistente viene aperto ed è un collegamento simbolico, l'handle restituito è un handle per il collegamento simbolico.
- Se vengono specificati TRUNCATE_EXISTING o FILE_FLAG_DELETE_ON_CLOSE, il file interessato è un collegamento simbolico.
-
Se FILE_FLAG_OPEN_REPARSE_POINT non è specificato:
- Se un file esistente viene aperto ed è un collegamento simbolico, l'handle restituito è un handle per la destinazione.
- Se vengono specificati CREATE_ALWAYS, TRUNCATE_EXISTINGo FILE_FLAG_DELETE_ON_CLOSE, il file interessato è la destinazione.
file
Se si rinomina o si elimina un file e quindi lo si ripristina poco dopo, il sistema cerca nella cache le informazioni sui file da ripristinare. Le informazioni memorizzate nella cache includono la coppia nome breve/lungo e il tempo di creazione.Se si chiama CreateFile2 in un file in sospeso come risultato di una chiamata precedente a DeleteFile, la funzione ha esito negativo. Il sistema operativo ritarda l'eliminazione dei file fino a quando tutti gli handle del file non vengono chiusi. getLastError restituisce ERROR_ACCESS_DENIED.
Il parametro dwDesiredAccess
Quando un'applicazione crea un file in una rete, è preferibile usare GENERIC_READ | GENERIC_WRITE per dwDesiredAccess piuttosto che usare GENERIC_WRITE da solo. Il codice risultante è più veloce, perché il redirector può usare gestione cache e inviare meno SMB con più dati.
Questa combinazione evita inoltre un problema per cui la scrittura in un file in una rete può occasionalmente restituire ERROR_ACCESS_DENIED.
Per altre informazioni, vedere Creazione e apertura di file.
flussi di file
Nei file system NTFS è possibile usare CreateFile2 per creare flussi separati all'interno di un file. Per altre informazioni, vedere flussi di file.directory
Un'applicazione non può creare una directory usando CreateFile2, pertanto solo il valore OPEN_EXISTING è valido per dwCreationDisposition per questo caso d'uso. Per creare una directory, l'applicazione deve chiamare CreateDirectory o CreateDirectoryEx.Per aprire una directory usando CreateFile2, specificare il flag FILE_FLAG_BACKUP_SEMANTICS come parte di dwFileFlags membro della struttura CREATEFILE2_EXTENDED_PARAMETERS passata nel parametro pCreateExParams. I controlli di sicurezza appropriati si applicano ancora quando questo flag viene usato senza SE_BACKUP_NAME e SE_RESTORE_NAME privilegi.
Quando si usa CreateFile2 per aprire una directory durante la deframmentazione di un volume di file system FAT o FAT32, non specificare il diritto di accesso MAXIMUM_ALLOWED. Se questa operazione viene eseguita, l'accesso alla directory viene negato. Specificare invece il diritto di accesso GENERIC_READ.
Per altre informazioni, vedere Informazioni su Gestione directory.
dischi fisici e volumi
L'accesso diretto al disco o a un volume è limitato.È possibile usare la funzione CreateFile2 per aprire un'unità disco fisico o un volume, che restituisce un handle DASD (Direct Access Storage Device) che può essere usato con la funzione DeviceIoControl. In questo modo è possibile accedere direttamente al disco o al volume, ad esempio metadati del disco come la tabella di partizione. Tuttavia, questo tipo di accesso espone anche l'unità disco o il volume a potenziali perdite di dati, perché una scrittura non corretta in un disco che usa questo meccanismo potrebbe rendere il contenuto inaccessibile al sistema operativo. Per garantire l'integrità dei dati, assicurarsi di acquisire familiarità con DeviceIoControl e il comportamento di altre API in modo diverso con un handle di accesso diretto anziché con un handle del file system.
Per il successo di una chiamata di questo tipo, è necessario soddisfare i requisiti seguenti:
- Il chiamante deve disporre di privilegi amministrativi. Per altre informazioni, vedere esecuzione con privilegi speciali.
- Il parametro dwCreationDisposition deve avere il flag di OPEN_EXISTING.
- Quando si apre un volume o un disco floppy, il parametro dwShareMode deve avere il flag FILE_SHARE_WRITE.
| Corda | Significato |
|---|---|
| "\.\PhysicalDrive0" | Apre la prima unità fisica. |
| "\.\PhysicalDrive2" | Apre la terza unità fisica. |
Per ottenere l'identificatore dell'unità fisica per un volume, aprire un handle al volume e chiamare la funzione DeviceIoControl
Per un esempio di apertura di un'unità fisica, vedere Chiamata di DeviceIoControl.
Quando si apre un volume o un'unità multimediale rimovibile (ad esempio, un'unità disco floppy o un'unità chiavetta flash), l'lpFileName stringa deve essere il formato seguente: "\\.\X:". Non usare una barra rovesciata finale (\), che indica la directory radice di un'unità. La tabella seguente illustra alcuni esempi di stringhe di unità.
| Corda | Significato |
|---|---|
| "\.\A:" | Apre l'unità disco floppy A. |
| "\\.\C:" | Apre il volume C: . |
| "\\.\C:\" | Apre il file system del volume C: . |
È anche possibile aprire un volume facendo riferimento al nome del volume. Per altre informazioni, vedere Naming a Volume.
Un volume contiene uno o più file system montati. Gli handle di volume possono essere aperti come non memorizzati nella cache a discrezione del file system specifico, anche quando l'opzione non memorizzata nella cache non è specificata in CreateFile2. È consigliabile presupporre che tutti i file system Microsoft aprono handle di volume come non memorizzati nella cache. Le restrizioni relative all'I/O non memorizzato nella cache per i file si applicano anche ai volumi.
Un file system può richiedere o meno l'allineamento del buffer anche se i dati non sono memorizzati nella cache. Tuttavia, se l'opzione non memorizzata nella cache viene specificata quando si apre un volume, l'allineamento del buffer viene applicato indipendentemente dal file system nel volume. È consigliabile in tutti i file system che si aprono handle di volume come non memorizzati nella cache e seguire le restrizioni di I/O non memorizzate nella cache.
dispositivo di modifica
I codici di controllounità nastro
È possibile aprire unità nastro usando un nome di file nel formato seguente: "\\.\TAPEx" dove x è un numero che indica quale unità aprire, a partire dall'unità nastro zero. Per aprire l'unità nastro zero in un'applicazione scritta in C o C++, usare il nome di file seguente: "\\\.\TAPE0".Per altre informazioni, vedere Backup.
Risorse di comunicazione
La funzione CreateFile2 può creare un handle per una risorsa di comunicazione, ad esempio la porta seriale COM1. Per le risorse di comunicazione, il parametro dwCreationDisposition deve essere OPEN_EXISTING, il parametro dwShareMode deve essere zero (accesso esclusivo) e il parametro hTemplateFile deve essere null. È possibile specificare l'accesso in lettura, scrittura o scrittura e l'handle può essere aperto per operazioni di I/O sovrapposte.Per specificare un numero di porta COM maggiore di 9, usare la sintassi seguente: "\.\COM10". Questa sintassi funziona per tutti i numeri di porta e l'hardware che consente di specificare i numeri di porta COM.
Per altre informazioni sulle comunicazioni, vedere Communications.
Console
La funzione| Parametri | Valore |
|---|---|
| lpFileName |
Usare il valore CONIN$ per specificare l'input della console.
Usare il valore CONOUT$ per specificare l'output della console. CONIN$ ottiene un handle per il buffer di input della console, anche se la funzione SetStdHandle reindirizza l'handle di input standard. Per ottenere l'handle di input standard, usare la funzione GetStdHandle. CONOUT$ ottiene un handle per il buffer dello schermo attivo, anche se SetStdHandle reindirizza l'handle di output standard. Per ottenere l'handle di output standard, usare GetStdHandle. |
| dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE è preferibile, ma è possibile limitare l'accesso.
|
| dwShareMode |
Quando si apre CONIN$, specificare FILE_SHARE_READ. Quando si apre CONOUT$, specificare FILE_SHARE_WRITE.
Se il processo chiamante eredita la console o se un processo figlio deve essere in grado di accedere alla console, questo parametro deve essere |
| dwCreationDisposition | È necessario specificare OPEN_EXISTING quando si usa CreateFile2 per aprire la console. |
Impostare i membri della struttura CREATEFILE2_EXTENDED_PARAMETERS passati nel parametro pCreateExParams come indicato di seguito.
| Membri | Valore |
|---|---|
| lpSecurityAttributes |
Se si desidera che la console venga ereditata, il membro |
|
dwFileAttributes dwFileFlags dwSecurityQosFlags hTemplateFile |
Ignorato. |
La tabella seguente illustra varie impostazioni di dwDesiredAccess e lpFileName.
| lpFileName | dwDesiredAccess | Risultato |
|---|---|---|
| "CON" | GENERIC_READ | Apre la console per l'input. |
| "CON" | GENERIC_WRITE | Apre la console per l'output. |
| "CON" | GENERIC_READ | GENERIC_WRITE |
Causa l'esito negativo di CreateFile2; getLastError restituisce ERROR_FILE_NOT_FOUND. |
Mailslots
Se CreateFile2 apre la fine del client di un messaggio di posta elettronica, la funzione restituisce INVALID_HANDLE_VALUE se il client mailslot tenta di aprire un file mailslot locale prima che il server mailslot lo abbia creato con la funzione CreateMailSlot.Per altre informazioni, vedere Mailslots.
pipe
Se CreateFile2 apre la fine client di una named pipe, la funzione usa qualsiasi istanza della named pipe nello stato di ascolto. Il processo di apertura può duplicare l'handle quante più volte necessario, ma dopo l'apertura, l'istanza della named pipe non può essere aperta da un altro client. L'accesso specificato quando viene aperta una pipe deve essere compatibile con l'accesso specificato nel parametro dwOpenMode della funzione CreateNamedPipe.Se la funzione CreateNamedPipe non è stata chiamata correttamente nel server prima di questa operazione, non esisterà una pipe e CreateFile2 avrà esito negativo con ERROR_FILE_NOT_FOUND.
Se nel server è presente almeno un'istanza della pipe attiva ma non sono presenti pipe del listener disponibili, il che significa che tutte le istanze della pipe sono attualmente connesse, CreateFile2 ha esito negativo con ERROR_PIPE_BUSY.
Per altre informazioni, vedere Pipe.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows 8 [app desktop | App UWP] |
| server minimo supportato | Windows Server 2012 [app desktop | App UWP] |
| piattaforma di destinazione | Finestre |
| intestazione |
fileapi.h (include Windows.h) |
| libreria |
Kernel32.lib |
| dll | Kernel32.dll |
Vedere anche
Informazioni sul di gestione directory
Informazioni sulla gestione dei volumi
creazione, eliminazione e gestione dei file
di input e output del dispositivo (IOCTL)
compressione e decompressione dei file
diritti di accesso e sicurezza dei file
Funzioni
ottenere e impostare le informazioni sui file
Panoramica