Функция WinHttpAddRequestHeaders (winhttp.h)
Функция WinHttpAddRequestHeaders добавляет один или несколько заголовков HTTP-запросов в дескриптор HTTP-запроса.
Синтаксис
WINHTTPAPI BOOL WinHttpAddRequestHeaders(
[in] HINTERNET hRequest,
[in] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in] DWORD dwModifiers
);
Параметры
[in] hRequest
Дескриптор HINTERNET, возвращаемый вызовом функции WinHttpOpenRequest.
[in] lpszHeaders
Указатель на строковую переменную, содержащую заголовки для добавления в запрос. Каждый заголовок, кроме последнего, должен заканчиваться возвратом каретки/перевода строки (CR/LF).
[in] dwHeadersLength
Длинное целое число без знака, содержащее длину pwszHeaders в символах. Если этот параметр имеет значение -1L, функция предполагает, что pwszHeaders завершается с нуля (ASCIIZ) и вычисляется длина.
[in] dwModifiers
Длинное целочисленное значение без знака, содержащее флаги, используемые для изменения семантики этой функции. Может быть одним или несколькими из следующих флагов.
Возвращаемое значение
Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Для получения дополнительных сведений об ошибке вызовите Метод GetLastError. Среди возвращаемых кодов ошибок:
| Код ошибки | Описание |
|---|---|
|
Не удается выполнить запрошенную операцию, так как предоставленный дескриптор находится в неправильном состоянии. |
|
Для этой операции указан неправильный тип дескриптора. |
|
Произошла внутренняя ошибка. |
|
Недостаточно памяти для выполнения запрошенной операции. |
Комментарии
Заголовки передаются между перенаправлениями. Это может быть проблемой безопасности. Чтобы избежать передачи заголовков при перенаправлении, используйте обратный вызов WINHTTP_STATUS_CALLBACK , чтобы исправить определенные заголовки при перенаправлении.
Даже если WinHTTP используется в асинхронном режиме (то есть, если WINHTTP_FLAG_ASYNC задано в WinHttpOpen), эта функция работает синхронно. Возвращаемое значение указывает на успех или сбой. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Функция WinHttpAddRequestHeaders добавляет дополнительные заголовки в свободном формате к дескриптору HTTP-запроса и предназначена для использования сложными клиентами, которым требуется подробный контроль над точным запросом, отправленным на HTTP-сервер.
Имя и значение заголовков запросов, добавленных с помощью этой функции, проверяются. Заголовки должны быть правильно сформированы. Дополнительные сведения о допустимых заголовках HTTP см. в статье RFC 2616. Если используется недопустимый заголовок, эта функция завершается сбоем и GetLastError возвращает ERROR_INVALID_PARAMETER. Недопустимый заголовок не добавлен.
Если вы отправляете заголовок запроса Date:, можно использовать функцию WinHttpTimeFromSystemTime для создания структуры для заголовка.
Для базовых winHttpAddRequestHeaders приложение может передавать несколько заголовков в одном буфере.
Приложение также может использовать WinHttpSendRequest для добавления дополнительных заголовков в дескриптор HTTP-запроса перед отправкой запроса.
Примеры
Следующий пример кода включает в запрос заголовок If-Modified-Since. Заголовок ответа интерпретируется, чтобы определить, был ли обновлен целевой документ.
DWORD dwSize = sizeof(DWORD);
DWORD dwStatusCode = 0;
BOOL bResults = FALSE;
HINTERNET hSession = NULL,
hConnect = NULL,
hRequest = NULL;
// Use WinHttpOpen to obtain a session handle.
hSession = WinHttpOpen( L"A WinHTTP Example Program/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_HTTP_PORT,
0 );
// Create an HTTP Request handle.
if( hConnect )
hRequest = WinHttpOpenRequest( hConnect,
L"GET",
NULL,
NULL,
WINHTTP_NO_REFERER,
WINHTTP_DEFAULT_ACCEPT_TYPES,
0 );
// Add a request header.
if( hRequest )
bResults = WinHttpAddRequestHeaders( hRequest,
L"If-Modified-Since: Mon, 20 Nov 2000 20:00:00 GMT",
(ULONG)-1L,
WINHTTP_ADDREQ_FLAG_ADD );
// Send a Request.
if( bResults )
bResults = WinHttpSendRequest( hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
0,
WINHTTP_NO_REQUEST_DATA,
0,
0,
0 );
// End the request.
if( bResults )
bResults = WinHttpReceiveResponse( hRequest, NULL);
// Use WinHttpQueryHeaders to obtain the header buffer.
if( bResults )
bResults = WinHttpQueryHeaders( hRequest,
WINHTTP_QUERY_STATUS_CODE | WINHTTP_QUERY_FLAG_NUMBER,
NULL,
&dwStatusCode,
&dwSize,
WINHTTP_NO_HEADER_INDEX );
// Based on the status code, determine whether
// the document was recently updated.
if( bResults )
{
if( dwStatusCode == 304 )
printf( "Document has not been updated.\n" );
else if( dwStatusCode == 200 )
printf( "Document has been updated.\n" );
else
printf( "Status code = %u.\n",dwStatusCode );
}
// Report any errors.
if( !bResults )
printf( "Error %d has occurred.\n", GetLastError( ) );
// Close 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. |