CHttpFile Class

Article
06/05/2017

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 CHttpFile Class.

Provides the functionality to request and read files on an HTTP server.

Syntax

class CHttpFile : public CInternetFile

Members

Protected Constructors

Name	Description
CHttpFile::CHttpFile	Creates a `CHttpFile` object.

Public Methods

Name	Description
CHttpFile::AddRequestHeaders	Adds headers to the request sent to an HTTP server.
CHttpFile::EndRequest	Ends a request sent to an HTTP server with the SendRequestEx member function.
CHttpFile::GetFileURL	Gets the URL for the specified file.
CHttpFile::GetObject	Gets the target object of the verb in a request to an HTTP server.
CHttpFile::GetVerb	Gets the verb that was used in a request to an HTTP server.
CHttpFile::QueryInfo	Returns the response or request headers from the HTTP server.
CHttpFile::QueryInfoStatusCode	Retrieves the status code associated with an HTTP request and places it in the supplied `dwStatusCode` parameter.
CHttpFile::SendRequest	Sends a request to an HTTP server.
CHttpFile::SendRequestEx	Sends a request to an HTTP server using the Write or WriteString methods of `CInternetFile`.

Remarks

If your Internet session reads data from an HTTP server, you must create an instance of CHttpFile.

To learn more about how CHttpFile works with the other MFC Internet classes, see the article Internet Programming with WinInet.

Inheritance Hierarchy

CHttpFile

Requirements

Header: afxinet.h

CHttpFile::AddRequestHeaders

Call this member function to add one or more HTTP request headers to the HTTP request handle.

BOOL AddRequestHeaders(
    LPCTSTR pstrHeaders,  
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW,  
    int dwHeadersLen = -1);

 
BOOL AddRequestHeaders(
    CString& str,  
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW);

Parameters

pstrHeaders
A pointer to a string containing the header or headers to append to the request. Each header must be terminated by a CR/LF pair.

dwFlags
Modifies the semantics of the new headers. Can be one of the following:

HTTP_ADDREQ_FLAG_COALESCE Merges headers of the same name, using the flag to add the first header found to the subsequent header. For example, "Accept: text/*" followed by "Accept: audio/*" results in the formation of the single header "Accept: text/*, audio/*". It is up to the calling application to ensure a cohesive scheme with respect to data received by requests sent with coalesced or separate headers.
HTTP_ADDREQ_FLAG_REPLACE Performs a remove and add to replace the current header. The header name will be used to remove the current header, and the full value will be used to add the new header. If the header-value is empty and the header is found, it is removed. If not empty, the header-value is replaced.
HTTP_ADDREQ_FLAG_ADD_IF_NEW Only adds the header if it does not already exist. If one exists, an error is returned.
HTTP_ADDREQ_FLAG_ADD Used with REPLACE. Adds the header if it doesn't exist.

dwHeadersLen
The length, in characters, of pstrHeaders. If this is -1L, then pstrHeaders is assumed to be zero-terminated and the length is computed.

str
A reference to a CString object containing the request header or headers to be added.

Return Value

Nonzero if successful; otherwise 0. If the call fails, the Win32 function GetLastError may be called to determine the cause of the error.

Remarks

AddRequestHeaders appends additional, free-format headers to the HTTP request handle. It is intended for use by sophisticated clients who need detailed control over the exact request sent to the HTTP server.

Note

The application can pass multiple headers in pstrHeaders or str for an AddRequestHeaders call using HTTP_ADDREQ_FLAG_ADD or HTTP_ADDREQ_FLAG_ADD_IF_NEW. If the application tries to remove or replace a header using HTTP_ADDREQ_FLAG_REMOVE or HTTP_ADDREQ_FLAG_REPLACE, only one header can be supplied in lpszHeaders.

CHttpFile::CHttpFile

This member function is called to construct a CHttpFile object.

CHttpFile(
    HINTERNET hFile,  
    HINTERNET hSession,  
    LPCTSTR pstrObject,  
    LPCTSTR pstrServer,  
    LPCTSTR pstrVerb,  
    DWORD_PTR dwContext);

 
CHttpFile(
    HINTERNET hFile,  
    LPCTSTR pstrVerb,  
    LPCTSTR pstrObject,  
    CHttpConnection* pConnection);

Parameters

hFile
A handle to an Internet file.

hSession
A handle to an Internet session.

pstrObject
A pointer to a string containing the CHttpFile object.

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

pstrVerb
A pointer to a string containing the method to be used when sending the request. Can be POST, HEAD, or GET.

dwContext
The context identifier for the CHttpFile object. See Remarks for more information about this parameter.

pConnection
A pointer to a CHttpConnection object.

Remarks

You never construct a CHttpFile object directly; rather call CInternetSession::OpenURL or CHttpConnection::OpenRequest instead.

The default value for dwContext is sent by MFC to the CHttpFile object from the CInternetSession object that created the CHttpFile object. When you call CInternetSession::OpenURL or CHttpConnection to construct a CHttpFile object, you can override the default to set the context identifier to a value of your choosing. The context identifier is returned to CInternetSession::OnStatusCallback to provide status on the object with which it is identified. See the article Internet First Steps: WinInet for more information about the context identifier.

CHttpFile::EndRequest

Call this member function to end a request sent to an HTTP server with the SendRequestEx member function.

BOOL EndRequest(
    DWORD dwFlags = 0,  
    LPINTERNET_BUFFERS lpBuffIn = NULL,  
    DWORD_PTR dwContext = 1);

Parameters

dwFlags
Flags describing the operation. For a list of the appropriate flags, see HttpEndRequest in the Windows SDK.

lpBuffIn
Pointer to an initialized INTERNET_BUFFERS that describes the input buffer used for the operation.

dwContext
The context identifier for the CHttpFile operation. See Remarks for more information about this parameter.

Return Value

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

Remarks

The default value for dwContext is sent by MFC to the CHttpFile object from the CInternetSession object that created the CHttpFile object. When you call CInternetSession::OpenURL or CHttpConnection to construct a CHttpFile object, you can override the default to set the context identifier to a value of your choosing. The context identifier is returned to CInternetSession::OnStatusCallback to provide status on the object with which it is identified. See article Internet First Steps: WinInet for more information about the context identifier.

CHttpFile::GetFileURL

Call this member function to get the name of the HTTP file as a URL.

virtual CString GetFileURL() const;

Return Value

A CString object containing a URL referencing the resource associated with this file.

Remarks

Use this member function only after a successful call to SendRequest or on a CHttpFile object successfully created by OpenURL.

CHttpFile::GetObject

Call this member function to get the name of the object associated with this CHttpFile.

CString GetObject() const;

Return Value

A CString object containing the name of the object.

Remarks

Use this member function only after a successful call to SendRequest or on a CHttpFile object successfully created by OpenURL.

CHttpFile::GetVerb

Call this member function to get the HTTP verb (or method) associated with this CHttpFile.

CString GetVerb() const;

Return Value

A CString object containing the name of the HTTP verb (or method).

Remarks

Use this member function only after a successful call to SendRequest or on a CHttpFile object successfully created by OpenURL.

CHttpFile::QueryInfo

Call this member function to return response or request headers from an HTTP request.

BOOL QueryInfo(
    DWORD dwInfoLevel,  
    LPVOID lpvBuffer,  
    LPDWORD lpdwBufferLength,  
    LPDWORD lpdwIndex = NULL) const;  
  
BOOL QueryInfo(
    DWORD dwInfoLevel,  
    CString& str,  
    LPDWORD dwIndex = NULL) const;  
  
BOOL QueryInfo(
    DWORD dwInfoLevel,  
    SYSTEMTIME* pSysTime,  
    LPDWORD dwIndex = NULL) const;

Parameters

dwInfoLevel
A combination of the attribute to query and the following flags that specify the type of information requested:

HTTP_QUERY_CUSTOM Finds the header name and returns this value in lpvBuffer on output. HTTP_QUERY_CUSTOM throws an assertion if the header isn't found.
HTTP_QUERY_FLAG_REQUEST_HEADERS Typically, the application queries the response headers, but an application can also query request headers by using this flag.
HTTP_QUERY_FLAG_SYSTEMTIME For those headers whose value is a date/time string, such as "Last-Modified-Time," this flag returns the header value as a standard Win32 SYSTEMTIME structure that does not require the application to parse the data. If you use this flag, you may want to use the SYSTEMTIME override of the function.
HTTP_QUERY_FLAG_NUMBER For those headers whose value is a number, such as the status code, this flag returns the data as a 32-bit number.

See the Remarks section for a list of the possible values.

lpvBuffer
A pointer to the buffer that receives the information.

lpdwBufferLength
On entry, this points to a value containing the length of the data buffer, in number of characters or bytes. See the Remarks section for more detailed information about this parameter.

lpdwIndex
A pointer to a zero-based header index. Can be NULL. Use this flag to enumerate multiple headers with the same name. On input, lpdwIndex indicates the index of the specified header to return. On output, lpdwIndex indicates the index of the next header. If the next index cannot be found, ERROR_HTTP_HEADER_NOT_FOUND is returned.

str
A reference to the CString object receiving the returned information.

dwIndex
An index value. See lpdwIndex.

pSysTime
A pointer to a Win32 SYSTEMTIME structure.

Return Value

Nonzero if successful; otherwise 0. If the call fails, the Win32 function GetLastError may be called to determine the cause of the error.

Remarks

Use this member function only after a successful call to SendRequest or on a CHttpFile object successfully created by OpenURL.

You can retrieve the following types of data from QueryInfo:

strings (default)
SYSTEMTIME (for "Data:" "Expires:" etc, headers)
DWORD (for STATUS_CODE, CONTENT_LENGTH, etc.)

When a string is written to the buffer, and the member function succeeds, lpdwBufferLength contains the length of the string in characters minus 1 for the terminating NULL character.

The possible dwInfoLevel values include:

HTTP_QUERY_MIME_VERSION
HTTP_QUERY_CONTENT_TYPE
HTTP_QUERY_CONTENT_TRANSFER_ENCODING
HTTP_QUERY_CONTENT_ID
HTTP_QUERY_CONTENT_DESCRIPTION
HTTP_QUERY_CONTENT_LENGTH
HTTP_QUERY_ALLOWED_METHODS
HTTP_QUERY_PUBLIC_METHODS
HTTP_QUERY_DATE
HTTP_QUERY_EXPIRES
HTTP_QUERY_LAST_MODIFIED
HTTP_QUERY_MESSAGE_ID
HTTP_QUERY_URI
HTTP_QUERY_DERIVED_FROM
HTTP_QUERY_LANGUAGE
HTTP_QUERY_COST
HTTP_QUERY_WWW_LINK
HTTP_QUERY_PRAGMA
HTTP_QUERY_VERSION
HTTP_QUERY_STATUS_CODE
HTTP_QUERY_STATUS_TEXT
HTTP_QUERY_RAW_HEADERS
HTTP_QUERY_RAW_HEADERS_CRLF

CHttpFile::QueryInfoStatusCode

Call this member function to get the status code associated with an HTTP request and place it in the supplied dwStatusCode parameter.

BOOL QueryInfoStatusCode(DWORD& dwStatusCode) const;

Parameters

dwStatusCode
A reference to a status code. Status codes indicate the success or failure of the requested event. See Remarks for a selection of status code descriptions.

Return Value

Nonzero if successful; otherwise 0. If the call fails, the Win32 function GetLastError may be called to determine the cause of the error.

Remarks

Use this member function only after a successful call to SendRequest or on a CHttpFile object successfully created by OpenURL.

HTTP status codes fall into groups indicating the success or failure of the request. The following tables outline the status code groups and the most common HTTP status codes.

Group	Meaning
200-299	Success
300-399	Information
400-499	Request error
500-599	Server error

Common HTTP Status Codes:

Status code	Meaning
200	URL located, transmission follows
400	Unintelligible request
404	Requested URL not found
405	Server does not support requested method
500	Unknown server error
503	Server capacity reached

CHttpFile::SendRequest

Call this member function to send a request to an HTTP server.

BOOL SendRequest(
    LPCTSTR pstrHeaders = NULL,  
    DWORD dwHeadersLen = 0,  
    LPVOID lpOptional = NULL,  
    DWORD dwOptionalLen = 0);

 
BOOL SendRequest(
    CString& strHeaders,  
    LPVOID lpOptional = NULL,  
    DWORD dwOptionalLen = 0);

Parameters

pstrHeaders
A pointer to a string containing the name of the headers to send.

dwHeadersLen
The length of the headers identified by pstrHeaders.

lpOptional
Any optional data to send immediately after the request headers. This is generally used for POST and PUT operations. This can be NULL if there is no optional data to send.

dwOptionalLen
The length of lpOptional.

strHeaders
A string containing the name of the headers for the request being sent.

Return Value

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

CHttpFile::SendRequestEx

Call this member function to send a request to an HTTP server.

BOOL SendRequestEx(
    DWORD dwTotalLen,  
    DWORD dwFlags = HSR_INITIATE,  
    DWORD_PTR dwContext = 1);

 
BOOL SendRequestEx(
    LPINTERNET_BUFFERS lpBuffIn,  
    LPINTERNET_BUFFERS lpBuffOut,  
    DWORD dwFlags = HSR_INITIATE,  
    DWORD_PTR dwContext = 1);

Parameters

dwTotalLen
Number of bytes to be sent in the request.

dwFlags
Flags describing the operation. For a list of appropriate flags, see HttpSendRequestEx in the Windows SDK*.*

dwContext
The context identifier for the CHttpFile operation. See Remarks for more information about this parameter.

lpBuffIn
Pointer to an initialized INTERNET_BUFFERS that describes the input buffer used for the operation.

lpBuffOut
Pointer to an initialized INTERNET_BUFFERS that describes the output buffer used for the operation.

Return Value

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

Remarks

This function allows your application to send data using the Write and WriteString methods of CInternetFile. You must know the length of the data to send before calling either override of this function. The first override allows you to specify the length of data you'd like to send. The second override accepts pointers to INTERNET_BUFFERS structures, which can be used to describe the buffer in great detail.

After content is written to the file, call EndRequest to end the operation.

The default value for dwContext is sent by MFC to the CHttpFile object from the CInternetSession object that created the CHttpFile object. When you call CInternetSession::OpenURL or CHttpConnection to construct a CHttpFile object, you can override the default to set the context identifier to a value of your choosing. The context identifier is returned to CInternetSession::OnStatusCallback to provide status on the object with which it is identified. See the article Internet First Steps: WinInet for more information about the context identifier.

Example

This code fragment sends the content of a string to a DLL named MFCISAPI.DLL on the LOCALHOST server. While this example uses only one call to WriteString, using multiple calls to send data in blocks is acceptable.

      CString strData = _T("Some very long data to be POSTed here!");
      pServer = session.GetHttpConnection(_T("localhost"));
      pFile = pServer->OpenRequest(CHttpConnection::HTTP_VERB_POST, 
         _T("/MFCISAPI/MFCISAPI.dll?"));
      pFile->SendRequestEx(strData.GetLength());

      pFile->WriteString(strData);   
      pFile->EndRequest();

Share via

CHttpFile Class

Syntax

Members

Protected Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CHttpFile::AddRequestHeaders

Parameters

Return Value

Remarks

CHttpFile::CHttpFile

Parameters

Remarks

CHttpFile::EndRequest

Parameters

Return Value

Remarks

CHttpFile::GetFileURL

Return Value

Remarks

CHttpFile::GetObject

Return Value

Remarks

CHttpFile::GetVerb

Return Value

Remarks

CHttpFile::QueryInfo

Parameters

Return Value

Remarks

CHttpFile::QueryInfoStatusCode

Parameters

Return Value

Remarks

CHttpFile::SendRequest

Parameters

Return Value

CHttpFile::SendRequestEx

Parameters

Return Value

Remarks

Example

See Also

Additional resources