CREATEFILE2_EXTENDED_PARAMETERS结构 (fileapi.h)
包含 CreateFile2 的可选扩展参数。
语法
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
成员
dwSize
包含此结构 sizeof(CREATEFILE2_EXTENDED_PARAMETERS)的大小。
dwFileAttributes
文件或设备属性和标志 ，FILE_ATTRIBUTE_NORMAL 是文件最常见的默认值。
此参数可以包含可用文件属性的任意组合 (FILE_ATTRIBUTE_*) 。 所有其他文件属性都替代 FILE_ATTRIBUTE_NORMAL。
注意
当 CreateFile2 打开现有文件时，它通常会将文件标志与现有文件的文件属性相结合，并忽略作为 dwFlagsAndAttributes 的一部分提供的任何文件属性。 创建和打开文件中详细介绍了特殊情况。
以下某些文件属性和标志可能仅适用于文件，不一定适用于所有 CreateFile2 可以打开的其他类型的设备。 有关其他信息，请参阅参考页的CreateFile2“备注”部分和“创建和打开文件”。
有关对文件属性的更高级访问，请参阅 SetFileAttributes。 有关所有文件属性及其值和说明的完整列表，请参阅 文件属性常量。
| Attribute | 含义 |
|---|---|
|
应存档该文件。 应用程序使用此属性来标记要备份或删除的文件。 |
|
此文件或目录已加密。 对于文件来说，表示文件中的所有数据都是加密的。 对于目录，这意味着加密是新创建的文件和子目录的默认设置。 有关详细信息，请参阅 文件加密。
如果还指定 了FILE_ATTRIBUTE_SYSTEM ，则此标志不起作用。 家庭版、家庭高级版、入门版或 ARM 版本的 Windows 不支持此标志。 从 Windows 应用商店应用调用时，不支持此标志。 |
|
文件被隐藏。 不要将其包含在普通目录列表中。 |
|
配置完整性的文件或目录。 对于文件，文件中的所有数据流都具有完整性。 对于目录，完整性是新创建的文件和子目录的默认值，除非调用方另行指定。
此标志仅在 ReFS 文件系统上受支持。 |
|
文件未设置其他属性。 此属性仅在单独使用时有效。 |
|
文件的数据不会立即可用。 此属性指示文件数据以物理方式移动到脱机存储。 此属性由远程存储（分层存储管理软件）使用。 应用程序不应随意更改此属性。 |
|
文件为只读文件。 应用程序可以读取文件，但不能写入或删除它。 |
|
该文件是操作系统的一部分，或者由操作系统独占使用。 |
|
该文件用于临时存储。
有关详细信息，请参阅本主题的 缓存行为 部分。 |
dwFileFlags
此参数可以包含标志的组合 (FILE_FLAG_*) ，用于控制文件或设备缓存行为、访问模式和其他特殊用途标志。
| 标志 | 含义 |
|---|---|
|
正在为备份或还原操作打开或创建文件。 当进程具有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 特权时，系统会确保调用进程替代文件安全检查。 有关详细信息，请参阅 更改令牌中的权限。
必须设置此标志才能获取目录的句柄。 目录句柄可以传递给某些函数，而不是文件句柄。 有关详细信息，请参见“备注”部分。 |
|
文件在其所有句柄都关闭后立即被删除，其中包括指定的句柄和任何其他打开或重复的句柄。
如果存在文件的现有打开句柄，则调用会失败，除非它们都以 FILE_SHARE_DELETE 共享模式打开。 针对文件的后续打开请求将失败，除非指定 FILE_SHARE_DELETE 共享模式。 |
|
设备映射是 DOS 设备名称与系统中设备之间的映射，在解析 DOS 名称时使用。 系统中的每个用户都存在单独的设备映射，用户可以管理自己的设备映射。 通常在模拟期间，将使用模拟用户的设备映射。 但是，设置此标志时，将改用进程用户的设备映射。 |
|
正在打开文件或设备，没有系统缓存数据读取和写入。 此标志不会影响硬盘缓存或内存映射文件。
使用 FILE_FLAG_NO_BUFFERING 标志成功处理使用 CreateFile2 打开的文件有严格的要求，有关详细信息，请参阅文件缓冲。 |
|
请求文件数据，但它应继续位于远程存储中。 不应将其传输回本地存储。 此标志供远程存储系统使用。 |
|
正常的 重分析点 处理不会发生; CreateFile2 将尝试打开重新分析点。 打开文件时，无论控制重分析点的筛选器是否正常运行，都返回文件句柄。
此标志不能与 CREATE_ALWAYS 标志一起使用。 如果文件不是重分析点，则忽略此标志。 有关详细信息，请参见“备注”部分。 |
|
正在打开该文件，并且正在请求将文件 (oplock) 的机会锁作为单个原子操作请求。 文件系统在执行创建操作之前会检查 oplock，如果结果为中断现有 oplock，则创建失败并返回最后一个错误代码 ERROR_CANNOT_BREAK_OPLOCK 。
如果使用此标志并且对 CreateFile2 函数的调用成功返回，则应对文件句柄执行的第一个操作是通过调用 DeviceIOControl 函数来请求 oplock，然后传入 FSCTL_REQUEST_OPLOCK 或其他 机会锁操作之一。 如果在请求 oplock 之前使用文件句柄执行其他文件系统操作，则可能会出现死锁。 注意 可以在文件句柄上安全地调用 CloseHandle 函数，而无需先请求 oplock。
|
|
正在为异步 I/O 打开或创建文件或设备。
在此句柄上完成后续 I/O 操作时， 在 OVERLAPPED 结构中指定的事件将设置为信号状态。 如果指定了此标志，则文件可用于同时读取和写入操作。 如果未指定此标志，则 I/O 操作将序列化，即使对读取和写入函数的调用指定 了 OVERLAPPED 结构也是如此。 有关使用此标志创建的文件句柄时的注意事项的信息，请参阅本主题的 同步和异步 I/O 句柄 部分。 |
|
将根据 POSIX 规则进行访问。 这包括允许多个具有名称的文件（仅针对支持该命名的文件系统）有所不同。 使用此选项时请小心，因为为 MS-DOS 或 16 位 Windows 编写的应用程序可能无法访问使用此标志创建的文件。 |
|
访问应是随机的。 系统可将此选项用作优化文件缓存的提示。
如果文件系统不支持缓存的 I/O 和 FILE_FLAG_NO_BUFFERING，则此标志不起作用。 有关详细信息，请参阅本主题的 缓存行为 部分。 |
|
正在使用会话感知打开文件或设备。 如果未指定此标志，则会话 0 中运行的进程无法打开每个会话设备 (，例如使用 RemoteFX USB 重定向) 的设备。 此标志对不在会话 0 中的调用方不起作用。 此标志仅在 Windows 的服务器版本上受支持。
Windows Server 2008 R2 和 Windows Server 2008： 在 Windows Server 2012 之前，不支持此标志。 |
|
访问旨在从头到尾按顺序进行。 系统可将此选项用作优化文件缓存的提示。
如果读取隐藏 (即使用向后扫描) ，则不应使用此标志。 如果文件系统不支持缓存的 I/O 和 FILE_FLAG_NO_BUFFERING，则此标志不起作用。 有关详细信息，请参阅本主题的 缓存行为 部分。 |
|
写入操作不会经过任何中间缓存，它们将直接转到磁盘。
有关其他信息，请参阅本主题的 缓存行为 部分。 |
dwSecurityQosFlags
dwSecurityQosFlags 参数指定 SQOS 信息。 有关详细信息，请参阅 模拟级别。
lpSecurityAttributes
指向 SECURITY_ATTRIBUTES 结构的指针，该结构包含两个独立但相关的数据成员：可选的安全描述符，以及一个布尔值，该值确定是否可由子进程继承返回的句柄。
此参数可以为 NULL。
如果此参数为 NULL，则应用程序可能创建的任何子进程都不能继承 CreateFile2 返回的句柄，并且与返回的句柄关联的文件或设备将获取默认安全描述符。
结构的 lpSecurityDescriptor 成员指定文件或设备的 SECURITY_DESCRIPTOR 。 如果此成员为 NULL，则会为与返回的句柄关联的文件或设备分配默认安全描述符。
CreateFile2 在打开现有文件或设备时会忽略 lpSecurityDescriptor 成员，但继续使用 bInheritHandle 成员。
结构的 bInheritHandle 成员指定是否可以继承返回的句柄。
有关详细信息，请参阅 CreateFile2 主题的“备注”部分。
hTemplateFile
具有 GENERIC_READ 访问权限的模板文件的有效句柄。 模板文件为正在创建的文件提供文件属性和扩展属性。
此参数可以为 NULL。
打开现有文件时， CreateFile2 将忽略此参数。
打开新的加密文件时，该文件会从其父目录继承任意访问控制列表。 有关其他信息，请参阅 文件加密。
备注
若要编译使用 CREATEFILE2_EXTENDED_PARAMETERS 结构的应用程序，请将 _WIN32_WINNT 宏 0x0602 定义为 或更高版本。 有关详细信息，请参阅 使用 Windows 标头。
缓存行为
dwFileFlags 成员的多个可能值用于控制或影响系统缓存与句柄关联的数据的方式。 它们是：
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
如果未指定这些标志，则系统会使用默认的常规用途缓存方案。 否则，系统缓存的行为将按为每个标志指定。
其中一些标志不应组合使用。 例如，将 FILE_FLAG_RANDOM_ACCESS 与 FILE_FLAG_SEQUENTIAL_SCAN 相结合是自败的。
指定 FILE_FLAG_SEQUENTIAL_SCAN 标志可以提高使用顺序访问读取大型文件的应用程序的性能。 对于主要按顺序读取大型文件，但偶尔在较小的字节范围内向前跳过的应用程序，性能提升可能更加明显。 如果应用程序移动文件指针进行随机访问，则很可能不会出现最佳缓存性能。 但是，仍能保证正确的操作。
标志FILE_FLAG_WRITE_THROUGH和FILE_FLAG_NO_BUFFERING是独立的，可以组合使用。
如果使用 FILE_FLAG_WRITE_THROUGH 但未同时指定 FILE_FLAG_NO_BUFFERING ，则系统缓存生效，则数据将写入系统缓存，但会立即刷新到磁盘。
如果 同时指定了FILE_FLAG_WRITE_THROUGH 和 FILE_FLAG_NO_BUFFERING ，则系统缓存无效，则数据会立即刷新到磁盘，而无需通过 Windows 系统缓存。 操作系统还会请求将硬盘的本地硬件缓存写入永久性媒体。
注意
并非所有硬盘硬件都支持这种写通功能。
正确使用 FILE_FLAG_NO_BUFFERING 标志需要特殊的应用程序注意事项。 有关详细信息，请参阅 文件缓冲。
通过 FILE_FLAG_WRITE_THROUGH 的写通请求还会导致 NTFS 刷新处理请求导致的任何元数据更改，例如时间戳更新或重命名操作。 因此， FILE_FLAG_WRITE_THROUGH 标志通常与 FILE_FLAG_NO_BUFFERING 标志一起使用，作为每次写入后调用 FlushFileBuffers 函数的替代，这可能会导致不必要的性能损失。 将这些标志一起使用可避免这些处罚。 有关文件和元数据缓存的常规信息，请参阅 文件缓存。
当FILE_FLAG_NO_BUFFERING与FILE_FLAG_OVERLAPPED结合使用时，标志会提供最大的异步性能，因为 I/O 不依赖于内存管理器的同步操作。 但是，某些 I/O 操作需要更多时间，因为数据不会保留在缓存中。 此外，文件元数据仍可能缓存 (例如，在创建空文件时) 。 若要确保元数据刷新到磁盘，请使用 FlushFileBuffers 函数。
如果有足够的缓存内存可用，则指定 FILE_ATTRIBUTE_TEMPORARY 属性会导致文件系统避免将数据写回到大容量存储，因为应用程序在关闭句柄后会删除临时文件。 在这种情况下，系统可以完全避免写入数据。 尽管它不会像前面提到的标志那样直接控制数据缓存， 但 FILE_ATTRIBUTE_TEMPORARY 属性确实会告知系统在不写入的情况下尽可能多地保留系统缓存，因此某些应用程序可能很关注。
同步和异步 I/O 句柄
CreateFile2 提供用于创建同步或异步的文件或设备句柄。 同步句柄的行为使使用该句柄的 I/O 函数调用被阻止，直到它们完成，而异步文件句柄使系统能够立即从 I/O 函数调用返回，无论它们是否完成了 I/O 操作。 如前所述，此同步与异步行为是通过在 pCreateExParams 参数中传递的CREATEFILE2_EXTENDED_PARAMETERS结构的 dwFileFlags 成员中指定FILE_FLAG_OVERLAPPED来确定的。 使用异步 I/O 时，存在一些复杂性和潜在缺陷：有关详细信息，请参阅 同步和异步 I/O。
要求
| 最低受支持的客户端 | Windows 8 [桌面应用 |UWP 应用] |
| 最低受支持的服务器 | Windows Server 2012 [桌面应用 |UWP 应用] |
| 标头 | fileapi.h (包括 Windows.h) |