通过

PathAllocCanonicalize 函数 （pathcch.h）

  • 项目

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

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

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

Note This function， PathCchCanonicalize， or PathCchCanonicalizeEx， should be used in place of 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 开始可用。
PATHCCH_CANONICALIZE_SLASHES
0x00000040
 将正斜杠转换为反斜杠并折叠多个斜杠。

注意 此值从 Windows 11 开始提供（SDK 版本 10.0.22000.194）。

[out] ppszPathOut

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

返回值

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

言论

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

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

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

要求

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