SetFileAttributesTransactedA-Funktion (winbase.h)

Artikel
03/03/2024

[Microsoft empfiehlt Entwicklern dringend, alternative Mittel zu verwenden, um die Anforderungen Ihrer Anwendung zu erfüllen. Viele Szenarios, für die TxF entwickelt wurde, können mit einfacheren und leichter verfügbaren Techniken erreicht werden. Darüber hinaus ist TxF in zukünftigen Versionen von Microsoft Windows möglicherweise nicht verfügbar. Weitere Informationen und Alternativen zu TxF finden Sie unter Alternativen zur Verwendung von transaktionalem NTFS.]

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

Syntax

BOOL SetFileAttributesTransactedA(
  [in] LPCSTR lpFileName,
  [in] DWORD  dwFileAttributes,
  [in] HANDLE hTransaction
);

Parameter

[in] lpFileName

Der Name der Datei, deren Attribute festgelegt werden sollen.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um diesen Grenzwert auf 32.767 Breitzeichen zu erweitern, stellen Sie dem Pfad "\\?\" voran. 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 aufheben, ohne "\\?\" vorab ausstehen zu müssen. Ausführliche Informationen finden Sie im Abschnitt "Maximale Längenbeschränkung für Pfade" unter Benennen von Dateien, Pfaden und Namespaces .

Die Datei muss sich auf dem lokalen Computer befinden. Andernfalls schlägt die Funktion fehl, und der letzte Fehlercode ist auf ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE festgelegt.

[in] dwFileAttributes

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

Eine Liste des Dateiattributewerts und ihrer Beschreibungen finden Sie unter Dateiattributekonstanten. Dieser Parameter kann ein oder mehrere Werte sein, kombiniert mit dem bitweisen OR-Operator. 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.

FILE_ATTRIBUTE_ARCHIVE (32 (0x20))

FILE_ATTRIBUTE_HIDDEN (2 (0x2))

FILE_ATTRIBUTE_NORMAL (128 (0x80))

FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (8192 (0x2000))

FILE_ATTRIBUTE_OFFLINE (4096 (0x1000))

FILE_ATTRIBUTE_READONLY (1 (0x1))

FILE_ATTRIBUTE_SYSTEM (4 (0x4))

FILE_ATTRIBUTE_TEMPORARY (256 (0x100))

[in] hTransaction

Ein Handle für die Transaktion. Dieses Handle wird von der CreateTransaction-Funktion zurückgegeben.

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 SetFileAttributesTransacted festgelegt werden können. Beachten Sie, dass es sich dabei nicht um Transaktionen handelt.

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 .

Wenn eine Datei zur Änderung in einer Transaktion geöffnet ist, kann kein anderer Thread die Datei zur Änderung öffnen, bis ein Commit für die Transaktion ausgeführt wurde. Wenn ein transaktionsfähiger Thread die Datei zuerst öffnet, erhalten alle nachfolgenden Threads, die versuchen, die Datei zur Änderung zu öffnen, bevor ein Commit für die Transaktion ausgeführt wird, einen Freigabeverstoß. Wenn ein nicht abgewickelter Thread die Datei zur Änderung öffnet, bevor der transaktionierte Thread dies tut, und sie immer noch geöffnet ist, wenn der transaktionierte Thread versucht, sie zu öffnen, erhält die Transaktion den ERROR_TRANSACTIONAL_CONFLICT Fehler.

Weitere Informationen zu Transaktionen finden Sie unter Transaktions-NTFS.

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

SMB 3.0 unterstützt TxF nicht.

Transaktionierte Vorgänge

Wenn eine Datei zur Änderung in einer Transaktion geöffnet ist, kann kein anderer Thread die Datei zur Änderung öffnen, bis ein Commit für die Transaktion ausgeführt wird. Wenn also ein transaktionsfähiger Thread die Datei zuerst öffnet, erhalten alle nachfolgenden Threads, die versuchen, die Datei zu ändern, bevor die Transaktion committet wird, einen Freigabeverstoß. Wenn ein nicht transaktioniertes Thread die Datei ändert, bevor der transaktionierte Thread dies tut, und die Datei weiterhin geöffnet ist, wenn die Transaktion versucht, sie zu öffnen, empfängt die Transaktion den Fehler ERROR_TRANSACTIONAL_CONFLICT.

Hinweis

Der winbase.h-Header definiert SetFileAttributesTransacted 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 Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll