createFile2FromAppW 函数 (fileapifromapp.h)

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

语法

WINSTORAGEAPI HANDLE CreateFile2FromAppW(
  LPCWSTR                           lpFileName,
  DWORD                             dwDesiredAccess,
  DWORD                             dwShareMode,
  DWORD                             dwCreationDisposition,
  LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
) noexcept;

参数

lpFileName

要创建或打开的文件或设备的名称。

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

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

有关在不附加“\\？\”的情况下选择退出 MAX_PATH 限制的信息，请参阅 命名文件、路径和命名空间 的“最大路径长度限制”部分以了解详细信息。

dwDesiredAccess

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

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

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

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

dwShareMode

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

如果此参数为零且函数成功，则在关闭文件或设备的句柄之前，无法共享文件或设备，并且无法再次打开。 有关详细信息，请参见“备注”部分。

不能请求与具有打开句柄的现有请求中指定的访问模式冲突的共享模式。 此函数将失败， GetLastError 函数将返回 ERROR_SHARING_VIOLATION。

若要使某个进程能够在另一个进程打开文件或设备时共享文件或设备，请使用以下一个或多个值的兼容组合。 有关此参数与 dwDesiredAccess 参数的有效组合的详细信息，请参阅 创建和打开文件。

注意 每个打开的句柄的共享选项一直有效，直到该句柄关闭，而不考虑进程上下文。

 

值	含义
0 0x00000000	阻止其他进程在请求删除、读取或写入访问权限时打开文件或设备。 仅当应用程序对文件具有写入访问权限时，才授予对文件或目录的独占访问权限。
FILE_SHARE_DELETE 0x00000004	启用文件或设备上的后续打开操作以请求删除访问权限。 否则，如果其他进程请求删除访问权限，则无法打开文件或设备。 如果未指定此标志，但已打开文件或设备进行删除访问，则函数将失败。 注意 删除访问权限允许删除和重命名操作。
FILE_SHARE_READ 0x00000001	启用文件或设备上的后续打开操作以请求读取访问权限。 否则，如果其他进程请求读取访问权限，则无法打开文件或设备。 如果未指定此标志，但已打开文件或设备进行读取访问，则函数将失败。 如果正在打开文件或目录，并且未指定此标志，并且调用方对文件或目录没有写入访问权限，则函数将失败。
FILE_SHARE_WRITE 0x00000002	启用文件或设备上的后续打开操作以请求写入访问权限。 否则，如果其他进程请求写入访问权限，则无法打开文件或设备。 如果未指定此标志，但文件或设备已打开进行写入访问，或者具有具有写入访问权限的文件映射，则函数将失败。

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 参数的一部分。

pCreateExParams

指向可选 CREATEFILE2_EXTENDED_PARAMETERS 结构的指针。

返回值

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

如果函数失败，则返回值为 INVALID_HANDLE_VALUE。 要获得更多的错误信息，请调用 GetLastError。

要求

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