ATL HTTP 公用程式函式
這些函式支援操作 URL。
| 函式 | 描述 |
|---|---|
| AtlCanonicalizeUrl | 標準化 URL，其中包括將不安全的字元和空格轉換成逸出序列。 |
| AtlCombineUrl | 將基底 URL 和相對 URL 合併成單一標準 URL。 |
| AtlEscapeUrl | 將所有不安全的字元轉換成逸出序列。 |
| AtlGetDefaultUrlPort | 取得與特定因特網通訊協定或配置相關聯的預設埠號碼。 |
| AtlIsUnsafeUrlChar | 判斷字元是否安全可用於URL。 |
| AtlUnescapeUrl | 將逸出字元轉換回其原始值。 |
| RGBToHtml | 將 COLORREF 值轉換為對應至該色彩值的 HTML 文字。 |
| SystemTimeToHttpDate | 呼叫此函式將系統時間轉換成採用適合在 HTTP 標頭中使用之格式的字串。 |
需求
標頭： atlutil.h
AtlCanonicalizeUrl
呼叫此函式可規範化 URL，包括將 Unsafe 字元和空格轉換成逸出序列。
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
呼叫此函式會將所有 Unsafe 字元轉換成逸出序列。
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
呼叫此函式可取得與特定網際網路通訊協定或配置相關聯的預設通訊埠編號。
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();
參數
下巴
要測試安全性的字元。
傳回值
如果輸入字元不安全，則傳回 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);
參數
聖
要取得為 HTTP 格式字串的系統時間。
strTime
字串變數的參考，以接收 RFC 2616 （https://www.ietf.org/rfc/rfc2616.txt） 和 RFC 1123 中https://www.ietf.org/rfc/rfc1123.txt定義的 HTTP 日期時間。