UrlCanonicalizeA 函式 (shlwapi.h)

將 URL 字串轉換成標準格式。

語法

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

參數

[in] pszUrl

類型： PCTSTR

包含 URL 字串的 null 終止字串指標，長度上限為INTERNET_MAX_URL_LENGTH。 若字串並非指向檔案，則必須包含有效的配置 (例如 "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)

將 Unsafe 字元取代為其逸出序列。 不安全的字元是在網際網路傳輸期間可能會改變的字元，並包含 (< 、 > 、「、#、{、}、|、、^、[、]、[、] 和 ') 字元。 此旗標適用於所有 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/quiet/.。/world「 已簡化為 」/hello/world」。 在此預設行為的例外狀況發生于下列情況下：

• 如果 URL_DONT_SIMPLIFY 旗標是在 dwFlags中設定，則函式不會簡化 URL。 在此案例中為 「/hello/inpage/../world「 會保持原樣。
• 如果為 「/../「 或 」/./「 是路徑中的第一個區段 (，例如」 http://domain/../path1/path2/file.htm 「) ， UrlCanonicalize 會輸出與輸入完全相同的路徑。

規格需求

另請參閱

處理統一資源定位器