SetFileInformationByHandle-Funktion (fileapi.h)

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.

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.

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

Weitere Informationen

CreateFile

Dateiverwaltungsfunktionen

Dateisicherheit und Zugriffsberechtigungen

Generische Zugriffsrechte

GetFileInformationByHandle

GetFileInformationByHandleEx