Функция WinHttpQueryHeaders (winhttp.h)

Статья
08/27/2023

Функция WinHttpQueryHeaders извлекает сведения о заголовке, связанные с HTTP-запросом.

Также см . раздел WinHttpQueryHeadersEx, который предлагает способ получения проанализированных строк имени заголовка и строк значений.

Синтаксис

WINHTTPAPI BOOL WinHttpQueryHeaders(
  [in]           HINTERNET hRequest,
  [in]           DWORD     dwInfoLevel,
  [in, optional] LPCWSTR   pwszName,
  [out]          LPVOID    lpBuffer,
  [in, out]      LPDWORD   lpdwBufferLength,
  [in, out]      LPDWORD   lpdwIndex
);

Параметры

[in] hRequest

Дескриптор запроса HINTERNET , возвращенный WinHttpOpenRequest. WinHttpReceiveResponse должен быть вызван для этого дескриптора и завершен до вызова WinHttpQueryHeaders .

[in] dwInfoLevel

Значение типа DWORD , указывающее сочетание флагов атрибутов и модификаторов, перечисленных на странице Флаги сведений о запросе . Эти флаги атрибутов и модификаторов указывают, что запрашиваются сведения и как они должны быть отформатированы.

[in, optional] pwszName

Указатель на строку, содержащую имя заголовка. Если флаг в dwInfoLevel не WINHTTP_QUERY_CUSTOM, задайте для этого параметра значение WINHTTP_HEADER_NAME_BY_INDEX.

[out] lpBuffer

Указатель на буфер, который получает сведения. Установка для этого параметра значения WINHTTP_NO_OUTPUT_BUFFER приводит к тому, что эта функция возвращает значение FALSE. Вызов Метода GetLastError возвращает ERROR_INSUFFICIENT_BUFFER , а lpdwBufferLength содержит количество байтов, необходимых для хранения запрошенной информации.

[in, out] lpdwBufferLength

Указатель на значение типа DWORD , указывающее длину буфера данных в байтах. При возврате функции этот параметр содержит указатель на значение, указывающее длину сведений, записанных в буфер. Когда функция возвращает строки, применяются следующие правила.

Если функция выполнена успешно, lpdwBufferLength указывает длину строки в байтах минус 2 для завершающего значения NULL.
Если функция завершается сбоем и возвращается ERROR_INSUFFICIENT_BUFFER , lpdwBufferLength указывает количество байтов, которое приложение должно выделить для получения строки.

[in, out] lpdwIndex

Указатель на отсчитываемый от нуля индекс заголовков, используемый для перечисления нескольких заголовков с одинаковым именем. При вызове функции этот параметр является индексом указанного возвращаемого заголовка. При возврате функции этот параметр является индексом следующего заголовка. Если следующий индекс не найден, возвращается ERROR_WINHTTP_HEADER_NOT_FOUND . Задайте для этого параметра значение WINHTTP_NO_HEADER_INDEX, чтобы указать, что должно возвращаться только первое вхождение заголовка.

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

Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Дополнительные сведения об ошибке можно получить, вызвав GetLastError. Среди возвращаемых кодов ошибок:

Код ошибки	Описание
ERROR_WINHTTP_HEADER_NOT_FOUND	Не удалось найти запрошенный заголовок.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Не удается выполнить запрошенную операцию, так как предоставленный дескриптор находится в неправильном состоянии.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Для этой операции указан неправильный тип дескриптора.
ERROR_WINHTTP_INTERNAL_ERROR	Произошла внутренняя ошибка.
ERROR_NOT_ENOUGH_MEMORY	Недостаточно памяти для выполнения запрошенной операции. (Код ошибки Windows)

Даже если WinHTTP используется в асинхронном режиме (то есть, если WINHTTP_FLAG_ASYNC задано в WinHttpOpen), эта функция работает синхронно. Возвращаемое значение указывает на успех или сбой. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

По умолчанию WinHttpQueryHeaders возвращает строку. Однако можно запросить данные в виде структуры SYSTEMTIME или DWORD , включив соответствующий флаг модификатора в dwInfoLevel. В следующей таблице показаны возможные типы данных, которые может возвращать WinHttpQueryHeaders , а также флаг модификатора, используемый для выбора этого типа данных.

Тип данных	Флаг модификатора
LPCWSTR	По умолчанию. Флаг модификатора не требуется.
SYSTEMTIME	WINHTTP_QUERY_FLAG_SYSTEMTIME
DWORD	WINHTTP_QUERY_FLAG_NUMBER

Примечание Для Windows XP и Windows 2000 см. раздел Требования к времени выполнения начальной страницы WinHttp.

Примеры

В следующем примере показано, как получить дескриптор HINTERNET , открыть сеанс HTTP, создать и отправить заголовок запроса, а также проверить возвращенный заголовок ответа.

    DWORD dwSize = 0;
    LPVOID lpOutBuffer = NULL;
    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);

    // 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);

    // First, use WinHttpQueryHeaders to obtain the size of the buffer.
    if (bResults)
    {
        WinHttpQueryHeaders( hRequest, WINHTTP_QUERY_RAW_HEADERS_CRLF,
                             WINHTTP_HEADER_NAME_BY_INDEX, NULL,
                             &dwSize, WINHTTP_NO_HEADER_INDEX);

        // Allocate memory for the buffer.
        if( GetLastError( ) == ERROR_INSUFFICIENT_BUFFER )
        {
            lpOutBuffer = new WCHAR[dwSize/sizeof(WCHAR)];

            // Now, use WinHttpQueryHeaders to retrieve the header.
            bResults = WinHttpQueryHeaders( hRequest,
                                       WINHTTP_QUERY_RAW_HEADERS_CRLF,
                                       WINHTTP_HEADER_NAME_BY_INDEX,
                                       lpOutBuffer, &dwSize,
                                       WINHTTP_NO_HEADER_INDEX);
        }
    }

    // Print the header contents.
    if (bResults)
        printf("Header contents: \n%S",lpOutBuffer);

    // Free the allocated memory.
    delete [] lpOutBuffer;

    // Report any errors.
    if (!bResults)
        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.