InternetCanonicalizeUrlA 函数 (wininet.h)

  • 项目

规范化 URL，包括将不安全的字符和空格转换为转义序列。

语法

BOOL InternetCanonicalizeUrlA(
  [in]      LPCSTR  lpszUrl,
  [out]     LPSTR   lpszBuffer,
  [in, out] LPDWORD lpdwBufferLength,
  [in]      DWORD   dwFlags
);

参数

[in] lpszUrl

指向包含要规范化的 URL 的字符串的指针。

[out] lpszBuffer

指向接收生成的规范化 URL 的缓冲区的指针。

[in, out] lpdwBufferLength

指向变量的指针，该变量包含 lpszBuffer 缓冲区的大小（以字符为单位）。 如果函数成功，此参数将接收实际复制到 lpszBuffer 缓冲区的字符数，该缓冲区不包括终止 null 字符。 如果函数失败，此参数将接收所需的缓冲区大小（以字符为单位），其中包括终止 null 字符。

[in] dwFlags

控制规范化。 如果未指定标志，该函数会将所有不安全字符和元序列 (（如 .、\ ..和 ...) ）转换为转义序列。 此参数的取值可为下列值之一：

值 含义
ICU_BROWSER_MODE
 不对“#”或“？”之后的字符进行编码或解码，也不删除“？”之后的尾随空格。 如果未指定此值，则会对整个 URL 进行编码，并删除尾部空格。
ICU_DECODE
 在分析 URL 之前，将所有 %XX 序列转换为字符，包括转义序列。
ICU_ENCODE_PERCENT
 对遇到的任何百分号进行编码。 默认情况下，不编码百分比符号。 此值在 Microsoft Internet Explorer 5 及更高版本中可用。
ICU_ENCODE_SPACES_ONLY
 仅对空格进行编码。
ICU_NO_ENCODE
 不将不安全字符转换为转义序列。
ICU_NO_META
 不删除 (元序列，如“.”和“.”。从 URL ) 。

返回值

如果成功，则返回 TRUE ，否则返回 FALSE 。 若要获得更多的错误信息，请调用 GetLastError 函数。 可能的错误包括以下内容。

返回代码 说明
ERROR_BAD_PATHNAME
 无法对 URL 进行规范化。
ERROR_INSUFFICIENT_BUFFER
 规范化的 URL 太大，无法容纳在提供的缓冲区中。 lpdwBufferLength 参数设置为保存规范化 URL 所需的缓冲区的大小（以字节为单位）。
ERROR_INTERNET_INVALID_URL
 URL 的格式无效。
ERROR_INVALID_PARAMETER
 存在无效的字符串、缓冲区、缓冲区大小或标志参数。

注解

在 Internet Explorer 4.0 及更高版本中， InternetCanonicalizeUrl 的功能始终与设置 ICU_BROWSER_MODE 标志一样。 必须规范化整个 URL 的客户端应用程序应将 CoInternetParseUrl (与操作 PARSE_CANONICALIZE 和标志 URL_ESCAPE_UNSAFE) 或 UrlCanonicalize 一起使用。

InternetCanonicalizeUrl 默认始终进行编码，即使已指定 ICU_DECODE 标志也是如此。 若要在不重新编码的情况下解码，请使用 ICU_DECODE | ICU_NO_ENCODE。 如果在不使用ICU_NO_ENCODE的情况下使用 ICU_DECODE 标志，则会在分析前解码 URL;然后，在分析后重新编码不安全字符。 此函数处理任意协议方案，但为此，它必须从不安全字符集进行推理。

使用 Internet Explorer 3.0 (或为 Internet Explorer 5 及更高版本设置ICU_ENCODE_PERCENT标志时调用 InternetCanonicalizeUrl 的应用程序) 应跟踪此函数在特定 URL 上的使用情况。 如果 URL 中的不安全字符已转换为转义序列，则再次在 URL (上使用 InternetCanonicalizeUrl ，不带标志) 会导致转义序列转换为另一个转义序列。 例如，URL 中的空格将转换为转义序列 %20。 在 URL 上再次调用 InternetCanonicalizeUrl 将导致转义序列 %20 转换为转义序列 %2520，因为 % 符号是一个不安全的字符，是为转义序列保留的，并且由具有转义序列 %25 的 函数替换。

与 WinINet API 的所有其他方面一样，无法从 DllMain 或全局对象的构造函数和析构函数中安全地调用此函数。

注意 WinINet 不支持服务器实现。 此外，不应从服务使用它。 对于服务器实现或服务，请使用 Microsoft Windows HTTP Services (WinHTTP) 。
 

注意

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

要求

   
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 wininet.h
Library Wininet.lib
DLL Wininet.dll

另请参阅

处理统一资源定位符

WinINet 函数