PathCchCanonicalizeEx 函数 (pathcch.h)

  • 项目

通过删除导航元素（如“.”和“...”）来简化路径，以生成格式正确的直接路径。

此函数不同于 PathCchCanonicalize ，因为它允许构造更长的最终路径。

此函数与 PathAllocCanonicalize 的不同之处在于，调用方必须声明返回的字符串的大小，该字符串存储在堆栈中。

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

注意 应使用此函数 PathCchCanonicalize 或 PathAllocCanonicalize 代替 PathCanonicalize ，以防止缓冲区溢出的可能性。

语法

WINPATHCCHAPI HRESULT PathCchCanonicalizeEx(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags
);

参数

[out] pszPathOut

指向缓冲区的指针，当此函数成功返回时，该缓冲区接收编辑的路径字符串。

[in] cchPathOut

pszPathOut 指向的缓冲区的大小（以字符为单位）。

[in] pszPathIn

指向原始路径字符串的指针。 如果此值为 NULL，指向空字符串，或在删除“.”和“...”元素后生成空字符串，则会将单个反斜杠复制到 pszPathOut 指向的缓冲区。

[in] dwFlags

以下一个或多个标志：

值 含义
PATHCCH_NONE
0x0000000
 不允许构造 \\？\ 路径 (即长路径) 长于 MAX_PATH 。
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 允许生成长于 MAX_PATH 的路径。 请注意， cchPathOut 必须大于 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 开始可用。

返回值

如果此函数成功，则返回 S_OK。 否则，它将返回 HRESULT 代码，包括但不限于以下内容。

返回代码 说明
E_INVALIDARG
 cchPathOut 值大于 PATHCCH_MAX_CCH。
PATHCCH_E_FILENAME_TOO_LONG
 路径段包含超过 PATHCCH_MAX_CCH 个字符，或者，如果未设置 PATHCCH_ALLOW_LONG_PATHS 标志，则超出标准路径段长度限制（256 个字符）。
E_OUTOFMEMORY
 函数无法分配所需大小的缓冲区。

注解

此函数响应路径中嵌入的字符串“.”和“..”。 “..”字符串指示删除紧靠前一个路径段。 “.”字符串指示跳过下一个路径段。 请注意，无法删除路径的根段。 如果“..”字符串多于路径段，则函数返回 S_OK 并且 pszPathOut 指向的缓冲区包含单个反斜杠“\”。

所有尾随句点都将从路径中删除，除非前面有“”野生卡字符。在这种情况下，在“”字符之后保留单个句点，但会删除所有其他尾随句点。

如果生成的路径是根驱动器 (“x：”) ，则会 (“x：\”) 追加反斜杠。

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

以下示例演示了这些字符串的效果。

原始字符串 规范化字符串
C：\name_1\.\name_2\..\name_3 C：\name_1\name_3
C：\name_1\..\name_2.\name_3 C：\name_2\name_3
C：\name_1\name_2\.\name_3\..\name_4 C：\name_1\name_2\name_4
C：\name_1\.\name_2\.\name_3\.。\name_4\.. C：\name_1\name_2
C：\name_1\*... C：\name_1\*。
C：\。。 C:\

要求

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

另请参阅

PathCchCanonicalize