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。 有关所有文件属性及其值和说明的完整列表,请参阅 文件属性常量。
属性 | 意义 |
---|---|
|
该文件应存档。 应用程序使用此属性标记文件以供备份或删除。 |
|
文件或目录已加密。 对于文件,这意味着文件中的所有数据都已加密。 对于目录,这意味着加密是新创建的文件和子目录的默认值。 有关详细信息,请参阅 文件加密。
如果还指定了 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 操作,即使对读取和写入函数的调用指定了 重叠 结构也是如此。 有关使用此标志创建的文件句柄时的注意事项,请参阅本主题的 同步和异步 I/O 句柄 部分。 |
|
访问将按照 POSIX 规则进行。 这包括允许具有名称的多个文件,仅在支持该命名的文件系统时有所不同。 使用此选项时请小心,因为使用此标志创建的文件可能无法由为 MS-DOS 或 16 位 Windows 编写的应用程序访问。 |
|
访问旨在随机访问。 系统可以将其用作优化文件缓存的提示。
如果文件系统不支持缓存的 I/O 并 FILE_FLAG_NO_BUFFERING,则此标志无效。 有关详细信息,请参阅本主题的 缓存行为 部分。 |
|
正在打开具有会话感知的文件或设备。 如果未指定此标志,则会话中运行的进程无法打开每个会话设备(例如使用 RemoteFX USB 重定向的设备)。 此标志对会话 0 中不具有调用方的影响。 此标志仅在 Windows 的服务器版本上受支持。
Windows Server 2008 R2 和 Windows Server 2008: Windows Server 2012 之前不支持此标志。 |
|
Access 旨在从头到尾的顺序。 系统可以将其用作优化文件缓存的提示。
如果使用读后(即向后扫描),则不应使用此标志。 如果文件系统不支持缓存的 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) |