CreateFileTransactedA-Funktion (winbase.h)

[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.]

Erstellt oder öffnet eine Datei, einen Dateistream oder ein Verzeichnis als Transaktionsvorgang. Die Funktion gibt ein Handle zurück, das für den Zugriff auf das Objekt verwendet werden kann.

Verwenden Sie die CreateFile-Funktion , um diesen Vorgang als nicht übersetzten Vorgang auszuführen oder auf andere Objekte als Dateien zuzugreifen (z. B. Named Pipes, physische Geräte, Mailslots).

Weitere Informationen zu Transaktionen finden Sie im Abschnitt Hinweise dieses Themas.

Syntax

HANDLE CreateFileTransactedA(
  [in]           LPCSTR                lpFileName,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwCreationDisposition,
  [in]           DWORD                 dwFlagsAndAttributes,
  [in, optional] HANDLE                hTemplateFile,
  [in]           HANDLE                hTransaction,
  [in, optional] PUSHORT               pusMiniVersion,
                 PVOID                 lpExtendedParameter
);

Parameter

[in] lpFileName

Der Name eines Objekts, das erstellt oder geöffnet werden soll.

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

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 .

Geben Sie zum Erstellen eines Dateidatenstroms den Namen der Datei, einen Doppelpunkt und dann den Namen des Datenstroms an. Weitere Informationen finden Sie unter Dateistreams.

[in] dwDesiredAccess

Der Zugriff auf das -Objekt, der als Lesen, Schreiben, beide oder keines (null) zusammengefasst werden kann. Die am häufigsten verwendeten Werte sind GENERIC_READ, GENERIC_WRITE oder beides (GENERIC_READ | GENERIC_WRITE). Weitere Informationen finden Sie unter Generische Zugriffsrechte und Dateisicherheit und Zugriffsrechte.

Wenn dieser Parameter null ist, kann die Anwendung Datei-, Verzeichnis- oder Geräteattribute abfragen, ohne auf diese Datei oder das Gerät zuzugreifen. Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.

Sie können keinen Zugriffsmodus anfordern, der mit dem Freigabemodus in Konflikt steht, der in einer offenen Anforderung mit einem geöffneten Handle angegeben ist. Weitere Informationen finden Sie unter Erstellen und Öffnen von Dateien.

[in] dwShareMode

Der Freigabemodus eines Objekts, der gelesen, geschrieben, beide, gelöscht, alle oder keine sein kann (siehe folgende Tabelle).

Wenn dieser Parameter null ist und CreateFileTransacted erfolgreich ist, kann das Objekt nicht freigegeben werden und kann erst wieder geöffnet werden, wenn das Handle geschlossen wird. Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.

Sie können keinen Freigabemodus anfordern, der in Konflikt mit dem Zugriffsmodus steht, der in einer offenen Anforderung mit einem geöffneten Handle angegeben ist, da dies zu folgendem Freigabeverstoß führen würde: ERROR_SHARING_VIOLATION. Weitere Informationen finden Sie unter Erstellen und Öffnen von Dateien.

Um einem Prozess die Freigabe eines Objekts zu ermöglichen, während das Objekt in einem anderen Prozess geöffnet ist, verwenden Sie eine Kombination aus einem oder mehreren der folgenden Werte, um den Zugriffsmodus anzugeben, den sie zum Öffnen des Objekts anfordern können.

Hinweis Die Freigabeoptionen für jedes geöffnete Handle bleiben in Kraft, bis dieses Handle geschlossen wird, unabhängig vom Prozesskontext.
 
Wert Bedeutung
0
0x00000000
Deaktiviert nachfolgende Geöffnete Vorgänge für ein Objekt, um einen beliebigen Zugriff auf dieses Objekt anzufordern.
FILE_SHARE_DELETE
0x00000004
Aktiviert nachfolgende Geöffnete Vorgänge für ein Objekt, um Löschzugriff anzufordern.

Andernfalls können andere Prozesse das Objekt nicht öffnen, wenn sie Löschzugriff anfordern.

Wenn dieses Flag nicht angegeben ist, aber das Objekt für den Löschzugriff geöffnet wurde, schlägt die Funktion fehl.

FILE_SHARE_READ
0x00000001
Aktiviert nachfolgende Geöffnete Vorgänge für ein Objekt, um Lesezugriff anzufordern.

Andernfalls können andere Prozesse das Objekt nicht öffnen, wenn sie Lesezugriff anfordern.

Wenn dieses Flag nicht angegeben ist, aber das Objekt für den Lesezugriff geöffnet wurde, schlägt die Funktion fehl.

FILE_SHARE_WRITE
0x00000002
Aktiviert nachfolgende Geöffnete Vorgänge für ein Objekt, um Schreibzugriff anzufordern.

Andernfalls können andere Prozesse das Objekt nicht öffnen, wenn sie Schreibzugriff anfordern.

Wenn dieses Flag nicht angegeben ist, aber das Objekt für den Schreibzugriff geöffnet wurde oder über eine Dateizuordnung mit Schreibzugriff verfügt, schlägt die Funktion fehl.

[in, optional] lpSecurityAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur , die einen optionalen Sicherheitsdeskriptor enthält und außerdem bestimmt, ob das zurückgegebene Handle von untergeordneten Prozessen geerbt werden kann. Der Parameter kann NULL sein.

Wenn der lpSecurityAttributes-ParameterNULL ist, kann das von CreateFileTransacted zurückgegebene Handle nicht von untergeordneten Prozessen geerbt werden, die ihre Anwendung möglicherweise erstellt, und das objekt, das dem zurückgegebenen Handle zugeordnet ist, erhält einen Standardsicherheitsdeskriptor.

Der bInheritHandle-Member der -Struktur gibt an, ob das zurückgegebene Handle geerbt werden kann.

Der lpSecurityDescriptor-Member der -Struktur gibt einen Sicherheitsdeskriptor für ein Objekt an, kann aber auch NULL sein.

Wenn lpSecurityDescriptor-MemberNULL ist, wird dem objekt, das dem zurückgegebenen Handle zugeordnet ist, ein Standardsicherheitsdeskriptor zugewiesen.

CreateFileTransacted ignoriert das lpSecurityDescriptor-Element beim Öffnen einer vorhandenen Datei, verwendet aber weiterhin das bInheritHandle-Element .

Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.

[in] dwCreationDisposition

Eine Aktion, die für Dateien ausgeführt werden soll, die vorhanden sind und nicht vorhanden sind.

Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.

Dieser Parameter muss einer der folgenden Werte sein, der nicht kombiniert werden kann.

Wert Bedeutung
CREATE_ALWAYS
2
Erstellt immer eine neue Datei.

Wenn die angegebene Datei vorhanden und schreibbar ist, schneidet die Funktion die Datei ab, die Funktion ist erfolgreich, und der Code für den letzten Fehler ist auf ERROR_ALREADY_EXISTS (183) festgelegt.

Wenn die angegebene Datei nicht vorhanden ist und ein gültiger Pfad ist, wird eine neue Datei erstellt, die Funktion ist erfolgreich, und der Letzte Fehlercode wird auf Null festgelegt.

Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.

CREATE_NEW
1
Erstellt nur dann eine neue Datei, wenn sie noch nicht vorhanden ist.

Wenn die angegebene Datei vorhanden ist, schlägt die Funktion fehl, und der Code für den letzten Fehler ist auf ERROR_FILE_EXISTS (80) festgelegt.

Wenn die angegebene Datei nicht vorhanden ist und ein gültiger Pfad zu einem schreibbaren Speicherort ist, wird eine neue Datei erstellt.

OPEN_ALWAYS
4
Öffnet eine Datei immer.

Wenn die angegebene Datei vorhanden ist, ist die Funktion erfolgreich, und der Code für den letzten Fehler wird auf ERROR_ALREADY_EXISTS (183) festgelegt.

Wenn die angegebene Datei nicht vorhanden ist und ein gültiger Pfad zu einem schreibbaren Speicherort ist, erstellt die Funktion eine Datei, und der Letzte Fehlercode wird auf Null festgelegt.

OPEN_EXISTING
3
Öffnet eine Datei oder ein Gerät nur, wenn es vorhanden ist.

Wenn die angegebene Datei nicht vorhanden ist, schlägt die Funktion fehl, und der Letzte Fehlercode ist auf ERROR_FILE_NOT_FOUND (2) festgelegt.

Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.

TRUNCATE_EXISTING
5
Öffnet eine Datei und schneidet sie ab, sodass ihre Größe null Bytes beträgt, wenn sie vorhanden ist.

Wenn die angegebene Datei nicht vorhanden ist, schlägt die Funktion fehl, und der Letzte Fehlercode ist auf ERROR_FILE_NOT_FOUND (2) festgelegt.

Der aufrufende Prozess muss die Datei mit dem GENERIC_WRITE Bit öffnen, das als Teil des dwDesiredAccess-Parameters festgelegt ist.

[in] dwFlagsAndAttributes

Die Dateiattribute und -flags FILE_ATTRIBUTE_NORMAL der gängigste Standardwert.

Dieser Parameter kann eine beliebige Kombination der verfügbaren Dateiattribute (FILE_ATTRIBUTE_*) enthalten. Alle anderen Dateiattribute überschreiben FILE_ATTRIBUTE_NORMAL.

Dieser Parameter kann auch Kombinationen von Flags (FILE_FLAG_) zur Steuerung des Pufferverhaltens, der Zugriffsmodi und anderer spezieller Flags enthalten. Diese werden mit beliebigen FILE_ATTRIBUTE_ Werten kombiniert.

Dieser Parameter kann auch SQOS-Informationen (Security Quality of Service) enthalten, indem das flag SECURITY_SQOS_PRESENT angegeben wird. Zusätzliche INFORMATIONEN zu SQOS-bezogenen Flags werden in der Tabelle nach den Tabellen für Attribute und Flags angezeigt.

Hinweis  

Wenn CreateFileTransacted eine vorhandene Datei öffnet, kombiniert es im Allgemeinen die Dateiflags mit den Dateiattributen der vorhandenen Datei und ignoriert alle Dateiattribute, die als Teil von dwFlagsAndAttributes bereitgestellt werden. Spezielle Fälle werden unter Erstellen und Öffnen von Dateien beschrieben.

 
Die folgenden Dateiattribute und -flags werden nur für Dateiobjekte verwendet, nicht für andere Objekttypen, die createFileTransacted öffnet (weitere Informationen finden Sie im Abschnitt Hinweise dieses Themas). Weitere Informationen zum erweiterten Zugriff auf Dateiattribute finden Sie unter SetFileAttributes. Eine vollständige Liste aller Dateiattribute mit ihren Werten und Beschreibungen finden Sie unter Dateiattributekonstanten.
attribute Bedeutung
FILE_ATTRIBUTE_ARCHIVE
32 (0x20)
Die Datei sollte archiviert werden. Anwendungen verwenden dieses Attribut, um Dateien für die Sicherung oder Entfernung zu markieren.
FILE_ATTRIBUTE_ENCRYPTED
16384 (0x4000)
Die Datei oder das Verzeichnis ist verschlüsselt. Bei einer Datei bedeutet dies, dass alle Daten in der Datei verschlüsselt sind. Für ein Verzeichnis bedeutet dies, dass die Verschlüsselung die Standardeinstellung für neu erstellte Dateien und Unterverzeichnisse ist. Weitere Informationen finden Sie unter Dateiverschlüsselung.

Dieses Flag hat keine Auswirkung, wenn auch FILE_ATTRIBUTE_SYSTEM angegeben wird.

FILE_ATTRIBUTE_HIDDEN
2 (0x2)
Die Datei ist ausgeblendet. Schließen Sie es nicht in eine normale Verzeichnisauflistung ein.
FILE_ATTRIBUTE_NORMAL
128 (0x80)
Für die Datei sind keine anderen Attribute festgelegt. Dieses Attribut ist nur gültig, wenn es allein verwendet wird.
FILE_ATTRIBUTE_OFFLINE
4096 (0x1000)
Die Daten einer Datei sind nicht sofort verfügbar. Dieses Attribut gibt an, dass Dateidaten physisch in den Offlinespeicher verschoben werden. Dieses Attribut wird von Remote storage verwendet, der hierarchischen Speicherverwaltungssoftware. Anwendungen sollten dieses Attribut nicht willkürlich ändern.
FILE_ATTRIBUTE_READONLY
1 (0x1)
Die Datei ist schreibgeschützter. Anwendungen können die Datei lesen, aber nicht in sie schreiben oder löschen.
FILE_ATTRIBUTE_SYSTEM
4 (0x4)
Die Datei ist Teil von oder wird ausschließlich von einem Betriebssystem verwendet.
FILE_ATTRIBUTE_TEMPORARY
256 (0x100)
Die Datei wird für den temporären Speicher verwendet. Dateisysteme vermeiden das Zurückschreiben von Daten in den Massenspeicher, wenn genügend Cachespeicher verfügbar ist, da eine Anwendung eine temporäre Datei löscht, nachdem ein Handle geschlossen wurde. In diesem Fall kann das System das Schreiben der Daten vollständig vermeiden. Andernfalls werden die Daten geschrieben, nachdem das Handle geschlossen wurde.
 
Flag Bedeutung
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
Die Datei wird für einen Sicherungs- oder Wiederherstellungsvorgang geöffnet oder erstellt. Das System stellt sicher, dass der aufrufende Prozess dateisicherheitsprüfungen außer Kraft setzt, wenn der Prozess über SE_BACKUP_NAME - und SE_RESTORE_NAME-Berechtigungen verfügt. Weitere Informationen finden Sie unter Ändern von Berechtigungen in einem Token.

Sie müssen dieses Flag festlegen, um ein Handle für ein Verzeichnis abzurufen. Ein Verzeichnishandle kann an einige Funktionen anstelle eines Dateihandles übergeben werden. Weitere Informationen finden Sie unter Verzeichnishandles.

FILE_FLAG_DELETE_ON_CLOSE
0x04000000
Die Datei muss sofort gelöscht werden, nachdem das letzte transaktionierte Writerhandle für die Datei geschlossen wurde, sofern die Transaktion noch aktiv ist. Wenn eine Datei zum Löschen markiert wurde und ein Transaktionsschreiberhandle nach Abschluss der Transaktion weiterhin geöffnet ist, wird die Datei nicht gelöscht.

Wenn geöffnete Handles für eine Datei vorhanden sind, schlägt der Aufruf fehl, es sei denn, sie wurden alle mit dem FILE_SHARE_DELETE Freigabemodus geöffnet.

Nachfolgende Öffnungsanforderungen für die Datei fehlschlagen, es sei denn, der Freigabemodus FILE_SHARE_DELETE ist angegeben.

FILE_FLAG_NO_BUFFERING
0x20000000
Die Datei wird ohne Systemzwischenspeicherung geöffnet. Dieses Flag wirkt sich nicht auf die Zwischenspeicherung von Festplatten oder zugeordnete Dateien im Arbeitsspeicher aus. In Kombination mit FILE_FLAG_OVERLAPPED bietet das Flag eine maximale asynchrone Leistung, da die E/A nicht auf den synchronen Vorgängen des Speicher-Managers basiert. Einige E/A-Vorgänge nehmen jedoch mehr Zeit in Anspruch, da die Daten nicht im Cache gespeichert werden. Außerdem können die Dateimetadaten weiterhin zwischengespeichert werden. Verwenden Sie die Funktion FlushFileBuffers, um die Metadaten auf den Datenträger zu leeren.

Eine Anwendung muss bestimmte Anforderungen erfüllen, wenn sie mit Dateien arbeitet, die mit FILE_FLAG_NO_BUFFERING geöffnet werden:

  • Der Dateizugriff muss bei Byteoffsets innerhalb einer Datei beginnen, die ganzzahlige Vielfache der Größe des Volumesektors sind.
  • Der Dateizugriff muss für Die Anzahl von Bytes erfolgen, bei denen es sich um ganzzahlige Vielfache der Größe des Volumesektors handelt. Wenn die Sektorgröße beispielsweise 512 Bytes beträgt, kann eine Anwendung Lese- und Schreibvorgänge von 512, 1024, 1536 oder 2048 Bytes anfordern, aber nicht von 335, 981 oder 7171 Bytes.
  • Pufferadressen für Lese- und Schreibvorgänge sollten sektorseitig ausgerichtet sein. Dies bedeutet, dass sie an Adressen im Arbeitsspeicher ausgerichtet sind, die ganzzahlige Vielfache der Größe des Volumesektors darstellen. Je nach Datenträger kann diese Anforderung nicht erzwungen werden.
Eine Möglichkeit zum Ausrichten von Puffern auf ganzzahligen Vielfachen der Größe des Volumesektors besteht darin , VirtualAlloc zum Zuordnen der Puffer zu verwenden. Es ordnet Arbeitsspeicher zu, der an Adressen ausgerichtet ist, die ganzzahlige Vielfache der Größe der Arbeitsspeicherseite des Betriebssystems sind. Da sowohl die Größe der Speicherseite als auch die Größe des Volumesektors eine Potenz von 2 aufweisen, wird dieser Arbeitsspeicher auch an Adressen ausgerichtet, die ganzzahlige Vielfache einer Volumesektorgröße sind. Speicherseiten sind 4 oder 8 KB groß; Sektoren sind 512 Bytes (Festplatten), 2048 Bytes (CD) oder 4.096 Bytes (Festplatten) und daher dürfen Volumesektoren niemals größer als Speicherseiten sein.

Eine Anwendung kann eine Volumensektorgröße ermitteln, indem sie die GetDiskFreeSpace-Funktion aufruft .

FILE_FLAG_OPEN_NO_RECALL
0x00100000
Die Dateidaten werden angefordert, sollten sich jedoch weiterhin im Remotespeicher befinden. Es sollte nicht zurück in den lokalen Speicher transportiert werden. Dieses Flag ist für Remotespeichersysteme vorgesehen.
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
Die normale Analysepunktverarbeitung erfolgt nicht. CreateFileTransacted versucht, den Analysepunkt zu öffnen. Wenn eine Datei geöffnet wird, wird ein Dateihandle zurückgegeben, unabhängig davon, ob der Filter, der den Analysepunkt steuert, funktionsfähig ist oder nicht. Dieses Flag kann nicht mit dem CREATE_ALWAYS-Flag verwendet werden. Wenn die Datei kein Analysepunkt ist, wird dieses Flag ignoriert.
FILE_FLAG_OVERLAPPED
0x40000000
Die Datei wird geöffnet oder für asynchrone E/A erstellt. Wenn der Vorgang abgeschlossen ist, wird das in der OVERLAPPED-Struktur angegebene Ereignis auf den signalierten Zustand festgelegt. Vorgänge, bei denen die Verarbeitung viel Zeit in Anspruch nimmt, geben ERROR_IO_PENDING zurück.

Wenn dieses Flag angegeben ist, kann die Datei für gleichzeitige Lese- und Schreibvorgänge verwendet werden. Das System behält den Dateizeiger nicht bei, daher müssen Sie die Dateiposition an die Lese- und Schreibfunktionen in der OVERLAPPED-Struktur übergeben oder den Dateizeiger aktualisieren.

Wenn dieses Flag nicht angegeben ist, werden E/A-Vorgänge serialisiert, auch wenn die Aufrufe der Lese- und Schreibfunktionen eine OVERLAPPED-Struktur angeben.

FILE_FLAG_POSIX_SEMANTICS
0x01000000
Auf die Datei muss gemäß POSIX-Regeln zugegriffen werden. Dies schließt das Zulassen mehrerer Dateien mit Namen ein, die sich nur für den Fall unterscheiden, für Dateisysteme, die diese Benennung unterstützen. Verwenden Sie diese Option vorsichtig, da dateien, die mit diesem Flag erstellt wurden, möglicherweise nicht für Anwendungen zugänglich sind, die für MS-DOS oder 16-Bit-Windows geschrieben wurden.
FILE_FLAG_RANDOM_ACCESS
0x10000000
Auf die Datei soll nach dem Zufallsprinzip zugegriffen werden. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden.
FILE_FLAG_SESSION_AWARE
0x00800000
Die Datei oder das Gerät wird mit Sitzungsbewusstsein geöffnet. Wenn dieses Flag nicht angegeben ist, können Geräte pro Sitzung (z. B. ein Gerät mit RemoteFX USB-Umleitung) nicht von Prozessen geöffnet werden, die in Sitzung 0 ausgeführt werden. Dieses Flag hat keine Auswirkung auf Anrufer, die sich nicht in Sitzung 0 befinden. Dieses Flag wird nur in Servereditionen von Windows unterstützt.

Windows Server 2008 R2 und Windows Server 2008: Dieses Flag wird vor Windows Server 2012 nicht unterstützt.

FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
Auf die Datei muss sequenziell von Anfang bis Ende zugegriffen werden. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden. Wenn eine Anwendung den Dateizeiger für den zufälligen Zugriff verschiebt, erfolgt möglicherweise keine optimale Zwischenspeicherung. Der korrekte Betrieb ist jedoch weiterhin garantiert.

Die Angabe dieses Flags kann die Leistung für Anwendungen erhöhen, die große Dateien mit sequenziellem Zugriff lesen. Noch deutlicher kann die Leistung bei Anwendungen sein, die große Dateien meist sequenziell lesen, gelegentlich aber kleine Bytesbereiche überspringen.

Dieses Flag hat keine Auswirkung, wenn das Dateisystem zwischengespeicherte E/A- und FILE_FLAG_NO_BUFFERING nicht unterstützt.

FILE_FLAG_WRITE_THROUGH
0x80000000
Schreibvorgänge durchlaufen keinen Zwischencache, sie werden direkt auf den Datenträger weitergeleitet.

Wenn FILE_FLAG_NO_BUFFERING nicht auch angegeben ist, sodass die Systemzwischenspeicherung wirksam ist, werden die Daten in den Systemcache geschrieben, aber ohne Verzögerung auf den Datenträger geleert.

Wenn auch FILE_FLAG_NO_BUFFERING angegeben ist, sodass die Systemzwischenspeicherung nicht wirksam ist, werden die Daten sofort auf den Datenträger geleert, ohne den Systemcache zu durchlaufen. Das Betriebssystem fordert auch einen Schreibvorgang für den Festplattencache auf persistente Medien an. Diese Durchschreibfunktion wird jedoch nicht von der gesamten Hardware unterstützt.

 

Der dwFlagsAndAttributes-Parameter kann auch Informationen zur Sicherheitsqualität des Diensts angeben. Weitere Informationen finden Sie unter Identitätswechselebenen. Wenn die aufrufende Anwendung das SECURITY_SQOS_PRESENT-Flag als Teil von dwFlagsAndAttributes angibt, kann sie auch einen oder mehrere der folgenden Werte enthalten.

Sicherheitsflagge Bedeutung
SECURITY_ANONYMOUS
Identitätswechsel eines Clients auf anonymer Identitätswechselebene.
SECURITY_CONTEXT_TRACKING
Der Sicherheitsnachverfolgungsmodus ist dynamisch. Wenn dieses Flag nicht angegeben ist, ist der Sicherheitsnachverfolgungsmodus statisch.
SECURITY_DELEGATION
Der Identitätswechsel eines Clients auf der Delegierungsebene.
SECURITY_EFFECTIVE_ONLY
Dem Server stehen nur die aktivierten Aspekte des Sicherheitskontexts des Clients zur Verfügung. Wenn Sie dieses Flag nicht angeben, sind alle Aspekte des Sicherheitskontexts des Clients verfügbar.

Dadurch kann der Client die Gruppen und Berechtigungen einschränken, die ein Server beim Annehmen der Identität des Clients verwenden kann.

SECURITY_IDENTIFICATION
Identitätswechsel eines Clients auf Identitätswechselebene.
SECURITY_IMPERSONATION
Identitätswechsel eines Clients auf Identitätswechselebene Dies ist das Standardverhalten, wenn keine anderen Flags zusammen mit dem SECURITY_SQOS_PRESENT-Flag angegeben werden.

[in, optional] hTemplateFile

Ein gültiges Handle für eine Vorlagendatei mit dem GENERIC_READ Zugriffsrecht. Die Vorlagendatei stellt Dateiattribute und erweiterte Attribute für die zu erstellende Datei bereit. Dieser Parameter kann NULL sein.

Beim Öffnen einer vorhandenen Datei ignoriert CreateFileTransacted die Vorlagendatei.

Beim Öffnen einer neuen EFS-verschlüsselten Datei erbt die Datei die DACL aus dem übergeordneten Verzeichnis.

[in] hTransaction

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

[in, optional] pusMiniVersion

Die miniversion, die geöffnet werden soll. Wenn die in hTransaction angegebene Transaktion nicht die Transaktion ist, die die Datei ändert, sollte dieser Parameter NULL sein. Andernfalls kann es sich bei diesem Parameter um einen Miniversionsbezeichner handeln, der vom FSCTL_TXFS_CREATE_MINIVERSION-Steuerelementcode zurückgegeben wird, oder um einen der folgenden Werte.

Wert Bedeutung
TXFS_MINIVERSION_COMMITTED_VIEW
0x0000
Die Ansicht der Datei ab dem letzten Commit.
TXFS_MINIVERSION_DIRTY_VIEW
0xFFFF
Die Ansicht der Datei, wie sie von der Transaktion geändert wird.
TXFS_MINIVERSION_DEFAULT_VIEW
0xFFFE
Je nach Kontext entweder die Commitansicht oder die modifiziert Ansicht der Datei. Eine Transaktion, die die Datei ändert, ruft die modifiziert Ansicht ab, während eine Transaktion, die die Datei nicht ändert, die committe Ansicht erhält.

lpExtendedParameter

Dieser Parameter ist reserviert und muss NULL sein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein geöffnetes Handle für die angegebene Datei, das angegebene Gerät, die benannte Pipe oder den angegebenen E-Mail-Slot.

Wenn die Funktion fehlschlägt, ist der Rückgabewert INVALID_HANDLE_VALUE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn Sie das von CreateFileTransacted zurückgegebene Handle verwenden, verwenden Sie ggf. die Transaktionsversion der Datei-E/A-Funktionen anstelle der Standardmäßigen Datei-E/A-Funktionen. Weitere Informationen finden Sie unter Überlegungen zur Programmierung für transaktionsbasiertes NTFS.

Beim Öffnen eines Transaktionshandles in einem Verzeichnis muss dieses Handle über FILE_WRITE_DATA (FILE_ADD_FILE) und FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY) Berechtigungen verfügen. Diese sind in FILE_GENERIC_WRITE Berechtigungen enthalten. Sie sollten Verzeichnisse mit weniger Berechtigungen öffnen, wenn Sie nur das Handle zum Erstellen von Dateien oder Unterverzeichnissen verwenden. andernfalls können Verstöße gegen die Freigabe auftreten.

Sie können eine Datei mit FILE_EXECUTE Zugriffsebene nicht öffnen, wenn diese Datei Teil einer anderen Transaktion ist (d. a. eine andere Anwendung hat sie durch Aufrufen von CreateFileTransacted geöffnet). Dies bedeutet, dass CreateFileTransacted fehlschlägt , wenn die Zugriffsebene FILE_EXECUTE oder FILE_ALL_ACCESS angegeben ist.

Wenn eine nicht transaktionierte Anwendung CreateFileTransacted mit MAXIMUM_ALLOWED aufruft, die für lpSecurityAttributes angegeben sind, wird jedes Mal ein Handle mit der gleichen Zugriffsebene geöffnet. Wenn eine transaktionierte Anwendung CreateFileTransacted mit MAXIMUM_ALLOWED aufruft, die für lpSecurityAttributes angegeben sind, wird ein Handle mit unterschiedlichem Zugriff geöffnet, je nachdem, ob die Datei durch eine Transaktion gesperrt ist. Wenn die aufrufende Anwendung beispielsweise über FILE_EXECUTE Zugriffsebene für eine Datei verfügt, erhält die Anwendung diesen Zugriff nur, wenn die geöffnete Datei entweder nicht durch eine Transaktion gesperrt oder durch eine Transaktion gesperrt ist und die Anwendung bereits ein Transaktionsleser für diese Datei ist.

Eine vollständige Beschreibung der transaktionenten Vorgänge finden Sie unter Transaktions-NTFS .

Verwenden Sie die CloseHandle-Funktion , um ein von CreateFileTransacted zurückgegebenes Objekthandle zu schließen, wenn das Handle nicht mehr benötigt wird, und vor dem Commit oder Rollback der Transaktion.

Einige Dateisysteme, z. B. das NTFS-Dateisystem, unterstützen die Komprimierung oder Verschlüsselung für einzelne Dateien und Verzeichnisse. Auf Volumes, die für diese Art von Dateisystem formatiert sind, erbt eine neue Datei die Komprimierungs- und Verschlüsselungsattribute ihres Verzeichnisses.

Sie können CreateFileTransacted nicht verwenden, um die Komprimierung für eine Datei oder ein Verzeichnis zu steuern. Weitere Informationen finden Sie unter Dateikomprimierung und Dekomprimierung und Dateiverschlüsselung.

Symbolisches Linkverhalten: Wenn durch den Aufruf dieser Funktion eine neue Datei erstellt wird, gibt es keine Verhaltensänderung.

Wenn FILE_FLAG_OPEN_REPARSE_POINT angegeben ist:

  • Wenn eine vorhandene Datei geöffnet wird und es sich um einen symbolischen Link handelt, ist das zurückgegebene Handle ein Handle für den symbolischen Link.
  • Wenn TRUNCATE_EXISTING oder FILE_FLAG_DELETE_ON_CLOSE angegeben werden, ist die betroffene Datei ein symbolischer Link.
Wenn FILE_FLAG_OPEN_REPARSE_POINT nicht angegeben ist:
  • Wenn eine vorhandene Datei geöffnet wird und es sich um einen symbolischen Link handelt, ist das zurückgegebene Handle ein Handle für das Ziel.
  • Wenn CREATE_ALWAYS, TRUNCATE_EXISTING oder FILE_FLAG_DELETE_ON_CLOSE angegeben sind, ist die betroffene Datei das Ziel.
Ein Schreibvorgang mit mehreren Sektoren ist nicht garantiert atomisch, es sei denn, Sie verwenden eine Transaktion (das heißt, das erstellte Handle ist ein Transaktionshandle). Ein einsektorischer Schreibvorgang ist atomisch. Zwischengespeicherte Schreibvorgänge mit mehreren Sektoren werden möglicherweise nicht immer auf den Datenträger geschrieben. Geben Sie daher FILE_FLAG_WRITE_THROUGH an, um sicherzustellen, dass ein ganzer multisektorenübergreifender Schreibvorgang ohne Zwischenspeicherung auf den Datenträger geschrieben wird.

Wie bereits erwähnt, kann das von CreateFileTransacted zurückgegebene Handle, wenn der lpSecurityAttributes-ParameterNULL ist, nicht von untergeordneten Prozessen geerbt werden, die Ihre Anwendung möglicherweise erstellt. Die folgenden Informationen zu diesem Parameter gelten ebenfalls:

  • Wenn bInheritHandle nicht FALSE ist, was ein beliebiger Nonzero-Wert ist, kann das Handle geerbt werden. Daher ist es wichtig, dass dieser Strukturmember ordnungsgemäß auf FALSE initialisiert wird, wenn Sie nicht beabsichtigen, dass das Handle vererbt werden kann.
  • Die Zugriffssteuerungslisten (Access Control Lists, ACL) in der Standardsicherheitsbeschreibung für eine Datei oder ein Verzeichnis werden vom übergeordneten Verzeichnis geerbt.
  • Das Zieldateisystem muss die Sicherheit von Dateien und Verzeichnissen unterstützen, damit der lpSecurityDescriptor eine Auswirkung darauf hat. Dies kann mithilfe von GetVolumeInformation bestimmt werden.
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
 

Beachten Sie, dass SMB 3.0 TxF nicht unterstützt.

Dateien

Wenn Sie versuchen, eine Datei auf einem Diskettenlaufwerk zu erstellen, das keine Diskette oder ein CD-ROM-Laufwerk ohne CD enthält, zeigt das System eine Meldung an, in der der Benutzer einen Datenträger oder eine CD einlegen soll. Um zu verhindern, dass das System diese Meldung anzeigt, rufen Sie die SetErrorMode-Funktion mit SEM_FAILCRITICALERRORS auf.

Weitere Informationen finden Sie unter Erstellen und Öffnen von Dateien.

Wenn Sie eine Datei umbenennen oder löschen und sie kurz danach wiederherstellen, durchsucht das System den Cache nach wiederherzustellenden Dateiinformationen. Zwischengespeicherte Informationen umfassen das Kurz-/Lange-Name-Paar und die Erstellungszeit.

Wenn Sie CreateFileTransacted für eine Datei aufrufen, die aufgrund eines vorherigen Aufrufs von DeleteFile löscht, schlägt die Funktion fehl. Das Betriebssystem verzögert das Löschen von Dateien, bis alle Handles für die Datei geschlossen sind. GetLastError gibt ERROR_ACCESS_DENIED zurück.

Der dwDesiredAccess-Parameter kann null sein, sodass die Anwendung Dateiattribute abfragen kann, ohne auf die Datei zuzugreifen, wenn die Anwendung mit angemessenen Sicherheitseinstellungen ausgeführt wird. Dies ist nützlich, um zu testen, ob eine Datei vorhanden ist, ohne sie für Lese- und/oder Schreibzugriff zu öffnen, oder um andere Statistiken über die Datei oder das Verzeichnis abzurufen. Weitere Informationen finden Sie unter Abrufen und Festlegen von Dateiinformationen und GetFileInformationByHandle.

Wenn eine Anwendung eine Datei in einem Netzwerk erstellt, ist es besser , GENERIC_READ | GENERIC_WRITE zu verwenden, als GENERIC_WRITE allein zu verwenden. Der resultierende Code ist schneller, da der Redirector den Cache-Manager verwenden und weniger SMBs mit mehr Daten senden kann. Durch diese Kombination wird auch ein Problem vermieden, bei dem das Schreiben in eine Datei in einem Netzwerk gelegentlich ERROR_ACCESS_DENIED zurückgeben kann.

Dateistreams

Auf NTFS-Dateisystemen können Sie CreateFileTransacted verwenden, um separate Datenströme innerhalb einer Datei zu erstellen.

Weitere Informationen finden Sie unter Dateistreams.

Verzeichnisse

Eine Anwendung kann kein Verzeichnis mit CreateFileTransacted erstellen. Daher ist nur der OPEN_EXISTING Wert für dwCreationDisposition für diesen Anwendungsfall gültig. Um ein Verzeichnis zu erstellen, muss die Anwendung CreateDirectoryTransacted, CreateDirectory oder CreateDirectoryEx aufrufen.

Um ein Verzeichnis mit CreateFileTransacted zu öffnen, geben Sie das FILE_FLAG_BACKUP_SEMANTICS-Flag als Teil von dwFlagsAndAttributes an. Entsprechende Sicherheitsüberprüfungen gelten weiterhin, wenn dieses Flag ohne SE_BACKUP_NAME - und SE_RESTORE_NAME-Berechtigungen verwendet wird.

Wenn Sie CreateFileTransacted zum Öffnen eines Verzeichnisses während der Defragmentierung eines FAT- oder FAT32-Dateisystemvolumes verwenden, geben Sie nicht das MAXIMUM_ALLOWED-Zugriffsrecht an. Der Zugriff auf das Verzeichnis wird verweigert, wenn dies geschieht. Geben Sie stattdessen das GENERIC_READ Zugriffsrecht an.

Weitere Informationen finden Sie unter Informationen zur Verzeichnisverwaltung.

Hinweis

Der winbase.h-Header definiert CreateFileTransacted 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 nicht codierungsneutralem Code 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 (einschließlich Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

CloseHandle

CopyFileTransacted

CreateDirectoryTransacted

DeleteFileTransacted

Komprimierung und Dekomprimierung von Dateien

Dateiverschlüsselung

Dateiverwaltungsfunktionen

Dateisicherheit und Zugriffsberechtigungen

Dateidatenströme

FindFirstFileTransacted

Funktionen

GetFileAttributesTransacted

MoveFileTransacted

Übersichtsthemen

Überlegungen zur Programmierung für transaktionales NTFS

ReadFile

Transaktionales NTFS (TxF)

WriteFile