Поделиться через

Класс CHttpFile

  • Статья

Предоставляет функции для запроса и чтения файлов на HTTP-сервере.

Синтаксис

class CHttpFile : public CInternetFile

Участники

Защищенные конструкторы

Имя Описание
CHttpFile::CHttpFile Создает объект CHttpFile.

Открытые методы

Имя Описание
CHttpFile::AddRequestHeaders Добавляет заголовки в запрос, отправленный на HTTP-сервер.
CHttpFile::EndRequest Завершает запрос, отправленный на HTTP-сервер с помощью функции-члена SendRequestEx .
CHttpFile::GetFileURL Возвращает URL-адрес указанного файла.
CHttpFile::GetObject Возвращает целевой объект команды в запросе на HTTP-сервер.
CHttpFile::GetVerb Возвращает команду, которая использовалась в запросе на HTTP-сервер.
CHttpFile::QueryInfo Возвращает заголовки ответа или запроса с HTTP-сервера.
CHttpFile::QueryInfoStatusCode Извлекает код состояния, связанный с HTTP-запросом, и помещает его в указанный dwStatusCode параметр.
CHttpFile::SendRequest Отправляет запрос на HTTP-сервер.
CHttpFile::SendRequestEx Отправляет запрос на HTTP-сервер с помощью методов Write или WriteString.CInternetFile

Замечания

Если сеанс Интернета считывает данные с HTTP-сервера, необходимо создать экземпляр CHttpFile.

Дополнительные сведения о CHttpFile работе с другими классами Интернета MFC см. в статье "Интернет-программирование с помощью WinInet".

Иерархия наследования

CObject

CFile

CStdioFile

CInternetFile

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/*, audio/*". Это относится к вызывающему приложению, чтобы обеспечить единую схему в отношении данных, полученных запросами, отправленными с объединенными или отдельными заголовками.

  • HTTP_ADDREQ_FLAG_REPLACE Выполняет удаление и добавление для замены текущего заголовка. Имя заголовка будет использоваться для удаления текущего заголовка, а полное значение будет использоваться для добавления нового заголовка. Если значение заголовка пусто, а заголовок найден, он удаляется. Если значение заголовка не пустое, заголовок заменяется.

  • HTTP_ADDREQ_FLAG_ADD_IF_NEW добавляет только заголовок, если он еще не существует. Если он существует, возвращается ошибка.

  • HTTP_ADDREQ_FLAG_ADD Используется с REPLACE. Добавляет заголовок, если он не существует.

dwHeadersLen
Длина в символах pstrHeaders. Если это значение равно -1L, то предполагается, что pstrHeaders будет нулевым и длина вычисляется.

str
Ссылка на объект CString , содержащий заголовок запроса или заголовки, которые необходимо добавить.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0. Если вызов завершается ошибкой, можно вызвать функцию GetLastError Win32, чтобы определить причину ошибки.

Замечания

AddRequestHeaders добавляет дополнительные заголовки свободного формата в дескриптор HTTP-запроса. Он предназначен для использования сложными клиентами, которым требуется подробный контроль над точным запросом, отправленным на HTTP-сервер.

Примечание.

Приложение может передавать несколько заголовков в pstrHeaders или str для AddRequestHeaders вызова с помощью HTTP_ADDREQ_FLAG_ADD или HTTP_ADDREQ_FLAG_ADD_IF_NEW. Если приложение пытается удалить или заменить заголовок с помощью 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
Дескриптор к интернет-файлу.

hSession
Дескриптор сеанса Интернета.

pstrObject
Указатель на строку, CHttpFile содержащую объект.

pstrServer
Указатель на строку, содержащую имя сервера.

pstrVerb
Указатель на строку, содержащую метод, используемый при отправке запроса. Может быть POST, HEAD или GET.

dwContext
Идентификатор контекста CHttpFile для объекта. Дополнительные сведения об этом параметре см . в примечаниях .

pConnection
Указатель на объект CHttpConnection .

Замечания

Объект никогда не создается напрямую CHttpFile ; вместо этого следует вызывать CInternetSession::OpenURL или CHttpConnection::OpenRequest .

Значение dwContext по умолчанию отправляется MFC CHttpFile объекту из объекта CInternetSession , создавшего CHttpFile объект. При вызове CInternetSession::OpenURL или CHttpConnection создании CHttpFile объекта можно переопределить значение по умолчанию, чтобы задать идентификатор контекста для выбранного значения. Идентификатор контекста возвращается в CInternetSession::OnStatusCallback , чтобы предоставить состояние объекта, с которым он определен. Дополнительные сведения об идентификаторе контекста см. в статье Internet First Steps: WinInet .

CHttpFile::EndRequest

Вызовите эту функцию-член, чтобы завершить запрос, отправленный на HTTP-сервер с функцией члена SendRequestEx .

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

Параметры

dwFlags
Флаги, описывающие операцию. Список соответствующих флагов см. в разделе HttpEndRequest в пакете SDK для Windows.

lpBuffIn
Указатель на инициализированную INTERNET_BUFFERS , описывающую входной буфер, используемый для операции.

dwContext
Идентификатор контекста CHttpFile для операции. Дополнительные сведения об этом параметре см. в примечаниях.

Возвращаемое значение

Имеет ненулевое значение в случае успешного выполнения, иначе — 0. Если вызов завершается ошибкой, определите причину сбоя, проверив создаваемый объект CInternetException .

Замечания

Значение по умолчанию для dwContext отправляется MFC CHttpFile объекту из объекта CInternetSession , создавшего CHttpFile объект. При вызове CInternetSession::OpenURL или CHttpConnection для создания CHttpFile объекта можно переопределить значение по умолчанию, чтобы задать идентификатор контекста для выбранного значения. Идентификатор контекста возвращается в CInternetSession::OnStatusCallback , чтобы предоставить состояние объекта, с которым он определен. Дополнительные сведения об идентификаторе контекста см. в статье Internet First Steps: WinInet .

CHttpFile::GetFileURL

Вызовите эту функцию-член, чтобы получить имя HTTP-файла в качестве URL-адреса.

virtual CString GetFileURL() const;

Возвращаемое значение

Объект CString, содержащий URL-адрес, ссылающийся на ресурс, связанный с этим файлом.

Замечания

Используйте эту функцию-член только после успешного вызова SendRequest или объекта, успешно созданного CHttpFile OpenURL.

CHttpFile::GetObject

Вызовите эту функцию-член, чтобы получить имя объекта, связанного с этим CHttpFile.

CString GetObject() const;

Возвращаемое значение

Объект CString , содержащий имя объекта.

Замечания

Используйте эту функцию-член только после успешного вызова SendRequest или объекта, успешно созданного CHttpFile OpenURL.

CHttpFile::GetVerb

Вызовите эту функцию-член, чтобы получить http-команду (или метод), связанную с этим CHttpFile.

CString GetVerb() const;

Возвращаемое значение

Объект CString, содержащий имя HTTP-команды (или метода).

Замечания

Используйте эту функцию-член только после успешного вызова SendRequest или объекта, успешно созданного CHttpFile OpenURL.

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. Если вызов завершается ошибкой, можно вызвать функцию GetLastError Win32, чтобы определить причину ошибки.

Замечания

Используйте эту функцию-член только после успешного вызова SendRequest или объекта, успешно созданного CHttpFile OpenURL.

Вы можете получить следующие типы данных из QueryInfo:

  • строки (по умолчанию)

  • SYSTEMTIME (для параметра Data:" "Срок действия:" и т. д., заголовки)

  • 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. Если вызов завершается ошибкой, можно вызвать функцию GetLastError Win32, чтобы определить причину ошибки.

Замечания

Используйте эту функцию-член только после успешного вызова SendRequest или объекта, успешно созданного CHttpFile OpenURL.

Коды состояния HTTP попадают в группы, указывающие на успешность или сбой запроса. В следующих таблицах описаны группы кода состояния и наиболее распространенные коды состояния HTTP.

Групповой Значение
200–299 Удачное завершение
300–399 Информация
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. Если вызов завершается ошибкой, определите причину сбоя, проверив создаваемый объект 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
Флаги, описывающие операцию. Список соответствующих флагов см. в разделе HttpSendRequestEx в пакете SDK для Windows.

dwContext
Идентификатор контекста CHttpFile для операции. Дополнительные сведения об этом параметре см. в примечаниях.

lpBuffIn
Указатель на инициализированную INTERNET_BUFFERS , описывающую входной буфер, используемый для операции.

lpBuffOut
Указатель на инициализированную INTERNET_BUFFERS, описывающую выходной буфер, используемый для операции.

Возвращаемое значение

Ненулевое значение в случае успешного выполнения. Если вызов завершается ошибкой, определите причину сбоя, проверив создаваемый объект CInternetException .

Замечания

Эта функция позволяет приложению отправлять данные с помощью методов Write и WriteString.CInternetFile Перед вызовом переопределения этой функции необходимо знать длину передаваемых данных. Первый переопределение позволяет указать длину данных, которые вы хотите отправить. Второй переопределение принимает указатели на INTERNET_BUFFERS структуры, которые можно использовать для подробного описания буфера.

После записи содержимого в файл вызовите EndRequest , чтобы завершить операцию.

Значение по умолчанию для dwContext отправляется MFC CHttpFile объекту из объекта CInternetSession , создавшего CHttpFile объект. При вызове CInternetSession::OpenURL или CHttpConnection для создания CHttpFile объекта можно переопределить значение по умолчанию, чтобы задать идентификатор контекста для выбранного значения. Идентификатор контекста возвращается в CInternetSession::OnStatusCallback , чтобы предоставить состояние объекта, с которым он определен. Дополнительные сведения об идентификаторе контекста см. в статье Internet First Steps: WinInet .

Пример

Этот фрагмент кода отправляет содержимое строки в библиотеку DLL с именем MFCISAPI.DLL на сервере LOCALHOST. Хотя в этом примере используется только один вызов 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