LWSTDAPI UrlEscapeA(
[in] PCSTR pszUrl,
[out] PSTR pszEscaped,
[in, out] DWORD *pcchEscaped,
DWORD dwFlags
[in] pszUrl
类型: PCTSTR
最大长度为 null 的字符串 INTERNET_MAX_URL_LENGTH ,其中包含完整或部分 URL(适合 dwFlags 中的值)。
[out] pszEscaped
类型: PTSTR
接收转换后的字符串的缓冲区,并将不安全字符转换为其转义序列。
[in, out] pcchEscaped
类型: DWORD*
指向 DWORD 值的指针,该值在输入时包含 pszEscaped 缓冲区中的字符数。 在调用 UrlEscape 之前,调用应用程序必须将 pcchEscaped 引用的值设置为缓冲区的大小。 当此函数成功返回时,值接收写入缓冲区的字符数,不包括终止 NULL 字符。
如果返回E_POINTER错误代码,则缓冲区太小,无法保存结果, 并且 pcchEscaped 引用的值将设置为缓冲区中所需的字符数。 如果返回任何其他错误,则 pcchEscaped 引用的值未定义。
dwFlags
类型:DWORD
指示 在 pszURL 中提供 URL 的哪一部分以及该字符串中的哪些字符应转换为其转义序列的标志。 定义了以下标志。
仅与 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,整个字符串中的所有不安全字符(包括 # 和 ? 字符)都将被转换。
将此标志与 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 中未保留集之外的所有 ASCII 字符进行百分比编码 (a-zA-Z0-9-.~_) 。
类型: HRESULT
如果成功,则返回S_OK。 如果 pcchEscaped 缓冲区太小而无法包含结果,则返回E_POINTER, 并将 pcchEscaped 指向的值设置为所需的缓冲区大小。 否则,将返回标准错误值。
就本文档而言,典型的 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”。
不安全字符是在 Internet 传输过程中可能被更改的字符。 此函数将不安全字符转换为其等效的“%xy”转义序列。 下表显示了不安全字符及其转义序列。
使用 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 标头将 UrlEscape 定义为别名,该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配,从而导致编译或运行时错误。 有关详细信息,请参阅 函数原型的约定。