urlEscapeA 函数 (shlwapi.h)

项目
01/10/2024

将 URL 中的字符或代理项对转换，这些字符或代理项对在通过 Internet 传输期间可能会更改 (“不安全”字符) 转换为相应的转义序列。代理项对是 UTF-32) 中 U+10000 到 U+10FFFF (之间的字符，或 UTF-16) 中 DC00 到 DFFF (之间的字符。

语法

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_DONT_ESCAPE_EXTRA_INFO (0x02000000)

仅与 URL_ESCAPE_SPACES_ONLY 结合使用，以防止转换查询中的字符 (第一个 # 或？字符串) 中遇到的字符。此标志不应单独使用，也不应与 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 (a-zA-Z0-9-.~_) 的未保留集之外的所有 ASCII 字符进行百分比编码。

返回值

类型： 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”转义序列。下表显示了不安全字符及其转义序列。

字符	转义序列
^	%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 标头将 UrlEscape 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 专业版、Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	shlwapi.h
Library	Shlwapi.lib
DLL	Shlwapi.dll (5.0 或更高版本)

另请参阅

处理统一资源定位符