CHttpFile 类

项目
06/16/2023

提供请求和读取 HTTP 服务器上文件的功能。

语法

class CHttpFile : public CInternetFile

成员

受保护构造函数

名称	描述
CHttpFile::CHttpFile	创建一个 `CHttpFile` 对象。

公共方法

名称	描述
CHttpFile::AddRequestHeaders	将标头添加到发送到 HTTP 服务器的请求。
CHttpFile::EndRequest	使用 SendRequestEx 成员函数结束发送到 HTTP 服务器的请求。
CHttpFile::GetFileURL	获取指定文件的 URL。
CHttpFile::GetObject	获取对 HTTP 服务器的请求中谓词的目标对象。
CHttpFile::GetVerb	获取在对 HTTP 服务器的请求中使用的谓词。
CHttpFile::QueryInfo	从 HTTP 服务器返回响应或请求头。
CHttpFile::QueryInfoStatusCode	检索与 HTTP 请求关联的状态代码，并将其置于提供的 `dwStatusCode` 参数中。
CHttpFile::SendRequest	将请求发送到 HTTP 服务器。
CHttpFile::SendRequestEx	使用 `CInternetFile` 的 Write 或 WriteString 方法向 HTTP 服务器发送请求。

备注

如果 Internet 会话从 HTTP 服务器读取数据，则必须创建 CHttpFile 的实例。

若要详细了解 CHttpFile 如何与其他 MFC Internet 类配合工作，请参阅使用 WinInet 进行 Internet 编程一文。

继承层次结构

CHttpFile

要求

标头：afxinet.h

CHttpFile::AddRequestHeaders

调用此成员函数，将一个或多个 HTTP 请求头添加到 HTTP 请求句柄。

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

参数

pstrHeaders
指向包含要追加到请求的一个或多个标头的字符串的指针。每个标头必须以 CR/LF 对结尾。

dwFlags
修改新标头的语义。可以是以下值之一：

HTTP_ADDREQ_FLAG_COALESCE 合并同名标头，使用该标志将找到的第一个标头添加到后续标头。例如，“Accept: text/*”后跟“Accept: audio/*”会导致形成单个标头“Accept: text/*, audio/*”。由调用应用程序决定，以确保与通过联合或单独标头发送的请求所接收的数据建立一致方案。
HTTP_ADDREQ_FLAG_REPLACE 执行删除并添加以替换当前标头。标头名称将用于删除当前标头，而完整值将用于添加新标头。如果标头值为空且找到标头，则会删除该标头。如果不为空，则会替换标头值。
HTTP_ADDREQ_FLAG_ADD_IF_NEW 仅添加尚不存在的标头。如果已存在，则会返回错误。
HTTP_ADDREQ_FLAG_ADD 与 REPLACE 一起使用。如果标头不存在，则添加该标头。

dwHeadersLen
pstrHeaders 的长度（以字符为单位）。如果是 -1L，则假定 pstrHeaders 以零结尾，并计算长度。

str
对包含要添加的请求头或标头的 CString 对象的引用。

返回值

如果成功，则不为 0；否则为 0。如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

备注

AddRequestHeaders 将其他自由格式标头追加到 HTTP 请求句柄。它适用于需要对发送到 HTTP 服务器的确切请求进行详细控制的复杂客户端使用。

注意

应用程序可以使用 HTTP_ADDREQ_FLAG_ADD 或 HTTP_ADDREQ_FLAG_ADD_IF_NEW 在 pstrHeaders 或 str 中为 AddRequestHeaders 调用传递多个标头。如果应用程序尝试使用 HTTP_ADDREQ_FLAG_REMOVE 或 HTTP_ADDREQ_FLAG_REPLACE 删除或替换标头，则只能在 lpszHeaders 中提供一个标头。

CHttpFile::CHttpFile

调用此成员函数来构造 CHttpFile 对象。

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

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

参数

hFile
Internet 文件的句柄。

hSession
Internet 会话的句柄。

pstrObject
指向包含 CHttpFile 对象的字符串的指针。

pstrServer
指向包含服务器名称的字符串的指针。

pstrVerb
指向包含发送请求时要使用的方法的字符串的指针。可以是 POST、HEAD 或 GET。

dwContext
CHttpFile 对象的上下文标识符。有关此参数的详细信息，请参阅注解。

pConnection
指向 CHttpConnection 对象的指针。

备注

你永远不会直接构造 CHttpFile 对象；而是调用 CInternetSession::OpenURL 或 CHttpConnection::OpenRequest。

MFC 将 dwContext 的默认值从创建 CHttpFile 对象的 CInternetSession 对象发送到 CHttpFile 对象。调用 CInternetSession::OpenURL 或 CHttpConnection 构造 CHttpFile 对象时，可以重写默认值，将上下文标识符设置为所选的值。上下文标识符将返回到 CInternetSession::OnStatusCallback，以提供标识它的对象的状态。有关上下文标识符的详细信息，请参阅 Internet 首要步骤：WinInet 一文。

CHttpFile::EndRequest

调用此成员函数以结束使用 SendRequestEx 成员函数发送到 HTTP 服务器的请求。

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

参数

dwFlags
描述操作的标志。有关相应标志的列表，请参阅 Windows SDK 中的 HttpEndRequest。

lpBuffIn
指向描述用于操作的输入缓冲区的初始化 INTERNET_BUFFERS 的指针。

dwContext
CHttpFile 操作的上下文标识符。有关此参数的详细信息，请参阅注解。

返回值

如果成功，则不为 0；否则为 0。如果调用失败，请通过检查引发的 CInternetException 对象来确定失败的原因。

备注

MFC 将 dwContext 的默认值从创建 CHttpFile 对象的 CInternetSession 对象发送到 CHttpFile 对象。调用 CInternetSession::OpenURL 或 CHttpConnection 来构造 CHttpFile 对象时，可以重写默认值，将上下文标识符设置为所选的值。上下文标识符将返回到 CInternetSession::OnStatusCallback，以提供标识它的对象的状态。有关上下文标识符的详细信息，请参阅 Internet 首要步骤：WinInet 一文。

CHttpFile::GetFileURL

调用此成员函数以获取 HTTP 文件的名称作为 URL。

virtual CString GetFileURL() const;

返回值

一个 CString 对象，其中包含引用与此文件关联的资源的 URL。

注解

仅在成功调用 SendRequest 后或在 OpenURL 成功创建的 CHttpFile 对象上使用此成员函数。

CHttpFile::GetObject

调用此成员函数以获取与此 CHttpFile 关联的对象的名称。

CString GetObject() const;

返回值

包含对象名称的 CString 对象。

备注

仅在成功调用 SendRequest 后或在 OpenURL 成功创建的 CHttpFile 对象上使用此成员函数。

CHttpFile::GetVerb

调用此成员函数以获取与此 CHttpFile 关联的 HTTP 谓词（或方法）。

CString GetVerb() const;

返回值

包含 HTTP 谓词（或方法）名称的 CString 对象。

备注

仅在成功调用 SendRequest 后或在 OpenURL 成功创建的 CHttpFile 对象上使用此成员函数。

CHttpFile::QueryInfo

调用此成员函数以从 HTTP 请求返回响应或请求头。

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;

参数

dwInfoLevel
要查询的属性和指定所请求信息类型的以下标志的组合：

HTTP_QUERY_CUSTOM 查找标头名称，并在输出时以 lpvBuffer 返回此值。如果找不到标头，HTTP_QUERY_CUSTOM 将引发断言。
HTTP_QUERY_FLAG_REQUEST_HEADERS 通常，应用程序会查询响应标头，但应用程序也可以使用此标志查询请求头。
HTTP_QUERY_FLAG_SYSTEMTIME 对于值为日期/时间字符串（如“Last-Modified-Time”）的标头，此标志将标头值作为标准 Win32 SYSTEMTIME 结构返回，该结构不需要应用程序分析数据。如果使用此标志，可能需要使用函数的 SYSTEMTIME 重写。
HTTP_QUERY_FLAG_NUMBER 对于值为数字（如状态代码）的标头，此标志以 32 位数字的形式返回数据。

有关可能值的列表，请参阅“注解”部分。

lpvBuffer
指向接收信息的缓冲区的指针。

lpdwBufferLength
在条目中，这指向包含数据缓冲区长度的值（以字符数或字节为单位）。有关此参数的更多详细信息，请参阅“注解”部分。

lpdwIndex
指向从零开始的标头索引的指针。可以为 NULL。使用此标志枚举具有相同名称的多个标头。在输入时，lpdwIndex 指示要返回的指定标头的索引。在输出时，lpdwIndex 指示下一个标头的索引。如果找不到下一个索引，则返回 ERROR_HTTP_HEADER_NOT_FOUND。

str
对接收返回信息的 CString 对象的引用。

dwIndex
索引值。请参阅 lpdwIndex。

pSysTime
指向 Win32 SYSTEMTIME 结构的指针。

返回值

如果成功，则不为 0；否则为 0。如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

注解

仅在成功调用 SendRequest 后或在 OpenURL 成功创建的 CHttpFile 对象上使用此成员函数。

可以从 QueryInfo 检索以下类型的数据：

字符串（默认）
SYSTEMTIME（对于“Data:”、“Expires:”等，为标头）
DWORD（用于 STATUS_CODE、CONTENT_LENGTH 等）

当字符串写入缓冲区并且成员函数成功时，lpdwBufferLength 包含字符串长度减去 1 作为终止 NULL 字符。

可能的 dwInfoLevel 值包括：

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

调用此成员函数以获取与 HTTP 请求关联的状态代码，并将其置于提供的 dwStatusCode 参数中。

BOOL QueryInfoStatusCode(DWORD& dwStatusCode) const;

参数

dwStatusCode
对状态代码的引用。状态代码指示请求的事件是成功还是失败。有关选择状态代码的说明，请参阅“注解”。

返回值

如果成功，则不为 0；否则为 0。如果调用失败，可能会调用 Win32 函数 GetLastError 以确定错误原因。

注解

仅在成功调用 SendRequest 后或在 OpenURL 成功创建的 CHttpFile 对象上使用此成员函数。

HTTP 状态代码分为指示请求成功或失败的组。下表概述了状态代码组和最常见的 HTTP 状态代码。

组	含义
200-299	Success
300-399	Information
400-499	请求错误
500-599	服务器错误

常见的 HTTP 状态代码：

状态代码	含义
200	找到了 URL，接下来进行传输
400	无法理解的请求
404	找不到请求的 URL
405	服务器不支持请求的方法
500	未知的服务器错误
503	达到服务器容量

CHttpFile::SendRequest

调用此成员函数以向 HTTP 服务器发送请求。

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

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

参数

pstrHeaders
指向包含要发送的标头名称的字符串的指针。

dwHeadersLen
由 pstrHeaders 标识的标头长度。

lpOptional
在请求头之后要立即发送的任何可选数据。这通常用于 POST 和 PUT 操作。如果没有要发送的可选数据，则可以为 NULL。

dwOptionalLen
lpOptional 的长度。

strHeaders
包含所发送请求的标头名称的字符串。

返回值

如果成功，则不为 0；否则为 0。如果调用失败，请通过检查引发的 CInternetException 对象来确定失败的原因。

CHttpFile::SendRequestEx

调用此成员函数以向 HTTP 服务器发送请求。

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

参数

dwTotalLen
请求中要发送的字节数。

dwFlags
描述操作的标志。有关相应标志的列表，请参阅 Windows SDK 中的 HttpSendRequestEx。

dwContext
CHttpFile 操作的上下文标识符。有关此参数的详细信息，请参阅注解。

lpBuffIn
指向描述用于操作的输入缓冲区的初始化 INTERNET_BUFFERS 的指针。

lpBuffOut
指向描述用于操作的输出缓冲区的初始化 INTERNET_BUFFERS 的指针。

返回值

如果成功，则返回非零。如果调用失败，请通过检查引发的 CInternetException 对象来确定失败的原因。

备注

此函数允许应用程序使用 CInternetFile 的 Write 和 WriteString 方法发送数据。在调用此函数的任一重写之前，必须知道要发送的数据长度。第一个重写允许指定要发送的数据长度。第二个重写接受指向 INTERNET_BUFFERS 结构的指针，该指针可用于非常详细地描述缓冲区。

将内容写入文件后，调用 EndRequest 以结束操作。

示例

此代码片段将字符串的内容发送到 LOCALHOST 服务器上名为 MFCISAPI.DLL 的 DLL。虽然此示例仅使用一次对 WriteString 的调用，但使用多次调用以块形式发送数据是可以接受的。

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

另请参阅

CInternetFile 类
 层次结构图
 CInternetFile 类
 CGopherFile 类
 CHttpConnection 类

通过

CHttpFile 类

语法

成员

受保护构造函数

公共方法

备注

继承层次结构

要求

CHttpFile::AddRequestHeaders

参数

返回值

备注

CHttpFile::CHttpFile

参数

备注

CHttpFile::EndRequest

参数

返回值

备注

CHttpFile::GetFileURL

返回值

注解

CHttpFile::GetObject

返回值

备注

CHttpFile::GetVerb

返回值

备注

CHttpFile::QueryInfo

参数

返回值

注解

CHttpFile::QueryInfoStatusCode

参数

返回值

注解

CHttpFile::SendRequest

参数

返回值

CHttpFile::SendRequestEx

参数

返回值

备注

示例

另请参阅

反馈

其他资源