Funzione SetFileInformationByHandle (fileapi.h)

Articolo
03/14/2023

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	FILE_BASIC_INFO
FileRenameInfo 3	FILE_RENAME_INFO
FileDispositionInfo 4	FILE_DISPOSITION_INFO
FileAllocationInfo 5	FILE_ALLOCATION_INFO
FileEndOfFileInfo 6	FILE_END_OF_FILE_INFO
FileIoPriorityHintInfo 12	FILE_IO_PRIORITY_HINT_INFO

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