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。

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

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

Value 含义
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 相关的标志信息显示在属性和标志表后面的表中。

Attribute 含义
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

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

访问旨在从头到尾按顺序进行。 系统可将此选项用作优化文件缓存的提示。

如果读取隐藏 (即使用反向扫描) ，则不应使用此标志。

如果文件系统不支持缓存的 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