ATL HTTP 效用函数
这些函数支持对 URL 的操作。
| Function | 说明 |
|---|---|
| AtlCanonicalizeUrl | 规范化 URL，包括将不安全的字符和空格转换为转义序列。 |
| AtlCombineUrl | 将基 URL 和相对 URL 合并为单个规范 URL。 |
| AtlEscapeUrl | 将所有不安全字符转换为转义序列。 |
| AtlGetDefaultUrlPort | 获取与特定 Internet 协议或方案关联的默认端口号。 |
| AtlIsUnsafeUrlChar | 确定是否可以 URL 中安全地使用字符。 |
| AtlUnescapeUrl | 将转义字符转换为其原始值。 |
| RGBToHtml | 将 COLORREF 值转换为与颜色值相对应的 HTML 文本。 |
| SystemTimeToHttpDate | 调用此函数可将系统时间转换为采用适合在 HTTP 标头中使用的格式的字符串。 |
要求
标头：atlutil.h
AtlCanonicalizeUrl
调用此函数可对 URL 进行规范化，包括将不安全的字符和空格转换为转义序列。
inline BOOL AtlCanonicalizeUrl(
LPCTSTR szUrl,
LPTSTR szCanonicalized,
DWORD* pdwMaxLength,
DWORD dwFlags = 0) throw();
参数
szUrl
要规范化的 URL。
szCanonicalized
调用方分配的缓冲区用于接收规范化 URL。
pdwMaxLength
指向包含 szCanonicalized 字符长度的变量的指针。 如果函数成功，变量将接收写入缓冲区的字符数，包括终止 null 字符。 如果函数失败，变量将接收缓冲区所需的长度（以字节为单位），包括终止 null 字符的空间。
dwFlags
控制此函数的行为的 ATL_URL 标志。
ATL_URL_BROWSER_MODE 不对“#”或“？”之后的字符进行编码或解码，也不会删除“？”后面的尾随空格。 如果未指定此值，则会对整个 URL 进行编码，并删除尾随空格。
ATL_URL_DECODE 在分析 URL 之前将所有 %XX 序列转换为字符，包括转义序列。
ATL_URL_ENCODE_PERCENT 对遇到的任何百分比符号进行编码。 默认情况下，不编码百分比符号。
ATL_URL_ENCODE_SPACES_ONLY 仅对空格进行编码。
ATL_URL_ESCAPE 将所有转义序列 (%XX) 转换为相应的字符。
ATL_URL_NO_ENCODE 不将不安全字符转换为转义序列。
ATL_URL_NO_META 不删除 URL 的元序列（比如 "." 和 ".."）。
返回值
如果成功，则返回 TRUE；如果失败，则返回 FALSE。
注解
像 InternetCanonicalizeUrl 的当前版本一样操作，但不需要安装 WinInet 或 Internet Explorer。
AtlCombineUrl
调用此函数可将基 URL 和相对 URL 合并为单个规范 URL。
inline BOOL AtlCombineUrl(
LPCTSTR szBaseUrl,
LPCTSTR szRelativeUrl,
LPTSTR szBuffer,
DWORD* pdwMaxLength,
DWORD dwFlags = 0) throw();
参数
szBaseUrl
基 URL。
szRelativeUrl
相对于基 URL 的 URL。
szBuffer
调用方分配的缓冲区用于接收规范化 URL。
pdwMaxLength
指向包含 szBuffer 字符长度的变量的指针。 如果函数成功，变量将接收写入缓冲区的字符数，包括终止 null 字符。 如果函数失败，变量将接收缓冲区所需的长度（以字节为单位），包括终止 null 字符的空间。
dwFlags
控制此函数的行为的标志。 请参阅 AtlCanonicalizeUrl。
返回值
如果成功，则返回 TRUE；如果失败，则返回 FALSE。
备注
像 InternetCombineUrl 的当前版本一样操作，但不需要安装 WinInet 或 Internet Explorer。
AtlEscapeUrl
调用此函数可将所有不安全字符转换为转义序列。
inline BOOL AtlEscapeUrl(
LPCSTR szStringIn,
LPSTR szStringOut,
DWORD* pdwStrLen,
DWORD dwMaxLength,
DWORD dwFlags = 0) throw();
inline BOOL AtlEscapeUrl(
LPCWSTR szStringIn,
LPWSTR szStringOut,
DWORD* pdwStrLen,
DWORD dwMaxLength,
DWORD dwFlags = 0) throw();
参数
lpszStringIn
要转换的 URL。
lpszStringOut
将向其写入转换 URL 的调用方分配的缓冲区。
pdwStrLen
指向 DWORD 变量的指针。 如果函数成功，pdwStrLen 将接收写入缓冲区的字符数，包括终止 null 字符。 如果函数失败，变量将接收缓冲区所需的长度（以字节为单位），包括终止 null 字符的空间。 使用此方法的宽字符版本时，pdwStrLen 接收所需的字符数，而不是字节数。
dwMaxLength
缓冲区 lpszStringOut 的大小。
dwFlags
控制此函数的行为的 ATL_URL 标志。 有关可能值，请参阅 ATLCanonicalizeUrl。
返回值
如果成功，则返回 TRUE；如果失败，则返回 FALSE。
AtlGetDefaultUrlPort
调用此函数可获取与特定 Internet 协议或方案关联的默认端口号。
inline ATL_URL_PORT AtlGetDefaultUrlPort(ATL_URL_SCHEME m_nScheme) throw();
参数
m_nScheme
ATL_URL_SCHEME 值用于标识要为其获取端口号的方案。
返回值
与指定方案关联的 ATL_URL_PORT；如果未识别方案，则为 ATL_URL_INVALID_PORT_NUMBER。
AtlIsUnsafeUrlChar
调用此函数可了解字符在 URL 中能否安全使用。
inline BOOL AtlIsUnsafeUrlChar(char chIn) throw();
参数
chIn
出于安全要测试的字符。
返回值
如果输入字符不安全，则返回 TRUE；否则返回 FALSE。
注解
不应在 URL 中使用的字符可以使用此函数进行测试，并使用 AtlCanonicalizeUrl 进行转换。
AtlUnescapeUrl
调用此函数可将转义字符转换为其原始值。
inline BOOL AtlUnescapeUrl(
LPCSTR szStringIn,
LPSTR szStringOut,
LPDWORD pdwStrLen,
DWORD dwMaxLength) throw();
inline BOOL AtlUnescapeUrl(
LPCWSTR szStringIn,
LPWSTR szStringOut,
LPDWORD pdwStrLen,
DWORD dwMaxLength) throw();
参数
lpszStringIn
要转换的 URL。
lpszStringOut
将向其写入转换 URL 的调用方分配的缓冲区。
pdwStrLen
指向 DWORD 变量的指针。 如果函数成功，变量将接收写入缓冲区的字符数，包括终止 null 字符。 如果函数失败，变量将接收缓冲区所需的长度（以字节为单位），包括终止 null 字符的空间。
dwMaxLength
缓冲区 lpszStringOut 的大小。
返回值
如果成功，则返回 TRUE；如果失败，则返回 FALSE。
注解
反转 AtlEscapeUrl 应用的转换过程。
RGBToHtml
将 COLORREF 值转换为与颜色值相对应的 HTML 文本。
bool inline RGBToHtml(
COLORREF color,
LPTSTR pbOut,
long nBuffer);
参数
color
RGB 颜色值。
pbOut
调用方分配的缓冲区，用于接收 HTML 颜色值的文本。 缓冲区必须具有至少 8 个字符的空间，包括 null 终止符的空间）。
nBuffer
缓冲区的大小（以字节为单位）（包括 null 终止符的空间）。
返回值
如果成功，则返回 TRUE；如果失败，则返回 FALSE。
备注
HTML 颜色值由井号加 6 未十六进制值表示，其中颜色的红黄蓝三个成分分别由 2 位数字表示（比如，#FFFFFF 表示白色）。
SystemTimeToHttpDate
调用此函数可将系统时间转换为采用适合在 HTTP 标头中使用的格式的字符串。
inline void SystemTimeToHttpDate(
const SYSTEMTIME& st,
CStringA& strTime);
参数
st
作为 HTTP 格式字符串获取的系统时间。
strTime
对字符串变量的引用，可接收 RFC 2616 (https://www.ietf.org/rfc/rfc2616.txt) 和 RFC 1123 (https://www.ietf.org/rfc/rfc1123.txt) 中定义的 HTTP 日期时间。