Funzione CreateFileW (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.
Per eseguire questa operazione come operazione transazionata, che comporta un handle che può essere usato per le operazioni di I/O transazioni, usare la funzione CreateFileTransacted.
Sintassi
HANDLE CreateFileW(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwCreationDisposition,
[in] DWORD dwFlagsAndAttributes,
[in, optional] HANDLE hTemplateFile
);
Parametri
[in] lpFileName
Nome del file o del dispositivo da creare o aprire. È possibile usare barre (/) o barre rovesciata (\) in questo nome.
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.
Per impostazione predefinita, il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, anteporre "\\?\" al percorso. Per altre informazioni, vedere denominazione di file, percorsi e spazi dei nomi.
Mancia
A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente alla rimozione della limitazione MAX_PATH senza anteporre "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di nomi, percorsi e spazi dei nomi.
[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 CreateFile ha esito positivo, il file o il dispositivo non può essere condiviso e non può essere aperto di nuovo fino alla chiusura dell'handle nel file o nel 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, optional] 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 CreateFile non può essere ereditato da qualsiasi 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.
[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] dwFlagsAndAttributes
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.
Questo parametro può contenere anche 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. Questi valori vengono combinati con qualsiasi FILE_ATTRIBUTE_ valori.
Questo parametro può contenere anche informazioni sulla qualità del servizio (SQOS) specificando il flag SECURITY_SQOS_PRESENT. Le informazioni aggiuntive sui flag correlati a SQOS vengono presentate nella tabella che segue gli attributi e le tabelle dei flag.
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. |
|
Il file è nascosto. Non includerlo in un elenco di directory normale. |
|
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 |
| 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. |
|
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 CreateFile usando il flag 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; CreateFile 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 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 analisi inversi). 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 |
Il parametro dwFlagsAndAttributes può specificare anche le informazioni SQOS. Per altre informazioni, vedere Livelli di rappresentazione. Quando l'applicazione chiamante specifica il flag SECURITY_SQOS_PRESENT come parte di dwFlagsAndAttributes, può contenere anche uno o più dei valori seguenti.
[in, optional] 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, CreateFile 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.
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
CreateFile è stato originariamente sviluppato appositamente per l'interazione con i file, ma è stato ampliato e migliorato per includere 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 CreateFile 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 CreateFile 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 .
Windows Server 2003 e Windows XP: Per motivi di compatibilità con le versioni precedenti, CreateFile non applica regole di ereditarietà quando si specifica un descrittore di sicurezza in lpSecurityAttributes. Per supportare l'ereditarietà, le funzioni che in seguito eseguono query sul descrittore di sicurezza di questo file possono determinare in modo euristico e segnalare che l'ereditarietà è attiva. Per altre informazioni, vedere propagazione automatica degli ACL ereditabili.
Come indicato in precedenza, se il parametro lpSecurityAttributes è NULL, l'handle restituito da CreateFile non può essere ereditato da processi figlio che l'applicazione può creare. Si applicano anche le informazioni seguenti relative a questo parametro:
- 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) | Vedere le osservazioni |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | Vedere le osservazioni |
| Cluster Shared Volume File System (CsvFS) | Sì |
| Resilient File System (ReFS) | Sì |
Si noti che CreateFile con eliminazione sostituita avrà esito negativo se eseguito in un file in cui è già presente un flusso di dati alternativo aperto.
comportamento del collegamento simbolico
Se la chiamata a questa funzione crea un file, non viene apportata alcuna modifica al comportamento. Considerare anche le informazioni seguenti relative a FILE_FLAG_OPEN_REPARSE_POINT:-
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.
comportamento di memorizzazione nella cache
Diversi valori possibili per il parametro dwFlagsAndAttributes vengono usati da CreateFile per controllare o influire sulla modalità di memorizzazione nella cache dei dati associati all'handle dal sistema. Sono:- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
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.
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.
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 CreateFile 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
Se vengono specificati CREATE_ALWAYS e FILE_ATTRIBUTE_NORMAL, CreateFile ha esito negativo e imposta l'ultimo errore su ERROR_ACCESS_DENIED se il file esiste e ha l'attributo FILE_ATTRIBUTE_HIDDEN o FILE_ATTRIBUTE_SYSTEM. Per evitare l'errore, specificare gli stessi attributi del file esistente.
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.
handle di I/O sincroni e asincroni
CreateFile 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 parametro dwFlagsAndAttributes. Esistono diverse complessità e potenziali insidie quando si usa l'I/O asincrona; Per altre informazioni, vedere I/O sincrona e asincrona .flussi di file
Nei file system NTFS è possibile usare CreateFile 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 CreateFile, 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 CreateFile, specificare il flag FILE_FLAG_BACKUP_SEMANTICS come parte di dwFlagsAndAttributes. 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 CreateFile 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.Windows Server 2003 e Windows XP: accesso diretto al disco o a un volume non è limitato in questo modo.
È possibile usare la funzione CreateFile
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 CreateFile. È 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 funzionePer 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 |
| lpSecurityAttributes |
Se si desidera che la console venga ereditata, il membro |
| dwCreationDisposition | È necessario specificare OPEN_EXISTING quando si usa CreateFile per aprire la console. |
| dwFlagsAndAttributes | Ignorato. |
| 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 CreateFile; getLastError restituisce ERROR_FILE_NOT_FOUND. |
Mailslots
Se CreateFile 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 messaggio di posta locale prima che il server mailslot lo abbia creato con la funzione CreateMailSlot.Per altre informazioni, vedere Mailslots.
pipe
Se CreateFile 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
Se è presente almeno un'istanza della pipe attiva, ma non sono presenti pipe del listener disponibili nel server, il che significa che tutte le istanze della pipe sono attualmente connesse, CreateFile ha esito negativo con ERROR_PIPE_BUSY.
Per altre informazioni, vedere Pipe.
Esempi
Le operazioni di file di esempio sono illustrate negli argomenti seguenti:
- accodare un file a un altro
- annullamento delle operazioni di I/O in sospeso
- Creazione di un processo figlio con input e output reindirizzati
- creazione e utilizzo di un di file temporaneo
- FSCTL_RECALL_FILE
- GetFinalPathNameByHandle
- blocco e sblocco di intervalli di byte nei file
- ottenere un nome file da un handle di file
- ottenere informazioni di riconoscimento del file system
- apertura di un file per la lettura o la scrittura di
- Recupero dell' di tempo di Last-Write
- SetFileInformationByHandle
- test per la fine di un di file
- uso di fibre
- uso di flussi
- un buffer di record del journal delle modifiche
- Wow64DisableWow64FsRedirection
- Wow64EnableWow64FsRedirection
- Chiamata di DeviceIoControl
- Configurazione di una risorsa di comunicazione
- monitoraggio degli eventi di comunicazione
- l'elaborazione di una richiesta di rimozione di un del dispositivo
L'utilizzo di un file mailslot viene visualizzato in Scrittura in unMailslot.
Un frammento di codice di backup su nastro è disponibile in Creazione di un'applicazione di backup.
Nota
L'intestazione fileapi.h definisce CreateFile come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [solo app desktop] |
| server minimo supportato | Windows Server 2003 [solo app desktop] |
| 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