Compartir a través de


Función WinHttpOpenRequest (winhttp.h)

La función WinHttpOpenRequest crea un identificador de solicitud HTTP.

Sintaxis

WINHTTPAPI HINTERNET WinHttpOpenRequest(
  [in] HINTERNET hConnect,
  [in] LPCWSTR   pwszVerb,
  [in] LPCWSTR   pwszObjectName,
  [in] LPCWSTR   pwszVersion,
  [in] LPCWSTR   pwszReferrer,
  [in] LPCWSTR   *ppwszAcceptTypes,
  [in] DWORD     dwFlags
);

Parámetros

[in] hConnect

Identificador de conexión HINTERNET a una sesión HTTP devuelta por WinHttpConnect.

[in] pwszVerb

Puntero a una cadena que contiene el verbo HTTP que se va a usar en la solicitud. Si este parámetro es NULL, la función usa GET como verbo HTTP. Nota Esta cadena debe estar en mayúsculas. Muchos servidores tratan los verbos HTTP con distinción entre mayúsculas y minúsculas y las solicitudes del Grupo de tareas de ingeniería de Internet (IETF) solo escriben estos verbos con caracteres en mayúsculas.

[in] pwszObjectName

Puntero a una cadena que contiene el nombre del recurso de destino del verbo HTTP especificado. Por lo general, se trata de un nombre de archivo, un módulo ejecutable o un especificador de búsqueda.

[in] pwszVersion

Puntero a una cadena que contiene la versión HTTP. Si este parámetro es NULL, la función usa HTTP/1.1.

[in] pwszReferrer

Puntero a una cadena que especifica la dirección URL del documento desde la que se obtuvo la dirección URL de la solicitud pwszObjectName . Si este parámetro se establece en WINHTTP_NO_REFERER, no se especifica ningún documento de referencia.

[in] ppwszAcceptTypes

Puntero a una matriz terminada en null de punteros de cadena que especifica los tipos de medios aceptados por el cliente. Si este parámetro se establece en WINHTTP_DEFAULT_ACCEPT_TYPES, el cliente no acepta ningún tipo. Normalmente, los servidores controlan la falta de tipos aceptados como indicación de que el cliente acepta solo documentos de tipo "text/*"; es decir, solo documentos de texto: no hay imágenes ni otros archivos binarios. Para obtener una lista de tipos de medios válidos, vea Tipos de medios definidos por IANA en http://www.iana.org/assignments/media-types/.

[in] dwFlags

Valor entero largo sin signo que contiene los valores de marca de Internet. Este puede ser uno o varios de los valores siguientes:

Valor Significado
WINHTTP_FLAG_BYPASS_PROXY_CACHE
Esta marca proporciona el mismo comportamiento que WINHTTP_FLAG_REFRESH.
WINHTTP_FLAG_ESCAPE_DISABLE
Los caracteres no seguros de la dirección URL pasada para pwszObjectName no se convierten en secuencias de escape.
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY
Los caracteres no seguros del componente de consulta de la dirección URL pasada para pwszObjectName no se convierten en secuencias de escape.
WINHTTP_FLAG_ESCAPE_PERCENT
La cadena pasada para pwszObjectName se convierte de LPCWSTR a LPSTR. Todos los caracteres no seguros se convierten en una secuencia de escape, incluido el símbolo de porcentaje. De forma predeterminada, todos los caracteres no seguros excepto el símbolo de porcentaje se convierten en una secuencia de escape.
WINHTTP_FLAG_NULL_CODEPAGE
Se supone que la cadena pasada para pwszObjectName consta de caracteres ANSI válidos representados por WCHAR. No se realiza ninguna comprobación para los caracteres no seguros.

Windows 7: Esta opción está obsoleta.

WINHTTP_FLAG_REFRESH
Indica que la solicitud se debe reenviar al servidor de origen en lugar de enviar una versión almacenada en caché de un recurso desde un servidor proxy. Cuando se usa esta marca, se agrega un encabezado "Pragma: no-cache" al identificador de solicitud. Al crear un encabezado de solicitud HTTP/1.1, también se agrega un "Cache-Control: no-cache".
WINHTTP_FLAG_SECURE
Usa semántica de transacción segura. Esto se traduce en el uso de capa de sockets seguros (SSL)/Seguridad de la capa de transporte (TLS).

Valor devuelto

Devuelve un identificador de solicitud HTTP válido si se ejecuta correctamente o NULL si no es así. 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_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_WINHTTP_INVALID_URL
La dirección URL no es válida.
ERROR_WINHTTP_OPERATION_CANCELLED
La operación se canceló, normalmente porque el identificador en el que estaba funcionando la solicitud se cerró antes de que se completara la operación.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
La dirección URL especificó un esquema distinto de "http:" o "https:".
ERROR_NOT_ENOUGH_MEMORY
No había suficiente memoria disponible para completar la operación solicitada. (Código de error de Windows)

Comentarios

El valor devuelto indica éxito o error. Para obtener información de error extendida, llame a GetLastError.

La función WinHttpOpenRequest crea un nuevo identificador de solicitud HTTP y almacena los parámetros especificados en ese identificador. Un identificador de solicitud HTTP contiene una solicitud para enviar a un servidor HTTP y contiene todos los encabezados RFC822/MIME/HTTP que se enviarán como parte de la solicitud.

Si pwszVerb se establece en "HEAD", se omite el encabezado Content-Length.

Si se ha instalado una función de devolución de llamada de estado con WinHttpSetStatusCallback, una notificación de WINHTTP_CALLBACK_STATUS_HANDLE_CREATED indica que WinHttpOpenRequest ha creado un identificador de solicitud.

Una vez que la aplicación que realiza la llamada finaliza con el identificador HINTERNET devuelto por WinHttpOpenRequest, debe cerrarse con la función WinHttpCloseHandle .

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 este ejemplo se muestra cómo obtener un identificador HINTERNET , abrir una sesión HTTP, crear un encabezado de solicitud y enviar ese encabezado al servidor.


    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.wingtiptoys.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

    // Create an HTTP Request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"PUT", 
                                       L"/writetst.txt", 
                                       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);

    // PLACE ADDITIONAL CODE HERE.

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

Consulte también

Acerca de los servicios HTTP de Microsoft Windows (WinHTTP)

Versiones de WinHTTP

WinHttpConnect

WinHttpOpen