urlCanonicalizeA 函数 (shlwapi.h)

  • 项目

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

语法

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

参数

[in] pszUrl

类型： PCTSTR

指向包含 URL 字符串的最大长度INTERNET_MAX_URL_LENGTH以 null 结尾的字符串的指针。 如果字符串不引用文件，则它必须包含“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 专业版、Windows XP [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 shlwapi.h
Library Shlwapi.lib
DLL Shlwapi.dll (5.0 或更高版本)

另请参阅

处理统一资源定位符