Funzione SetFileInformationByHandle (fileapi.h)
Imposta le informazioni sul file per il file specificato.
Per recuperare informazioni sui file usando un handle di file, vedere GetFileInformationByHandle o GetFileInformationByHandleEx.
Sintassi
BOOL SetFileInformationByHandle(
[in] HANDLE hFile,
[in] FILE_INFO_BY_HANDLE_CLASS FileInformationClass,
[in] LPVOID lpFileInformation,
[in] DWORD dwBufferSize
);
Parametri
[in] hFile
Handle per il file per il quale modificare le informazioni.
Questo handle deve essere aperto con le autorizzazioni appropriate per la modifica richiesta. Per altre informazioni, vedere le sezioni Osservazioni e Codice di esempio.
Questo handle non deve essere un handle pipe.
[in] FileInformationClass
Valore di enumerazione FILE_INFO_BY_HANDLE_CLASS che specifica il tipo di informazioni da modificare.
Per una tabella di valori validi, vedere la sezione Osservazioni.
[in] lpFileInformation
Puntatore al buffer contenente le informazioni da modificare per la classe di informazioni sul file specificata. Struttura a cui punta questo parametro corrisponde alla classe specificata da FileInformationClass.
Per una tabella di tipi di struttura validi, vedere la sezione Osservazioni.
[in] dwBufferSize
Dimensioni di lpFileInformation, in byte.
Valore restituito
Restituisce un valore diverso da zero se ha esito positivo o zero in caso contrario.
Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
Alcune classi di informazioni sui file si comportano in modo leggermente diverso nelle diverse versioni del sistema operativo. Queste classi sono supportate dai driver sottostanti e tutte le informazioni restituite sono soggette a modifiche tra le versioni del sistema operativo.
La tabella seguente illustra le classi di informazioni sui file valide e i relativi tipi di struttura di dati corrispondenti da usare con questa funzione.
| Valore FileInformationClass | Tipo lpFileInformation |
|---|---|
|
FileBasicInfo
0 |
|
|
FileRenameInfo
3 |
|
|
FileDispositionInfo
4 |
|
|
FileAllocationInfo
5 |
|
|
FileEndOfFileInfo
6 |
|
|
FileIoPriorityHintInfo
12 |
È necessario specificare i flag di accesso appropriati durante la creazione dell'handle di file da usare con SetFileInformationByHandle. Ad esempio, se l'applicazione usa FILE_DISPOSITION_INFO con il membro DeleteFile impostato su TRUE, il file dovrà richiedere l'accesso DELETE nella chiamata alla funzione CreateFile . Per un esempio di questo, vedere la sezione Codice di esempio. Per altre informazioni sulle autorizzazioni per i file, vedere Protezione file e diritti di accesso.
Se è presente una transazione associata all'handle, le modifiche apportate verranno transazionate per le classi di informazioni FileBasicInfo, FileRenameInfo, FileAllocationInfo, FileEndOfFileInfo e FileDispositionInfo. Se si specifica FileDispositionInfo , viene eseguita solo l'operazione di eliminazione se è stata richiesta un'operazione DeleteFile . In questo caso, se la transazione non viene sottoposta a commit prima della chiusura dell'handle, l'eliminazione non verrà eseguita. Per altre informazioni su TxF, vedere NTFS transazionale (TxF).For more information about TxF, see Transactional NTFS (TxF).
In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| Failover trasparente SMB 3.0 (TFO) | Vedere il commento |
| SMB 3.0 con condivisioni file di scalabilità orizzontale (SO) | Vedere il commento |
| File system del volume condiviso cluster (CsvFS) | Sì |
| Resilient File System (ReFS) | Sì |
SMB 3.0 non supporta la ridenominazione di flussi di dati alternativi nelle condivisioni file con funzionalità di disponibilità continua.
Esempio
L'esempio C++ seguente illustra come creare un file e contrassegnarlo per l'eliminazione quando l'handle viene chiuso.
//...
HANDLE hFile = CreateFile( TEXT("tempfile"),
GENERIC_READ | GENERIC_WRITE | DELETE,
0 /* exclusive access */,
NULL,
CREATE_ALWAYS,
0,
NULL);
if (hFile != INVALID_HANDLE_VALUE)
{
FILE_DISPOSITION_INFO fdi;
fdi.DeleteFile = TRUE; // marking for deletion
BOOL fResult = SetFileInformationByHandle( hFile,
FileDispositionInfo,
&fdi,
sizeof(FILE_DISPOSITION_INFO) );
if (fResult)
{
// File will be deleted upon CloseHandle.
_tprintf( TEXT("SetFileInformationByHandle marked tempfile for deletion\n") );
// ...
// Now use the file for whatever temp data storage you need,
// it will automatically be deleted upon CloseHandle or
// application termination.
// ...
}
else
{
_tprintf( TEXT("error %lu: SetFileInformationByHandle could not mark tempfile for deletion\n"),
GetLastError() );
}
CloseHandle(hFile);
// At this point, the file is closed and deleted by the system.
}
else
{
_tprintf( TEXT("error %lu: could not create tempfile\n"),
GetLastError() );
}
//...
Requisiti
| Client minimo supportato | Windows Vista [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2008 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | fileapi.h (include Windows.h) |
| Libreria | Kernel32.lib; FileExtd.lib in Windows Server 2003 e Windows XP |
| DLL | Kernel32.dll |
| Componente ridistribuibile | Windows SDK in Windows Server 2003 e Windows XP. |