Share via

CInternetSession::CInternetSession

  • Article

CInternetSession( LPCTSTR pstrAgent = NULL, DWORD dwContext = 1, DWORD dwAccessType = INTERNET_OPEN_TYPE_PRECONFIG, LPCTSTR pstrProxyName = NULL, LPCTSTR pstrProxyBypass = NULL, DWORD dwFlags = 0 );

Parameters

pstrAgent

A pointer to a string that identifies the name of the application or entity calling the Internet functions (for example, "Microsoft Internet Browser"). If pstrAgent is NULL (the default), the framework calls the global function AfxGetAppName, which returns a null-terminated string containing an application’s name. Some protocols use this string to identify your application to the server.

dwContext

The context identifier for the operation. dwContext identifies the operation’s status information returned by CInternetSession::OnStatusCallback. The default is set to 1; however, you can explicitly assign a specific context ID for the operation. The object and any work it does will be associated with that context ID. If dwFlags includes INTERNET_FLAG_ASYNC, then objects created by this object have asynchronous behavior as long as a status callback routine is registered. In order for a function to be completed synchronously, dwContext has to be set to zero for that call.

dwAccessType

The type of access required. The following are valid values, exactly one of which may be supplied:

  • INTERNET_OPEN_TYPE_PRECONFIG   Preconfigured (in the registry). This access type is set as the default.

  • INTERNET_OPEN_TYPE_DIRECT   Direct to Internet.

  • INTERNET_OPEN_TYPE_PROXY   Through CERN proxy.

pstrProxyName

The name of the preferred CERN proxy if dwAccessType is set as INTERNET_OPEN_TYPE_PROXY. The default is NULL.

pstrProxyBypass

A pointer to a string containing an optional list of server addresses. These addresses may be bypassed when using proxy access. If a NULL value is supplied, the bypass list will be read from the registry. This parameter is meaningful only if dwAccessType is set to INTERNET_OPEN_TYPE_PROXY.

dwFlags

Indicates various options such as caching and asynchronous behavior. The default is set to 0. The possible values include:

  • INTERNET_FLAG_DONT_CACHE   Do not cache the data, either locally or in any gateway servers.

  • INTERNET_FLAG_ASYNC   Future operations on this object may fail with ERROR_IO_PENDING. A status callback will be made with INTERNET_STATUS_REQUEST_COMPLETE when the operation finishes. This callback is on a thread other than the one for the original request. You must call EnableStatusCallback to establish a status callback routine, or the functions will be completed synchronously.

  • INTERNET_FLAG_OFFLINE   Download operations are satisfied through the persistent cache only. If the item does not exist in the cache, an appropriate error code is returned. This flag may be combined with the bitwise OR (|) operator.

Remarks

This member function is called when a CInternetSession object is created. CInternetSession is the first Internet function called by an application. It initializes internal data structures and prepares for future calls from the application.

If dwFlags includes INTERNET_FLAG_ASYNC, then all handles derived from this handle will have asynchronous behavior as long as a status callback routine is registered.

If no Internet connection can be opened, CInternetSession throws an AfxThrowInternetException.

Example

See the example for CFtpFileFind.

CInternetSession Overview |  Class Members |  Hierarchy Chart

See Also   CInternetSession::Close, CInternetSession::EnableStatusCallback, CInternetSession::GetContext