CInternetSession 类

注意

Microsoft基础类（MFC）库将继续受到支持。 但是，我们不再添加功能或更新文档。

创建和初始化一个或多个同时 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 连接必须在应用程序期间保持，可以创建 CInternetSession 类的 CWinApp 成员。

建立 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_BUFFER dwBufLen 中传递的值不足以复制所有 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_* 标志的任意组合。 有关 值的说明，请参阅 CHttpConnection::OpenRequest 的“注解”dwFlags部分中的表。

返回值

一个指向 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	连接到 SOCKADDR 指向的套接字地址 (lpvStatusInformation)。
INTERNET_STATUS_CONNECTED_TO_SERVER	已成功连接到 SOCKADDR 指向的套接字地址 (lpvStatusInformation)。
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 语义。 与 CInternetConnection 中的 OpenURL 一起使用。

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 类