| description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | |||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CUrl Class |
CUrl Class |
05/06/2019 |
|
|
b3894d34-47b9-4961-9719-4197153793da |
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.
class CUrl
| Name | Description |
|---|---|
| CUrl::CUrl | The constructor. |
| CUrl::~CUrl | The destructor. |
| 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. |
| Name | Description |
|---|---|
| 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:[email protected]: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();
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.
Returns TRUE on success, FALSE on failure.
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();
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.)
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();
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.
Returns TRUE on success, FALSE on failure.
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.
This sample demonstrates creation of a CUrl object and retrieving its URL string
[!code-cppNVC_ATL_Utilities#133]
The constructor.
CUrl() throw();
CUrl(const CUrl& urlThat) throw();
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();
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();
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();
Returns the host name.
Call this method to get the length of the host name.
inline DWORD GetHostNameLength() const throw();
Returns the host name length.
Call this method to get the password from the URL.
inline LPCTSTR GetPassword() const throw();
Returns the password.
Call this method to get the length of the password.
inline DWORD GetPasswordLength() const throw();
Returns the password length.
Call this method to get the port number.
inline ATL_URL_PORT GetPortNumber() const throw();
Returns the port number.
Call this method to get the URL scheme.
inline ATL_URL_SCHEME GetScheme() const throw();
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();
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();
Returns the URL scheme name length.
Call this method to get the URL length.
inline DWORD GetUrlLength() const throw();
Returns the URL length.
Call this method to get the URL path.
inline LPCTSTR GetUrlPath() const throw();
Returns the URL path.
Call this method to get the URL path length.
inline DWORD GetUrlPathLength() const throw();
Returns the URL path length.
Call this method to get the user name from the URL.
inline LPCTSTR GetUserName() const throw();
Returns the user name.
Call this method to get the length of the user name.
inline DWORD GetUserNameLength() const throw();
Returns the user name length.
Assigns the specified CUrl object to the current CUrl object.
CUrl& operator= (const CUrl& urlThat) throw();
urlThat
The CUrl object to copy into the current object.
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();
lpszInfo
The string containing the extra information to include in the URL.
Returns TRUE on success, FALSE on failure.
Call this method to set the host name.
inline BOOL SetHostName(LPCTSTR lpszHost) throw();
lpszHost
The host name.
Returns TRUE on success, FALSE on failure.
Call this method to set the password.
inline BOOL SetPassword(LPCTSTR lpszPass) throw();
lpszPass
The password.
Returns TRUE on success, FALSE on failure.
Call this method to set the port number.
inline BOOL SetPortNumber(ATL_URL_PORT nPrt) throw();
nPrt
The port number.
Returns TRUE on success, FALSE on failure.
Call this method to set the URL scheme.
inline BOOL SetScheme(ATL_URL_SCHEME nScheme) throw();
nScheme
One of the ATL_URL_SCHEME values for the scheme.
Returns TRUE on success, FALSE on failure.
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();
lpszSchm
The URL scheme name.
Returns TRUE on success, FALSE on failure.
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();
lpszPath
The URL path.
Returns TRUE on success, FALSE on failure.
Call this method to set the user name.
inline BOOL SetUserName(LPCTSTR lpszUser) throw();
lpszUser
The user name.
Returns TRUE on success, FALSE on failure.