Función WinHttpAddRequestHeaders (winhttp.h)

Artículo
08/27/2023

La función WinHttpAddRequestHeaders agrega uno o varios encabezados de solicitud HTTP al identificador de solicitud HTTP.

Sintaxis

WINHTTPAPI BOOL WinHttpAddRequestHeaders(
  [in] HINTERNET hRequest,
  [in] LPCWSTR   lpszHeaders,
  [in] DWORD     dwHeadersLength,
  [in] DWORD     dwModifiers
);

Parámetros

[in] hRequest

Un identificador HINTERNET devuelto por una llamada a la función WinHttpOpenRequest .

[in] lpszHeaders

Puntero a una variable de cadena que contiene los encabezados que se van a anexar a la solicitud. Cada encabezado excepto el último debe terminar por un retorno de carro/avance de línea (CR/LF).

[in] dwHeadersLength

Valor entero largo sin signo que contiene la longitud, en caracteres, de pwszHeaders. Si este parámetro es -1L, la función asume que pwszHeaders está terminada en cero (ASCIIZ) y se calcula la longitud.

[in] dwModifiers

Valor entero largo sin signo que contiene las marcas usadas para modificar la semántica de esta función. Puede ser una o varias de las marcas siguientes.

Value	Significado
WINHTTP_ADDREQ_FLAG_ADD	Agrega el encabezado si no existe. Se usa con WINHTTP_ADDREQ_FLAG_REPLACE.
WINHTTP_ADDREQ_FLAG_ADD_IF_NEW	Agrega el encabezado solo si aún no existe; de lo contrario, se devuelve un error.
WINHTTP_ADDREQ_FLAG_COALESCE	Combina encabezados con el mismo nombre.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA	Combina encabezados del mismo nombre con una coma. Por ejemplo, agregar "Accept: text/" seguido de "Accept: audio/" con esta marca da como resultado un solo encabezado "Accept: text/, audio/". Esto hace que se combine el primer encabezado encontrado. La aplicación que llama debe garantizar un esquema cohesivo con respecto a encabezados combinados y independientes.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON	Combina encabezados del mismo nombre con un punto y coma.
WINHTTP_ADDREQ_FLAG_REPLACE	Reemplaza o quita un encabezado. Si el valor del encabezado está vacío y se encuentra el encabezado, se quita. Si el valor no está vacío, se reemplaza.

Valor devuelto

Devuelve TRUE si se ejecuta correctamente o FALSE de lo contrario. Para obtener información de error extendida, llame a GetLastError. Entre los códigos de error devueltos se incluyen los siguientes.

Código de error	Descripción
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	No se puede realizar la operación solicitada porque el identificador proporcionado 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.

Comentarios

Los encabezados se transfieren entre redireccionamientos. Esto puede ser un problema de seguridad. Para evitar que se transfieran encabezados cuando se produzca una redirección, use el WINHTTP_STATUS_CALLBACK devolución de llamada para corregir los encabezados específicos cuando se produce una redirección.

Incluso cuando WinHTTP se usa en modo asincrónico (es decir, cuando WINHTTP_FLAG_ASYNC se ha establecido 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.

La función WinHttpAddRequestHeaders anexa encabezados de formato libre adicionales al identificador de solicitud HTTP y está pensado para su uso por parte de clientes sofisticados que requieren control detallado sobre la solicitud exacta enviada al servidor HTTP.

Se valida el nombre y el valor de los encabezados de solicitud agregados con esta función. Los encabezados deben estar bien formados. Para obtener más información sobre los encabezados HTTP válidos, consulte RFC 2616. Si se usa un encabezado no válido, se produce un error en esta función y GetLastError devuelve ERROR_INVALID_PARAMETER. No se agrega el encabezado no válido.

Si va a enviar un encabezado de solicitud Date: , puede usar la función WinHttpTimeFromSystemTime para crear una estructura para el encabezado.

Para WinHttpAddRequestHeaders básico, la aplicación puede pasar varios encabezados en un solo búfer.

Una aplicación también puede usar WinHttpSendRequest para agregar encabezados adicionales al identificador de solicitud HTTP antes de enviar una solicitud.

Nota Para obtener más información, consulte Requisitos en tiempo de ejecución.

Ejemplos

En el ejemplo de código siguiente se incluye un encabezado If-Modified-Since en una solicitud. El encabezado de respuesta se interpreta para determinar si se ha actualizado el documento de destino.


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

Requisitos


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.