SetFileAttributesTransactedA-Funktion (winbase.h)

Artikel
11/20/2024

[Microsoft empfiehlt Entwicklern dringend, alternative Mittel zu nutzen, um die Anforderungen Ihrer Anwendung zu erreichen. Viele Szenarien, für die TxF entwickelt wurde, können durch einfachere und leichter verfügbare 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 Transactional NTFS.]

Legt die Attribute für eine Datei oder ein Verzeichnis als transacted-Vorgang 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 breite Zeichen zu erweitern, stellen Sie "\\?\" dem Pfad voran. Weitere Informationen finden Sie unter Namensdateien, Pfade und Namespaces.

Trinkgeld

Ab Windows 10, Version 1607, können Sie sich anmelden, um die MAX_PATH Einschränkung zu entfernen, ohne "\\?\". Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbeschränkung" Benennungsdateien, Pfade und Namespaces.

Die Datei muss sich auf dem lokalen Computer befinden; andernfalls schlägt die Funktion fehl, und der letzte Fehlercode wird auf ERROR_TRANSACTIONS_UNSUPPORTED_REMOTEfestgelegt.

[in] dwFileAttributes

Die für die Datei festzulegenden Dateiattribute.

Eine Liste der Datei-Attributwerte und deren Beschreibungen finden Sie unter Dateiattributekonstanten. Dieser Parameter kann ein oder mehrere Werte sein, kombiniert mit dem Bitweise-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 "Hinweise".

Es folgt eine Liste der unterstützten Attributwerte.

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 fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

In der folgenden Tabelle wird beschrieben, wie Sie die Attribute festlegen, die nicht mit SetFileAttributesTransactedfestgelegt werden können. Beachten Sie, dass es sich bei diesen vorgängen nicht um Transaktionen handelt.

Attribut	Festlegen
FILE_ATTRIBUTE_COMPRESSED 0x800	Verwenden Sie zum Festlegen des Komprimierungszustands einer Datei die DeviceIoControl--Funktion mit dem FSCTL_SET_COMPRESSION Vorgang.
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. Um eine vorhandene Datei in eine verschlüsselte Datei zu konvertieren, verwenden Sie die funktion EncryptFile.
FILE_ATTRIBUTE_REPARSE_POINT 0x400	Um einen Analysepunkt einer Datei oder einem Verzeichnis zuzuordnen, verwenden Sie die DeviceIoControl--Funktion mit dem FSCTL_SET_REPARSE_POINT Vorgang.
FILE_ATTRIBUTE_SPARSE_FILE 0x200	Verwenden Sie zum Festlegen des sparse-Attributs einer Datei die DeviceIoControl--Funktion mit dem FSCTL_SET_SPARSE-Vorgang.

Wenn eine Datei zur Änderung in einer Transaktion geöffnet ist, kann kein anderer Thread die Datei zur Änderung öffnen, bis die Transaktion zugesichert wurde. Wenn ein transacted Thread die Datei zuerst öffnet, erhalten alle nachfolgenden Threads, die versuchen, die Datei zur Änderung zu öffnen, bevor die Transaktion zugesichert wird, eine Freigabeverletzung. Wenn ein nicht durchgeführter Thread die Datei zur Änderung öffnet, bevor der Transacted-Thread ausgeführt wird und es immer noch geöffnet ist, wenn der Transacted-Thread versucht, ihn zu öffnen, erhält die Transaktion den ERROR_TRANSACTIONAL_CONFLICT Fehler.

Weitere Informationen zu Transaktionen finden Sie unter Transactional NTFS.

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

Technologie	Abgestützt
Server Message Block (SMB) 3.0-Protokoll	Nein
SMB 3.0 Transparent Failover (TFO)	Nein
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Nein
Freigegebenes Clustervolumedateisystem (CsvFS)	Nein
Resilient File System (ReFS)	Nein

SMB 3.0 unterstützt TxF nicht.

Transacted Operations

Wenn eine Datei zur Änderung in einer Transaktion geöffnet ist, kann kein anderer Thread die Datei zur Änderung öffnen, bis die Transaktion zugesichert wurde. Wenn also ein transacted Thread die Datei zuerst öffnet, erhalten alle nachfolgenden Threads, die versuchen, die Datei zu ändern, bevor die Transaktion zugesichert wird, eine Freigabeverletzung. Wenn ein Nicht-Transact-Thread die Datei vor dem Transaktionsthread ändert und die Datei weiterhin geöffnet ist, wenn die Transaktion versucht, sie zu öffnen, erhält die Transaktion den Fehler ERROR_TRANSACTIONAL_CONFLICT.

Anmerkung

Der winbase.h-Header definiert SetFileAttributesTransacted als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll