Función WinHttpAddRequestHeaders (winhttp.h)
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.
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 |
|---|---|
|
No se puede realizar la operación solicitada porque el identificador proporcionado no está en el estado correcto. |
|
El tipo de identificador proporcionado es incorrecto para esta operación. |
|
Se ha producido un error interno. |
|
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.
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. |