CUrl 类
此类表示 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。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈