Función WinHttpOpen (winhttp.h)

  • Artículo

La función WinHttpOpen inicializa, para una aplicación, el uso de funciones WinHTTP y devuelve un identificador de sesión winHTTP.

Sintaxis

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

Parámetros

[in, optional] pszAgentW

Puntero a una variable de cadena que contiene el nombre de la aplicación o entidad que llama a las funciones WinHTTP. Este nombre se usa como agente de usuario en el protocolo HTTP.

[in] dwAccessType

Tipo de acceso necesario. Puede ser uno de los siguientes valores.

Valor Significado
WINHTTP_ACCESS_TYPE_NO_PROXY
 Resuelve todos los nombres de host directamente sin un proxy.
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
Importante El uso de esta opción está en desuso en Windows 8.1 y versiones más recientes. Use WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY en su lugar.
 
Recupera el proxy estático o la configuración directa del Registro. WINHTTP_ACCESS_TYPE_DEFAULT_PROXY no hereda la configuración del proxy del explorador.

La configuración del proxy WinHTTP se establece mediante uno de estos mecanismos.
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 Pasa solicitudes al proxy a menos que se proporcione una lista de omisión de proxy y el nombre que se va a resolver omite el proxy. En este caso, esta función usa los valores pasados para pwszProxyName y pwszProxyBypass.
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 Usa la configuración del proxy por usuario y del sistema (incluida la configuración de proxy de Internet Explorer) para determinar qué proxy o proxy usar. Intenta controlar automáticamente la conmutación por error entre varios servidores proxy, configuraciones de proxy diferentes por interfaz y autenticación. Se admite en Windows 8.1 y versiones más recientes.

[in] pszProxyW

Puntero a una variable de cadena que contiene el nombre del servidor proxy que se va a usar cuando se especifica el acceso de proxy estableciendo dwAccessTypeen WINHTTP_ACCESS_TYPE_NAMED_PROXY. Las funciones WinHTTP solo reconocen servidores proxy de tipo CERN para HTTP. Si dwAccessType no está establecido en WINHTTP_ACCESS_TYPE_NAMED_PROXY, este parámetro debe establecerse en WINHTTP_NO_PROXY_NAME.

[in] pszProxyBypassW

Puntero a una variable de cadena que contiene una lista opcional delimitada por punto y coma de nombres de host o direcciones IP, o ambas, que no se deben enrutar a través del proxy cuando dwAccessType está establecido en WINHTTP_ACCESS_TYPE_NAMED_PROXY. La lista puede contener caracteres comodín. No use una cadena vacía, ya que la función WinHttpOpen la usa como lista de omisión de proxy. Si este parámetro especifica la macro "<local>" de la lista como la única entrada, esta función omite cualquier nombre de host que no contenga un punto. Si dwAccessType no está establecido en WINHTTP_ACCESS_TYPE_NAMED_PROXY, este parámetro debe establecerse en WINHTTP_NO_PROXY_BYPASS.

[in] dwFlags

Valor entero largo sin signo que contiene las marcas que indican varias opciones que afectan al comportamiento de esta función. Este parámetro puede tener el siguiente valor.

Valor Significado
WINHTTP_FLAG_ASYNC
 Use las funciones WinHTTP de forma asincrónica. De forma predeterminada, todas las funciones WinHTTP que usan el identificador HINTERNET devuelto se realizan de forma sincrónica. Cuando se establece esta marca, el autor de la llamada debe especificar una función de devolución de llamada a través de WinHttpSetStatusCallback.
WINHTTP_FLAG_SECURE_DEFAULTS
 Cuando se establece esta marca, WinHttp requerirá el uso de TLS 1.2 o posterior. Si el autor de la llamada intenta habilitar las versiones anteriores de TLS estableciendo WINHTTP_OPTION_SECURE_PROTOCOLS, se producirá un error con ERROR_ACCESS_DENIED. Además, se deshabilitará la reserva TLS. Tenga en cuenta que al establecer esta marca también se establece la marca WINHTTP_FLAG_ASYNC.

Valor devuelto

Devuelve un identificador de sesión válido si es correcto o NULL de lo contrario. Para recuperar 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_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

Se recomienda encarecidamente usar WinHTTP en modo asincrónico (es decir, cuando se ha establecido WINHTTP_FLAG_ASYNC en WinHttpOpen, de modo que el uso de HINTERNET devuelto se convierta en asincrónico). El valor devuelto indica éxito o error. Para recuperar información de error extendida, llame a GetLastError.

La función WinHttpOpen es la primera de las funciones WinHTTP llamadas por una aplicación. Inicializa estructuras de datos winHTTP internas y se prepara para futuras llamadas desde la aplicación. Cuando la aplicación termine de usar las funciones WinHTTP, debe llamar a WinHttpCloseHandle para liberar el identificador de sesión y los recursos asociados.

La aplicación puede realizar cualquier número de llamadas a WinHttpOpen, aunque una sola llamada es normalmente suficiente. Cada llamada a WinHttpOpen abre un nuevo contexto de sesión. Dado que los datos de usuario no se comparten entre varios contextos de sesión, una aplicación que realiza solicitudes en nombre de varios usuarios debe crear una sesión independiente para cada usuario, por lo que no compartir cookies específicas del usuario y el estado de autenticación. La aplicación debe definir comportamientos independientes para cada instancia de WinHttpOpen , como diferentes servidores proxy configurados para cada uno.

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

Nota Para Windows XP y Windows 2000, consulta Requisitos en tiempo de ejecución.
 

Ejemplos

En el código de ejemplo siguiente se muestra cómo recuperar el valor de tiempo de espera de conexión predeterminado.


    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {


        // Use WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", 
                    GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

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.

Consulte también

Acerca de los servicios HTTP de Microsoft Windows (WinHTTP)

Versiones winHTTP

WinHttpCloseHandle