Funzione CreateFileFromAppW (fileapifromapp.h)

Crea o apre un file o un dispositivo di I/O. Il comportamento di questa funzione è identico a CreateFile, ad eccezione del fatto che questa funzione rispetta il modello di sicurezza delle app piattaforma UWP (Universal Windows Platform).

Sintassi

WINSTORAGEAPI HANDLE CreateFileFromAppW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
) noexcept;

Parametri

lpFileName

Nome del file o del dispositivo da creare o aprire. È possibile usare barre (/) o barre rovesciata (\) in questo nome.

Nella versione ANSI di questa funzione il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, chiamare la versione Unicode della funzione e anteporre "\\?\" al percorso. Per altre informazioni, vedere Denominazione di file, percorsi e spazi dei nomi.

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.

Per la versione Unicode di questa funzione (CreateFileFromAppW), è possibile acconsentire esplicitamente per rimuovere la limitazione di MAX_PATH senza anteporre "\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di Denominazione di file, percorsi e spazi dei nomi .

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.

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.

Valore	Significato
0 0x00000000	Impedisce ad altri processi di aprire un file o un dispositivo se richiedono l'eliminazione, la lettura o l'accesso in scrittura.
FILE_SHARE_DELETE 0x00000004	Consente alle operazioni aperte successive su un file o un dispositivo di richiedere l'accesso all'eliminazione. In caso contrario, altri processi non possono aprire il file o il dispositivo se richiedono l'accesso di eliminazione. Se questo flag non è specificato, ma il file o il dispositivo è stato aperto per l'accesso all'eliminazione, la funzione ha esito negativo. Nota L'accesso eliminato consente sia le operazioni di eliminazione che di ridenominazione.
0x00000001 FILE_SHARE_READ	Abilita le operazioni aperte successive su un file o un dispositivo per richiedere l'accesso in lettura. In caso contrario, altri processi non possono aprire il file o il dispositivo se richiedono l'accesso in lettura. Se questo flag non è specificato, ma il file o il dispositivo è stato aperto per l'accesso in lettura, la funzione ha esito negativo.
FILE_SHARE_WRITE 0x00000002	Consente alle successive operazioni aperte su un file o un dispositivo di richiedere l'accesso in scrittura. In caso contrario, altri processi non possono aprire il file o il dispositivo se richiedono l'accesso in scrittura. Se questo flag non viene specificato, ma il file o il dispositivo è stato aperto per l'accesso in scrittura o ha un mapping di file con accesso in scrittura, la funzione ha esito negativo.

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 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 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.

Questa funzione 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.

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:

Valore	Significato
CREATE_ALWAYS 2	Crea sempre un nuovo file. Se il file specificato esiste ed è scrivibile, la funzione tronca il file, la funzione ha esito positivo e il codice dell'ultimo errore viene impostato su ERROR_ALREADY_EXISTS (183). Se il file specificato non esiste ed è un percorso valido, viene creato un nuovo file, la funzione ha esito positivo e il codice dell'ultimo errore viene impostato su zero. Per altre informazioni, vedere la sezione Osservazioni di questo argomento.
CREATE_NEW 1	Crea un nuovo file, solo se non esiste già. Se il file specificato esiste, la funzione ha esito negativo e l'ultimo codice di errore viene impostato su ERROR_FILE_EXISTS (80). Se il file specificato non esiste ed è un percorso valido per un percorso scrivibile, viene creato un nuovo file.
OPEN_ALWAYS 4	Apre sempre un file. Se il file specificato esiste, la funzione ha esito positivo e l'ultimo codice di errore viene impostato su ERROR_ALREADY_EXISTS (183). Se il file specificato non esiste ed è un percorso valido per un percorso scrivibile, la funzione crea un file e il codice dell'ultimo errore è impostato su zero.
OPEN_EXISTING 3	Apre un file o un dispositivo, solo se esistente. Se il file o il dispositivo specificato non esiste, la funzione ha esito negativo e il codice dell'ultimo errore è impostato su ERROR_FILE_NOT_FOUND (2). Per altre informazioni sui dispositivi, vedere la sezione Osservazioni.
TRUNCATE_EXISTING 5	Apre un file e lo tronca in modo che la dimensione sia pari a zero byte, solo se esistente. Se il file specificato non esiste, la funzione ha esito negativo e l'ultimo codice di errore è impostato su ERROR_FILE_NOT_FOUND (2). Il processo chiamante deve aprire il file con il set di bit GENERIC_WRITE come parte del parametro dwDesiredAccess .

dwFlagsAndAttributes

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.

Questo parametro può anche 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. Questi valori vengono combinati con qualsiasi valore FILE_ATTRIBUTE_* .

Questo parametro può anche contenere informazioni sqOS (Security Quality of Service) specificando il flag SECURITY_SQOS_PRESENT . Altre informazioni sui flag correlati a SQOS vengono presentate nella tabella che segue gli attributi e le tabelle dei flag.

Attributo	Significato
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Il file deve essere archiviato. Le applicazioni usano questo attributo per contrassegnare i file per il backup o la rimozione.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	Il file o la directory è crittografato. Per un file, questo significa che tutti i dati del file sono crittografati. Per una directory, significa che la crittografia è l'impostazione predefinita per i file e le sottodirectory appena create. Per altre informazioni, vedere Crittografia file. Questo flag non ha effetto se viene specificato anche FILE_ATTRIBUTE_SYSTEM . Questo flag non è supportato nelle edizioni Home, Home Premium, Starter o ARM di Windows.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	Il file è nascosto. Non includerlo in un elenco di directory normale.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	Il file non ha altri attributi impostati. Questo attributo è valido solo se usato da solo.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	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.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Il file è di sola lettura. Le applicazioni possono leggere il file, ma non possono scrivere o eliminarle.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Il file fa parte o viene usato esclusivamente da un sistema operativo.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Il file viene usato per l'archiviazione temporanea. Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento.

 

Contrassegno	Significato
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	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.
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	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.
FILE_FLAG_NO_BUFFERING 0x20000000	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 questa funzione usando il flag FILE_FLAG_NO_BUFFERING , per informazioni dettagliate, vedere Buffering file.
FILE_FLAG_OPEN_NO_RECALL 0x00100000	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.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	L'elaborazione normale del punto di ripristino non si verificherà; questa funzione 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 di CREATE_ALWAYS . Se il file non è un punto di correzione, questo flag viene ignorato. Per altre informazioni, vedere la sezione Osservazioni.
FILE_FLAG_OVERLAPPED 0x40000000	Il file o il dispositivo vengono aperti o creati per I/O asincroni. Quando le operazioni di I/O successive vengono completate su questo handle, l'evento specificato nella struttura OVERLAPPED verrà impostato sullo stato segnalato. Se questo flag è specificato, il file può essere usato per operazioni di lettura e scrittura simultanee. Se questo flag non è 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 sull'uso di un handle di file creato con questo flag, vedere la sezione Handle di I/O sincroni e asincroni di questo argomento.
FILE_FLAG_POSIX_SEMANTICS 0x0100000	L'accesso verrà eseguito in base alle regole POSIX. Ciò include l'autorizzazione di più file con nomi, diversi solo nel caso, per i file system che supportano tale denominazione. Usare attenzione quando si usa questa opzione, poiché i file creati con questo flag potrebbero non essere accessibili dalle applicazioni scritte per MS-DOS o Windows a 16 bit.
FILE_FLAG_RANDOM_ACCESS 0x10000000	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 alcun effetto se il file system non supporta l'I/O memorizzato nella cache e FILE_FLAG_NO_BUFFERING. Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento.
FILE_FLAG_SESSION_AWARE 0x00800000	Il file o il dispositivo viene aperto con la consapevolezza della sessione. Se questo flag non è 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.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	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 analisi inversa). Questo flag non ha alcun effetto se il file system non supporta l'I/O memorizzato nella cache e FILE_FLAG_NO_BUFFERING. Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento.
FILE_FLAG_WRITE_THROUGH 0x80000000	Le operazioni di scrittura non verranno eseguite tramite alcuna cache intermedia, verranno eseguite direttamente sul disco. Per altre informazioni, vedere la sezione Comportamento di memorizzazione nella cache di questo argomento.

 

Il parametro dwFlagsAndAttributespuò anche specificare 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.

Flag di sicurezza	Significato
SECURITY_ANONYMOUS	Rappresenta un client a livello di rappresentazione anonima.
SECURITY_CONTEXT_TRACKING	La modalità di rilevamento della sicurezza è dinamica. Se questo flag non è specificato, la modalità di rilevamento della sicurezza è statica.
SECURITY_DELEGATION	Rappresenta un client a livello di rappresentazione della delega.
SECURITY_EFFECTIVE_ONLY	Solo gli aspetti abilitati del contesto di sicurezza del client sono disponibili per il server. Se non si specifica questo flag, sono disponibili tutti gli aspetti del contesto di sicurezza del client. Ciò consente al client di limitare i gruppi e i privilegi che un server può usare durante la rappresentazione del client.
SECURITY_IDENTIFICATION	Rappresenta un client a livello di rappresentazione dell'identificazione.
SECURITY_IMPERSONATION	Rappresentazione di un client a livello di rappresentazione. Si tratta del comportamento predefinito se non vengono specificati altri flag insieme al flag di SECURITY_SQOS_PRESENT .

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 creato.

Questo parametro può essere NULL.

Quando si apre un file esistente, questo parametro viene ignorato.

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 pipe denominata o lo slot di posta elettronica.

Se la funzione ha esito negativo, il valore restituito viene INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Requisiti

Client minimo supportato	Windows 10, versione 1803
Intestazione	fileapifromapp.h