Функция WinHttpReadData (winhttp.h)
Функция WinHttpReadData считывает данные из дескриптора, открытого функцией WinHttpOpenRequest .
См. также статью WinHttpReadDataEx.
Синтаксис
WINHTTPAPI BOOL WinHttpReadData(
[in] HINTERNET hRequest,
[out] LPVOID lpBuffer,
[in] DWORD dwNumberOfBytesToRead,
[out] LPDWORD lpdwNumberOfBytesRead
);
Параметры
[in] hRequest
Допустимый дескриптор HINTERNET, возвращенный при предыдущем вызове WinHttpOpenRequest. WinHttpReceiveResponse или WinHttpQueryDataAvailable должны быть вызваны для этого дескриптора и должны быть завершены до вызова WinHttpReadData . Хотя вызов WinHttpReadData сразу после завершения winHttpReceiveResponse позволяет избежать расходов на копирование буфера, для этого приложение должно использовать буфер фиксированной длины для чтения.
[out] lpBuffer
Указатель на буфер, который получает считываемые данные. Убедитесь, что этот буфер остается действительным до завершения работы WinHttpReadData .
[in] dwNumberOfBytesToRead
Длинное целочисленное значение без знака, содержащее количество считываемых байтов.
[out] lpdwNumberOfBytesRead
Указатель на непознавленную длинную целочисленную переменную, получающую число прочитанных байтов. WinHttpReadData устанавливает это значение в нулевое значение перед выполнением какой-либо работы или проверки ошибок. При асинхронном использовании WinHTTP всегда присвойте этому параметру значение NULL и получите сведения в функции обратного вызова; Это может привести к сбою памяти.
Возвращаемое значение
Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError. В следующей таблице указаны коды ошибок, которые возвращаются.
| Код ошибки | Описание |
|---|---|
|
Подключение к серверу было сброшено или прервано, или обнаружен несовместимый протокол SSL. Например, WinHTTP 5.1 не поддерживает SSL2, если только клиент специально не включает его. |
|
Запрошенная операция не может быть выполнена, так как предоставленный дескриптор находится в неправильном состоянии. |
|
Для этой операции указан неправильный тип дескриптора. |
|
Произошла внутренняя ошибка. |
|
Операция была отменена, как правило, из-за того, что дескриптор, с которым работал запрос, был закрыт до завершения операции. |
|
Возвращается, когда входящий ответ превышает внутренний предел размера WinHTTP. |
|
Истекло время ожидания запроса. |
|
Недостаточно памяти для выполнения запрошенной операции. (Код ошибки Windows) |
Комментарии
Начиная с Windows Vista и Windows Server 2008, WinHttp позволяет приложениям выполнять кодирование фрагментов передачи данных, отправляемых на сервер. Когда заголовок Transfer-Encoding присутствует в ответе WinHttp, WinHttpReadData удаляет сведения о фрагментации, прежде чем предоставлять данные приложению.
Даже если WinHTTP используется в асинхронном режиме (то есть, когда WINHTTP_FLAG_ASYNC задано в WinHttpOpen), эта функция может работать как синхронно, так и асинхронно. Если эта функция возвращает значение FALSE, эта функция завершилась сбоем, и вы можете вызвать GetLastError , чтобы получить расширенные сведения об ошибке. Если эта функция возвращает значение TRUE, используйте WINHTTP_CALLBACK_STATUS_READ_COMPLETE завершения, чтобы определить, была ли эта функция успешной и значение параметров. Завершение WINHTTP_CALLBACK_STATUS_REQUEST_ERROR указывает, что операция завершилась асинхронно, но завершилась сбоем.
Если вы используете WinHttpReadData синхронно и возвращается значение TRUE , а число прочитанных байтов равно нулю, передача завершена и больше нет байтов для чтения на дескрипторе. Это аналогично достижению конца файла в локальном файле. Если функция используется асинхронно, обратный вызов WINHTTP_CALLBACK_STATUS_READ_COMPLETE вызывается с параметром dwStatusInformationLength , равным нулю при обнаружении конца ответа.
WinHttpReadData пытается заполнить буфер, на который указывает lpBuffer , пока не будет больше доступных данных из ответа. Если с сервера не поступило достаточно данных, буфер не заполняется.
Для дескрипторов HINTERNET, созданных функцией WinHttpOpenRequest и отправленных WinHttpSendRequest, перед использованием WinHttpReadData необходимо выполнить вызов WinHttpReceiveResponse.
Однобайтовые символы, полученные с помощью WinHttpReadData , не преобразуются в многобайтовые символы.
Если буфер чтения очень мал, WinHttpReadData может выполняться синхронно, и если WINHTTP_CALLBACK_STATUS_READ_COMPLETE завершения активирует другой вызов WinHttpReadData, может возникнуть переполнение стека. Рекомендуется использовать буфер чтения размером 8 Килобайт или больше.
Если с сервера не поступило достаточно данных, WinHttpReadData не полностью заполняет буфер, на который указывает lpBuffer. Буфер должен быть достаточно большим по крайней мере для хранения заголовков HTTP при первом чтении, а при чтении записей каталога в кодировке HTML он должен быть достаточно большим, чтобы вместить по крайней мере одну полную запись.
Если функция обратного вызова состояния была установлена с помощью WinHttpSetStatusCallback, то следующие уведомления, заданные в параметре dwNotificationFlagswinHttpSetStatusCallback , указывают на ход проверки доступных данных:
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED
- WINHTTP_CALLBACK_STATUS_READ_COMPLETE
Примеры
В следующем примере показано, как использовать семантику безопасных транзакций для скачивания ресурса с сервера HTTPS. В примере кода инициализируется программный интерфейс приложения (API) WinHTTP, выбирается целевой HTTPS-сервер, а затем открывается и отправляется запрос на этот безопасный ресурс.
WinHttpQueryDataAvailable используется с дескриптором запроса, чтобы определить объем данных, доступных для скачивания, а затем WinHttpReadData используется для чтения данных. Этот процесс повторяется до тех пор, пока не будет извлечен и отображен весь документ.
DWORD dwSize = 0;
DWORD dwDownloaded = 0;
LPSTR pszOutBuffer;
BOOL bResults = FALSE;
HINTERNET hSession = NULL,
hConnect = NULL,
hRequest = NULL;
// Use WinHttpOpen to obtain a session handle.
hSession = WinHttpOpen( L"WinHTTP Example/1.0",
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
WINHTTP_NO_PROXY_NAME,
WINHTTP_NO_PROXY_BYPASS, 0);
// Specify an HTTP server.
if (hSession)
hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
INTERNET_DEFAULT_HTTPS_PORT, 0);
// Create an HTTP request handle.
if (hConnect)
hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
NULL, WINHTTP_NO_REFERER,
WINHTTP_DEFAULT_ACCEPT_TYPES,
WINHTTP_FLAG_SECURE);
// Send a request.
if (hRequest)
bResults = WinHttpSendRequest( hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
0, WINHTTP_NO_REQUEST_DATA, 0,
0, 0);
// End the request.
if (bResults)
bResults = WinHttpReceiveResponse( hRequest, NULL);
// Keep checking for data until there is nothing left.
if (bResults)
{
do
{
// Check for available data.
dwSize = 0;
if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
{
printf( "Error %u in WinHttpQueryDataAvailable.\n",
GetLastError());
break;
}
// No more available data.
if (!dwSize)
break;
// Allocate space for the buffer.
pszOutBuffer = new char[dwSize+1];
if (!pszOutBuffer)
{
printf("Out of memory\n");
break;
}
// Read the Data.
ZeroMemory(pszOutBuffer, dwSize+1);
if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer,
dwSize, &dwDownloaded))
{
printf( "Error %u in WinHttpReadData.\n", GetLastError());
}
else
{
printf("%s", pszOutBuffer);
}
// Free the memory allocated to the buffer.
delete [] pszOutBuffer;
// This condition should never be reached since WinHttpQueryDataAvailable
// reported that there are bits to read.
if (!dwDownloaded)
break;
} while (dwSize > 0);
}
else
{
// Report any errors.
printf( "Error %d has occurred.\n", GetLastError() );
}
// Close any open handles.
if (hRequest) WinHttpCloseHandle(hRequest);
if (hConnect) WinHttpCloseHandle(hConnect);
if (hSession) WinHttpCloseHandle(hSession);
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP, Windows 2000 Профессиональная с пакетом обновления 3 (SP3) [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003, Windows 2000 Server с пакетом обновления 3 (SP3) [только классические приложения] |
| Целевая платформа | Windows |
| Header | winhttp.h |
| Библиотека | Winhttp.lib |
| DLL | Winhttp.dll |
| Распространяемые компоненты | WinHTTP 5.0 и Internet Обозреватель 5.01 или более поздней версии в Windows XP и Windows 2000. |