Función WinHttpAddRequestHeaders (winhttp.h)

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

Syntax

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 lpszHeaders. Si dwHeadersLength es -1L, la función asume que lpszHeaders está terminada en cero (ASCIIZ) y se calcula la longitud.

Si dwHeadersLength no es -1L, la función copia exactamente caracteres dwHeadersLength . WinHTTP no comprobará si lpszHeaders contiene una cadena terminada en cero.

[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.

Valor devuelto

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

Remarks

Los encabezados se transfieren entre redirecciones. 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 un redireccionamiento.

Incluso cuando WinHTTP se usa en modo asincrónico (es decir, cuando se ha establecido WINHTTP_FLAG_ASYNC en WinHttpOpen), esta función funciona sincrónicamente. 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 validan 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, esta función produce un error 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.

Examples

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

Requirements

Consulte también

Acerca de los servicios HTTP de Microsoft Windows (WinHTTP)

Versiones winHTTP

WinHttpOpenRequest

WinHttpSendRequest