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 日期时间。

另请参阅

概念
ATL COM 桌面组件
InternetCanonicalizeUrl