CUrl Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

This class represents a URL. It allows you to manipulate each element of the URL independently of the others whether parsing an existing URL string or building a string from scratch.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

class CUrl

Public Constructors

NameDescription
CUrl::CUrlThe constructor.
CUrl::~CUrlThe destructor.

Public Methods

NameDescription
CUrl::CanonicalizeCall this method to convert the URL string to canonical form.
CUrl::ClearCall this method to clear all of the URL fields.
CUrl::CrackUrlCall this method to decode and parse the URL.
CUrl::CreateUrlCall this method to create the URL.
CUrl::GetExtraInfoCall this method to get extra information (such as text or # text) from the URL.
CUrl::GetExtraInfoLengthCall this method to get the length of the extra information (such as text or # text) to retrieve from the URL.
CUrl::GetHostNameCall this method to get the host name from the URL.
CUrl::GetHostNameLengthCall this method to get the length of the host name.
CUrl::GetPasswordCall this method to get the password from the URL.
CUrl::GetPasswordLengthCall this method to get the length of the password.
CUrl::GetPortNumberCall this method to get the port number in terms of ATL_URL_PORT.
CUrl::GetSchemeCall this method to get the URL scheme.
CUrl::GetSchemeNameCall this method to get the URL scheme name.
CUrl::GetSchemeNameLengthCall this method to get the length of the URL scheme name.
CUrl::GetUrlLengthCall this method to get the URL length.
CUrl::GetUrlPathCall this method to get the URL path.
CUrl::GetUrlPathLengthCall this method to get the URL path length.
CUrl::GetUserNameCall this method to get the user name from the URL.
CUrl::GetUserNameLengthCall this method to get the length of the user name.
CUrl::SetExtraInfoCall this method to set the extra information (such as text or # text) of the URL.
CUrl::SetHostNameCall this method to set the host name.
CUrl::SetPasswordCall this method to set the password.
CUrl::SetPortNumberCall this method to set the port number in terms of ATL_URL_PORT.
CUrl::SetSchemeCall this method to set the URL scheme.
CUrl::SetSchemeNameCall this method to set the URL scheme name.
CUrl::SetUrlPathCall this method to set the URL path.
CUrl::SetUserNameCall this method to set the user name.

Public Operators

NameDescription
CUrl::operator =Assigns the specified CUrl object to the current CUrl object.

CUrl allows you to manipulate the fields of a URL, such as the path or port number. CUrl understands URLs of the following form:

<Scheme>://<UserName>:<Password>@<HostName>:<PortNumber>/<UrlPath><ExtraInfo>

(Some fields are optional.) For example, consider this URL:

http://someone:secret@www.microsoft.com:80/visualc/stuff.htm#contents

CUrl::CrackUrl parses it as follows:

  • Scheme: "http" or ATL_URL_SCHEME_HTTP

  • UserName: "someone"

  • Password: "secret"

  • HostName: "www.microsoft.com"

  • PortNumber: 80

  • UrlPath: "visualc/stuff.htm"

  • ExtraInfo: "#contents"

To manipulate the UrlPath field (for instance), you would use GetUrlPath, GetUrlPathLength, and SetUrlPath. You would use CreateUrl to create the complete URL string.

Header: atlutil.h

Call this method to convert the URL string to canonical form.

inline BOOL Canonicalize(DWORD dwFlags = 0) throw();

Parameters

dwFlags
The flags that control canonicalization. If no flags are specified ( dwFlags = 0), the method converts all unsafe characters and meta sequences (such as \.,\ .., and \...) to escape sequences. dwFlags can be one of the following values:

  • ATL_URL_BROWSER_MODE: Does not encode or decode characters after "#" or "" and does not remove trailing white space after "". If this value is not specified, the entire URL is encoded and trailing white space is removed.

  • ATL_URL _DECODE: Converts all %XX sequences to characters, including escape sequences, before the URL is parsed.

  • ATL_URL _ENCODE_PERCENT: Encodes any percent signs encountered. By default, percent signs are not encoded.

  • ATL_URL _ENCODE_SPACES_ONLY: Encodes spaces only.

  • ATL_URL _NO_ENCODE: Does not convert unsafe characters to escape sequences.

  • ATL_URL _NO_META: Does not remove meta sequences (such as "." and "..") from the URL.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

Converting to canonical form involves converting unsafe characters and spaces to escape sequences.

Call this method to clear all of the URL fields.

inline void Clear() throw();

Call this method to decode and parse the URL.

BOOL CrackUrl(LPCTSTR lpszUrl, DWORD dwFlags = 0) throw();

Parameters

lpszUrl
The URL.

dwFlags
Specify ATL_URL_DECODE or ATL_URL_ESCAPE to convert all escape characters in lpszUrl to their real values after parsing. (Before Visual C++ 2005, ATL_URL_DECODE converted all escape characters before parsing.)

Return Value

Returns TRUE on success, FALSE on failure.

This method constructs a URL string from a CUrl object's component fields.

inline BOOL CreateUrl(
    LPTSTR lpszUrl,
    DWORD* pdwMaxLength,
    DWORD dwFlags = 0) const throw();

Parameters

lpszUrl
A string buffer to hold the complete URL string.

pdwMaxLength
The maximum length of the lpszUrl string buffer.

dwFlags
Specify ATL_URL_ESCAPE to convert all escape characters in lpszUrl to their real values.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

This method appends its individual fields in order to construct the complete URL string using the following format:

<scheme>://<user>:<pass>@<domain>:<port><path><extra>

When calling this method, the pdwMaxLength parameter should initially contain the maximum length of the string buffer referenced by the lpszUrl parameter. The value of the pdwMaxLength parameter will be updated with the actual length of the URL string.

Example

This sample demonstrates creation of a CUrl object and retrieving its URL string

   CUrl url;

   // Set the CUrl contents
   url.CrackUrl(_T("http://someone:secret@www.microsoft.com:8080/visualc/stuff.htm#contents"));

   // Obtain the length of the URL string and allocate a buffer to 
   // hold its contents
   DWORD dwUrlLen = url.GetUrlLength() + 1;
   TCHAR* szUrl = new TCHAR[dwUrlLen];

   // Retrieve the contents of the CUrl object
   url.CreateUrl(szUrl, &dwUrlLen, 0L);

   // Cleanup
   delete[] szUrl;   

The constructor.

CUrl() throw();
CUrl(const CUrl& urlThat) throw();

Parameters

urlThat
The CUrl object to copy to create the URL.

The destructor.

~CUrl() throw();

Call this method to get extra information (such as text or # text) from the URL.

inline LPCTSTR GetExtraInfo() const throw();

Return Value

Returns a string containing the extra information.

Call this method to get the length of the extra information (such as text or # text) to retrieve from the URL.

inline DWORD GetExtraInfoLength() const throw();

Return Value

Returns the length of the string containing the extra information.

Call this method to get the host name from the URL.

inline LPCTSTR GetHostName() const throw();

Return Value

Returns the host name.

Call this method to get the length of the host name.

inline DWORD GetHostNameLength() const throw();

Return Value

Returns the host name length.

Call this method to get the password from the URL.

inline LPCTSTR GetPassword() const throw();

Return Value

Returns the password.

Call this method to get the length of the password.

inline DWORD GetPasswordLength() const throw();

Return Value

Returns the password length.

Call this method to get the port number.

inline ATL_URL_PORT GetPortNumber() const throw();

Return Value

Returns the port number.

Call this method to get the URL scheme.

inline ATL_URL_SCHEME GetScheme() const throw();

Return Value

Returns the ATL_URL_SCHEME value describing the scheme of the URL.

Call this method to get the URL scheme name.

inline LPCTSTR GetSchemeName() const throw();

Return Value

Returns the URL scheme name (such as "http" or "ftp").

Call this method to get the length of the URL scheme name.

inline DWORD GetSchemeNameLength() const throw();

Return Value

Returns the URL scheme name length.

Call this method to get the URL length.

inline DWORD GetUrlLength() const throw();

Return Value

Returns the URL length.

Call this method to get the URL path.

inline LPCTSTR GetUrlPath() const throw();

Return Value

Returns the URL path.

Call this method to get the URL path length.

inline DWORD GetUrlPathLength() const throw();

Return Value

Returns the URL path length.

Call this method to get the user name from the URL.

inline LPCTSTR GetUserName() const throw();

Return Value

Returns the user name.

Call this method to get the length of the user name.

inline DWORD GetUserNameLength() const throw();

Return Value

Returns the user name length.

Assigns the specified CUrl object to the current CUrl object.

CUrl& operator= (const CUrl& urlThat) throw();

Parameters

urlThat
The CUrl object to copy into the current object.

Return Value

Returns a reference to the current object.

Call this method to set the extra information (such as text or # text) of the URL.

inline BOOL SetExtraInfo(LPCTSTR lpszInfo) throw();

Parameters

lpszInfo
The string containing the extra information to include in the URL.

Return Value

Returns TRUE on success, FALSE on failure.

Call this method to set the host name.

inline BOOL SetHostName(LPCTSTR lpszHost) throw();

Parameters

lpszHost
The host name.

Return Value

Returns TRUE on success, FALSE on failure.

Call this method to set the password.

inline BOOL SetPassword(LPCTSTR lpszPass) throw();

Parameters

lpszPass
The password.

Return Value

Returns TRUE on success, FALSE on failure.

Call this method to set the port number.

inline BOOL SetPortNumber(ATL_URL_PORT nPrt) throw();

Parameters

nPrt
The port number.

Return Value

Returns TRUE on success, FALSE on failure.

Call this method to set the URL scheme.

inline BOOL SetScheme(ATL_URL_SCHEME nScheme) throw();

Parameters

nScheme
One of the ATL_URL_SCHEME values for the scheme.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

You can also set the scheme by name (see CUrl::SetSchemeName).

Call this method to set the URL scheme name.

inline BOOL SetSchemeName(LPCTSTR lpszSchm) throw();

Parameters

lpszSchm
The URL scheme name.

Return Value

Returns TRUE on success, FALSE on failure.

Remarks

You can also set the scheme by using an ATL_URL_SCHEME constant (see CUrl::SetScheme).

Call this method to set the URL path.

inline BOOL SetUrlPath(LPCTSTR lpszPath) throw();

Parameters

lpszPath
The URL path.

Return Value

Returns TRUE on success, FALSE on failure.

Call this method to set the user name.

inline BOOL SetUserName(LPCTSTR lpszUser) throw();

Parameters

lpszUser
The user name.

Return Value

Returns TRUE on success, FALSE on failure.

Classes

Show: