Función WinHttpQueryHeaders (winhttp.h)

Artículo
08/27/2023

La función WinHttpQueryHeaders recupera información de encabezado asociada a una solicitud HTTP.

Consulta también WinHttpQueryHeadersEx, que ofrece una manera de recuperar cadenas de nombre y valor de encabezado analizados.

Sintaxis

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

Parámetros

[in] hRequest

Identificador de solicitud HINTERNET devuelto por WinHttpOpenRequest. Se debe haber llamado a WinHttpReceiveResponse para este identificador y se ha completado antes de llamar a WinHttpQueryHeaders .

[in] dwInfoLevel

Valor de tipo DWORD que especifica una combinación de marcas de atributo y modificador enumeradas en la página Marcas de información de consulta . Estas marcas de atributo y modificador indican que se solicita la información y cómo se va a dar formato.

[in, optional] pwszName

Puntero a una cadena que contiene el nombre del encabezado. Si la marca de dwInfoLevel no está WINHTTP_QUERY_CUSTOM, establezca este parámetro en WINHTTP_HEADER_NAME_BY_INDEX.

[out] lpBuffer

Puntero al búfer que recibe la información. Establecer este parámetro en WINHTTP_NO_OUTPUT_BUFFER hace que esta función devuelva FALSE. La llamada a GetLastError devuelve ERROR_INSUFFICIENT_BUFFER y lpdwBufferLength contiene el número de bytes necesarios para contener la información solicitada.

[in, out] lpdwBufferLength

Puntero a un valor de tipo DWORD que especifica la longitud del búfer de datos, en bytes. Cuando se devuelve la función, este parámetro contiene el puntero a un valor que especifica la longitud de la información escrita en el búfer. Cuando la función devuelve cadenas, se aplican las reglas siguientes.

Si la función se realiza correctamente, lpdwBufferLength especifica la longitud de la cadena, en bytes, menos 2 para el valor null de terminación.
Si se produce un error en la función y se devuelve ERROR_INSUFFICIENT_BUFFER , lpdwBufferLength especifica el número de bytes que la aplicación debe asignar para recibir la cadena.

[in, out] lpdwIndex

Puntero a un índice de encabezado de base cero que se usa para enumerar varios encabezados con el mismo nombre. Al llamar a la función , este parámetro es el índice del encabezado especificado que se va a devolver. Cuando se devuelve la función, este parámetro es el índice del encabezado siguiente. Si no se encuentra el siguiente índice, se devuelve ERROR_WINHTTP_HEADER_NOT_FOUND . Establezca este parámetro en WINHTTP_NO_HEADER_INDEX para especificar que solo se debe devolver la primera aparición de un encabezado.

Valor devuelto

Devuelve TRUE si es correcto o FALSE en caso contrario. Para obtener información de error extendida, llame a GetLastError. Entre los códigos de error devueltos se encuentran los siguientes.

Código de error	Descripción
ERROR_WINHTTP_HEADER_NOT_FOUND	No se pudo encontrar el encabezado solicitado.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	No se puede llevar a cabo la operación solicitada porque el controlador suministrado no está en el estado correcto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	El tipo de identificador proporcionado es incorrecto para esta operación.
ERROR_WINHTTP_INTERNAL_ERROR	Se ha producido un error interno.
ERROR_NOT_ENOUGH_MEMORY	No había suficiente memoria disponible para completar la operación solicitada. (Código de error de Windows)

Comentarios

Incluso cuando WinHTTP se usa en modo asincrónico (es decir, cuando se ha establecido WINHTTP_FLAG_ASYNC en WinHttpOpen), esta función funciona de forma sincrónica. El valor devuelto indica éxito o error. Para obtener información de error extendida, llame a GetLastError.

De forma predeterminada , WinHttpQueryHeaders devuelve una cadena. Sin embargo, puede solicitar datos en forma de una estructura SYSTEMTIME o DWORD mediante la inclusión de la marca modificadora adecuada en dwInfoLevel. En la tabla siguiente se muestran los posibles tipos de datos que WinHttpQueryHeaders puede devolver junto con la marca modificadora que se usa para seleccionar ese tipo de datos.

Tipo de datos	Marca modificadora
LPCWSTR	Predeterminada. No se requiere ninguna marca modificadora.
SYSTEMTIME	WINHTTP_QUERY_FLAG_SYSTEMTIME
DWORD	WINHTTP_QUERY_FLAG_NUMBER

Nota Para Windows XP y Windows 2000, consulta la sección Requisitos en tiempo de ejecución de la página de inicio de WinHttp.

Ejemplos

En el ejemplo siguiente se muestra cómo obtener un identificador HINTERNET , abrir una sesión HTTP, crear y enviar un encabezado de solicitud y examinar el encabezado de respuesta devuelto.

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP, Windows 2000 Professional con SP3 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003, Windows 2000 Server con SP3 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winhttp.h
Library	Winhttp.lib
Archivo DLL	Winhttp.dll
Redistribuible	WinHTTP 5.0 e Internet Explorer 5.01 o posterior en Windows XP y Windows 2000.