UrlEscapeW 函式 （shlwapi.h）
將 URL 中的字元或代理組，在因特網傳輸期間可能改變的字元或代理組，轉換為其對應的逸出序列。 Surrogate 字組介於 U+10000 到 U+10FFFF 之間（在 UTF-32 中）或 DC00 到 DFFF 之間（在 UTF-16 中）。
語法
LWSTDAPI UrlEscapeW(
[in] PCWSTR pszUrl,
[out] PWSTR pszEscaped,
[in, out] DWORD *pcchEscaped,
DWORD dwFlags
);
參數
[in] pszUrl
類型：PCTSTR
長度上限為 null 的字串，INTERNET_MAX_URL_LENGTH 包含完整或部分 URL，適用於 dwFlags 中的值。
[out] pszEscaped
類型：PTSTR
接收已轉換字串的緩衝區，並將不安全字元轉換成其逸出序列。
[in, out] pcchEscaped
類型：DWORD*
如果傳回E_POINTER錯誤碼，緩衝區太小而無法保存結果，而且 pcchEscaped 所參考的值會設定為緩衝區中所需的字元數。 如果傳回任何其他錯誤，則未定義 pcchEscaped 所參考的值。
dwFlags
類型：DWORD
旗標，指出 pszURL 中提供哪個部分的 URL，以及該字串中的哪些字元應該轉換成其逸出序列。 定義下列旗標。
URL_DONT_ESCAPE_EXTRA_INFO （0x02000000）
僅與 URL_ESCAPE_SPACES_ONLY 搭配使用，以防止在查詢中轉換字元（字串中遇到第一個 # 或 ？ 字元後面的 URL 部分）。 這個旗標不應單獨使用，也不應與 URL_ESCAPE_SEGMENT_ONLY結合。
URL_BROWSER_MODE
定義為與 URL_DONT_ESCAPE_EXTRA_INFO相同。
URL_ESCAPE_SPACES_ONLY（0x04000000）
只將空格字元轉換成逸出序列，包括URL查詢部分中的這些空格字元。 其他不安全的字元不會轉換成其逸出序列。 此旗標假設 pszURL 不包含完整的 URL。 它只預期伺服器規格之後的部分。
將此旗標與 URL_DONT_ESCAPE_EXTRA_INFO 結合，以防止在URL的查詢部分中轉換空格字元。
這個旗標無法與 URL_ESCAPE_PERCENT 或 URL_ESCAPE_SEGMENT_ONLY結合。
URL_ESCAPE_PERCENT （0x00001000）
轉換 URL 區段中找到的任何 % 字元（該區段落在伺服器規格與第一個 # 或 ？ 個字元之間）。 根據預設，% 字元不會轉換成其逸出序列。 區段中的其他不安全字元也會正常轉換。
將此旗標與 URL_ESCAPE_SEGMENT_ONLY 結合，會在 URL 的查詢部分中包含這些 % 字元。 不過，由於 URL_ESCAPE_SEGMENT_ONLY 旗標會導致整個字串視為區段、任何 # 或 ？ 字元也會轉換。
這個旗標無法與 URL_ESCAPE_SPACES_ONLY結合。
URL_ESCAPE_SEGMENT_ONLY （0x00002000）
表示 pszURL 只包含伺服器元件之後但查詢前面的 URL 區段。 字串中的所有不安全字元都會轉換。 如果設定此旗標時提供完整的網址，則會轉換整個字串中的所有不安全字元，包括 # 和 ？ 字元。
將此旗標與 URL_ESCAPE_PERCENT 結合，以在轉換中包含該字元。
這個旗標無法與 URL_ESCAPE_SPACES_ONLY 或 URL_DONT_ESCAPE_EXTRA_INFO結合。
URL_ESCAPE_AS_UTF8 （0x00040000）
Windows 7 和更新版本。 將所有非 ASCII 字元的百分比編碼為其 UTF-8 對等專案。
URL_ESCAPE_ASCII_URI_COMPONENT （0x00080000）
Windows 8 和更新版本。 從 URI RFC 3986 （a-zA-Z0-9-.~_） 未保留集合以外的所有 ASCII 字元進行百分比編碼。
傳回值
類型：HRESULT
如果成功，則傳回S_OK。 如果 pcchEscaped 緩衝區太小而無法包含結果，則會傳回E_POINTER，而且 pcchEscap ed 所指向的值會設定為所需的緩衝區大小。 否則會傳回標準錯誤值。
言論
為了本檔的目的，一般 URL 分成三個區段：伺服器、區段和查詢。 例如：
http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment
伺服器部分為 「http://microsoft.com/"。 尾端正斜線會被視為伺服器部分的一部分。
區段部分是在伺服器部分之後找到的路徑的任何部分，但在第一個 # 或 之前？ 字元，在此案例中只是 「test.asp」。
查詢部分是第一個 # 或 中路徑的其餘部分？ 字元（內含）到結尾。 在此範例中，它是 “？url=/example/abc.asp？frame=true#fragment”。
不安全的字元是因特網傳輸期間可能會改變的字元。 此函式會將不安全字元轉換成其相等的 「%xy」 逸出序列。 下表顯示不安全的字元及其逸出序列。
| 字元 | 逸出序列 |
|---|---|
| ^ | %5E |
| & | %26 |
| ` | %60 |
| { | %7B |
| } | %7D |
| | | %7C |
| ] | %5D |
| [ | %5B |
| " | %22 |
| < | %3C |
| > | %3E |
| \ | %5C |
使用 URL_ESCAPE_SEGMENT_ONLY 旗標也會導致 # （%23）， 的轉換？ （%3F）和/（%2F）字元。
根據預設，UrlEscape 會忽略 # 或 之後的任何文字？ 字元。 URL_ESCAPE_SEGMENT_ONLY 旗標會將整個字串當做區段來覆寫此行為。 URL_ESCAPE_SPACES_ONLY 旗標會覆寫此行為，但僅適用於空格字元。
例子
下列範例顯示 URL 上各種旗標的效果。 範例 URL 無效，但為了示範目的而誇大。
// The full original URL
http://microsoft.com/test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY
// Only space characters are escaped. Other unsafe characters are ignored.
// Note: This flag expects the server portion of the URL to be omitted.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex%%20ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY | URL_DONT_ESCAPE_EXTRA_INFO
// Spaces in the segment are converted into their escape sequences, but
// spaces in the query are not.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_PERCENT
// Here only the segment and query are supplied and the server component is
// omitted, although that is not required. Only the segment is considered.
// All unsafe characters plus the % character are converted in the segment.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%25e%3Cs%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SEGMENT_ONLY
// Note: This flag expects only the segment, omitting the server and query
// components.
// The / character is escaped as well as the usual unsafe characters.
Original = test/t%e<s t.asp
Result = test%2Ft%e%3Cs%20t.asp
注意
shlwapi.h 標頭會根據 UNICODE 預處理器常數的定義，將 UrlEscape 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 Professional、Windows XP [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | shlwapi.h |
| 連結庫 | Shlwapi.lib |
| DLL | Shlwapi.dll 版 （5.0 版或更新版本） |