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.

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

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

Vedi anche

CreateFile

Funzioni di gestione file

Diritti di accesso e sicurezza dei file

Diritti di accesso generici

GetFileInformationByHandle

GetFileInformationByHandleEx