UrlCanonicalizeW 函数 (shlwapi.h)

项目
08/26/2023

将 URL 字符串转换为规范格式。

语法

LWSTDAPI UrlCanonicalizeW(
  [in]      PCWSTR pszUrl,
  [out]     PWSTR  pszCanonicalized,
  [in, out] DWORD  *pcchCanonicalized,
            DWORD  dwFlags
);

参数

[in] pszUrl

类型： PCTSTR

指向包含 URL 字符串的最大长度为 null 的字符串INTERNET_MAX_URL_LENGTH的指针。如果字符串不引用文件，则它必须包含“http://”等有效的方案。

[out] pszCanonicalized

类型： PTSTR

指向缓冲区的指针，当此函数成功返回时，该缓冲区以 null 结尾的字符串的形式接收转换后的 URL。

[in, out] pcchCanonicalized

类型： DWORD*

指向值的指针，该值在输入时设置为 pszCanonicalized 缓冲区中的字符数。

dwFlags

类型：DWORD

指定如何将 URL 转换为规范形式的标志。可以组合以下标志。

URL_UNESCAPE (0x10000000)

取消转义 URL 包含的任何转义序列，但有两个例外。未对“?”和“#”的转义序列进行转回操作。如果同时设置了URL_ESCAPE_XXX标志之一，则先取消转义两个 URL，然后组合，然后转义。

URL_ESCAPE_UNSAFE (0x20000000)

用转义序列替换不安全字符。不安全字符是在 Internet 传输期间可能会更改的字符，包括 (<、 >、、#、{、}、|、^、[、]和') 字符。此标志适用于所有 URL，包括非跳转 URL。

URL_PLUGGABLE_PROTOCOL (0x40000000)

根据 W3C 规范，将 URL 与客户端定义的可插入协议组合在一起。此标志不适用于 FTP、HTTP 和 Gopher 等标准协议。如果设置了此标志，则 UrlCombine 不会简化 URL，因此无需同时设置 URL_DONT_SIMPLIFY。

URL_ESCAPE_SPACES_ONLY (0x04000000)

只用转义序列替换空格。此标志优先于 URL_ESCAPE_UNSAFE，但不适用于不透明的 URL。

URL_DONT_SIMPLIFY (0x08000000)

将 URL 字符串中的“/./”和“/../”视为文本字符，而不是导航的简写。有关进一步讨论，请参阅备注。

URL_NO_META (0x08000000)

定义为与 URL_DONT_SIMPLIFY 相同。

URL_ESCAPE_PERCENT (0x00001000)

将出现的所有“%”转换为其转义序列。

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 及更高版本。将所有非 ASCII 字符作为其 UTF-8 等效项进行百分比编码。

返回值

类型： HRESULT

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

注解

此函数执行诸如将不安全字符替换为其转义序列和折叠序列（如“.....”）等任务。

如果 URL 字符串包含“/.”。/“或”/./“， UrlCanonicalize 将字符视为指示 URL 层次结构中的导航。函数在合并 URL 之前简化这些 URL。例如“/hello/cruel/.”。/world“已简化为”/hello/world”。此默认行为在以下情况下发生异常：

如果在 dwFlags 中设置了URL_DONT_SIMPLIFY标志，则函数不会简化 URL。在本例中，“/hello/cruel/.。/world“是原样。
如果为“/.”。/“或”/./“是路径中的第一个段， (例如”“http://domain/../path1/path2/file.htm) ，UrlCanonicalize 输出路径与输入完全一样。

注意

shlwapi.h 标头将 UrlCanonicalize 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 专业版、Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	shlwapi.h
Library	Shlwapi.lib
DLL	Shlwapi.dll (5.0 或更高版本)

另请参阅

处理统一资源定位符

通过