ATL HTTP Utility Functions

Visual Studio 2015
 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at ATL HTTP Utility Functions.

These functions support manipulation of URLs.

AtlCanonicalizeUrlCanonicalizes a URL, which includes converting unsafe characters and spaces into escape sequences.
AtlCombineUrlCombines a base URL and a relative URL into a single, canonical URL.
AtlEscapeUrlConverts all unsafe characters to escape sequences.
AtlGetDefaultUrlPortGets the default port number associated with a particular Internet protocol or scheme.
AtlIsUnsafeUrlCharDetermines whether a character is safe for use in a URL.
AtlUnescapeUrlConverts escaped characters back to their original values.
RGBToHtmlConverts a COLORREF value to the HTML text corresponding to that color value.
SystemTimeToHttpDateCall this function to convert a system time to a string in a format suitable for using in HTTP headers.

Call this function to canonicalize a URL, which includes converting unsafe characters and spaces into escape sequences.

Syntax

inline BOOL AtlCanonicalizeUrl(  
   LPCTSTR szUrl,  
   LPTSTR szCanonicalized,  
   DWORD* pdwMaxLength,  
   DWORD dwFlags = 0) throw();  

Parameters

szUrl
The URL to be canonicalized.

szCanonicalized
Caller-allocated buffer to receive the canonicalized URL.

pdwMaxLength
Pointer to a variable that contains the length in characters of szCanonicalized. If the function succeeds, the variable receives the number of characters written to the buffer not including the terminating null character. If the function fails, the variable receives the required length in bytes of the buffer including space for the terminating null character.

dwFlags
Flags controlling the behavior of this function. See ATL_URL Flags.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Behaves like the current version of InternetCanonicalizeUrl but does not require WinInet or Internet Explorer to be installed.

Requirements

Header: atlutil.h

See Also

InternetCanonicalizeUrl

Call this function to combine a base URL and a relative URL into a single, canonical URL.

Syntax

inline BOOL AtlCombineUrl(  
   LPCTSTR szBaseUrl,  
   LPCTSTR szRelativeUrl,  
   LPTSTR szBuffer,  
   DWORD* pdwMaxLength,  
   DWORD dwFlags = 0) throw();  

Parameters

szBaseUrl
The base URL.

szRelativeUrl
The URL relative to the base URL.

szBuffer
Caller-allocated buffer to receive the canonicalized URL.

pdwMaxLength
Pointer to a variable that contains the length in characters of szBuffer. If the function succeeds, the variable receives the number of characters written to the buffer not including the terminating null character. If the function fails, the variable receives the required length in bytes of the buffer including space for the terminating null character.

dwFlags
Flags controlling the behavior of this function. See ATL_URL Flags.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Behaves like the current version of InternetCombineUrl but does not require WinInet or Internet Explorer to be installed.

Requirements

Header: atlutil.h

Call this function to convert all unsafe characters to escape sequences.

Syntax

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();  

Parameters

lpszStringIn
The URL to be converted.

lpszStringOut
Caller-allocated buffer to which the converted URL will be written.

pdwStrLen
Pointer to a DWORD variable. If the function succeeds, pdwStrLen receives the number of characters written to the buffer, not including the terminating null character. If the function fails, the variable receives the required length in bytes of the buffer including space for the terminating null character. When using the wide character version of this method, pdwStrLen receives the number of characters required, not the number of bytes.

dwMaxLength
The size of the buffer lpszStringOut.

dwFlags
Flags controlling the behavior of this function. See ATL_URL Flags.

Return Value

Returns TRUE on success, FALSE on failure.

Requirements

Header: atlutil.h


Call this function to get the default port number associated with a particular Internet protocol or scheme.

Syntax

inline ATL_URL_PORT AtlGetDefaultUrlPort(ATL_URL_SCHEME m_nScheme) throw();  

Parameters

m_nScheme
The ATL_URL_SCHEME value identifying the scheme for which you want to obtain the port number.

Return Value

The ATL_URL_PORT associated with the specified scheme or ATL_URL_INVALID_PORT_NUMBER if the scheme is not recognized.

Requirements

Header: atlutil.h

Call this function to find out whether a character is safe for use in a URL.

inline BOOL AtlIsUnsafeUrlChar(char chIn) throw();  

Parameters

chIn
The character to be tested for safety.

Return Value

Returns TRUE if the input character is unsafe, FALSE otherwise.

Remarks

Characters that should not be used in URLs can be tested using this function and converted using AtlCanonicalizeUrl.

Requirements

Header: atlutil.h

Call this function to convert escaped characters back to their original values.

Syntax

inline BOOL AtlUnescapeUrl(  
   LPCSTR szStringIn,  
   LPSTR szStringOut,  
   LPDWORD pdwStrLen,  
   DWORD dwMaxLength) throw();  

inline BOOL AtlUnescapeUrl(  
   LPCWSTR szStringIn,  
   LPWSTR szStringOut,  
   LPDWORD pdwStrLen,  
   DWORD dwMaxLength) throw();  

Parameters

lpszStringIn
The URL to be converted.

lpszStringOut
Caller-allocated buffer to which the converted URL will be written.

pdwStrLen
Pointer to a DWORD variable. If the function succeeds, the variable receives the number of characters written to the buffer not including the terminating null character. If the function fails, the variable receives the required length in bytes of the buffer including space for the terminating null character.

dwMaxLength
The size of the buffer lpszStringOut.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Reverses the conversion process applied by AtlEscapeUrl.

Requirements

Header: atlutil.h

Converts a COLORREF value to the HTML text corresponding to that color value.

Syntax

bool inline RGBToHtml(  
   COLORREF color,  
   LPTSTR pbOut,  
   long nBuffer);  

Parameters

color
An RGB color value.

pbOut
Caller-allocated buffer to receive the text for the HTML color value. The buffer must have space for at least 8 characters including space for the null terminator).

nBuffer
The size in bytes of the buffer (including space for the null terminator).

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

An HTML color value is a pound sign followed by a 6-digit hexadecimal value using 2 digits for each of the red, green, and blue components of the color (for example, #FFFFFF is white).

Requirements

Header: atlutil.h

Call this function to convert a system time to a string in a format suitable for using in HTTP headers.

Syntax

inline void SystemTimeToHttpDate( 
   const SYSTEMTIME& st,  
   CStringA& strTime);  

Parameters

st
The system time to be obtained as an HTTP format string.

strTime
A reference to a string variable to receive the HTTP date time as defined in RFC 2616 (http://www.ietf.org/rfc/rfc2616.txt) and RFC 1123 (http://www.ietf.org/rfc/rfc1123.txt).

Requirements

Header: atlutil.h

Concepts
ATL COM Desktop Components

Show: