CREATEFILE3_EXTENDED_PARAMETERS结构（fileapi.h）

包含 CreateFile3 的可选扩展参数。

语法

typedef struct _CREATEFILE3_EXTENDED_PARAMETERS {
  DWORD                 dwSize;
  DWORD                 dwFileAttributes;
  DWORD                 dwFileFlags;
  DWORD                 dwSecurityQosFlags;
  LPSECURITY_ATTRIBUTES lpSecurityAttributes;
  HANDLE                hTemplateFile;
} CREATEFILE3_EXTENDED_PARAMETERS, *PCREATEFILE3_EXTENDED_PARAMETERS, *LPCREATEFILE3_EXTENDED_PARAMETERS;

成员

dwSize

包含此结构的大小，sizeof(CREATEFILE3_EXTENDED_PARAMETERS)。

dwFileAttributes

文件或设备属性和标志，FILE_ATTRIBUTE_NORMAL 是文件最常见的默认值。

此参数可以包含可用文件属性的任意组合（FILE_ATTRIBUTE_*）。 所有其他文件属性都替代 FILE_ATTRIBUTE_NORMAL。

以下某些文件属性和标志可能仅适用于文件，不一定是 CreateFile3 可以打开的所有其他类型的设备。 有关详细信息，请参阅 CreateFile3 参考页的“备注”部分和“创建和打开文件”。

有关对文件属性的更高级访问，请参阅 SetFileAttributes。 有关所有文件属性及其值和说明的完整列表，请参阅 文件属性常量。

dwFileFlags

此参数可以包含标志（FILE_FLAG_*）的组合，用于控制文件或设备缓存行为、访问模式和其他特殊用途标志。

dwSecurityQosFlags

dwSecurityQosFlags 参数指定 SQOS 信息。 有关详细信息，请参阅 模拟级别。

lpSecurityAttributes

指向包含两个独立但相关数据成员的 SECURITY_ATTRIBUTES 结构的指针：可选的安全描述符，以及一个布尔值，该值确定是否可由子进程继承返回的句柄。

此参数可以是 NULL.

如果此参数是 NULL，则 由 CreateFile3 返回的句柄不能由应用程序可能创建的任何子进程继承，并且与返回的句柄关联的文件或设备将获得默认的安全描述符。

结构的 lpSecurityDescriptor 成员指定文件或设备的 SECURITY_DESCRIPTOR。 如果此成员是 NULL，则向与返回的句柄关联的文件或设备分配默认安全描述符。

CreateFile3 在打开现有文件或设备时忽略 lpSecurityDescriptor 成员，但继续使用 bInheritHandle 成员。

bInheritHandle 结构的成员指定是否可以继承返回的句柄。

有关详细信息，请参阅 CreateFile3 主题的“备注”部分。

hTemplateFile

具有 GENERIC_READ 访问权限的模板文件的有效句柄。 模板文件为正在创建的文件提供文件属性和扩展属性。

此参数可以是 NULL.

打开现有文件时， CreateFile3 将忽略此参数。

打开新的加密文件时，该文件从其父目录继承自由访问控制列表。 有关详细信息，请参阅 文件加密。

注解

若要编译使用 CREATEFILE3_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 句柄

CreateFile3 提供用于创建同步或异步的文件或设备句柄。 同步句柄的行为使使用该句柄的 I/O 函数调用被阻止，直到它们完成，而异步文件句柄使系统能够立即从 I/O 函数调用返回，无论它们是否已完成 I/O 操作。 如前所述，此同步与异步行为是通过在 lpCreateExParams 参数中传递的 CREATEFILE3_EXTENDED_PARAMETERS 结构的 dwFileFlags 成员中指定FILE_FLAG_OVERLAPPED来确定的。 使用异步 I/O 时，存在多种复杂性和潜在缺陷;有关详细信息，请参阅 同步和异步 I/O。

要求

另请参阅

CreateFile3

文件管理结构