UrlCanonicalizeW 函式 (shlwapi.h)
將 URL 字串轉換成標準格式。
語法
LWSTDAPI UrlCanonicalizeW(
[in] PCWSTR pszUrl,
[out] PWSTR 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 會輸出與輸入完全相同的路徑。
注意
shlwapi.h 標頭會將 UrlCanonicalize 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows 2000 專業版、Windows XP [僅限傳統型應用程式] |
最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | shlwapi.h |
程式庫 | Shlwapi.lib |
Dll | Shlwapi.dll (5.0 版或更新版本) |