urlCombineA 函数 (shlwapi.h)

项目
08/26/2023

当提供相对 URL 及其基时，返回规范形式的 URL。

语法

LWSTDAPI UrlCombineA(
  [in]            PCSTR pszBase,
  [in]            PCSTR pszRelative,
  [out, optional] PSTR  pszCombined,
  [in, out]       DWORD *pcchCombined,
                  DWORD dwFlags
);

参数

[in] pszBase

类型： PCTSTR

指向包含基 URL 的最大长度INTERNET_MAX_URL_LENGTH以 null 结尾的字符串的指针。

[in] pszRelative

类型： PCTSTR

指向包含相对 URL 的最大长度为 null 的字符串INTERNET_MAX_URL_LENGTH的指针。

[out, optional] pszCombined

类型： PTSTR

指向缓冲区的指针，当此函数成功返回时，该缓冲区接收包含组合 URL 的以 null 结尾的字符串。

[in, out] pcchCombined

类型： DWORD*

指向某个值的指针，该值在输入时设置为 pszCombined 缓冲区中的字符数。当函数成功返回时，该值取决于函数是成功还是返回E_POINTER。对于其他返回值，此参数的值毫无意义。

dwFlags

类型：DWORD

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

URL_DONT_SIMPLIFY (0x08000000)

处理“/./”和“/.”。/' 在 URL 字符串中作为文本字符，而不是作为导航的速记。有关进一步讨论，请参阅备注。

URL_ESCAPE_PERCENT (0x00001000)

将“%”的任何匹配项转换为其转义序列。

URL_ESCAPE_SPACES_ONLY (0x04000000)

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

URL_ESCAPE_UNSAFE (0x20000000)

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

URL_NO_META

定义为与 URL_DONT_SIMPLIFY 相同。

URL_PLUGGABLE_PROTOCOL (0x40000000)

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

URL_UNESCAPE (0x10000000)

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

URL_ESCAPE_AS_UTF8 (0x00040000)

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

返回值

类型： HRESULT

返回标准 COM 错误代码，包括以下内容。

返回代码	说明
S_OK	pszCombined 指向包含组合 URL 的字符串。 pcchCombined 的值设置为字符串中的字符数，不计算终止 NULL 字符。
E_POINTER	缓冲区太小。 pcchCombined 的值设置为缓冲区必须能够包含的最小字符数，包括终止 NULL 字符。

注解

斜杠之间的项被视为分层标识符;最后一项指定文档本身。您必须在文档名称后输入斜杠 (/) 才能追加更多项;否则， UrlCombine 将一个文档交换另一个文档。例如：


hRetVal = UrlCombine(TEXT("http://xyz/test/abc"), 
                     TEXT("bar"), 
                     lpszCombined, 
                     &dwLength, 0);

上述代码返回 URL http://xyz/test/bar. 如果希望合并的 URL 为 http://xyz/test/abc/bar，请使用对 UrlCombine 的以下调用。


hRetVal = UrlCombine(TEXT("http://xyz/test/abc/"), 
                     TEXT("bar"), 
                     lpszCombined, 
                     &dwLength, 0);

如果 URL 字符串包含 '/.。/“或”/./“， UrlCombine 通常将字符视为它们指示 URL 层次结构中的导航。函数在合并 URL 之前简化这些 URL。例如，“/hello/cruel/.。/world“已简化为”/hello/world”。如果在 dwFlags 中设置了URL_DONT_SIMPLIFY标志，则函数不会简化 URL。在本例中，“/hello/cruel/.。/world“是原样。

注意

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

要求

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

另请参阅

处理统一资源定位符

UrlCanonicalize

通过