CHttpFile Class

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

Syntax

class CHttpFile : public CInternetFile

Members

Protected Constructors

Public Methods

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

CObject

CFile

CStdioFile

CInternetFile

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.

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.

Common HTTP Status Codes:

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

See also

CInternetFile Class
Hierarchy Chart
CInternetFile Class
CGopherFile Class
CHttpConnection Class