UrlCombineA 函式 (shlwapi.h)

發行項
03/13/2024

當提供相對 URL 及其基底時，會以標準形式傳回 URL。

語法

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

參數

[in] pszBase

類型： PCTSTR

包含基底 URL 之長度上限之 null 終止字串的指標INTERNET_MAX_URL_LENGTH。

[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)

將 Unsafe 字元取代為其逸出序列。不安全字元是在因特網傳輸期間可能改變的字元，並包含 (<、 >“、”、#、{、}、|、、^、~、[、]、和 ') 字元。此旗標適用於所有 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/quiet/.。/world“ 已簡化為 ”/hello/world“。如果在 dwFlags 中設定URL_DONT_SIMPLIFY旗標，函式就不會簡化 URL。在此案例中為「hello/quiet/.。/world“ 會保持原樣。

注意

shlwapi.h 標頭會將 UrlCombine 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional、Windows XP [僅限桌面應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	shlwapi.h
程式庫	Shlwapi.lib
Dll	Shlwapi.dll (5.0 版或更新版本)

另請參閱

處理統一資源定位器

UrlCanonicalize

共用方式為