创建和初始化一个或多个同时 Internet 会话,并说明与代理服务器的连接(如果需要)。
语法
class CInternetSession : public CObject
成员
公共构造函数
| 名称 | 描述 |
|---|---|
CInternetSession::CInternetSession |
构造 CInternetSession 对象。 |
公共方法
| 名称 | 描述 |
|---|---|
CInternetSession::Close |
当 Internet 会话终止时关闭 Internet 连接。 |
CInternetSession::EnableStatusCallback |
建立状态回调例程。 |
CInternetSession::GetContext |
当 Internet 会话终止时关闭 Internet 连接。 |
CInternetSession::GetCookie |
返回指定的 URL 及其所有父 URL 的 Cookie。 |
CInternetSession::GetCookieLength |
检索指定存储在缓冲区中的 Cookie 长度的变量。 |
CInternetSession::GetFtpConnection |
打开与服务器的 FTP 会话。 登录用户。 |
CInternetSession::GetGopherConnection |
为尝试打开连接的应用程序打开 gopher 服务器。 |
CInternetSession::GetHttpConnection |
为尝试打开连接的应用程序打开 HTTP 服务器。 |
CInternetSession::OnStatusCallback |
当启用状态回调时更新操作的状态。 |
CInternetSession::OpenURL |
分析并打开 URL。 |
CInternetSession::SetCookie |
设置指定的 URL 的 Cookie。 |
CInternetSession::SetOption |
设置 Internet 会话的选项。 |
公共运算符
| “属性” | 描述 |
|---|---|
CInternetSession::operator HINTERNET |
当前 Internet 会话的句柄。 |
备注
如果 Internet 连接必须在应用程序期间保持,可以创建 CWinApp 类的 CInternetSession 成员。
建立 Internet 会话后,可以调用 OpenURL。 然后,CInternetSession 通过调用全局函数 AfxParseURL 为你解析 URL。 无论其协议类型如何,CInternetSession 都会解释 URL 并为你管理它。 它可以处理对使用 URL 资源“file://”标识的本地文件的请求。 如果传递的名称是本地文件,OpenURL 将返回指向 CStdioFile 对象的指针。
如果使用 OpenURL 在 Internet 服务器上打开 URL,则可以从该站点读取信息。 如果要对服务器上的文件执行特定于服务(例如 HTTP、FTP 或 gopher)的操作,则必须与该服务器建立适当的连接。 若要直接打开到特定服务的特定类型的连接,请使用以下成员函数之一:
GetGopherConnection打开与 gopher 服务的连接。GetHttpConnection打开与 HTTP 服务的连接。GetFtpConnection打开与 FTP 服务的连接。
SetOption 允许设置会话的查询选项,例如超时值、重试次数等。
CInternetSession 成员函数 SetCookie、GetCookie 和 GetCookieLength 提供管理 Win32 Cookie 数据库的方法,服务器和脚本通过此方法维护有关客户端工作站的状态信息。
有关基本 Internet 编程任务的详细信息,请参阅 Internet 第一步:WinInet一文。 有关使用 MFC WinInet 类的一般信息,请参阅使用 WinInet 进行 Internet 编程一文。
注意
CInternetSession 将针对不受支持的服务类型引发 AfxThrowNotSupportedException。 目前仅支持以下服务类型:FTP、HTTP、gopher 和文件。
继承层次结构
CObject
CInternetSession
要求
标头:afxinet.h
CInternetSession::CInternetSession
创建 CInternetSession 对象时会调用此成员函数。
CInternetSession(
LPCTSTR pstrAgent = NULL,
DWORD_PTR dwContext = 1,
DWORD dwAccessType = PRE_CONFIG_INTERNET_ACCESS,
LPCTSTR pstrProxyName = NULL,
LPCTSTR pstrProxyBypass = NULL,
DWORD dwFlags = 0);
参数
pstrAgent
指向字符串的指针,该字符串标识调用 Internet 函数的应用程序或实体的名称(例如“Microsoft Internet 浏览器”)。 如果 pstrAgent 为 NULL(默认值),则框架调用全局函数 AfxGetAppName,该函数返回一个包含应用程序名称的以 null 结尾的字符串。 某些协议使用此字符串向服务器标识应用程序。
dwContext
操作的上下文标识符。 dwContext 标识 CInternetSession::OnStatusCallback 返回的操作状态信息。 默认设置为 1;但是,可以为操作显式分配特定的上下文 ID。 该对象及其执行的任何工作都将与该上下文 ID 相关联。
dwAccessType
所需的访问类型。 以下是有效值,确切地说是可能提供的一个值:
INTERNET_OPEN_TYPE_PRECONFIG使用注册表中的预配置设置进行连接。 此访问类型设置为默认值。 若要通过 TIS 代理进行连接,请将dwAccessType设置为此值;然后相应地设置注册表。INTERNET_OPEN_TYPE_DIRECT直接连接到 Internet。INTERNET_OPEN_TYPE_PROXY通过 CERN 代理进行连接。
有关连接不同类型代理的信息,请参阅典型 FTP 客户端应用程序中的步骤。
pstrProxyName
如果将 dwAccessType 设置为 INTERNET_OPEN_TYPE_PROXY,则为首选 CERN 代理的名称。 默认值为 NULL。
pstrProxyBypass
指向包含服务器地址可选列表的字符串的指针。 使用代理访问时可能会绕过这些地址。 如果提供了 NULL 值,则将从注册表中读取绕过列表。 此参数仅在 dwAccessType 设置为 INTERNET_OPEN_TYPE_PROXY 时才有意义。
dwFlags
指示各种缓存选项。 默认值设为 0。 可能的值包括:
INTERNET_FLAG_DONT_CACHE不要在本地或任何网关服务器中缓存数据。INTERNET_FLAG_OFFLINE仅通过持久缓存满足下载操作。 如果缓存中不存在该项,则返回相应的错误代码。 此标志可以与按位“或”(|) 运算符结合使用。
注解
CInternetSession 是应用程序调用的第一个 Internet 函数。 它初始化内部数据结构并为来自应用程序的未来调用做准备。
如果无法打开 Internet 连接,则 CInternetSession 会引发 AfxThrowInternetException。
示例
请参阅 CFtpFileFind 的示例。
CInternetSession::Close
应用程序使用完 CInternetSession 对象后调用此成员函数。
virtual void Close();
示例
请参阅 CFtpFileFind 的示例。
CInternetSession::EnableStatusCallback
调用此成员函数启用状态回调。
BOOL EnableStatusCallback(BOOL bEnable = TRUE);
参数
bEnable
指定是启用还是禁用回调。 默认为 TRUE。
返回值
如果成功,则不为 0;否则为 0。 如果调用失败,请通过检查引发的 CInternetException 对象来确定失败的原因。
备注
在处理状态回调时,可以在应用程序的状态栏中提供有关操作进度的状态(例如正在解析名称、正在连接到服务器等)。 在长期运行期间,特别需要显示运行状态。
因为回调发生在请求的处理过程中,应用程序应该在回调中花费尽可能少的时间,以防止网络数据吞吐量下降。 例如,在回调中放置一个对话框可能是一个冗长的操作,以至于服务器终止了请求。
只要有任何回调处于挂起状态,就无法删除状态回调。
若要异步处理任何操作,必须创建自己的线程或使用没有 MFC 的 WinInet 函数。
CInternetSession::GetContext
调用此成员函数以获取特定应用程序会话的上下文值。
DWORD_PTR GetContext() const;
返回值
应用程序定义的上下文标识符。
备注
OnStatusCallback 使用 GetContext 返回的上下文 ID 报告特定应用程序的状态。 例如,当用户激活涉及返回状态信息的 Internet 请求时,状态回调使用上下文 ID 报告该特定请求的状态。 如果用户激活两个单独的 Internet 请求,这两个请求都涉及返回状态信息,则 OnStatusCallback 使用上下文标识符来返回有关其相应请求的状态。 因此,上下文标识符用于所有状态回调操作,并与会话相关联,直到会话结束。
有关异步操作的详细信息,请参阅 Internet 第一步:WinInet 一文。
CInternetSession::GetCookie
此成员函数实现 Win32 函数 InternetGetCookie 的行为,如 Windows SDK 中所述。
static BOOL GetCookie(
LPCTSTR pstrUrl,
LPCTSTR pstrCookieName,
LPTSTR pstrCookieData,
DWORD dwBufLen);
static BOOL GetCookie(
LPCTSTR pstrUrl,
LPCTSTR pstrCookieName,
CString& strCookieData);
参数
pstrUrl
指向包含 URL 的字符串的指针。
pstrCookieName
指向包含要获取指定 URL 的 Cookie 名称的字符串的指针。
pstrCookieData
在第一个重载中,指向包含接收 Cookie 数据的缓冲区地址的字符串的指针。 此值可为 NULL。 在第二个重载中,引用 CString 对象以接收 Cookie 数据。
dwBufLen
指定 pstrCookieData 缓冲区大小的变量。 如果函数成功,则缓冲区接收复制到 pstrCookieData 缓冲区的数据量。 如果 pstrCookieData 是 NULL,则此参数接收一个值,该值指定复制所有 Cookie 数据所需的缓冲区大小。
返回值
如果成功,则返回 TRUE,否则返回 FALSE。 如果调用失败,则调用 Win32 函数 GetLastError 以确定错误原因。 以下错误值适用:
ERROR_NO_MORE_ITEMS没有指定 URL 及其所有父项的 Cookie。ERROR_INSUFFICIENT_BUFFERdwBufLen中传递的值不足以复制所有 Cookie 数据。dwBufLen中返回的值是获取所有数据所需的缓冲区大小。
备注
在第二个重载中,MFC 将 Cookie 数据检索到提供的 CString 对象中。
CInternetSession::GetCookieLength
调用此成员函数以获取存储在缓冲区中的 Cookie 的长度。
static DWORD GetCookieLength(
LPCTSTR pstrUrl,
LPCTSTR pstrCookieName);
参数
pstrUrl
指向包含 URL 的字符串的指针
pstrCookieName
指向包含 Cookie 名称的字符串的指针。
返回值
一个 DWORD 值,指示存储在缓冲区中的 Cookie 的长度。 如果不存在名称由 pstrCookieName 指示的 Cookie,则为 0。
备注
GetCookie 使用此值。
CInternetSession::GetFtpConnection
调用此成员函数以建立 FTP 连接并获取指向 CFtpConnection 对象的指针。
CFtpConnection* GetFtpConnection(
LPCTSTR pstrServer,
LPCTSTR pstrUserName = NULL,
LPCTSTR pstrPassword = NULL,
INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
BOOL bPassive = FALSE);
参数
pstrServer
指向包含 FTP 服务器名称的字符串的指针。
pstrUserName
指向一个以 NULL 结尾的字符串的指针,该字符串指定要登录的用户的名称。 如果为 NULL,默认为匿名。
pstrPassword
指向一个以 NULL 结尾的字符串的指针,该字符串指定用于登录的密码。 如果 pstrPassword 和 pstrUserName 都是 NULL,则默认匿名密码是用户的电子邮件名称。 如果 pstrPassword 是 NULL(或空字符串)但 pstrUserName 不是 NULL,则使用空白密码。 下表描述了 pstrUserName 和 pstrPassword 的四种可能设置的行为:
pstrUserName |
pstrPassword |
发送到 FTP 服务器的用户名 | 发送到 FTP 服务器的密码 |
|---|---|---|---|
NULL 或 " " |
NULL 或 " " |
"anonymous" |
用户的电子邮件名称 |
非 NULL 字符串 |
NULL 或 " " |
pstrUserName |
[.] |
NULL |
非 NULL 字符串 |
ERROR | ERROR |
非 NULL 字符串 |
非 NULL 字符串 |
pstrUserName |
pstrPassword |
nPort
标识要在服务器上使用的 TCP/IP 端口的数字。
bPassive
为此 FTP 会话指定被动模式或主动模式。 如果设置为 TRUE,它会将 Win32 API dwFlag 设置为 INTERNET_FLAG_PASSIVE。
返回值
一个指向 CFtpConnection 对象的指针。 如果调用失败,请通过检查引发的 CInternetException 对象来确定失败的原因。
注解
GetFtpConnection 连接到 FTP 服务器,创建并返回指向 CFTPConnection 对象的指针。 它不对服务器执行任何特定操作。 例如,如果你打算读取或写入文件,则必须将这些操作作为单独的步骤执行。 有关搜索文件、打开文件以及读取或写入文件的信息,请参阅类 CFtpConnection 和 CFtpFileFind。 有关执行常见 FTP 连接任务的步骤,请参阅使用 WinInet 进行 Internet 编程一文。
示例
请参阅 CFtpFileFind 的示例。
CInternetSession::GetGopherConnection
调用此成员函数以建立新的 gopher 连接并获取指向 CGopherConnection 对象的指针。
CGopherConnection* GetGopherConnection(
LPCTSTR pstrServer,
LPCTSTR pstrUserName = NULL,
LPCTSTR pstrPassword = NULL,
INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER);
参数
pstrServer
指向包含 gopher 服务器名称的字符串的指针。
pstrUserName
指向包含用户名的字符串的指针。
pstrPassword
指向包含访问密码的字符串的指针。
nPort
标识要在服务器上使用的 TCP/IP 端口的数字。
返回值
一个指向 CGopherConnection 对象的指针。 如果调用失败,请通过检查引发的 CInternetException 对象来确定失败的原因。
备注
GetGopherConnection 连接到 gopher 服务器,创建并返回指向 CGopherConnection 对象的指针。 它不对服务器执行任何特定操作。 例如,如果你打算读取或写入数据,则必须将这些操作作为单独的步骤执行。 有关搜索文件、打开文件以及读取或写入文件的信息,请参阅类 CGopherConnection、CGopherFile 和 CGopherFileFind。 有关浏览 FTP 站点的信息,请参阅成员函数 OpenURL。 有关执行常见 gopher 连接任务的步骤,请参阅使用 WinInet 进行 Internet 编程一文。
CInternetSession::GetHttpConnection
调用此成员函数以建立 HTTP 连接并获取指向 CHttpConnection 对象的指针。
CHttpConnection* GetHttpConnection(
LPCTSTR pstrServer,
INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
LPCTSTR pstrUserName = NULL,
LPCTSTR pstrPassword = NULL);
CHttpConnection* GetHttpConnection(
LPCTSTR pstrServer,
DWORD dwFlags,
INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
LPCTSTR pstrUserName = NULL,
LPCTSTR pstrPassword = NULL);
参数
pstrServer
指向包含 HTTP 服务器名称的字符串的指针。
nPort
标识要在服务器上使用的 TCP/IP 端口的数字。
pstrUserName
指向包含用户名的字符串的指针。
pstrPassword
指向包含访问密码的字符串的指针。
dwflags
INTERNET_FLAG_* 标志的任意组合。 有关 dwFlags 值的说明,请参阅 CHttpConnection::OpenRequest 的“注解”部分中的表。
返回值
一个指向 CHttpConnection 对象的指针。 如果调用失败,请通过检查引发的 CInternetException 对象来确定失败的原因。
注解
GetHttpConnection 连接到 HTTP 服务器,创建并返回指向 CHttpConnection 对象的指针。 它不对服务器执行任何特定操作。 例如,如果你打算查询 HTTP 标头,则必须将此操作作为单独的步骤执行。 有关可以通过使用与 HTTP 服务器的连接执行的操作的信息,请参阅类 CHttpConnection 和 CHttpFile。 有关浏览 HTTP 站点的信息,请参阅成员函数 OpenURL。 有关执行常见 HTTP 连接任务的步骤,请参阅使用 WinInet 进行 Internet 编程一文。
CInternetSession::OnStatusCallback
当启用状态回调并且操作处于挂起状态时,框架调用此成员函数来更新状态。
virtual void OnStatusCallback(
DWORD_PTR dwContext,
DWORD dwInternetStatus,
LPVOID lpvStatusInformation,
DWORD dwStatusInformationLength);
参数
dwContext
应用程序提供的上下文值。
dwInternetStatus
一个状态代码,指示为何执行回调。 有关可能值的表,请参阅注解。
lpvStatusInformation
指向包含与此回调相关的信息的缓冲区的指针。
dwStatusInformationLength
lpvStatusInformation 的大小。
备注
必须先调用 EnableStatusCallback 才能利用状态回调。
dwInternetStatus 参数指示正在执行的操作,并确定 lpvStatusInformation 的内容将是什么。 dwStatusInformationLength 指示lpvStatusInformation 中包含的数据的长度。 dwInternetStatus 的以下状态值定义如下:
| 值 | 含义 |
|---|---|
INTERNET_STATUS_RESOLVING_NAME |
查找包含在 lpvStatusInformation 中的名称的 IP 地址。 |
INTERNET_STATUS_NAME_RESOLVED |
已成功找到 lpvStatusInformation 中包含的名称的 IP 地址。 |
INTERNET_STATUS_CONNECTING_TO_SERVER |
连接到 lpvStatusInformation 指向的套接字地址 (SOCKADDR)。 |
INTERNET_STATUS_CONNECTED_TO_SERVER |
已成功连接到 lpvStatusInformation 指向的套接字地址 (SOCKADDR)。 |
INTERNET_STATUS_SENDING_REQUEST |
将信息请求发送到服务器。 lpvStatusInformation 参数为 NULL。 |
INTERNET_STATUS_REQUEST_SENT |
已成功将信息请求发送到服务器。 lpvStatusInformation 参数为 NULL。 |
INTERNET_STATUS_RECEIVING_RESPONSE |
等待服务器响应请求。 lpvStatusInformation 参数为 NULL。 |
INTERNET_STATUS_RESPONSE_RECEIVED |
已成功从服务器收到响应。 lpvStatusInformation 参数为 NULL。 |
INTERNET_STATUS_CLOSING_CONNECTION |
关闭与服务器的连接。 lpvStatusInformation 参数为 NULL。 |
INTERNET_STATUS_CONNECTION_CLOSED |
已成功关闭与服务器的连接。 lpvStatusInformation 参数为 NULL。 |
INTERNET_STATUS_HANDLE_CREATED |
由 Win32 API 函数 InternetConnect 使用以指示它已创建新句柄。 如果连接时间过长,这使应用程序可以从另一个线程调用 Win32 函数 InternetCloseHandle。 有关这些函数的详细信息,请参阅 Windows SDK。 |
INTERNET_STATUS_HANDLE_CLOSING |
已成功终止此句柄值。 |
重写此成员函数以在执行状态回调例程之前要求执行某些操作。
注意
状态回调需要线程状态保护。 如果在共享库中使用 MFC,请将以下行添加到替代的开头:
AFX_MANAGE_STATE(AfxGetAppModuleState());
有关异步操作的详细信息,请参阅 Internet 第一步:WinInet 一文。
CInternetSession::OpenURL
调用此成员函数,以将指定的请求发送到 HTTP 服务器,并允许客户端指定其他 RFC822、MIME 或 HTTP 标头以随请求一起发送。
CStdioFile* OpenURL(
LPCTSTR pstrURL,
DWORD_PTR dwContext = 1,
DWORD dwFlags = INTERNET_FLAG_TRANSFER_ASCII,
LPCTSTR pstrHeaders = NULL,
DWORD dwHeadersLength = 0);
参数
pstrURL
指向要开始读取的 URL 名称的指针。 仅支持以 file:、ftp:、gopher: 或 http: 开头的 URL。 如果 pstrURL 是 NULL,则断言。
dwContext
与回调中返回的句柄一起传递的应用程序定义的值。
dwFlags
描述如何处理此连接的标志。 有关有效标志的详细信息,请参阅注解。 有效标志为:
INTERNET_FLAG_TRANSFER_ASCII默认值。 将文件作为 ASCII 文本传输。INTERNET_FLAG_TRANSFER_BINARY将文件作为二进制文件传输。INTERNET_FLAG_RELOAD即使数据是本地缓存的,也可以从网络中获取数据。INTERNET_FLAG_DONT_CACHE:不要在本地或任何网关中缓存数据。INTERNET_FLAG_SECURE此标志仅适用于 HTTP 请求。 它通过安全套接字层或 PCT 请求网络上的安全事务。INTERNET_OPEN_FLAG_USE_EXISTING_CONNECT如果可能,为OpenUrl生成的新请求重用与服务器的现有连接,而不是为每个连接请求创建一个新会话。INTERNET_FLAG_PASSIVE用于 FTP 站点。 使用被动 FTP 语义。 与OpenURL中的CInternetConnection一起使用。
pstrHeaders
指向包含要发送到 HTTP 服务器的标头的字符串的指针。
dwHeadersLength
附加标头的长度(以字符为单位)。 如果这是 -1L 并且 pstrHeaders 是非 NULL,则假定 pstrHeaders 以 0 结尾并计算长度。
返回值
仅返回 FTP、GOPHER、HTTP 和 FILE 类型 Internet 服务的文件句柄。 如果分析失败,则返回 NULL。
OpenURL 返回的指针取决于 pstrURL 的服务类型。 下表说明了可能的指针 OpenURL 可以返回。
| URL 类型 | 返回 |
|---|---|
file:// |
CStdioFile* |
http:// |
CHttpFile* |
gopher:// |
CGopherFile* |
ftp:// |
CInternetFile* |
备注
参数 dwFlags 必须包含 INTERNET_FLAG_TRANSFER_ASCII 或 INTERNET_FLAG_TRANSFER_BINARY,但不能同时包含两者。 其余标志可以与按位“或”(|) 运算符组合。
OpenURL 包装了 Win32 函数 InternetOpenURL,只允许从 Internet 服务器下载、检索和读取数据。 OpenURL 不允许对远程位置进行文件操作,因此它不需要 CInternetConnection 对象。
若要使用特定于连接(即特定于协议)的函数(例如写入文件),必须打开会话,然后打开特定类型的连接,然后使用该连接以所需模式打开文件。 有关特定于连接的函数的详细信息,请参阅 CInternetConnection。
CInternetSession::operator HINTERNET
使用此运算符获取当前 Internet 会话的 Windows 句柄。
operator HINTERNET() const;
CInternetSession::SetCookie
设置指定的 URL 的 Cookie。
static BOOL SetCookie(
LPCTSTR pstrUrl,
LPCTSTR pstrCookieName,
LPCTSTR pstrCookieData);
参数
pstrUrl
指向以 null 结尾的字符串的指针,该字符串指定应为其设置 Cookie 的 URL。
pstrCookieName
指向包含 Cookie 名称的字符串的指针。
pstrCookieData
指向包含要与 URL 关联的实际字符串数据的字符串的指针。
返回值
如果成功,则返回 TRUE,否则返回 FALSE。 若要获取特定错误代码,请调用 GetLastError。
注解
此成员函数实现 Win32 消息 InternetSetCookie 的行为,如 Windows SDK 中所述。
CInternetSession::SetOption
调用此成员函数以设置 Internet 会话的选项。
BOOL SetOption(
DWORD dwOption,
LPVOID lpBuffer,
DWORD dwBufferLength,
DWORD dwFlags = 0);
BOOL SetOption(
DWORD dwOption,
DWORD dwValue,
DWORD dwFlags = 0);
参数
dwOption
要设置的 Internet 选项。 有关可能选项的列表,请参阅 Windows SDK 中的选项标志。
lpBuffer
包含选项设置的缓冲区。
dwBufferLength
lpBuffer 的长度或 dwValue 的大小。
dwValue
包含选项设置的 DWORD。
dwFlags
指示各种缓存选项。 默认值设为 0。 可能的值包括:
INTERNET_FLAG_DONT_CACHE不要在本地或任何网关服务器中缓存数据。INTERNET_FLAG_OFFLINE仅通过持久缓存满足下载操作。 如果缓存中不存在该项,则返回相应的错误代码。 此标志可以与按位“或”(|) 运算符结合使用。
返回值
如果操作成功,则返回值 TRUE。 如果发生错误,则返回值 FALSE。 如果调用失败,可能会调用 Win32 函数 GetLastError 以确定错误原因。
另请参阅
CObject 类
层次结构图
CInternetConnection 类
CHttpConnection 类
CFtpConnection 类
CGopherConnection 类