CUrl 类

项目
04/03/2023

此类表示 URL。它允许独立于元素操作 URL 的每个元素，无论是分析现有 URL 字符串还是从头开始生成字符串。

重要

无法在 Windows 运行时中执行的应用程序中使用此类及其成员。

语法

class CUrl

成员

公共构造函数

名称	描述
CUrl::CUrl	构造函数。
CUrl::~CUrl	析构函数。

公共方法

名称	描述
CUrl::Canonicalize	调用此方法可将 URL 字符串转换为规范格式。
CUrl::Clear	调用此方法可清除所有 URL 字段。
CUrl::CrackUrl	调用此方法可解码和分析 URL。
CUrl::CreateUrl	调用此方法可创建 URL。
CUrl::GetExtraInfo	调用此方法可从 URL 中获取附加信息（例如 text 或 # text）。
CUrl::GetExtraInfoLength	调用此方法可从 URL 中获取要检索的附加信息（例如 text 或 # text）的长度。
CUrl::GetHostName	调用此方法可从 URL 中获取主机名。
CUrl::GetHostNameLength	调用此方法可获取主机名的长度。
CUrl::GetPassword	调用此方法可从 URL 中获取密码。
CUrl::GetPasswordLength	调用此方法可获取密码的长度。
CUrl::GetPortNumber	调用此方法可获取 ATL_URL_PORT 的端口号部分。
CUrl::GetScheme	调用此方法可获取 URL 方案。
CUrl::GetSchemeName	调用此方法可获取 URL 方案名称。
CUrl::GetSchemeNameLength	调用此方法可获取 URL 方案名称的长度。
CUrl::GetUrlLength	调用此方法可获取 URL 长度。
CUrl::GetUrlPath	调用此方法可获取 URL 路径。
CUrl::GetUrlPathLength	调用此方法可获取 URL 路径长度。
CUrl::GetUserName	调用此方法可从 URL 中获取用户名。
CUrl::GetUserNameLength	调用此方法可获取用户名的长度。
CUrl::SetExtraInfo	调用此方法可设置 URL 的附加信息（例如 text 或 # text）。
CUrl::SetHostName	调用此方法可设置主机名。
CUrl::SetPassword	调用此方法可设置密码。
CUrl::SetPortNumber	调用此方法可设置 ATL_URL_PORT 的端口号部分。
CUrl::SetScheme	调用此方法可设置 URL 方案。
CUrl::SetSchemeName	调用此方法可设置 URL 方案名称。
CUrl::SetUrlPath	调用此方法可设置 URL 路径。
CUrl::SetUserName	调用此方法可设置用户名。

公共运算符

“属性”	描述
CUrl::operator =	将指定的 `CUrl` 对象分配给当前 `CUrl` 对象。

备注

CUrl 允许操作 URL 的字段，例如路径或端口号。 CUrl 识别以下格式的 URL：

<方案>://<用户名>:<密码>@<主机名>:<端口号>/<URL 路径><附加信息>

（某些字段是可选的。）例如，考虑以下 URL：

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

CUrl::CrackUrl 按如下所示分析该 URL：

方案：“http”或 ATL_URL_SCHEME_HTTP
用户名：“someone”
密码：“secret”
主机名：“www.microsoft.com”
端口号：80
URL 路径：“visualc/stuff.htm”
附加信息：“#contents”

例如，若要操作 URL 路径字段，可以使用 GetUrlPath、GetUrlPathLength 和 SetUrlPath。可以使用 CreateUrl 创建完整的 URL 字符串。

要求

标头：atlutil.h

CUrl::Canonicalize

调用此方法可将 URL 字符串转换为规范格式。

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

参数

dwFlags
控制规范化的标志。如果未指定标志 (dwFlags = 0)，则该方法会将所有不安全的字符和元序列（例如 \.、\ .. 和 \...）转换为转义序列。 dwFlags 可为下列值之一：

ATL_URL_BROWSER_MODE：不对“#”或 "" 之后的字符进行编码或解码，也不会删除 "" 后面的尾部空格。如果未指定此值，则会对整个 URL 进行编码，并删除尾随空格。
ATL_URL_DECODE：在分析 URL 之前将所有 %XX 序列转换为字符，包括转义序列。
ATL_URL_ENCODE_PERCENT：对遇到的任何百分比符号进行编码。默认情况下，不编码百分比符号。
ATL_URL_ENCODE_SPACES_ONLY：仅对空格进行编码。
ATL_URL_NO_ENCODE：不会将不安全的字符转换为转义序列。
ATL_URL_NO_META：不删除 URL 中的元序列（例如“.”和“..”）。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

转换为规范格式涉及到将不安全的字符和空格转换为转义序列。

CUrl::Clear

调用此方法可清除所有 URL 字段。

inline void Clear() throw();

CUrl::CrackUrl

调用此方法可解码和分析 URL。

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

参数

lpszUrl
URL。

dwFlags
指定 ATL_URL_DECODE 或 ATL_URL_ESCAPE 以在分析之后将 lpszUrl 中的所有转义字符转换为其实际值。（在 Visual C++ 2005 之前，ATL_URL_DECODE 会在分析之前转换所有转义字符。）

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

CUrl::CreateUrl

此方法从 CUrl 对象的组件字段构造 URL 字符串。

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

参数

lpszUrl
保存完整 URL 字符串的字符串缓冲区。

pdwMaxLength
lpszUrl 字符串缓冲区的最大长度。

dwFlags
指定 ATL_URL_ESCAPE 以将 lpszUrl 中的所有转义字符转换为其实际值。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

此方法追加其各个字段，以使用以下格式构造完整的 URL 字符串：

<方案>://<用户名>:<密码>@<域>:<端口><路径><附加信息>

调用此方法时，pdwMaxLength 参数最初应包含 lpszUrl 参数引用的字符串缓冲区的最大长度。 pdwMaxLength 参数的值将以 URL 字符串的实际长度更新。

示例

此示例演示如何创建 CUrl 对象及检索其 URL 字符串

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;

CUrl::CUrl

构造函数。

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

参数

urlThat
要复制的用于创建 URL 的 CUrl 对象。

CUrl::~CUrl

析构函数。

~CUrl() throw();

CUrl::GetExtraInfo

调用此方法可从 URL 中获取附加信息（例如 text 或 # text）。

inline LPCTSTR GetExtraInfo() const throw();

返回值

返回一个包含附加信息的字符串。

CUrl::GetExtraInfoLength

调用此方法可从 URL 中获取要检索的附加信息（例如 text 或 # text）的长度。

inline DWORD GetExtraInfoLength() const throw();

返回值

返回包含附加信息的字符串的长度。

CUrl::GetHostName

调用此方法可从 URL 中获取主机名。

inline LPCTSTR GetHostName() const throw();

返回值

返回主机名。

CUrl::GetHostNameLength

调用此方法可获取主机名的长度。

inline DWORD GetHostNameLength() const throw();

返回值

返回主机名长度。

CUrl::GetPassword

调用此方法可从 URL 中获取密码。

inline LPCTSTR GetPassword() const throw();

返回值

返回密码。

CUrl::GetPasswordLength

调用此方法可获取密码的长度。

inline DWORD GetPasswordLength() const throw();

返回值

返回密码长度。

CUrl::GetPortNumber

调用此方法可获取端口号。

inline ATL_URL_PORT GetPortNumber() const throw();

返回值

返回端口号。

CUrl::GetScheme

调用此方法可获取 URL 方案。

inline ATL_URL_SCHEME GetScheme() const throw();

返回值

返回描述 URL 方案的 ATL_URL_SCHEME 值。

CUrl::GetSchemeName

调用此方法可获取 URL 方案名称。

inline LPCTSTR GetSchemeName() const throw();

返回值

返回 URL 方案名称（例如“http”或“ftp”）。

CUrl::GetSchemeNameLength

调用此方法可获取 URL 方案名称的长度。

inline DWORD GetSchemeNameLength() const throw();

返回值

返回 URL 方案名称长度。

CUrl::GetUrlLength

调用此方法可获取 URL 长度。

inline DWORD GetUrlLength() const throw();

返回值

返回 URL 长度。

CUrl::GetUrlPath

调用此方法可获取 URL 路径。

inline LPCTSTR GetUrlPath() const throw();

返回值

返回 URL 路径。

CUrl::GetUrlPathLength

调用此方法可获取 URL 路径长度。

inline DWORD GetUrlPathLength() const throw();

返回值

返回 URL 路径长度。

CUrl::GetUserName

调用此方法可从 URL 中获取用户名。

inline LPCTSTR GetUserName() const throw();

返回值

返回用户名。

CUrl::GetUserNameLength

调用此方法可获取用户名的长度。

inline DWORD GetUserNameLength() const throw();

返回值

返回用户名长度。

CUrl::operator =

将指定的 CUrl 对象分配给当前 CUrl 对象。

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

参数

urlThat
要复制到当前对象中的 CUrl 对象。

返回值

返回对当前对象的引用。

CUrl::SetExtraInfo

调用此方法可设置 URL 的附加信息（例如 text 或 # text）。

inline BOOL SetExtraInfo(LPCTSTR lpszInfo) throw();

参数

lpszInfo
包含附加信息的字符串，这些信息将包含在 URL 中。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

CUrl::SetHostName

调用此方法可设置主机名。

inline BOOL SetHostName(LPCTSTR lpszHost) throw();

参数

lpszHost
主机名。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

CUrl::SetPassword

调用此方法可设置密码。

inline BOOL SetPassword(LPCTSTR lpszPass) throw();

参数

lpszPass
密码。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

CUrl::SetPortNumber

调用此方法可设置端口号。

inline BOOL SetPortNumber(ATL_URL_PORT nPrt) throw();

参数

nPrt
端口号。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

CUrl::SetScheme

调用此方法可设置 URL 方案。

inline BOOL SetScheme(ATL_URL_SCHEME nScheme) throw();

参数

nScheme
方案的 ATL_URL_SCHEME 值之一。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

还可以按名称设置方案（请参阅 CUrl::SetSchemeName）。

CUrl::SetSchemeName

调用此方法可设置 URL 方案名称。

inline BOOL SetSchemeName(LPCTSTR lpszSchm) throw();

参数

lpszSchm
URL 方案名称。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

备注

还可以使用 ATL_URL_SCHEME 常量设置方案（请参阅 CUrl::SetScheme）。

CUrl::SetUrlPath

调用此方法可设置 URL 路径。

inline BOOL SetUrlPath(LPCTSTR lpszPath) throw();

参数

lpszPath
URL 路径。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

CUrl::SetUserName

调用此方法可设置用户名。

inline BOOL SetUserName(LPCTSTR lpszUser) throw();

参数

lpszUser
用户名。

返回值

如果成功，则返回 TRUE；如果失败，则返回 FALSE。

另请参阅

类

通过

CUrl 类

语法

成员

公共构造函数

公共方法

公共运算符

备注

要求

CUrl::Canonicalize

参数

返回值

备注

CUrl::Clear

CUrl::CrackUrl

参数

返回值

CUrl::CreateUrl

参数

返回值

备注

示例

CUrl::CUrl

参数

CUrl::~CUrl

CUrl::GetExtraInfo

返回值

CUrl::GetExtraInfoLength

返回值

CUrl::GetHostName

返回值

CUrl::GetHostNameLength

返回值

CUrl::GetPassword

返回值

CUrl::GetPasswordLength

返回值

CUrl::GetPortNumber

返回值

CUrl::GetScheme

返回值

CUrl::GetSchemeName

返回值

CUrl::GetSchemeNameLength

返回值

CUrl::GetUrlLength

返回值

CUrl::GetUrlPath

返回值

CUrl::GetUrlPathLength

返回值

CUrl::GetUserName

返回值

CUrl::GetUserNameLength

返回值

CUrl::operator =

参数

返回值

CUrl::SetExtraInfo

参数

返回值

CUrl::SetHostName

参数

返回值

CUrl::SetPassword

参数

返回值

CUrl::SetPortNumber

参数

返回值

CUrl::SetScheme

参数

返回值

备注

CUrl::SetSchemeName

参数

返回值

备注

CUrl::SetUrlPath

参数