SetFileAttributesW-Funktion (fileapi.h)

Artikel
03/06/2024

Legt die Attribute für eine Datei oder ein Verzeichnis fest.

Um diesen Vorgang als transaktionierten Vorgang auszuführen, verwenden Sie die SetFileAttributesTransacted-Funktion .

Syntax

BOOL SetFileAttributesW(
  [in] LPCWSTR lpFileName,
  [in] DWORD   dwFileAttributes
);

Parameter

[in] lpFileName

Der Name der Datei, deren Attribute festgelegt werden sollen.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um dieses Limit auf 32.767 breite Zeichen zu erweitern, müssen Sie dem Pfad "\\?\" voranstellen. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Tipp

Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung entfernen, ohne "\\?\" vorauszustellen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .

[in] dwFileAttributes

Die Dateiattribute, die für die Datei festgelegt werden sollen.

Bei diesem Parameter kann es sich um einen oder mehrere Werte handeln, die mit dem bitweisen OR-Operator kombiniert werden. Alle anderen Werte überschreiben jedoch FILE_ATTRIBUTE_NORMAL.

Nicht alle Attribute werden von dieser Funktion unterstützt. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

Im Folgenden ist eine Liste der unterstützten Attributwerte aufgeführt.

Wert	Bedeutung
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Eine Datei oder ein Verzeichnis, bei dem es sich um eine Archivdatei oder ein Verzeichnis handelt. Anwendungen verwenden dieses Attribut in der Regel, um Dateien für die Sicherung oder Entfernung zu markieren.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	Die Datei oder das Verzeichnis ist versteckt. Die Datei ist ausgeblendet und daher nicht in einer normalen Verzeichnisliste enthalten.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	Eine Datei, für die keine anderen Attribute festgelegt sind. Dieses Attribut ist nur gültig, wenn es allein verwendet wird.
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 8192 (0x2000)	Die Datei oder das Verzeichnis darf nicht vom Inhaltsindizierungsdienst indiziert werden.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Die Daten einer Datei sind nicht sofort verfügbar. Dieses Attribut gibt an, dass die Dateidaten physisch in den Offlinespeicher verschoben werden. Dieses Attribut wird von Remotespeicher verwendet, bei der es sich um die hierarchische Speicherverwaltungssoftware handelt. Anwendungen sollten dieses Attribut nicht willkürlich ändern.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Eine Datei, die schreibgeschützt ist. Anwendungen können die Datei lesen, aber nicht in sie schreiben oder löschen. Dieses Attribut wird in Verzeichnissen nicht berücksichtigt. Weitere Informationen finden Sie unter "Sie können die schreibgeschützten oder Systemattribute von Ordnern in Windows Server 2003, windows XP oder Windows Vista nicht anzeigen oder ändern.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Eine Datei oder ein Verzeichnis, teilweise oder ausschließlich vom Betriebssystem verwendet.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Eine Datei, die für die temporäre Speicherung verwendet wird. Dateisysteme vermeiden das Zurückschreiben von Daten in den Massenspeicher, wenn genügend Cachespeicher verfügbar ist, da in der Regel eine Anwendung eine temporäre Datei löscht, nachdem das Handle geschlossen wurde. In diesem Szenario kann das System das Schreiben der Daten vollständig vermeiden. Andernfalls werden die Daten geschrieben, nachdem das Handle geschlossen wurde.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

In der folgenden Tabelle wird beschrieben, wie die Attribute festgelegt werden, die nicht mit SetFileAttributes festgelegt werden können. Eine vollständige Liste aller Dateiattributewerte und deren Beschreibungen finden Sie unter Dateiattributekonstanten.

attribute	Festlegen
FILE_ATTRIBUTE_COMPRESSED 0x800	Um den Komprimierungsstatus einer Datei festzulegen, verwenden Sie die DeviceIoControl-Funktion mit dem vorgang FSCTL_SET_COMPRESSION .
FILE_ATTRIBUTE_DEVICE 0x40	Reserviert; nicht verwenden.
FILE_ATTRIBUTE_DIRECTORY 0x10	Dateien können nicht in Verzeichnisse konvertiert werden. Verwenden Sie zum Erstellen eines Verzeichnisses die Funktion CreateDirectory oder CreateDirectoryEx .
FILE_ATTRIBUTE_ENCRYPTED 0x4000	Verwenden Sie zum Erstellen einer verschlüsselten Datei die CreateFile-Funktion mit dem attribut FILE_ATTRIBUTE_ENCRYPTED . Verwenden Sie die Funktion EncryptFile , um eine vorhandene Datei in eine verschlüsselte Datei zu konvertieren.
FILE_ATTRIBUTE_REPARSE_POINT 0x400	Um einen Analysepunkt einer Datei oder einem Verzeichnis zuzuordnen, verwenden Sie die DeviceIoControl-Funktion mit dem vorgang FSCTL_SET_REPARSE_POINT .
FILE_ATTRIBUTE_SPARSE_FILE 0x200	Um das Sparse-Attribut einer Datei festzulegen, verwenden Sie die DeviceIoControl-Funktion mit dem vorgang FSCTL_SET_SPARSE .

Transaktionen

Wenn eine Datei zur Änderung in einer Transaktion geöffnet ist, kann kein anderer Thread die Datei zur Änderung öffnen, bis das Commit für die Transaktion erfolgt. Wenn also ein Transaktionsthread zuerst die Datei öffnet, erhalten alle nachfolgenden Threads, die versuchen, die Datei zu ändern, bevor die Transaktion committet wird, eine Freigabeverletzung. Wenn ein nicht abgewickelter Thread die Datei vor dem Transaktionsthread ändert und die Datei weiterhin geöffnet ist, wenn die Transaktion versucht, sie zu öffnen, empfängt die Transaktion den Fehler ERROR_TRANSACTIONAL_CONFLICT.

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)	Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Beispiele

Ein Beispiel finden Sie unter Abrufen und Ändern von Dateiattributen.

Hinweis

Der Fileapi.h-Header definiert SetFileAttributes als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	fileapi.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll