createFileTransactedA 函数 (winbase.h)
[Microsoft 强烈建议开发人员利用替代方法来实现应用程序的需求。 TxF 致力于实现的许多方案都可以通过更简单、更易用的技术来实现。 此外，TxF 在 Microsoft Windows 的将来版本中可能不可用。 有关详细信息，以及 TxF 的替代方法，请参阅事务性 NTFS 的替代方法。]
创建或打开文件、文件流或目录作为事务处理操作。 函数返回可用于访问 对象的句柄。
若要以非事务性操作的形式执行此操作或访问除文件 (以外的对象，例如命名管道、物理设备、mailslot) ，请使用 CreateFile 函数。
有关事务的详细信息，请参阅本主题的“备注”部分。
语法
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
);
参数
[in] lpFileName
要创建或打开的对象的名称。
对象必须驻留在本地计算机上;否则，函数将失败，最后一个错误代码设置为 ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE。
默认情况下，名称限制为MAX_PATH个字符。 若要将此限制扩展到 32,767 个宽字符，请在路径前面添加“\\？\”。 有关详细信息，请参阅命名文件、路径和命名空间。
提示
从 Windows 10 版本 1607 开始，可以选择删除MAX_PATH限制，而无需在前面添加“\\？\”。 有关详细信息，请参阅 命名文件、路径和命名空间 的“最大路径长度限制”部分。
若要创建文件流，请指定文件的名称、冒号，然后指定流的名称。 有关详细信息，请参阅 文件流。
[in] dwDesiredAccess
对 对象的访问，可以汇总为读取、写入或两者都不 (零) 。 最常用的值是 GENERIC_READ、 GENERIC_WRITE或两者 (GENERIC_READ | GENERIC_WRITE) 。 有关详细信息，请参阅 通用访问权限 和 文件安全性和访问权限。
如果此参数为零，则应用程序可以在不访问该文件或设备的情况下查询文件、目录或设备属性。 有关详细信息，请参阅本主题的“备注”部分。
不能请求的访问模式与具有打开句柄的打开请求中指定的共享模式冲突。 有关详细信息，请参阅创建和打开文件。
[in] dwShareMode
对象的共享模式（可以是读取、写入、删除、所有这些或无 (请参阅下表) 。
如果此参数为零且 CreateFileTransacted 成功，则对象不能共享，并且不能再次打开，直到句柄关闭。 有关详细信息，请参阅本主题的“备注”部分。
不能请求的共享模式与具有打开句柄的打开请求中指定的访问模式冲突，因为这会导致以下共享冲突： ERROR_SHARING_VIOLATION。 有关详细信息，请参阅创建和打开文件。
若要使一个进程能够在另一个进程打开对象时共享对象，请使用以下一个或多个值的组合来指定它们可请求打开该对象的访问模式。
[in, optional] lpSecurityAttributes
指向 SECURITY_ATTRIBUTES 结构的指针，该结构包含可选的 安全描述符 ，还确定返回的句柄是否可以由子进程继承。 参数可以为 NULL。
如果 lpSecurityAttributes 参数为 NULL，则应用程序可能创建的任何子进程都不能继承 CreateFileTransacted 返回的句柄，并且与返回的句柄关联的对象将获取默认安全描述符。
结构的 bInheritHandle 成员指定是否可以继承返回的句柄。
结构的 lpSecurityDescriptor 成员为对象指定 安全描述符 ，但也可以为 NULL。
如果 lpSecurityDescriptor 成员为 NULL，则会为与返回的句柄关联的对象分配默认安全描述符。
CreateFileTransacted 在打开现有文件时忽略 lpSecurityDescriptor 成员，但会继续使用 bInheritHandle 成员。
有关详细信息，请参阅本主题的“备注”部分。
[in] dwCreationDisposition
对存在和不存在的文件执行的操作。
有关详细信息，请参阅本主题的“备注”部分。
此参数必须是以下值之一，这些值不能组合。
[in] dwFlagsAndAttributes
文件属性和标志 FILE_ATTRIBUTE_NORMAL 是最常见的默认值。
此参数可以包含可用文件属性的任意组合 (FILE_ATTRIBUTE_*) 。 所有其他文件属性都替代 FILE_ATTRIBUTE_NORMAL。
此参数还可以包含标志的组合 (FILE_FLAG_) ，用于控制缓冲行为、访问模式和其他特殊用途标志。 这些值与任何 FILE_ATTRIBUTE_ 值结合使用。
此参数还可以通过指定 SECURITY_SQOS_PRESENT 标志来包含安全服务质量 (SQOS ) 信息。 属性和标志表后面的表中显示了与 SQOS 相关的其他标志信息。
当 CreateFileTransacted 打开现有文件时，它通常会将文件标志与现有文件的文件属性组合在一起，并忽略作为 dwFlagsAndAttributes 的一部分提供的任何文件属性。 创建和打开文件中详细介绍了特殊情况。
| Attribute | 含义 |
|---|---|
|
文件应存档。 应用程序使用此属性来标记要备份或删除的文件。 |
|
此文件或目录已加密。 对于文件来说，表示文件中的所有数据都是加密的。 对于目录，这意味着加密是新创建的文件和子目录的默认设置。 有关详细信息，请参阅 文件加密。
如果还指定 了FILE_ATTRIBUTE_SYSTEM ，则此标志无效。 |
|
文件被隐藏。 不要将其包含在普通目录列表中。 |
|
该文件未设置其他属性。 此属性仅在单独使用时有效。 |
|
文件的数据不会立即可用。 此属性指示文件数据以物理方式移动到脱机存储。 远程存储（分层存储管理软件）使用此属性。 应用程序不应随意更改此属性。 |
|
文件为只读文件。 应用程序可以读取文件，但不能写入或删除它。 |
|
该文件是操作系统的一部分或由操作系统独占使用。 |
|
该文件用于临时存储。 如果有足够的缓存内存可用，文件系统会避免将数据写回到大容量存储，因为应用程序在关闭句柄后会删除临时文件。 在这种情况下，系统可以完全避免写入数据。 否则，在句柄关闭后写入数据。 |
| 标志 | 含义 |
|---|---|
|
正在为备份或还原操作打开或创建文件。 当进程具有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 权限时，系统将确保调用进程替代文件安全检查。 有关详细信息，请参阅 更改令牌中的特权。
必须设置此标志才能获取目录的句柄。 目录句柄可以传递给某些函数，而不是文件句柄。 有关详细信息，请参阅 目录句柄。 |
|
文件将在关闭文件的最后一个事务处理编写器句柄后立即删除，前提是事务仍处于活动状态。 如果文件已被标记为要删除，并且事务处理编写器句柄在事务完成后仍处于打开状态，则不会删除该文件。
如果存在文件的现有打开句柄，则调用会失败，除非它们都以 FILE_SHARE_DELETE 共享模式打开。 针对文件的后续打开请求将失败，除非指定 FILE_SHARE_DELETE 共享模式。 |
|
正在打开文件，没有系统缓存。 此标志不会影响硬盘缓存或内存映射文件。 与 FILE_FLAG_OVERLAPPED 结合使用时， 标志可提供最大的异步性能，因为 I/O 不依赖于内存管理器的同步操作。
但是，某些 I/O 操作需要更多时间，因为数据未保存在缓存中。 此外，文件元数据可能仍会缓存。 要将元数据刷新到磁盘，请使用 FlushFileBuffers 函数。
处理使用 FILE_FLAG_NO_BUFFERING 打开的文件时，应用程序必须满足某些要求：
应用程序可以通过调用 GetDiskFreeSpace 函数来确定卷扇区大小。 |
|
文件数据已请求，但应继续位于远程存储中。 不应将其传输回本地存储。 此标志供远程存储系统使用。 |
|
不会进行正常的 重分析点 处理; CreateFileTransacted 将尝试打开重新分析点。 打开文件时，无论控制重分析点的筛选器是否正常运行，都返回文件句柄。 此标志不能与 CREATE_ALWAYS 标志一起使用。 如果文件不是重分析点，则忽略此标志。 |
|
文件是针对异步 I/O 打开或创建的。 操作完成后， 在 OVERLAPPED 结构中指定的事件将设置为信号状态。 处理需要大量时间的操作返回 ERROR_IO_PENDING。
如果指定了此标志，则文件可用于同时读取和写入操作。 系统不维护文件指针，因此必须将文件位置传递给 OVERLAPPED 结构中的读取和写入函数，或更新文件指针。 如果未指定此标志，则 I/O 操作将序列化，即使对读取和写入函数的调用指定 了 OVERLAPPED 结构也是如此。 |
|
根据 POSIX 规则访问该文件。 这包括允许多个具有名称的文件（仅在大小写上不同）用于支持该命名的文件系统。 使用此选项时请小心，因为为 MS-DOS 或 16 位 Windows 编写的应用程序可能无法访问使用此标志创建的文件。 |
|
该文件是随机访问的。 系统可将此选项用作优化文件缓存的提示。 |
|
正在使用会话感知打开文件或设备。 如果未指定此标志，则会话 0 中运行的进程无法打开每个会话 (设备，例如使用 RemoteFX USB 重定向) 的设备。
此标志对不在会话 0 中的调用方无效。 此标志仅在服务器版本的 Windows 上受支持。
Windows Server 2008 R2 和 Windows Server 2008： 在Windows Server 2012之前，不支持此标志。 |
|
将从头到尾按顺序访问该文件。 系统可将此选项用作优化文件缓存的提示。 如果应用程序移动文件指针进行随机访问，则可能不会进行最佳缓存。 但是，仍能保证正确的操作。
指定此标志可以提高使用顺序访问读取大型文件的应用程序的性能。 对于主要按顺序读取大型文件，但偶尔跳过小范围字节的应用程序，性能提升可能更为明显。 如果文件系统不支持缓存的 I/O 且 FILE_FLAG_NO_BUFFERING，则此标志无效。 |
|
写入操作不会通过任何中间缓存，它们将直接转到磁盘。
如果未同时指定 FILE_FLAG_NO_BUFFERING ，以便系统缓存生效，则数据将写入系统缓存，但会立即刷新到磁盘。 如果还指定 了 FILE_FLAG_NO_BUFFERING ，以便系统缓存无效，则数据会立即刷新到磁盘，而无需通过系统缓存。 操作系统还会请求将硬盘缓存写入永久性介质。 但是，并非所有硬件都支持此写通功能。 |
dwFlagsAndAttributes 参数还可以指定安全服务质量信息。 有关详细信息，请参阅 模拟级别。 当调用应用程序将 SECURITY_SQOS_PRESENT 标志指定为 dwFlagsAndAttributes 的一部分时，它还可以包含以下一个或多个值。
[in, optional] hTemplateFile
具有 GENERIC_READ 访问权限的模板文件的有效句柄。 模板文件为正在创建的文件提供文件属性和扩展属性。 此参数可以为 NULL。
打开现有文件时， CreateFileTransacted 将忽略模板文件。
打开新的 EFS 加密文件时，该文件会从其父目录继承 DACL。
[in] hTransaction
事务的句柄。 此句柄由 CreateTransaction 函数返回。
[in, optional] pusMiniVersion
要打开的微型版本。 如果 hTransaction 中指定的事务不是修改文件的事务，则此参数应为 NULL。 否则，此参数可以是 FSCTL_TXFS_CREATE_MINIVERSION 控制代码返回的微型版本标识符，也可以是以下值之一。
| 值 | 含义 |
|---|---|
|
文件自上次提交时起的视图。 |
|
事务正在修改文件时的视图。 |
|
文件的已提交视图或脏视图，具体取决于上下文。 修改文件的事务获取脏视图，而未修改文件的事务获取已提交的视图。 |
lpExtendedParameter
此参数是保留的，必须为 NULL。
返回值
如果函数成功，则返回值是指定文件、设备、命名管道或邮件槽的打开句柄。
如果函数失败，则返回值为 INVALID_HANDLE_VALUE。 要获得更多的错误信息，请调用 GetLastError。
注解
使用 CreateFileTransacted 返回的句柄时，请根据需要使用文件 I/O 函数的事务处理版本，而不是标准文件 I/O 函数。 有关详细信息，请参阅 事务性 NTFS 的编程注意事项。
向目录打开事务句柄时，该句柄必须具有 FILE_WRITE_DATA (FILE_ADD_FILE) 和 FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY) 权限。 这些权限包含在 FILE_GENERIC_WRITE 权限中。 如果只是使用 句柄创建文件或子目录，则应使用较少的权限打开目录;否则，可能会发生共享冲突。
当该文件是另一个事务 (即，另一个应用程序通过调用 CreateFileTransacted) 打开该文件时，无法打开具有FILE_EXECUTE访问级别的文件。 这意味着，如果指定了访问级别FILE_EXECUTE或FILE_ALL_ACCESS，CreateFileTransacted 将失败
当非事务处理应用程序使用为 lpSecurityAttributes 指定的MAXIMUM_ALLOWED调用 CreateFileTransacted 时，每次都会使用相同的访问级别打开句柄。 当事务处理的应用程序使用为 lpSecurityAttributes 指定的MAXIMUM_ALLOWED调用 CreateFileTransacted 时，根据事务是否锁定文件，以不同的访问量打开句柄。 例如，如果调用应用程序对某个文件具有 FILE_EXECUTE 访问级别，则仅当正在打开的文件未被事务锁定，或者被事务锁定，并且应用程序已是该文件的交易读取器时，应用程序才会获得此访问权限。
有关事务处理操作的完整说明，请参阅 事务 NTFS 。
当不再需要句柄时，在提交或回滚事务之前，使用 CloseHandle 函数关闭 CreateFileTransacted 返回的对象句柄。
某些文件系统（如 NTFS 文件系统）支持对单个文件和目录进行压缩或加密。 在为此类文件系统设置格式的卷上，新文件继承其目录的压缩和加密属性。
不能使用 CreateFileTransacted 来控制文件或目录上的压缩。 有关详细信息，请参阅 文件压缩和解压缩和 文件加密。
符号链接行为 - 如果对此函数的调用创建了一个新文件，则行为没有变化。
如果指定 了FILE_FLAG_OPEN_REPARSE_POINT ：
- 如果打开现有文件并且它是符号链接，则返回的句柄是符号链接的句柄。
- 如果指定 了TRUNCATE_EXISTING 或 FILE_FLAG_DELETE_ON_CLOSE ，则受影响的文件是符号链接。
- 如果打开现有文件并且它是符号链接，则返回的句柄是目标的句柄。
- 如果指定 CREATE_ALWAYS、TRUNCATE_EXISTING 或 FILE_FLAG_DELETE_ON_CLOSE，则受影响的文件是目标。
如前所述，如果 lpSecurityAttributes 参数为 NULL，则应用程序可能创建的任何子进程都不能继承 CreateFileTransacted 返回的句柄。 有关此参数的以下信息也适用：
- 如果 bInheritHandle 不是 FALSE（任何非零值），则可以继承句柄。 因此，如果不希望句柄可继承，则必须将此结构成员正确初始化为 FALSE 。
- 文件或目录的默认安全描述符中的访问控制列表 (ACL) 是从其父目录继承的。
- 目标文件系统必须支持文件和目录的安全性，lpSecurityDescriptor 才能对它们产生影响，这可以通过使用 GetVolumeInformation 确定
| 技术 | 支持 |
|---|---|
| 服务器消息块 (SMB) 3.0 协议 | 否 |
| SMB 3.0 透明故障转移 (TFO) | 否 |
| 具有横向扩展文件共享的 SMB 3.0 (SO) | 否 |
| 群集共享卷文件系统 (CSV) | 否 |
| 弹性文件系统 (ReFS) | 否 |
请注意，SMB 3.0 不支持 TxF。
文件
如果尝试在没有软盘的软盘驱动器或没有 CD 的 CD-ROM 驱动器上创建文件，系统会显示一条消息，要求用户插入磁盘或 CD。 若要防止系统显示此消息，请使用 SEM_FAILCRITICALERRORS调用 SetErrorMode 函数。有关详细信息，请参阅创建和打开文件。
如果重命名或删除文件，然后在不久后还原它，系统会在缓存中搜索要还原的文件信息。 缓存的信息包括其短/长名称对和创建时间。
如果对由于上次调用 DeleteFile 而挂起删除的文件调用 CreateFileTransacted，则函数将失败。 操作系统会延迟文件删除，直到文件的所有句柄都关闭。 GetLastError 返回 ERROR_ACCESS_DENIED。
dwDesiredAccess 参数可以为零，如果应用程序正在运行且具有足够安全设置，则允许应用程序在不访问文件的情况下查询文件属性。 这对于测试文件是否存在而不打开文件进行读取和/或写入访问，或者获取有关文件或目录的其他统计信息非常有用。 请参阅 获取和设置文件信息和GetFileInformationByHandle。
当应用程序通过网络创建文件时，最好使用 GENERIC_READ | GENERIC_WRITE 而不是单独使用 GENERIC_WRITE 。 生成的代码速度更快，因为重定向程序可以使用缓存管理器，并发送更少的具有更多数据的 SMB。 此组合还避免了通过网络写入文件偶尔会返回 ERROR_ACCESS_DENIED的问题。
文件流
在 NTFS 文件系统上，可以使用 CreateFileTransacted 在文件中创建单独的流。有关详细信息，请参阅 文件流。
目录
应用程序无法使用 CreateFileTransacted 创建目录，因此对于此用例，只有 OPEN_EXISTING 值对 dwCreationDisposition 有效。 若要创建目录，应用程序必须调用 CreateDirectoryTransacted、 CreateDirectory 或 CreateDirectoryEx。若要使用 CreateFileTransacted 打开目录，请将 FILE_FLAG_BACKUP_SEMANTICS 标志指定为 dwFlagsAndAttributes 的一部分。 在没有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 特权的情况下使用此标志时，仍适用适当的安全检查。
在对 FAT 或 FAT32 文件系统卷进行碎片整理期间使用 CreateFileTransacted 打开目录时，请不要指定 MAXIMUM_ALLOWED 访问权限。 如果执行此操作，将拒绝访问目录。 请改为指定 GENERIC_READ 访问权限。
有关详细信息，请参阅 关于目录管理。
注意
winbase.h 标头将 CreateFileTransacted 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows Vista [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | winbase.h (包括 Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |
另请参阅
函数
概述主题
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈