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 mailslots 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 di dispositivi speciali, vedere Definizione di un nome 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
L'accesso richiesto al file o al dispositivo, che può essere riepilogato come lettura, scrittura, entrambi o nessuno zero).
I valori usati più di frequente sono GENERIC_READ, GENERIC_WRITE o entrambi (GENERIC_READ | GENERIC_WRITE). Per altre informazioni, vedere Diritti di accesso generico, sicurezza dei file e diritti di accesso, costanti dei diritti di accesso ai file e 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 (fare riferimento alla 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. CreateFile2 avrà esito negativo e la funzione GetLastError restituirà ERROR_SHARING_VIOLATION.
Per consentire a un processo di condividere un file o un dispositivo mentre un altro processo ha aperto il file o il dispositivo, usare una combinazione compatibile di uno o più dei valori seguenti. Per altre informazioni sulle combinazioni valide di questo parametro con il parametro dwDesiredAccess , vedere Creazione e apertura di file.
[in] dwCreationDisposition
Azione da eseguire su un file o un dispositivo esistente o che non esiste.
Per i dispositivi diversi dai file, questo parametro è 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 di 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 specificato.
Se la funzione ha esito negativo, il valore restituito viene INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
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 dei file e la maggior parte degli altri tipi di dispositivi e meccanismi di I/O disponibili per gli sviluppatori Windows. Questa sezione tenta di coprire i vari problemi che gli sviluppatori possono riscontrare quando si usa CreateFile2 in contesti diversi e con tipi di I/O diversi. Il testo tenta di utilizzare il file di parola solo quando si fa riferimento specificamente ai dati archiviati in un file system effettivo in un file system. Tuttavia, alcuni usi del 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 CreateFile2, usare la funzione CloseHandle per chiudere l'handle. Ciò non solo libera le risorse di sistema, ma può avere un'influenza più ampia su elementi come la condivisione del file o del dispositivo e il commit dei dati su disco. Le specifiche sono indicate all'interno di questo argomento in base alle esigenze.
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 dei file e crittografia dei file.
Se il membro lpSecurityAttributes della struttura CREATEFILE2_EXTENDED_PARAMETERS passata nel parametro pCreateExParams è NULL, l'handle restituito da CreateFile2 non può essere ereditato da eventuali processi 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 che questo membro della struttura venga inizializzato correttamente su 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 relativa directory padre.
- Il file system di destinazione deve supportare la sicurezza nei file e nelle directory affinché il membro lpSecurityDescriptor abbia un effetto su di essi, che può essere determinato tramite GetVolumeInformation.
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| Failover trasparente SMB 3.0 (TFO) | No |
| SMB 3.0 con condivisioni file di scalabilità orizzontale (SO) | No |
| File system del volume condiviso cluster (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 FILE_FLAG_OPEN_REPARSE_POINT per il membro dwFileFlags della struttura CREATEFILE2_EXTENDED_PARAMETERS passata nel parametro pCreateExParams :-
Se viene specificato FILE_FLAG_OPEN_REPARSE_POINT :
- Se viene aperto un file esistente 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 non viene specificato FILE_FLAG_OPEN_REPARSE_POINT:
- Se un file esistente viene aperto ed è un collegamento simbolico, l'handle restituito è un handle per la destinazione.
- Se vengono specificati CREATE_ALWAYS, TRUNCATE_EXISTING o 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 relativa coppia nome breve/lungo e il tempo di creazione.Se si chiama CreateFile2 in un file in attesa di eliminazione in seguito a 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 può essere zero, consentendo all'applicazione di eseguire query sugli attributi del file senza accedere al file se l'applicazione è in esecuzione con impostazioni di sicurezza adeguate. Ciò è utile per verificare l'esistenza di un file senza aprirlo per l'accesso in lettura e/o scrittura o per ottenere altre statistiche sul file o sulla directory. Vedi Ottenere e impostare le informazioni sui file e GetFileInformationByHandle.
Quando un'applicazione crea un file in una rete, è preferibile usare GENERIC_READ | GENERIC_WRITE per dwDesiredAccess rispetto all'uso di GENERIC_WRITE da solo. Il codice risultante è più veloce, perché il redirector può usare la gestione cache e inviare meno SDB 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 del membro dwFileFlags della struttura CREATEFILE2_EXTENDED_PARAMETERS passata nel parametro pCreateExParams . I controlli di sicurezza appropriati si applicano comunque 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 ottenere 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 OPEN_EXISTING .
- Quando si apre un volume o un disco floppy, il parametro dwShareMode deve avere il flag FILE_SHARE_WRITE .
| string | Significato |
|---|---|
| "\\.\PhysicalDrive0" | Apre la prima unità fisica. |
| "\\.\PhysicalDrive2" | Apre la terza unità fisica. |
Per ottenere l'identificatore di unità fisica per un volume, aprire un handle al volume e chiamare la funzione DeviceIoControl con IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Questo codice di controllo restituisce il numero e l'offset del disco per ogni extent del volume; un volume può estendersi su più dischi fisici.
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à personale di memoria flash), la stringa lpFileName deve essere la 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à.
| string | 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 Denominazione di un volume.
Un volume contiene uno o più file system montati. I handle del volume possono essere aperti come non incached a discrezione del file system specifico, anche quando l'opzione non memorizzata non è specificata in CreateFile2. Si supponga che tutti i file system Microsoft aprono i handle del volume come non incached. Le restrizioni per i file di I/O non incluse si applicano anche ai volumi.
Un file system può o non richiedere l'allineamento del buffer anche se i dati non sono memorizzati. Tuttavia, se l'opzione non memorizzata viene specificata quando si apre un volume, l'allineamento del buffer viene applicato indipendentemente dal file system nel volume. È consigliabile usare tutti i file system che si aprono handle di volume come non incached e seguire le restrizioni di I/O non memorizzate.
Dispositivo changer
I codici di controllo IOCTL_CHANGER_* per DeviceIoControl accettano un handle in un dispositivo changer. Per aprire un dispositivo changer, usare un nome file del modulo seguente: "\\.\Changerx" dove x è un numero che indica quale dispositivo aprire, a partire da zero. Per aprire il dispositivo changer zero in un'applicazione scritta in C o C++, usare il nome file seguente: "\\\.\Changer0".Unità nastro
È possibile aprire unità nastro usando un nome file del modulo seguente: "\\.\TAPEx" dove x è un numero che indica l'unità da aprire, a partire da zero dell'unità nastro. Per aprire l'unità nastro zero in un'applicazione scritta in C o C++, usare il nome del file seguente: "\.\TAPE0".Per altre informazioni, vedere Backup.
Risorse di comunicazione
La funzione CreateFile2 può creare un handle in 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 le 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 Comunicazioni.
Console
La funzione CreateFile2 può creare un handle per l'input della console (CONIN$). Se il processo ha un handle aperto a esso come risultato dell'ereditarietà o della duplicazione, può anche creare un handle per il buffer dello schermo attivo (CONOUT$). Il processo chiamante deve essere collegato a una console ereditata o una allocata dalla funzione AllocConsole . Per gli handle della console, impostare i parametri CreateFile2 come indicato di seguito.| 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 nel 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 è preferito, ma uno può 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 vuole che la console venga ereditata, il membro bInheritHandle della struttura SECURITY_ATTRIBUTES deve essere TRUE. |
|
dwFileAttributes
dwFileFlags dwSecurityQosFlags hTemplateFile |
Ignorato. |
La tabella seguente mostra 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 una mailslot, la funzione restituisce INVALID_HANDLE_VALUE se il client mailslot tenta di aprire una mailslot locale prima che il server mailslot lo abbia creato con la funzione CreateMailSlot .Per altre informazioni, vedere Mailslots.
Tubi
Se CreateFile2 apre la fine del client di una pipe denominata, la funzione usa qualsiasi istanza della pipe denominata nello stato di ascolto. Il processo di apertura può duplicare l'handle quante volte necessario, ma dopo l'apertura, l'istanza della pipe denominata 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, una pipe non esisterà e CreateFile2 avrà esito negativo con ERROR_FILE_NOT_FOUND.
Se è presente almeno un'istanza della pipe attiva, ma non sono disponibili pipe di listener nel server, 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.
Requisiti
| Client minimo supportato | Windows 8 [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2012 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | fileapi.h (includere Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |
Vedere anche
Informazioni sulla gestione delle directory
Informazioni sulla gestione dei volumi
Creazione, eliminazione e gestione di file
Controllo input e output del dispositivo (IOCTL)
Compressione e decompressione dei file
Diritti di sicurezza e accesso dei file
Funzioni
Recupero e impostazione delle informazioni sui file
Argomenti di panoramica
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per