PathAllocCanonicalize 函数 (pathcch.h)

  • 项目

将路径字符串转换为规范形式。

此函数不同于 PathCchCanonicalize 和 PathCchCanonicalizeEx ，因为它在堆上返回结果。 这意味着调用方不必声明返回的字符串的大小，减少了堆栈的使用。

此函数不同于 PathCanonicalize ，因为它接受前缀为“\”、“\？”和“\？\UNC”的路径。

注意 应使用此函数 PathCchCanonicalize 或 PathCchCanonicalizeEx 代替 PathCanonicalize。

语法

WINPATHCCHAPI HRESULT PathAllocCanonicalize(
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags,
  [out] PWSTR  *ppszPathOut
);

参数

[in] pszPathIn

指向包含原始字符串的缓冲区的指针。 此值不能为 NULL。

[in] dwFlags

以下一个或多个标志：

值 含义
PATHCCH_NONE
0x0000000
 不允许构造 \\？\ 路径 (即长路径) 长于 MAX_PATH 。
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 允许生成长于 MAX_PATH 的路径。
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS
0x00000002
 强制 API 将调用方视为已启用长路径，这与进程的长名称启用状态无关。 仅当指定 了PATHCCH_ALLOW_LONG_PATHS 时才可使用此选项，不能与 PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS 一起使用。

注意此值从 Windows 10 版本 1703 开始可用。
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS
0x00000004
 强制 API 将调用方视为已禁用的长路径，与进程的长名称启用状态无关。 仅当指定 PATHCCH_ALLOW_LONG_PATHS 时才可使用此选项，不能与 PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS 一起使用。

注意此值从 Windows 10 版本 1703 开始可用。
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS
0x00000008
 禁用路径段的规范化，包括删除尾随点和空格。 这样就可以访问 win32 路径规范化将阻止的路径。

注意此值从 Windows 10 版本 1703 开始可用。
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH
0x00000010
 将输入路径转换为具有 \\？\ 前缀) 的扩展长度 DOS 设备路径窗体 (（如果尚未在该窗体中）。 这样就可以访问由于 Win32 规范化规则 (而无法寻址的路径，这些规则可以去除尾随点和空格) 和路径长度限制。 此选项意味着 PATHCCH_DO_NOT_NORMALIZE_SEGMENTS的行为相同。

注意此值从 Windows 10 版本 1703 开始可用。
PATHCCH_ENSURE_TRAILING_SLASH
0x00000020
 组合或规范化路径时，请确保存在尾随反斜杠。

注意此值从 Windows 10 版本 1703 开始可用。

[out] ppszPathOut

指向缓冲区的指针的地址，当此函数成功返回时，该缓冲区接收规范化路径字符串。 当不再需要此资源时，调用方有责任通过调用 LocalFree 函数来释放此资源。 此值不能为 NULL。

返回值

如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。

注解

此函数支持以下备用路径形式：

  • \\?\
  • \\？\\Unc\
  • \\？\Volume{guid}\

此函数不会将 /) (正斜杠转换为 (\) 的反斜杠。 对于不受信任的输入，此函数本身不能用于将路径转换为可与子路径或标识的其他路径进行比较的形式。 需要该功能的调用方应在使用此函数之前将正斜杠转换为反斜杠。

要求

要求 值
最低受支持的客户端 Windows 8 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2012 [桌面应用 |UWP 应用]
目标平台 Windows
标头 pathcch.h
Library Pathcch.lib