通过

CreateFileFromAppW 函数（fileapifromapp.h）

  • 项目

创建或打开文件或 I/O 设备。 此函数的行为与 CreateFile相同，只不过此函数遵循通用 Windows 平台应用安全模型。

语法

WINSTORAGEAPI HANDLE CreateFileFromAppW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
) noexcept;

参数

lpFileName

要创建或打开的文件或设备的名称。 可以在此名称中使用正斜杠 （/） 或反斜杠 （\）。

在此函数的 ANSI 版本中，名称限制为 MAX_PATH 个字符。 若要将此限制扩展到 32,767 宽字符，请调用函数的 Unicode 版本，并将“\\？\”追加到路径。 有关详细信息，请参阅 命名文件、路径和命名空间。

有关特殊设备名称的信息，请参阅 定义 MS-DOS 设备名称。

若要创建文件流，请指定文件的名称、冒号，然后指定流的名称。 有关详细信息，请参阅 文件流。

对于此函数的 unicode 版本（CreateFileFromAppW），可以选择删除 MAX_PATH 限制，而无需追加“\\？\”。 有关详细信息，请参阅 命名文件、路径和命名空间 的“最大路径长度限制”部分。

dwDesiredAccess

请求对文件或设备的访问权限，可以汇总为读取、写入或两者均未进行零访问。

最常用的值是 GENERIC_READ、GENERIC_WRITE或两者（GENERIC_READ | GENERIC_WRITE）。 有关详细信息，请参阅 通用访问权限、文件安全性和访问权限、文件访问权限常量和 ACCESS_MASK。

如果此参数为零，则应用程序可以在不访问该文件或设备的情况下查询某些元数据（如文件、目录或设备属性），即使拒绝 GENERIC_READ 访问也是如此。

不能请求与共享模式冲突的访问模式，该模式由 dwShareMode 参数指定的打开请求中已具有打开句柄。

dwShareMode

请求的文件或设备的共享模式，可以读取、写入、删除、所有这些或无（请参阅下表）。 对属性或扩展属性的访问请求不受此标志的影响。

价值 意义
0 0x00000000

如果其他进程请求删除、读取或写入访问权限，则阻止其他进程打开文件或设备。
FILE_SHARE_DELETE 0x00000004

启用对文件或设备上的后续打开操作以请求删除访问权限。

否则，如果进程请求删除访问权限，则无法打开文件或设备。

如果未指定此标志，但文件或设备已打开以删除访问权限，则函数将失败。

注释 删除访问权限允许删除和重命名操作。
 
FILE_SHARE_READ 0x00000001

允许对文件或设备执行后续打开操作以请求读取访问权限。

否则，如果进程请求读取访问权限，则其他进程无法打开文件或设备。

如果未指定此标志，但已打开文件或设备进行读取访问，则函数将失败。
FILE_SHARE_WRITE 0x00000002

允许对文件或设备执行后续打开操作以请求写入访问权限。

否则，如果进程请求写入访问权限，则其他进程无法打开文件或设备。

如果未指定此标志，但已打开文件或设备进行写入访问或具有写入访问权限的文件映射，则函数将失败。

lpSecurityAttributes

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

此参数可以 NULL。

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

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

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

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

dwCreationDisposition

对存在或不存在的文件或设备执行的操作。

对于文件以外的设备，此参数通常设置为 OPEN_EXISTING。

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

此参数必须是以下值之一，不能组合这些值：

价值 意义
CREATE_ALWAYS 2

始终创建新文件。

如果指定的文件存在且可写，则函数将截断文件、函数成功，最后错误代码设置为 ERROR_ALREADY_EXISTS（183）。

如果指定的文件不存在且路径有效，则会创建一个新文件，该函数会成功，最后一个错误代码设置为零。

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

仅当该文件尚不存在时，才会创建一个新文件。

如果指定的文件存在，函数将失败，最后一个错误代码设置为 ERROR_FILE_EXISTS（80）。

如果指定的文件不存在，并且是可写位置的有效路径，则会创建一个新文件。
OPEN_ALWAYS 4

始终打开文件。

如果指定文件存在，则函数成功，最后一个错误代码设置为 ERROR_ALREADY_EXISTS（183）。

如果指定的文件不存在并且是可写位置的有效路径，该函数将创建一个文件，最后一个错误代码设置为零。
OPEN_EXISTING 3

仅当文件或设备存在时才打开该文件或设备。

如果指定的文件或设备不存在，该函数将失败，最后一个错误代码设置为 ERROR_FILE_NOT_FOUND（2）。

有关设备的详细信息，请参阅“备注”部分。
TRUNCATE_EXISTING 5

打开一个文件并截断它，使其大小为零字节，仅当它存在时。

如果指定的文件不存在，该函数将失败，最后一个错误代码设置为 ERROR_FILE_NOT_FOUND（2）。

调用过程必须打开文件，并将 GENERIC_WRITE 位设置为 dwDesiredAccess 参数的一部分。

dwFlagsAndAttributes

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

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

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

此参数还可以通过指定 SECURITY_SQOS_PRESENT 标志来包含安全服务质量（SQOS）信息。 下表中显示了与 SQOS 相关的其他标志信息，这些属性和标志表如下。

属性 意义
FILE_ATTRIBUTE_ARCHIVE 32 （0x20）

该文件应存档。 应用程序使用此属性标记文件以供备份或删除。
FILE_ATTRIBUTE_ENCRYPTED 16384 （0x4000）

文件或目录已加密。 对于文件，这意味着文件中的所有数据都已加密。 对于目录，这意味着加密是新创建的文件和子目录的默认值。 有关详细信息，请参阅 文件加密。

如果还指定了 FILE_ATTRIBUTE_SYSTEM，则此标志无效。

家庭版、家庭高级版、入门版或 ARM 版 Windows 不支持此标志。
FILE_ATTRIBUTE_HIDDEN 2 （0x2）

文件已隐藏。 不要将其包含在普通目录列表中。
FILE_ATTRIBUTE_NORMAL 128 （0x80）

该文件没有设置其他属性。 仅当单独使用时，此属性才有效。
FILE_ATTRIBUTE_OFFLINE 4096 （0x1000）

文件的数据不会立即可用。 此属性指示文件数据在物理上移动到脱机存储。 此属性由远程存储（分层存储管理软件）使用。 应用程序不应任意更改此属性。
FILE_ATTRIBUTE_READONLY 1 （0x1）

该文件是只读的。 应用程序可以读取文件，但无法写入或删除该文件。
FILE_ATTRIBUTE_SYSTEM 4 （0x4）

该文件是操作系统的一部分或独占使用。
FILE_ATTRIBUTE_TEMPORARY 256 （0x100）

该文件用于临时存储。

有关详细信息，请参阅本主题的“缓存行为”部分。

 

旗 意义
FILE_FLAG_BACKUP_SEMANTICS 0x02000000

正在为备份或还原操作打开或创建该文件。 当进程具有 SE_BACKUP_NAME 和 SE_RESTORE_NAME 特权时，系统可确保调用进程替代文件安全检查。 有关详细信息，请参阅 更改令牌中的特权。

必须设置此标志才能获取目录的句柄。 目录句柄可以传递给某些函数，而不是文件句柄。 有关详细信息，请参阅“备注”部分。
FILE_FLAG_DELETE_ON_CLOSE 0x04000000

文件将在关闭所有句柄后立即删除，其中包括指定的句柄和任何其他打开或重复的句柄。

如果文件存在现有的打开句柄，则调用将失败，除非它们都以 FILE_SHARE_DELETE 共享模式打开。

文件的后续打开请求失败，除非指定了 FILE_SHARE_DELETE 共享模式。
FILE_FLAG_NO_BUFFERING 0x20000000

文件或设备正在打开，没有数据读取和写入的系统缓存。 此标志不会影响硬盘缓存或内存映射文件。

使用 FILE_FLAG_NO_BUFFERING 标志成功处理使用此函数打开的文件有严格的要求，有关详细信息，请参阅 文件缓冲。
FILE_FLAG_OPEN_NO_RECALL 0x00100000

请求文件数据，但它应继续位于远程存储中。 不应将其传输回本地存储。 此标志供远程存储系统使用。
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000

正常 重新分析点 处理不会发生;此函数将尝试打开重新分析点。 打开文件时，将返回文件句柄，无论控制重新分析点的筛选器是否正常运行。

此标志不能与 CREATE_ALWAYS 标志一起使用。

如果文件不是重新分析点，则忽略此标志。

有关详细信息，请参阅“备注”部分。
FILE_FLAG_OVERLAPPED 0x40000000

文件或设备正在为异步 I/O 打开或创建。

在此句柄上完成后续 I/O 操作时，OVERLAPPED 结构中指定的事件将设置为信号状态。

如果指定了此标志，则文件可用于同时读取和写入操作。

如果未指定此标志，则将序列化 I/O 操作，即使对读取和写入函数的调用指定了 OVERLAPPED 结构也是如此。

有关使用此标志创建的文件句柄时的注意事项的信息，请参阅本主题的“同步和异步 I/O 句柄”部分。
FILE_FLAG_POSIX_SEMANTICS 0x0100000

访问将按照 POSIX 规则进行。 这包括允许具有名称的多个文件，仅在支持该命名的文件系统时有所不同。 使用此选项时请小心，因为使用此标志创建的文件可能无法由为 MS-DOS 或 16 位 Windows 编写的应用程序访问。
FILE_FLAG_RANDOM_ACCESS 0x10000000

访问旨在随机访问。 系统可以将其用作优化文件缓存的提示。

如果文件系统不支持缓存的 I/O 并 FILE_FLAG_NO_BUFFERING，则此标志无效。

有关详细信息，请参阅本主题的“缓存行为”部分。
FILE_FLAG_SESSION_AWARE 0x00800000

正在打开具有会话感知的文件或设备。 如果未指定此标志，则会话中运行的进程无法打开每个会话设备（例如使用 RemoteFX USB 重定向的设备）。 此标志对会话 0 中不具有调用方的影响。 此标志仅在 Windows 的服务器版本上受支持。
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000

Access 旨在从头到尾的顺序。 系统可以将其用作优化文件缓存的提示。

如果使用读后（即反向扫描），则不应使用此标志。

如果文件系统不支持缓存的 I/O 并 FILE_FLAG_NO_BUFFERING，则此标志无效。

有关详细信息，请参阅本主题的“缓存行为”部分。
FILE_FLAG_WRITE_THROUGH 0x80000000

写入操作不会经历任何中间缓存，它们将直接转到磁盘。

有关详细信息，请参阅本主题的“缓存行为”部分。

 

dwFlagsAndAttributes参数还可以指定 SQOS 信息。 有关详细信息，请参阅 模拟级别。 当调用应用程序将 SECURITY_SQOS_PRESENT 标志指定为 dwFlagsAndAttributes的一部分时，它还可以包含以下一个或多个值。

安全标志 意义
SECURITY_ANONYMOUS

在匿名模拟级别模拟客户端。
SECURITY_CONTEXT_TRACKING

安全跟踪模式是动态的。 如果未指定此标志，则安全跟踪模式是静态的。
SECURITY_DELEGATION

在委派模拟级别模拟客户端。
SECURITY_EFFECTIVE_ONLY

只有客户端安全上下文的启用方面可供服务器使用。 如果未指定此标志，则客户端安全上下文的所有方面都可用。

这允许客户端限制服务器在模拟客户端时可以使用的组和特权。
SECURITY_IDENTIFICATION

在标识模拟级别模拟客户端。
SECURITY_IMPERSONATION

在模拟级别模拟客户端。 如果未指定其他标志以及 SECURITY_SQOS_PRESENT 标志，则这是默认行为。

hTemplateFile

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

此参数可以 NULL。

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

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

返回值

如果函数成功，则返回值是指定文件、设备、命名管道或邮件槽的打开句柄。

如果函数失败，则返回值 INVALID_HANDLE_VALUE。 若要获取扩展的错误信息，请调用 GetLastError。

要求

要求 价值
最低支持的客户端 Windows 10 版本 1803
标头 fileapifromapp.h