CHttpConnection Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CHttpConnection Class.

Manages your connection to an HTTP server.

class CHttpConnection : public CInternetConnection  

Public Constructors

NameDescription
CHttpConnection::CHttpConnectionCreates a CHttpConnection object.

Public Methods

NameDescription
CHttpConnection::OpenRequestOpens an HTTP request.

HTTP is one of three Internet server protocols implemented by the MFC WinInet classes.

The class CHttpConnection contains a constructor and one member function, OpenRequest, that manages connections to a server with an HTTP protocol.

To communicate with an HTTP server, you must first create an instance of CInternetSession, and then create a CHttpConnection object. You never create a CHttpConnection object directly; rather, call CInternetSession::GetHttpConnection, which creates the CHttpConnection object and returns a pointer to it.

To learn more about how CHttpConnection works with the other MFC Internet classes, see the article Internet Programming with WinInet. For more information about connecting to servers using the other two supported Internet protocols, gopher and FTP, see the classes CGopherConnection and CFtpConnection.

CObject

CInternetConnection

CHttpConnection

Header: afxinet.h

This member function is called to construct a CHttpConnection object.

CHttpConnection(
    CInternetSession* pSession,  
    HINTERNET hConnected,  
    LPCTSTR pstrServer,  
    DWORD_PTR dwContext);

 
CHttpConnection(
    CInternetSession* pSession,  
    LPCTSTR pstrServer,  
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,  
    LPCTSTR pstrUserName = NULL,  
    LPCTSTR pstrPassword = NULL,  
    DWORD_PTR dwContext = 1);

 
CHttpConnection(
    CInternetSession* pSession,  
    LPCTSTR pstrServer,  
    DWORD dwFlags,  
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,  
    LPCTSTR pstrUserName = NULL,  
    LPCTSTR pstrPassword = NULL,  
    DWORD_PTR dwContext = 1);

Parameters

pSession
A pointer to a CInternetSession object.

hConnected
A handle to an Internet connection.

pstrServer
A pointer to a string containing the server name.

dwContext
The context identifier for the CInternetConnection object. See Remarks for more information about dwContext.

nPort
The number that identifies the Internet port for this connection.

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 is not NULL, a blank password is used. The following table describes the behavior for the four possible settings of pstrUserName and pstrPassword:

pstrUserNamepstrPasswordUsername sent to FTP serverPassword sent to FTP server
NULL or " "NULL or " ""anonymous"User's email name
Non- NULL StringNULL or " "pstrUserName" "
NULL Non- NULL StringERRORERROR
Non- NULL StringNon- NULL StringpstrUserNamepstrPassword

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

Remarks

You never create a CHttpConnection directly. Rather, you create an object by calling CInternetSession::GetHttpConnection.

Call this member function to open an HTTP connection.

CHttpFile* OpenRequest(
    LPCTSTR pstrVerb,  
    LPCTSTR pstrObjectName,  
    LPCTSTR pstrReferer = NULL,  
    DWORD_PTR dwContext = 1,  
    LPCTSTR* ppstrAcceptTypes = NULL,  
    LPCTSTR pstrVersion = NULL,  
    DWORD dwFlags = INTERNET_FLAG_EXISTING_CONNECT);

 
CHttpFile* OpenRequest(
    int nVerb,  
    LPCTSTR pstrObjectName,  
    LPCTSTR pstrReferer = NULL,  
    DWORD_PTR dwContext = 1,  
    LPCTSTR* ppstrAcceptTypes = NULL,  
    LPCTSTR pstrVersion = NULL,  
    DWORD dwFlags = INTERNET_FLAG_EXISTING_CONNECT);

Parameters

pstrVerb
A pointer to a string containing the verb to use in the request. If NULL, "GET" is used.

pstrObjectName
A pointer to a string containing the target object of the specified verb. This is generally a filename, an executable module, or a search specifier.

pstrReferer
A pointer to a string that specifies the address (URL) of the document from which the URL in the request ( pstrObjectName) was obtained. If NULL, no HTTP header is specified.

dwContext
The context identifier for the OpenRequest operation. See the Remarks section for more information about dwContext.

ppstrAcceptTypes
A pointer to a null-terminated array of LPCTSTR pointers to strings indicating content types accepted by the client. If ppstrAcceptTypes is NULL, the servers interpret that the client only accepts documents of type "text/*" (that is, only text documents and not pictures or other binary files). The content type is equivalent to the CGI variable CONTENT_TYPE, which identifies the type of data for queries that have attached information, such as HTTP POST and PUT.

pstrVersion
A pointer to a string defining the HTTP version. If NULL, "HTTP/1.0" is used.

dwFlags
Any combination of the INTERNET_ FLAG_* flags. See the Remarks section for a description of possible dwFlags values.

nVerb
A number associated with the HTTP request type. Can be one of the following:

HTTP request typenVerb value
HTTP_VERB_POST0
HTTP_VERB_GET1
HTTP_VERB_HEAD2
HTTP_VERB_PUT3
HTTP_VERB_LINK4
HTTP_VERB_DELETE5
HTTP_VERB_UNLINK6

Return Value

A pointer to the CHttpFile object requested.

Remarks

dwFlags can be one of the following:

Internet flagDescription
INTERNET_FLAG_RELOADForces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_DONT_CACHEDoes not add the returned entity to the cache.
INTERNET_FLAG_MAKE_PERSISTENTAdds the returned entity to the cache as a persistent entity. This means that standard cache cleanup, consistency checking, or garbage collection cannot remove this item from the cache.
INTERNET_FLAG_SECUREUses secure transaction semantics. This translates to using SSL/PCT and is only meaningful in HTTP requests
INTERNET_FLAG_NO_AUTO_REDIRECTUsed only with HTTP, specifies that redirections should not be automatically handled in CHttpFile::SendRequest.

Override the dwContext default to set the context identifier to a value of your choosing. The context identifier is associated with this specific operation of the CHttpConnection object created by its CInternetSession object. The value is returned to CInternetSession::OnStatusCallback to provide status on the operation with which it is identified. See the article Internet First Steps: WinInet for more information about the context identifier.

Exceptions may be thrown with this function.

CInternetConnection Class
Hierarchy Chart
CInternetConnection Class
CHttpFile Class

Show: