Функция 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 );

Требования

См. также раздел

Сведения о службах MICROSOFT Windows HTTP (WinHTTP)

Версии WinHTTP

WinHttpOpenRequest

WinHttpSendRequest