Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Функция WinHttpAddRequestHeaders добавляет один или несколько заголовков HTTP-запросов в дескриптор HTTP-запроса.
Синтаксис
WINHTTPAPI BOOL WinHttpAddRequestHeaders(
[in] HINTERNET hRequest,
[in] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in] DWORD dwModifiers
);
Parameters
[in] hRequest
Дескриптор HINTERNET , возвращаемый вызовом функции WinHttpOpenRequest .
[in] lpszHeaders
Указатель на строковую переменную, содержащую заголовки, добавляемые к запросу. Каждый заголовок, кроме последнего, должен быть завершен каналом возврата или строки каретки (CR/LF).
[in] dwHeadersLength
Целое число без знака, содержащее длину в символах lpszHeaders. Если dwHeadersLength имеет значение -1L, то функция предполагает, что lpszHeaders не завершается (ASCIIZ), а длина вычисляется.
Если dwHeadersLength не является -1L, функция копирует именно символы dwHeadersLength . WinHTTP не проверяет, содержит ли lpszHeaders строку с нуля.
[in] dwModifiers
Целое число без знака, содержащее флаги, используемые для изменения семантики этой функции. Может быть одним или несколькими из следующих флагов.
Возвращаемое значение
Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Для получения расширенных сведений об ошибке вызовите GetLastError. Среди возвращенных кодов ошибок приведены следующие коды.
| Код ошибки | Описание |
|---|---|
|
Запрошенная операция не может быть выполнена, так как предоставленный дескриптор не находится в правильном состоянии. |
|
Тип дескриптора некорректен для этой операции. |
|
Произошла внутренняя ошибка. |
|
Недостаточно памяти было доступно для выполнения запрошенной операции. |
Remarks
Заголовки передаются через перенаправления. Это может быть проблема безопасности. Чтобы избежать передачи заголовков при перенаправлении, используйте обратный вызов WINHTTP_STATUS_CALLBACK , чтобы исправить определенные заголовки при возникновении перенаправления.
Даже если WinHTTP используется в асинхронном режиме (то есть если WINHTTP_FLAG_ASYNC задан в WinHttpOpen), эта функция работает синхронно. Возвращаемое значение указывает на успешность или сбой. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
Функция WinHttpAddRequestHeaders добавляет дополнительные заголовки свободного формата к дескриптору HTTP-запроса и предназначена для использования сложными клиентами, требующими подробного контроля над точным запросом, отправленным на HTTP-сервер.
Проверяется имя и значение заголовков запросов, добавленных с помощью этой функции. Заголовки должны быть хорошо сформированы. Дополнительные сведения о допустимых заголовках HTTP см. в rfC 2616. Если используется недопустимый заголовок, эта функция завершается ошибкой, и GetLastError возвращает ERROR_INVALID_PARAMETER. Недопустимый заголовок не добавлен.
При отправке заголовка запроса Date можно использовать функцию WinHttpTimeFromSystemTime для создания структуры для заголовка.
Для базовых WinHttpAddRequestHeaders приложение может передавать несколько заголовков в одном буфере.
Приложение также может использовать WinHttpSendRequest для добавления дополнительных заголовков в дескриптор HTTP-запроса перед отправкой запроса.
Примечание Дополнительные сведения см. в разделе Run-Time Требования.
Примеры
В следующем примере кода содержится заголовок 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 );
Requirements
| Требование | Ценность |
|---|---|
| Минимальный поддерживаемый клиент | Windows XP, Windows 2000 Профессиональный с пакетом обновления 3 (SP3) [только классические приложения] |
| минимальный поддерживаемый сервер | Windows Server 2003, Windows 2000 Server с пакетом обновления 3 (SP3) [классические приложения только] |
| целевая платформа | Windows |
| Header | winhttp.h |
| Library | Winhttp.lib |
| DLL | Winhttp.dll |
| Распространяемый | WinHTTP 5.0 и Internet Explorer 5.01 или более поздней версии в Windows XP и Windows 2000. |