Funzione CreateFileTransactedA (winbase.h)
[Microsoft consiglia vivamente agli sviluppatori di usare mezzi alternativi per soddisfare le esigenze dell'applicazione. Molti scenari per cui è stato sviluppato TxF possono essere ottenuti tramite tecniche più semplici e più facilmente disponibili. Inoltre, TxF potrebbe non essere disponibile nelle versioni future di Microsoft Windows. Per altre informazioni e alternative a TxF, vedere Alternative all'uso di NTFS transazionale.]
Crea o apre un file, un flusso di file o una directory come operazione transazionata. La funzione restituisce un handle che può essere utilizzato per accedere all'oggetto .
Per eseguire questa operazione come operazione non transazionata o per accedere a oggetti diversi dai file ,ad esempio named pipe, dispositivi fisici, mailslots, utilizzare la funzione CreateFile.
Per altre informazioni sulle transazioni, vedere la sezione Osservazioni di questo argomento.
Sintassi
HANDLE CreateFileTransactedA(
[in] LPCSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwCreationDisposition,
[in] DWORD dwFlagsAndAttributes,
[in, optional] HANDLE hTemplateFile,
[in] HANDLE hTransaction,
[in, optional] PUSHORT pusMiniVersion,
PVOID lpExtendedParameter
);
Parametri
[in] lpFileName
Nome di un oggetto da creare o aprire.
L'oggetto deve risiedere nel computer locale; in caso contrario, la funzione ha esito negativo e l'ultimo codice di errore è impostato su ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.
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.
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 all'oggetto, che può essere riepilogato come lettura, scrittura, entrambi o nessuno dei due (zero). I valori usati più comunemente sono GENERIC_READ, GENERIC_WRITEo entrambi (GENERIC_READ | GENERIC_WRITE). Per altre informazioni, vedere diritti di accesso generico e diritti di accesso e sicurezza dei file.
Se questo parametro è zero, l'applicazione può eseguire query su file, directory o attributi del dispositivo senza accedere a tale file o dispositivo. Per altre informazioni, vedere la sezione Osservazioni di questo argomento.
Non è possibile richiedere una modalità di accesso in conflitto con la modalità di condivisione specificata in una richiesta aperta con un handle aperto. Per altre informazioni, vedere Creazione e apertura di file.
[in] dwShareMode
La modalità di condivisione di un oggetto, che può essere letta, scritta, entrambe, eliminate, tutte queste o nessuna (fare riferimento alla tabella seguente).
Se questo parametro è zero e CreateFileTransacted ha esito positivo, l'oggetto non può essere condiviso e non può essere aperto di nuovo finché l'handle non viene chiuso. Per altre informazioni, vedere la sezione Osservazioni di questo argomento.
Non è possibile richiedere una modalità di condivisione in conflitto con la modalità di accesso specificata in una richiesta aperta con un handle aperto, perché ciò comporta la violazione di condivisione seguente: ERROR_SHARING_VIOLATION. Per altre informazioni, vedere Creazione e apertura di file.
Per consentire a un processo di condividere un oggetto mentre un altro processo ha l'oggetto aperto, utilizzare una combinazione di uno o più dei valori seguenti per specificare la modalità di accesso che è possibile richiedere di aprire l'oggetto.
[in, optional] lpSecurityAttributes
Puntatore a una struttura di SECURITY_ATTRIBUTES che contiene un descrittore di sicurezza facoltativo e determina anche se l'handle restituito può essere ereditato dai processi figlio. Il parametro può essere NULL.
Se il parametro lpSecurityAttributes
Il bInheritHandle membro della struttura specifica se l'handle restituito può essere ereditato.
Il lpSecurityDescriptor membro della struttura specifica un descrittore di sicurezza per un oggetto, ma può anche essere NULL.
Se membro lpSecurityDescriptor è NULL, all'oggetto associato all'handle restituito viene assegnato un descrittore di sicurezza predefinito.
Per altre informazioni, vedere la sezione Osservazioni di questo argomento.
[in] dwCreationDisposition
Azione da intraprendere sui file esistenti e non esistenti.
Per altre informazioni, vedere la sezione Osservazioni di questo argomento.
Questo parametro deve essere uno dei valori seguenti, che non può essere combinato.
[in] dwFlagsAndAttributes
Gli attributi e i flag del file FILE_ATTRIBUTE_NORMAL il valore predefinito più comune.
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 buffering, 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.
Quando CreateFileTransacted 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.
| 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. |
|
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. I file system evitano di scrivere nuovamente 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. In caso contrario, i dati sono scritti dopo la chiusura dell'handle. |
| 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 handle di directory . |
|
Il file deve essere eliminato immediatamente dopo la chiusura dell'ultimo handle del writer transazionale nel file, purché la transazione sia ancora attiva. Se un file è stato contrassegnato per l'eliminazione e un handle di scrittura transazionale è ancora aperto al termine della transazione, il file non verrà eliminato.
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 viene aperto senza memorizzazione nella cache del sistema. Questo flag non influisce sulla memorizzazione nella cache del disco rigido o sui file mappati alla memoria. Se combinato con FILE_FLAG_OVERLAPPED, il flag offre 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 comunque essere memorizzati nella cache. Per scaricare i metadati su disco, usare la funzione flushFileBuffers Un'applicazione deve soddisfare determinati requisiti quando si aprono file aperti con FILE_FLAG_NO_BUFFERING:
Un'applicazione può determinare una dimensione del settore del volume chiamando la funzione GetDiskFreeSpace |
|
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; CreateFileTransacted tenterà di aprire il punto di analisi. 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. |
|
Il file viene aperto o creato per le operazioni di I/O asincrone. Al termine dell'operazione, l'evento specificato nella struttura OVERLAPPED Se questo flag viene specificato, il file può essere usato per operazioni di lettura e scrittura simultanee. Il sistema non gestisce il puntatore al file, pertanto è necessario passare la posizione del file alle funzioni di lettura e scrittura nella struttura 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. |
|
Il file deve essere accessibile 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. |
|
Il file deve essere accessibile in modo casuale. Il sistema può usarlo come suggerimento per ottimizzare la memorizzazione nella cache dei file. |
|
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. |
|
Il file deve essere accessibile in sequenza dall'inizio alla fine. Il sistema può usarlo come suggerimento per ottimizzare la memorizzazione nella cache dei file. Se un'applicazione sposta il puntatore al file per l'accesso casuale, la memorizzazione nella cache ottimale potrebbe non verificarsi. Tuttavia, l'operazione corretta è comunque garantita.
La specifica di questo flag 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 intervalli di byte di piccole dimensioni. 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. |
|
Le operazioni di scrittura non passeranno attraverso alcuna cache intermedia, verranno passate direttamente al disco.
Se non viene specificato anche 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 viene specificata anche FILE_FLAG_NO_BUFFERING, in modo che la memorizzazione nella cache del sistema non sia effettiva, i dati vengono immediatamente scaricati su disco senza passare attraverso la cache di sistema. Il sistema operativo richiede anche una scrittura tramite la cache del disco rigido a supporti persistenti. Tuttavia, non tutti gli hardware supportano questa funzionalità write-through. |
Il parametro dwFlagsAndAttributes può specificare anche informazioni sulla qualità del servizio per la sicurezza. 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, CreateFileTransacted ignora il file modello.
Quando si apre un nuovo file crittografato EFS, il file eredita l'elenco DACL dalla directory padre.
[in] hTransaction
Handle per la transazione. Questo handle viene restituito dalla funzione CreateTransaction.
[in, optional] pusMiniVersion
Miniversione da aprire. Se la transazione specificata in hTransaction non è la transazione che sta modificando il file, questo parametro deve essere NULL. In caso contrario, questo parametro può essere un identificatore miniversione restituito dal codice di controllo FSCTL_TXFS_CREATE_MINIVERSION o uno dei valori seguenti.
lpExtendedParameter
Questo parametro è riservato e deve essere NULL.
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
Quando si usa l'handle restituito da CreateFileTransacted, usare la versione transazionata delle funzioni di I/O dei file anziché le funzioni di I/O di file standard, se appropriato. Per altre informazioni, vedere considerazioni sulla programmazione per ntfs transazionali.
Quando si apre un handle transazionato in una directory, tale handle deve avere autorizzazioni FILE_WRITE_DATA (FILE_ADD_FILE) e FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY). Queste sono incluse nelle autorizzazioni di FILE_GENERIC_WRITE. È consigliabile aprire directory con meno autorizzazioni se si usa solo l'handle per creare file o sottodirectory; in caso contrario, possono verificarsi violazioni di condivisione.
Non è possibile aprire un file con FILE_EXECUTE livello di accesso quando tale file fa parte di un'altra transazione, ovvero un'altra applicazione la apre chiamando CreateFileTransacted). Ciò significa che CreateFileTransacted ha esito negativo se viene specificato il livello di accesso FILE_EXECUTE o FILE_ALL_ACCESS
Quando un'applicazione non transazionata chiama CreateFileTransacted con MAXIMUM_ALLOWED specificato per lpSecurityAttributes, viene aperto un handle con lo stesso livello di accesso ogni volta. Quando un'applicazione transazionale chiama CreateFileTransacted con MAXIMUM_ALLOWED specificato per lpSecurityAttributes, un handle viene aperto con una quantità di accesso diversa in base al fatto che il file sia bloccato da una transazione. Ad esempio, se l'applicazione chiamante ha FILE_EXECUTE livello di accesso per un file, l'applicazione ottiene questo accesso solo se il file aperto non è bloccato da una transazione o è bloccato da una transazione e l'applicazione è già un lettore transazionale per tale file.
Vedere NTFS transazionale per una descrizione completa delle operazioni transazionali.
Utilizzare la funzione CloseHandle per chiudere un handle di oggetto restituito da CreateFileTransacted quando l'handle non è più necessario e prima di eseguire il commit o il rollback della transazione.
Alcuni file system, ad esempio il file system NTFS, supportano la compressione o la crittografia per singoli file e directory. Nei volumi formattati per quel tipo di file system, un nuovo file eredita gli attributi di compressione e crittografia della directory.
Non è possibile utilizzare CreateFileTransacted per controllare la compressione in un file o in una directory. Per altre informazioni, vedere Compressione e decompressione dei file e Crittografia file.
Comportamento del collegamento simbolico: se la chiamata a questa funzione crea un nuovo file, non viene apportata alcuna modifica al comportamento.
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 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.
Come indicato in precedenza, se il parametro lpSecurityAttributes è NULL, l'handle restituito da CreateFileTransacted non può essere ereditato da alcun processo figlio che l'applicazione può creare. Si applicano anche le informazioni seguenti relative a questo parametro:
- Se 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 dei file e delle directory per il
lpSecurityDescriptor, che può essere determinato usando GetVolumeInformation
| Tecnologia | Sostenuto |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | No |
| SMB 3.0 Transparent Failover (TFO) | No |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | No |
| Cluster Shared Volume File System (CsvFS) | No |
| Resilient File System (ReFS) | No |
Si noti che SMB 3.0 non supporta TxF.
file
Se si tenta di creare un file su un'unità floppy che non dispone di un disco floppy o di un'unità CD-ROM che non dispone di un CD, il sistema visualizza un messaggio per l'utente di inserire un disco o un CD. Per impedire al sistema di visualizzare questo messaggio, chiamare la funzionePer altre informazioni, vedere Creazione e apertura di 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 CreateFileTransacted 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 che usare solo GENERIC_WRITE. 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.
flussi di file
Nei file system NTFS è possibile usare CreateFileTransacted 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 CreateFileTransacted, pertanto solo il valore OPEN_EXISTING è valido per dwCreationDisposition per questo caso d'uso. Per creare una directory, l'applicazione deve chiamare CreateDirectoryTransacted, CreateDirectory o CreateDirectoryEx.Per aprire una directory usando CreateFileTransacted, 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 CreateFileTransacted 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.
Nota
L'intestazione winbase.h definisce CreateFileTransacted 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 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 Vista [solo app desktop] |
| server minimo supportato | Windows Server 2008 [solo app desktop] |
| piattaforma di destinazione | Finestre |
| intestazione |
winbase.h (include Windows.h) |
| libreria |
Kernel32.lib |
| dll | Kernel32.dll |
Vedere anche
compressione e decompressione dei file
diritti di accesso e sicurezza dei file
Funzioni
Panoramica
considerazioni sulla programmazione di per i NTFS transazionali
NTFS transazionale (TxF)