Función WinHttpOpen (winhttp.h)
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 |
|---|---|
|
Resuelve todos los nombres de host directamente sin un 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.
La configuración del proxy WinHTTP se establece mediante uno de estos mecanismos.
|
|
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. |
|
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 |
|---|---|
|
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. |
|
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 |
|---|---|
|
Se ha producido un error interno. |
|
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 .
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. |