Share via

CUrl Class

  • Article

 

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 CUrl Class.

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.

Important

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

Syntax

class CUrl

Members

Public Constructors

Name Description
CUrl::CUrl The constructor.
CUrl::~CUrl The destructor.

Public Methods

Name Description
CUrl::Canonicalize Call this method to convert the URL string to canonical form.
CUrl::Clear Call this method to clear all of the URL fields.
CUrl::CrackUrl Call this method to decode and parse the URL.
CUrl::CreateUrl Call this method to create the URL.
CUrl::GetExtraInfo Call this method to get extra information (such as text or # text) from the URL.
CUrl::GetExtraInfoLength Call this method to get the length of the extra information (such as text or # text) to retrieve from the URL.
CUrl::GetHostName Call this method to get the host name from the URL.
CUrl::GetHostNameLength Call this method to get the length of the host name.
CUrl::GetPassword Call this method to get the password from the URL.
CUrl::GetPasswordLength Call this method to get the length of the password.
CUrl::GetPortNumber Call this method to get the port number in terms of ATL_URL_PORT.
CUrl::GetScheme Call this method to get the URL scheme.
CUrl::GetSchemeName Call this method to get the URL scheme name.
CUrl::GetSchemeNameLength Call this method to get the length of the URL scheme name.
CUrl::GetUrlLength Call this method to get the URL length.
CUrl::GetUrlPath Call this method to get the URL path.
CUrl::GetUrlPathLength Call this method to get the URL path length.
CUrl::GetUserName Call this method to get the user name from the URL.
CUrl::GetUserNameLength Call this method to get the length of the user name.
CUrl::SetExtraInfo Call this method to set the extra information (such as text or # text) of the URL.
CUrl::SetHostName Call this method to set the host name.
CUrl::SetPassword Call this method to set the password.
CUrl::SetPortNumber Call this method to set the port number in terms of ATL_URL_PORT.
CUrl::SetScheme Call this method to set the URL scheme.
CUrl::SetSchemeName Call this method to set the URL scheme name.
CUrl::SetUrlPath Call this method to set the URL path.
CUrl::SetUserName Call this method to set the user name.

Public Operators

Name Description
CUrl::operator = Assigns the specified CUrl object to the current CUrl object.

Remarks

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:

https://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.

Requirements

Header: atlutil.h

CUrl::Canonicalize

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.

CUrl::Clear

Call this method to clear all of the URL fields.

inline void Clear() throw();

CUrl::CrackUrl

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.

CUrl::CreateUrl

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("https://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;

CUrl::CUrl

The constructor.

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

Parameters

urlThat
The CUrl object to copy to create the URL.

CUrl::~CUrl

The destructor.

~CUrl() throw();

CUrl::GetExtraInfo

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.

CUrl::GetExtraInfoLength

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.

CUrl::GetHostName

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

inline LPCTSTR GetHostName() const throw();

Return Value

Returns the host name.

CUrl::GetHostNameLength

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

inline DWORD GetHostNameLength() const throw();

Return Value

Returns the host name length.

CUrl::GetPassword

Call this method to get the password from the URL.

inline LPCTSTR GetPassword() const throw();

Return Value

Returns the password.

CUrl::GetPasswordLength

Call this method to get the length of the password.

inline DWORD GetPasswordLength() const throw();

Return Value

Returns the password length.

CUrl::GetPortNumber

Call this method to get the port number.

inline ATL_URL_PORT GetPortNumber() const throw();

Return Value

Returns the port number.

CUrl::GetScheme

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.

CUrl::GetSchemeName

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").

CUrl::GetSchemeNameLength

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.

CUrl::GetUrlLength

Call this method to get the URL length.

inline DWORD GetUrlLength() const throw();

Return Value

Returns the URL length.

CUrl::GetUrlPath

Call this method to get the URL path.

inline LPCTSTR GetUrlPath() const throw();

Return Value

Returns the URL path.

CUrl::GetUrlPathLength

Call this method to get the URL path length.

inline DWORD GetUrlPathLength() const throw();

Return Value

Returns the URL path length.

CUrl::GetUserName

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

inline LPCTSTR GetUserName() const throw();

Return Value

Returns the user name.

CUrl::GetUserNameLength

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

inline DWORD GetUserNameLength() const throw();

Return Value

Returns the user name length.

CUrl::operator =

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.

CUrl::SetExtraInfo

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.

CUrl::SetHostName

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.

CUrl::SetPassword

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.

CUrl::SetPortNumber

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.

CUrl::SetScheme

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).

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).

CUrl::SetUrlPath

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.

CUrl::SetUserName

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.

See Also

Classes