通过

UrlCanonicalizeA 函数 （shlwapi.h）

  • 项目

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

语法

LWSTDAPI UrlCanonicalizeA(
  [in]      PCSTR pszUrl,
  [out]     PSTR  pszCanonicalized,
  [in, out] DWORD *pcchCanonicalized,
            DWORD dwFlags
);

参数

[in] pszUrl

类型：PCTSTR

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

[out] pszCanonicalized

类型：PTSTR

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

[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 Professional、Windows XP [仅限桌面应用]
支持的最低服务器 Windows 2000 Server [仅限桌面应用]
目标平台 窗户
标头 shlwapi.h
库 Shlwapi.lib
DLL Shlwapi.dll （版本 5.0 或更高版本）

另请参阅

处理统一资源定位符