SetFileInformationByHandle-Funktion (fileapi.h)

Artikel
08/23/2023

Legt die Dateiinformationen für die angegebene Datei fest.

Informationen zum Abrufen von Dateiinformationen mithilfe eines Dateihandles finden Sie unter GetFileInformationByHandle oder GetFileInformationByHandleEx.

Syntax

BOOL SetFileInformationByHandle(
  [in] HANDLE                    hFile,
  [in] FILE_INFO_BY_HANDLE_CLASS FileInformationClass,
  [in] LPVOID                    lpFileInformation,
  [in] DWORD                     dwBufferSize
);

Parameter

[in] hFile

Ein Handle für die Datei, für die Informationen geändert werden sollen.

Dieses Handle muss mit den entsprechenden Berechtigungen für die angeforderte Änderung geöffnet werden. Weitere Informationen finden Sie in den Abschnitten Hinweise und Beispielcode.

Dieser Handle sollte kein Pipehandle sein.

[in] FileInformationClass

Ein FILE_INFO_BY_HANDLE_CLASS Enumerationswert, der den Typ der zu ändernden Informationen angibt.

Eine Tabelle mit gültigen Werten finden Sie im Abschnitt Hinweise.

[in] lpFileInformation

Ein Zeiger auf den Puffer, der die informationen enthält, die für die angegebene Dateiinformationsklasse geändert werden sollen. Die Struktur, auf die dieser Parameter verweist, entspricht der Klasse, die von FileInformationClass angegeben wird.

Eine Tabelle mit gültigen Strukturtypen finden Sie im Abschnitt Hinweise.

[in] dwBufferSize

Die Größe von lpFileInformation in Bytes.

Rückgabewert

Gibt nonzero zurück, wenn der Vorgang erfolgreich war oder andernfalls null.

Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Bestimmte Dateiinformationsklassen verhalten sich in verschiedenen Betriebssystemversionen geringfügig unterschiedlich. Diese Klassen werden von den zugrunde liegenden Treibern unterstützt, und alle informationen, die sie zurückgeben, können sich zwischen Betriebssystemversionen ändern.

Die folgende Tabelle zeigt die gültigen Dateiinformationsklassen und die entsprechenden Datentypen für die Verwendung mit dieser Funktion.

FileInformationClass-Wert	lpFileInformation-Typ
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

Sie müssen beim Erstellen des Dateihandles für die Verwendung mit SetFileInformationByHandle geeignete Zugriffsflags angeben. Wenn die Anwendung beispielsweise FILE_DISPOSITION_INFO verwendet, wobei das DeleteFile-Element auf TRUE festgelegt ist, benötigt die Datei den DELETE-Zugriff , der beim Aufruf der CreateFile-Funktion angefordert wurde. Ein Beispiel dafür finden Sie im Abschnitt Beispielcode. Weitere Informationen zu Dateiberechtigungen finden Sie unter Dateisicherheit und Zugriffsrechte.

Ist an das Handle eine Transaktion gebunden, sind die vorgenommenen Änderungen für die Informationsklassen FileBasicInfo, FileRenameInfo, FileAllocationInfo, FileEndOfFileInfo und FileDispositionInfo transaktiv. Wenn FileDispositionInfo angegeben ist, wird nur der Löschvorgang ausgeführt, wenn ein DeleteFile-Vorgang angefordert wurde. Wenn die Transaktion in diesem Fall nicht vor dem Schließen des Handles committet wird, erfolgt der Löschvorgang nicht. Weitere Informationen zu TxF finden Sie unter Transactional NTFS (TxF).

Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Unterstützt
SMB 3.0-Protokoll (Server Message Block)	Ja
SMB 3.0 Transparent Failover (TFO)	Siehe Kommentar
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Siehe Kommentar
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

SMB 3.0 unterstützt keine Umbenennung alternativer Datenströme auf Dateifreigaben mit kontinuierlicher Verfügbarkeitsfunktion.

Beispiele

Das folgende C++-Beispiel zeigt, wie Eine Datei erstellt und zum Löschen markiert wird, wenn das Handle geschlossen ist.

//...
  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() );
 }
//...

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	fileapi.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib; FileExtd.lib unter Windows Server 2003 und Windows XP
DLL	Kernel32.dll
Verteilbare Komponente	Windows SDK unter Windows Server 2003 und Windows XP.