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.
| FileInformationClass-Wert | lpFileInformation-Typ |
|---|---|
|
FileBasicInfo
0 |
|
|
FileRenameInfo
3 |
|
|
FileDispositionInfo
4 |
|
|
FileAllocationInfo
5 |
|
|
FileEndOfFileInfo
6 |
|
|
FileIoPriorityHintInfo
12 |
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. |