CInternetSession Class

Creates and initializes a single or several simultaneous Internet sessions and, if necessary, describes your connection to a proxy server.

Syntax

class CInternetSession : public CObject

Members

Public Constructors

Name	Description
CInternetSession::CInternetSession	Constructs a CInternetSession object.

Public Methods

Name	Description
CInternetSession::Close	Closes the Internet connection when the Internet session is terminated.
CInternetSession::EnableStatusCallback	Establishes a status callback routine.
CInternetSession::GetContext	Closes the Internet connection when the Internet session is terminated.
CInternetSession::GetCookie	Returns cookies for the specified URL and all its parent URLs.
CInternetSession::GetCookieLength	Retrieves the variable specifying the length of the cookie stored in the buffer.
CInternetSession::GetFtpConnection	Opens an FTP session with a server. Logs on the user.
CInternetSession::GetGopherConnection	Opens a gopher server for an application that is trying to open a connection.
CInternetSession::GetHttpConnection	Opens an HTTP server for an application that is trying to open a connection.
CInternetSession::OnStatusCallback	Updates the status of an operation when status callback is enabled.
CInternetSession::OpenURL	Parses and opens a URL.
CInternetSession::SetCookie	Sets a cookie for the specified URL.
CInternetSession::SetOption	Sets options for the Internet session.

Public Operators

Name	Description
CInternetSession::operator HINTERNET	A handle to the current Internet session.

Remarks

If your Internet connection must be maintained for the duration of an application, you can create a CInternetSession member of the class CWinApp.

Once you've established an Internet session, you can call OpenURL. CInternetSession then parses the URL for you by calling the global function AfxParseURL. Regardless of its protocol type, CInternetSession interprets the URL and manages it for you. It can handle requests for local files identified with the URL resource "file://". OpenURL will return a pointer to a CStdioFile object if the name you pass it is a local file.

If you open a URL on an Internet server using OpenURL, you can read information from the site. If you want to perform service-specific (for example, HTTP, FTP, or gopher) actions on files located on a server, you must establish the appropriate connection with that server. To open a particular kind of connection directly to a particular service, use one of the following member functions:

• GetGopherConnection to open a connection to a gopher service.

• GetHttpConnection to open a connection to an HTTP service.

• GetFtpConnection to open a connection to an FTP service.

SetOption allows you to set the query options of your session, such as time-out values, number of retries, and so on.

CInternetSession member functions SetCookie, GetCookie, and GetCookieLength provide the means to manage a Win32 cookie database, through which servers and scripts maintain state information about the client workstation.

For more information about basic Internet programming tasks, see the article Internet First Steps: WinInet. For general information about using the MFC WinInet classes, see the article Internet Programming with WinInet.

Note

CInternetSession will throw an AfxThrowNotSupportedException for unsupported service types. Only the following service types are currently supported: FTP, HTTP, gopher, and file.

Inheritance Hierarchy

CObject
 CInternetSession

Requirements

Header: afxinet.h

CInternetSession::CInternetSession

This member function is called when a CInternetSession object is created.

CInternetSession(
    LPCTSTR pstrAgent = NULL,
    DWORD_PTR dwContext = 1,
    DWORD dwAccessType = PRE_CONFIG_INTERNET_ACCESS,
    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.

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

• INTERNET_OPEN_TYPE_PRECONFIG Connect using preconfigured settings in the registry. This access type is set as the default. To connect through a TIS proxy, set dwAccessType to this value; you then set the registry appropriately.

• INTERNET_OPEN_TYPE_DIRECT Connect directly to Internet.

• INTERNET_OPEN_TYPE_PROXY Connect through a CERN proxy.

For information on connecting with different types of proxies, see Steps in a Typical FTP Client Application.

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 caching options. The default is set to 0. The possible values include:

• INTERNET_FLAG_DONT_CACHE Don't cache the data, either locally or in any gateway servers.

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

Remarks

CInternetSession is the first Internet function called by an application. It initializes internal data structures and prepares for future calls from the application.

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

Example

See the example for CFtpFileFind.

CInternetSession::Close

Call this member function when your application has finished using the CInternetSession object.

virtual void Close();

Example

See the example for CFtpFileFind.

CInternetSession::EnableStatusCallback

Call this member function to enable status callback.

BOOL EnableStatusCallback(BOOL bEnable = TRUE);

Parameters

bEnable
Specifies whether callback is enabled or disabled. The default is TRUE.

Return Value

Nonzero if successful; otherwise 0. If the call fails, determine the cause of the failure by examining the thrown CInternetException object.

Remarks

When handling status callback, you can provide status about the progress of the operation (such as resolving name, connecting to server, and so on) in the status bar of the application. Displaying operation status is especially desirable during a long-term operation.

Because callbacks occur during the request's processing, the application should spend as little time as possible in the callback to prevent degradation of data throughput to the network. For example, putting up a dialog box in a callback may be such a lengthy operation that the server terminates the request.

The status callback can't be removed as long as any callbacks are pending.

To handle any operations asynchronously, you must either create your own thread or use the WinInet functions without MFC.

CInternetSession::GetContext

Call this member function to get the context value for a particular application session.

DWORD_PTR GetContext() const;

Return Value

The application-defined context Identifier.

Remarks

OnStatusCallback uses the context ID returned by GetContext to report the status of a particular application. For example, when a user activates an Internet request that involves returning status information, the status callback uses the context ID to report status on that particular request. If the user activates two separate Internet requests that both involve returning status information, OnStatusCallback uses the context identifiers to return status about their corresponding requests. Consequently, the context identifier is used for all status callback operations, and it's associated with the session until the session is ended.

For more information about asynchronous operations, see the article Internet First Steps: WinInet.

CInternetSession::GetCookie

This member function implements the behavior of the Win32 function InternetGetCookie, as described in the Windows SDK.

static BOOL GetCookie(
    LPCTSTR pstrUrl,
    LPCTSTR pstrCookieName,
    LPTSTR pstrCookieData,
    DWORD dwBufLen);

static BOOL GetCookie(
    LPCTSTR pstrUrl,
    LPCTSTR pstrCookieName,
    CString& strCookieData);

Parameters

pstrUrl
A pointer to a string containing the URL.

pstrCookieName
A pointer to a string containing the name of the cookie to get for the specified URL.

pstrCookieData
In the first overload, a pointer to a string containing the address of the buffer that receives the cookie data. This value can be NULL. In the second overload, a reference to a CString object to receive the cookie data.

dwBufLen
The variable specifying the size of the pstrCookieData buffer. If the function succeeds, the buffer receives the amount of data copied to the pstrCookieData buffer. If pstrCookieData is NULL, this parameter receives a value that specifies the size of the buffer necessary to copy all the cookie data.

Return Value

Returns TRUE if successful, or FALSE otherwise. If the call fails, call the Win32 function GetLastError to determine the cause of the error. The following error values apply:

• ERROR_NO_MORE_ITEMS There's no cookie for the specified URL and all its parents.

• ERROR_INSUFFICIENT_BUFFER The value passed in dwBufLen is insufficient to copy all the cookie data. The value returned in dwBufLen is the size of the buffer necessary to get all the data.

Remarks

In the second overload, MFC retrieves the cookie data into the supplied CString object.

CInternetSession::GetCookieLength

Call this member function to get the length of the cookie stored in the buffer.

static DWORD GetCookieLength(
    LPCTSTR pstrUrl,
    LPCTSTR pstrCookieName);

Parameters

pstrUrl
A pointer to a string containing the URL

pstrCookieName
A pointer to a string containing the name of the cookie.

Return Value

A DWORD value indicating the length of the cookie, stored in the buffer. Zero if no cookie with the name indicated by pstrCookieName exists.

Remarks

This value is used by GetCookie.

CInternetSession::GetFtpConnection

Call this member function to establish an FTP connection and get a pointer to a CFtpConnection object.

CFtpConnection* GetFtpConnection(
    LPCTSTR pstrServer,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
    BOOL bPassive = FALSE);

Parameters

pstrServer
A pointer to a string containing the FTP server name.

pstrUserName
Pointer to a null-terminated string that specifies the name of the user to log in. If NULL, the default is anonymous.

pstrPassword
A pointer to a null-terminated string that specifies the password to use to log in. If both pstrPassword and pstrUserName are NULL, the default anonymous password is the user's email name. If pstrPassword is NULL (or an empty string) but pstrUserName isn't NULL, a blank password is used. The following table describes the behavior for the four possible settings of pstrUserName and pstrPassword:

pstrUserName	pstrPassword	Username sent to FTP server	Password sent to FTP server
NULL or " "	NULL or " "	"anonymous"	User's email name
Non-NULL String	NULL or " "	pstrUserName	" "
NULL	Non-NULL String	ERROR	ERROR
Non-NULL String	Non-NULL String	pstrUserName	pstrPassword

nPort
A number that identifies the TCP/IP port to use on the server.

bPassive
Specifies passive or active mode for this FTP session. If set to TRUE, it sets the Win32 API dwFlag to INTERNET_FLAG_PASSIVE.

Return Value

A pointer to a CFtpConnection object. If the call fails, determine the cause of the failure by examining the thrown CInternetException object.

Remarks

GetFtpConnection connects to an FTP server, and creates and returns a pointer to a CFTPConnection object. It doesn't perform any specific operation on the server. If you intend to read or write to files, for example, you must perform those operations as separate steps. See the classes CFtpConnection and CFtpFileFind for information about searching for files, opening files, and reading or writing to files. See the article Internet Programming with WinInet for steps in performing common FTP connection tasks.

Example

See the example for CFtpFileFind.

CInternetSession::GetGopherConnection

Call this member function to establish a new gopher connection and get a pointer to a CGopherConnection object.

CGopherConnection* GetGopherConnection(
    LPCTSTR pstrServer,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER);

Parameters

pstrServer
A pointer to a string containing the gopher server name.

pstrUserName
A pointer to a string containing the user name.

pstrPassword
A pointer to a string containing the access password.

nPort
A number that identifies the TCP/IP port to use on the server.

Return Value

A pointer to a CGopherConnection object. If the call fails, determine the cause of the failure by examining the thrown CInternetException object.

Remarks

GetGopherConnection connects to a gopher server, and creates and returns a pointer to a CGopherConnection object. It doesn't perform any specific operation on the server. If you intend to read or write data, for example, you must perform those operations as separate steps. See the classes CGopherConnection, CGopherFile, and CGopherFileFind for information about searching for files, opening files, and reading or writing to files. For information about browsing an FTP site, see the member function OpenURL. See the article Internet Programming with WinInet for steps in performing common gopher connection tasks.

CInternetSession::GetHttpConnection

Call this member function to establish an HTTP connection and get a pointer to a CHttpConnection object.

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);

Parameters

pstrServer
A pointer to a string containing the HTTP server name.

nPort
A number that identifies the TCP/IP port to use on the server.

pstrUserName
A pointer to a string containing the user name.

pstrPassword
A pointer to a string containing the access password.

dwflags
Any combination of the INTERNET_FLAG_* flags. See the table in the Remarks section of CHttpConnection::OpenRequest for a description of dwFlags values.

Return Value

A pointer to a CHttpConnection object. If the call fails, determine the cause of the failure by examining the thrown CInternetException object.

Remarks

GetHttpConnection connects to an HTTP server, and creates and returns a pointer to a CHttpConnection object. It doesn't perform any specific operation on the server. If you intend to query an HTTP header, for example, you must perform this operation as a separate step. See the classes CHttpConnection and CHttpFile for information about operations you can perform by using a connection to an HTTP server. For information about browsing an HTTP site, see the member function OpenURL. See the article Internet Programming with WinInet for steps in performing common HTTP connection tasks.

CInternetSession::OnStatusCallback

This member function is called by the framework to update the status when status callback is enabled and an operation is pending.

virtual void OnStatusCallback(
    DWORD_PTR dwContext,
    DWORD dwInternetStatus,
    LPVOID lpvStatusInformation,
    DWORD dwStatusInformationLength);

Parameters

dwContext
The context value supplied by the application.

dwInternetStatus
A status code that indicates why the callback is being made. See Remarks for a table of possible values.

lpvStatusInformation
A pointer to a buffer containing information pertinent to this callback.

dwStatusInformationLength
The size of lpvStatusInformation.

Remarks

You must first call EnableStatusCallback to take advantage of status callback.

The dwInternetStatus parameter indicates the operation being performed and determines what the contents of lpvStatusInformation will be. dwStatusInformationLength indicates the length of the data included in lpvStatusInformation. The following status values for dwInternetStatus are defined as follows:

Value	Meaning
INTERNET_STATUS_RESOLVING_NAME	Looking up the IP address of the name contained in lpvStatusInformation.
INTERNET_STATUS_NAME_RESOLVED	Successfully found the IP address of the name contained in lpvStatusInformation.
INTERNET_STATUS_CONNECTING_TO_SERVER	Connecting to the socket address (SOCKADDR) pointed to by lpvStatusInformation.
INTERNET_STATUS_CONNECTED_TO_SERVER	Successfully connected to the socket address (SOCKADDR) pointed to by lpvStatusInformation.
INTERNET_STATUS_SENDING_REQUEST	Sending the information request to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_REQUEST_SENT	Successfully sent the information request to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_RECEIVING_RESPONSE	Waiting for the server to respond to a request. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_RESPONSE_RECEIVED	Successfully received a response from the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_CLOSING_CONNECTION	Closing the connection to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_CONNECTION_CLOSED	Successfully closed the connection to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_HANDLE_CREATED	Used by the Win32 API function InternetConnect to indicate that it has created the new handle. This lets the application call the Win32 function InternetCloseHandle from another thread if the connect is taking too long. See the Windows SDKfor more information about these functions.
INTERNET_STATUS_HANDLE_CLOSING	Successfully terminated this handle value.

Override this member function to require some action before a status callback routine is performed.

Note

Status callbacks need thread-state protection. If you are using MFC in a shared library, add the following line to the beginning of your override:

AFX_MANAGE_STATE(AfxGetAppModuleState());

For more information about asynchronous operations, see the article Internet First Steps: WinInet.

CInternetSession::OpenURL

Call this member function to send the specified request to the HTTP server and allow the client to specify additional RFC822, MIME, or HTTP headers to send along with the request.

CStdioFile* OpenURL(
    LPCTSTR pstrURL,
    DWORD_PTR dwContext = 1,
    DWORD dwFlags = INTERNET_FLAG_TRANSFER_ASCII,
    LPCTSTR pstrHeaders = NULL,
    DWORD dwHeadersLength = 0);

Parameters

pstrURL
A pointer to the name of the URL to begin reading. Only URLs beginning with file:, ftp:, gopher:, or http: are supported. Asserts if pstrURL is NULL.

dwContext
An application-defined value passed with the returned handle in callback.

dwFlags
The flags describing how to handle this connection. See Remarks for more information about the valid flags. The valid flags are:

• INTERNET_FLAG_TRANSFER_ASCII The default. Transfer the file as ASCII text.

• INTERNET_FLAG_TRANSFER_BINARY Transfer the file as a binary file.

• INTERNET_FLAG_RELOAD Get the data from the wire even if it's locally cached.

• INTERNET_FLAG_DONT_CACHE Don't cache the data, either locally or in any gateways.

• INTERNET_FLAG_SECURE This flag is applicable to HTTP requests only. It requests secure transactions on the wire with Secure Sockets Layer or PCT.

• INTERNET_OPEN_FLAG_USE_EXISTING_CONNECT If possible, reuse the existing connections to the server for new requests generated by OpenUrl instead of creating a new session for each connection request.

• INTERNET_FLAG_PASSIVE Used for an FTP site. Uses passive FTP semantics. Used with CInternetConnection of OpenURL.

pstrHeaders
A pointer to a string containing the headers to be sent to the HTTP server.

dwHeadersLength
The length, in characters, of the additional headers. If this is -1L and pstrHeaders is non-NULL, then pstrHeaders is assumed to be zero terminated and the length is calculated.

Return Value

Returns a file handle for FTP, GOPHER, HTTP, and FILE-type Internet services only. Returns NULL if parsing was unsuccessful.

The pointer that OpenURL returns depends on pstrURL's type of service. The table below illustrates the possible pointers OpenURL can return.

URL type	Returns
file://	CStdioFile*
http://	CHttpFile*
gopher://	CGopherFile*
ftp://	CInternetFile*

Remarks

The parameter dwFlags must include either INTERNET_FLAG_TRANSFER_ASCII or INTERNET_FLAG_TRANSFER_BINARY, but not both. The remaining flags can be combined with the bitwise "or" (|) operator.

OpenURL, which wraps the Win32 function InternetOpenURL, allows only downloading, retrieving, and reading the data from an Internet server. OpenURL allows no file manipulation on a remote location, so it requires no CInternetConnection object.

To use connection-specific (that is, protocol-specific) functions, such as writing to a file, you must open a session, then open a particular kind of connection, then use that connection to open a file in the desired mode. See CInternetConnection for more information about connection-specific functions.

CInternetSession::operator HINTERNET

Use this operator to get the Windows handle for the current Internet session.

operator HINTERNET() const;

CInternetSession::SetCookie

Sets a cookie for the specified URL.

static BOOL SetCookie(
    LPCTSTR pstrUrl,
    LPCTSTR pstrCookieName,
    LPCTSTR pstrCookieData);

Parameters

pstrUrl
A pointer to a null-terminated string that specifies the URL for which the cookie should be set.

pstrCookieName
A pointer to a string containing the name of the cookie.

pstrCookieData
A pointer to a string containing the actual string data to associate with the URL.

Return Value

Returns TRUE if successful, or FALSE otherwise. To get the specific error code, call GetLastError.

Remarks

This member function implements the behavior of the Win32 message InternetSetCookie, as described in the Windows SDK.

CInternetSession::SetOption

Call this member function to set options for the Internet session.

BOOL SetOption(
    DWORD dwOption,
    LPVOID lpBuffer,
    DWORD dwBufferLength,
    DWORD dwFlags = 0);

BOOL SetOption(
    DWORD dwOption,
    DWORD dwValue,
    DWORD dwFlags = 0);

Parameters

dwOption
The Internet option to set. See Option Flags in the Windows SDK for a list of the possible options.

lpBuffer
A buffer that contains the option setting.

dwBufferLength
The length of lpBuffer or the size of dwValue.

dwValue
A DWORD that contains the option setting.

dwFlags
Indicates various caching options. The default is set to 0. The possible values include:

• INTERNET_FLAG_DONT_CACHE Don't cache the data, either locally or in any gateway servers.

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

Return Value

If the operation was successful, a value of TRUE is returned. If an error occurred, a value of FALSE is returned. If the call fails, the Win32 function GetLastError may be called to determine the cause of the error.

See also

CObject Class
Hierarchy Chart
CInternetConnection Class
CHttpConnection Class
CFtpConnection Class
CGopherConnection Class