Funzione CreateFileTransactedA (winbase.h)
[Microsoft consiglia vivamente agli sviluppatori di usare mezzi alternativi per raggiungere le esigenze dell'applicazione. Molti scenari sviluppati da TxF possono essere ottenuti tramite tecniche più semplici e più leggibili. 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 usato per accedere all'oggetto.
Per eseguire questa operazione come operazione nontransacted o per accedere a oggetti diversi da file (ad esempio, named pipe, dispositivi fisici, mailslots), usare 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, prependo "\\?\" al percorso. Per altre informazioni, vedere Denominazione di file, percorsi e spazi dei nomi.
Suggerimento
A partire da Windows 10, versione 1607, è possibile scegliere di rimuovere la limitazione MAX_PATH senza pre sospeso "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima lunghezza percorso" di nomi, nomi, percorsi e spazi dei nomi .
Per creare un flusso di file, specificare il nome del file, un punto 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, sia (zero). I valori usati più comunemente sono GENERIC_READ, GENERIC_WRITE o entrambi (GENERIC_READ GENERIC_WRITE | ). Per altre informazioni, vedere Diritti di accesso generico e diritti di accesso ai 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
Modalità di condivisione di un oggetto, che può essere letto, scritto, sia eliminato, tutto questo o nessuno (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 abilitare un processo per condividere un oggetto mentre un altro processo ha l'oggetto aperto, usare una combinazione di uno o più dei valori seguenti per specificare la modalità di accesso che possono richiedere di aprire l'oggetto.
[in, optional] lpSecurityAttributes
Puntatore a una struttura 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 è NULL, l'handle restituito da CreateFileTransacted non può essere ereditato da eventuali processi figlio che l'applicazione può creare e l'oggetto associato all'handle restituito ottiene un descrittore di sicurezza predefinito.
Il membro bInheritHandle della struttura specifica se l'handle restituito può essere ereditato.
Il membro lpSecurityDescriptor della struttura specifica un descrittore di sicurezza per un oggetto, ma può anche essere NULL.
Se il membro lpSecurityDescriptor è NULL, l'oggetto associato all'handle restituito viene assegnato un descrittore di sicurezza predefinito.
CreateFileTransacted ignora il membro lpSecurityDescriptor quando si apre un file esistente, ma continua a usare il membro bInheritHandle .
Per altre informazioni, vedere la sezione Osservazioni di questo argomento.
[in] dwCreationDisposition
Un'azione da eseguire sui file esistenti e non esiste.
Per altre informazioni, vedere la sezione Osservazioni di questo argomento.
Questo parametro deve essere uno dei valori seguenti, che non possono essere combinati.
[in] dwFlagsAndAttributes
Gli attributi e i flag dei file FILE_ATTRIBUTE_NORMAL il valore predefinito più comune.
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 del buffering, delle modalità di accesso e di altri flag a scopo speciale. Si combinano con tutti i valori FILE_ATTRIBUTE_ .
Questo parametro può anche contenere informazioni sqOS (Security Quality of Service) specificando il flag di SECURITY_SQOS_PRESENT . Le informazioni sui flag correlati a SQOS aggiuntive 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 dettagliati 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, questo significa che tutti i dati del file sono crittografati. Per una directory, ciò significa che la crittografia è l'impostazione predefinita per i file appena creati e le sottodirectory. Per altre informazioni, vedere Crittografia file.
Questo flag non ha alcun effetto se è specificato anche FILE_ATTRIBUTE_SYSTEM . |
|
Il file è nascosto. Non includerlo in un elenco di directory normale. |
|
Il file non ha 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 dell'archiviazione gerarchica. Le applicazioni non devono modificare arbitrariamente questo attributo. |
|
Il file è di sola lettura. Le applicazioni possono leggere il file, ma non possono scrivere o eliminarle. |
|
Il file fa parte o viene usato 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. |
| Contrassegno | Significato |
|---|---|
|
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 Handle directory. |
|
Il file deve essere eliminato immediatamente dopo la chiusura dell'ultimo handle writer transazionato al file, purché la transazione sia ancora attiva. Se un file è stato contrassegnato per l'eliminazione e un handle writer transazionato è ancora aperto dopo il completamento della transazione, il file non verrà eliminato.
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. |
|
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 memoria.
Tuttavia, alcune operazioni di I/O richiedono più tempo, perché i dati non vengono mantenuti nella cache. Inoltre, i metadati dei file possono comunque essere memorizzati nella cache. Per scaricare i metadati sul disco, usare la funzione FlushFileBuffers .
Un'applicazione deve soddisfare determinati requisiti quando si riguardano i 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 all'archiviazione locale. Questo flag è usato dai sistemi di archiviazione remoti. |
|
L'elaborazione normale del punto di ripristino non si verificherà; CreateFileTransacted 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. |
|
Il file è aperto o creato per gli I/O asincroni. Al termine dell'operazione, l'evento specificato nella struttura OVERLAPPED è impostato sullo stato segnalato. Operazioni che richiedono un tempo significativo per elaborare ERROR_IO_PENDING.
Se questo flag è specificato, il file può essere usato per operazioni di lettura e scrittura simultanee. Il sistema non mantiene il puntatore al file, pertanto è necessario passare la posizione del file alle funzioni di lettura e scrittura nella struttura OVERLAPPED o aggiornare il puntatore del file. 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 . |
|
Il file deve essere accessibile 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. |
|
Il file deve essere accessibile in modo casuale. Il sistema può interpretare questa situazione come hint per l'ottimizzazione della memorizzazione del file nella cache. |
|
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.
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ò interpretare questa situazione come hint per l'ottimizzazione della memorizzazione del file nella cache. Se un'applicazione sposta il puntatore al file per l'accesso casuale, la memorizzazione nella cache ottimale potrebbe non verificarsi. Tuttavia, l'operazione corretta è ancora garantita.
Specificando questo flag è possibile aumentare le prestazioni per le applicazioni che leggeno 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 l'I/O memorizzato nella cache e FILE_FLAG_NO_BUFFERING. |
|
Le operazioni di scrittura non verranno eseguite tramite alcuna cache intermedia, verranno eseguite direttamente sul disco.
Se FILE_FLAG_NO_BUFFERING non è specificato anche, in modo che la memorizzazione nella cache del sistema sia effettiva, i dati vengono scritti nella cache di sistema, ma vengono scaricati su disco senza ritardo. Se FILE_FLAG_NO_BUFFERING viene specificato anche, in modo che la memorizzazione nella cache del sistema non sia effettiva, i dati vengono immediatamente scaricati su disco senza passare dalla cache di sistema. Il sistema operativo richiede anche una scrittura tramite la cache del disco rigido per supporti persistenti. Tuttavia, non tutti gli hardware supportano questa funzionalità di scrittura. |
Il parametro dwFlagsAndAttributes può anche specificare la qualità del servizio. 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 creato. 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 dati dalla directory padre.
[in] hTransaction
Handle per la transazione. Questo handle viene restituito dalla funzione CreateTransaction .
[in, optional] pusMiniVersion
Miniversion da aprire. Se la transazione specificata in hTransaction non è la transazione che modifica il file, questo parametro deve essere NULL. In caso contrario, questo parametro può essere un identificatore miniversion 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 pipe denominata o lo slot di posta elettronica.
Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
Quando si usa l'handle restituito da CreateFileTransacted, usare la versione transazionata delle funzioni di I/O file anziché le funzioni di I/O file standard, se appropriato. Per altre informazioni, vedere Considerazioni sulla programmazione per NTFS transazionale.
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, le violazioni di condivisione possono verificarsi.
Non è possibile aprire un file con FILE_EXECUTE livello di accesso quando tale file fa parte di un'altra transazione, ovvero un'altra applicazione aperta 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 specificata per lpSecurityAttributes, un handle viene aperto con lo stesso livello di accesso ogni volta. Quando un'applicazione transazionata chiama CreateFileTransacted con MAXIMUM_ALLOWED specificata 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 che viene aperto non è bloccato da una transazione o è bloccato da una transazione e l'applicazione è già un lettore transazionale per tale file.
Per una descrizione completa delle operazioni transazionali, vedere NTFS transazionale .
Usare la funzione CloseHandle per chiudere un handle 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 tale 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 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 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.
Come indicato in precedenza, se il parametro lpSecurityAttributes è NULL, l'handle restituito da CreateFileTransacted non può essere ereditato da processi 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 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 su file e directory affinché lpSecurityDescriptor abbia un effetto su di essi, che può essere determinato tramite GetVolumeInformation
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | No |
| 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) | 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 consentire all'utente di inserire un disco o un CD. Per impedire al sistema di visualizzare questo messaggio, chiamare la funzione SetErrorMode con SEM_FAILCRITICALERRORS.Per 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 relativa coppia nome breve/lungo e il tempo di creazione.
Se si chiama CreateFileTransacted 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 | che usare solo GENERIC_WRITE. 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.
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 comunque 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| 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
Argomenti generali