Habilitación de la funcionalidad de Internet
Antes de usar las funciones WinINet, la aplicación debe intentar realizar una conexión a Internet mediante la función InternetAttemptConnect . Esta función llama al cuadro de diálogo de acceso telefónico para iniciar una conexión a Internet o comprobar si ya existe una conexión. Si se produce un error en esta función, la aplicación puede entrar en modo sin conexión, lo que le permite acceder a la información almacenada en caché durante las conexiones anteriores a Internet.
Use la función InternetCheckConnection para comprobar la conexión a Internet. Intenta hacer ping al servidor designado por la dirección URL que se pasa a la función. Si se establece la marca FLAG_ICC_FORCE_CONNECTION y la dirección URL es NULL, la función comprueba si hay una entrada en la base de datos del servidor para el servidor más cercano. Si existe, la función hace ping a ese servidor.
A continuación, use la función InternetOpen para establecer las características de la conexión a Internet que usa la aplicación cliente. InternetOpen crea el identificador HINTERNET raíz que se usa para establecer sesiones http ftp. InternetOpen no prueba la conexión a Internet para comprobar que las características pasadas a la función son correctas.
Use la función InternetConnect para crear una sesión específica. InternetConnect inicializa una sesión para el sitio especificado con los argumentos que se le pasan y crea un identificador HINTERNET que es una rama del identificador raíz. InternetConnect no intenta acceder a ni establecer una conexión con el sitio especificado, excepto en el caso de una sesión FTP. Las funciones FtpFindFirstFile, FtpOpenFile y HttpOpenRequest usan el identificador creado por InternetConnect para establecer una conexión con el sitio especificado.
Uso de InternetOpen
Para habilitar una conexión a Internet, se debe crear un identificador HINTERNET raíz mediante InternetOpen. Información sobre el agente de usuario (la aplicación que llama a las funciones de Internet), el tipo de acceso a Internet, los nombres de proxy, los hosts y las direcciones que omiten el proxy y el comportamiento se pasan a InternetOpen.
Establecimiento del Agente de usuario
La aplicación que llama debe proporcionar una cadena que contenga el nombre de la aplicación o entidad que accede a Internet al parámetro lpszAgent de InternetOpen. Esta cadena se usa como agente de usuario en el protocolo HTTP. Por ejemplo, Microsoft Internet Explorer usa "Microsoft Internet Explorer".
Establecer tipos de acceso
InternetOpen admite tres tipos de acceso:
- Use INTERNET_OPEN_TYPE_DIRECT si el sistema en el que se ejecuta la aplicación usa una conexión directa a Internet. Los parámetros lpszProxyName y lpszProxyBypass de InternetOpen no se usan y deben establecerse en NULL.
- Use INTERNET_OPEN_TYPE_PROXY si el sistema en el que se ejecuta la aplicación usa uno o varios servidores proxy para acceder a Internet. InternetOpen usa los servidores proxy indicados por lpszProxyName y omite el proxy para cualquier nombre de host o direcciones IP especificadas por lpszProxyBypass.
- Use INTERNET_OPEN_TYPE_PRECONFIG para indicar a la aplicación que recupere la configuración del registro. Normalmente, esta es la mejor opción, ya que la mayoría de las aplicaciones, incluidos los exploradores web, usan esta opción.
INTERNET_OPEN_TYPE_PRECONFIG examina los valores del Registro ProxyEnable, ProxyServer y ProxyOverride. Estos valores se encuentran en "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings".
Si ProxyEnable es cero, la aplicación usa INTERNET_OPEN_TYPE_DIRECT. De lo contrario, la aplicación usa INTERNET_OPEN_TYPE_PROXY y usa la información proxyServer y ProxyOverride .
Las funciones WinINet proporcionan compatibilidad con servidores proxy de tipo SOCKS solo si Está instalado Internet Explorer. La instalación de Internet Explorer incluye el archivo Wsock32n.dll, que es necesario para admitir servidores proxy SOCKS. Wsock32n.dll no se puede redistribuir.
Enumeración de servidores proxy
WinINet reconoce dos tipos de servidores proxy: servidores proxy de tipo CERN (solo HTTP) y servidores proxy FTP de TIS (solo FTP). Si Internet Explorer está instalado, WinINet también admite servidores proxy de tipo SOCKS. InternetConnect supone, de forma predeterminada, que el proxy especificado es un proxy CERN. Si el tipo de acceso se establece en INTERNET_OPEN_TYPE_DIRECT o INTERNET_OPEN_TYPE_PRECONFIG, el parámetro lpszProxyName de InternetOpen debe establecerse en NULL. De lo contrario, el valor pasado a lpszProxyName debe contener los servidores proxy en una cadena delimitada por espacio. Las listas de proxy pueden contener el número de puerto que se usa para acceder al proxy.
Para enumerar un proxy para un protocolo específico, la cadena debe seguir el formato ""<protocol protocol><>://<proxy_name>"". Los protocolos válidos son HTTP, HTTPS y FTP. Por ejemplo, para enumerar un proxy FTP, una cadena válida sería ""ftp=ftp://ftp_proxy_name:21"", donde ftp_proxy_name es el nombre del proxy FTP y 21 es el número de puerto que se debe usar para acceder al proxy. Si el proxy usa el número de puerto predeterminado para ese protocolo, se puede omitir el número de puerto. Si un nombre de proxy aparece por sí mismo, se usa como proxy predeterminado para los protocolos que no tienen un proxy específico especificado. Por ejemplo, ""http=https://http_proxy other"" usaría http_proxy para cualquier operación HTTP, mientras que todos los demás protocolos usarían otros.
De forma predeterminada, la función asume que el proxy especificado por lpszProxyName es un proxy CERN. Una aplicación puede especificar más de un proxy, incluidos servidores proxy diferentes para los distintos protocolos. Por ejemplo, si especifica ""ftp=ftp://ftp-gw HTTP=https://jericho:99 proxy"", las solicitudes FTP se realizan a través del proxy ftp-gw, que escucha en el puerto 21 y las solicitudes HTTP se realizan a través de un proxy CERN denominado jericho, que escucha en el puerto 99. De lo contrario, las solicitudes HTTP se realizarían a través del proxy CERN denominado proxy, que escucha en el puerto 80. Tenga en cuenta que si la aplicación solo usa FTP, por ejemplo, no tendría que especificar ""ftp=ftp://ftp-gw:21"". Podría especificar solo ""ftp-gw"". Una aplicación solo es necesaria para especificar los nombres de protocolo si usa más de un protocolo por identificador devuelto por InternetOpen.
Enumeración de la omisión de proxy
Los nombres de host o las direcciones IP que no se deben enviar al proxy se pueden enumerar en la lista de omisión de proxy. Esta lista puede contener caracteres comodín, "*", lo que hace que la aplicación omita el servidor proxy para las direcciones que se ajustan al patrón especificado. Para enumerar varias direcciones y nombres de host, parelas con punto y coma en la cadena de omisión de proxy. Si se especifica la macro "<local>", la función omite el proxy de cualquier nombre de host que no contenga un punto.
De forma predeterminada, WinINet omitirá el proxy de las solicitudes que usan los nombres de host "localhost", "loopback", "127.0.0.1" o "[::1]". Este comportamiento existe porque un servidor proxy remoto normalmente no resolverá estas direcciones correctamente.
Internet Explorer 9: Puede quitar el equipo local de la lista de omisión de proxy mediante la macro "<-loopback>".
En el ejemplo siguiente se muestran llamadas de ejemplo a InternetOpen mediante diferentes cadenas de omisión de proxy. Los comentarios anteriores de cada llamada describen qué efecto tiene la cadena de omisión en los nombres de host a los que se accede desde el identificador HINTERNET que crea.
HINTERNET hInternetRoot;
/* bypass the proxy for any host name that does not
contain a period */
hInternetRoot = InternetOpen(TEXT("WinInet Example"),
INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("<local>"), 0);
/* bypass the proxy for any host name that starts with the
letters "ms" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"),
INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("ms*"), 0);
/* bypass the proxy for any host name that contains "int",
such as "internet" and "painter" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"),
INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("*int*"), 0);
/* bypass the proxy for the host name "example" and any
host name that contains "test" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"),
INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("example *test*"), 0);
/* Disable the loopback proxy bypass for localhost */
hInternetRoot = InternetOpen(TEXT("WinInet Example"),
INTERNET_OPEN_TYPE_PROXY,TEXT("127.0.0.1:8888"),TEXT("<-loopback>"), 0);
Uso de InternetConnect
Para iniciar una sesión, la función InternetConnect debe crear un identificador fuera del identificador raíz devuelto por la función InternetOpen . InternetConnect establece la dirección del servidor, el número de puerto, el nombre de usuario, la contraseña y el tipo de servicio.
InternetConnect usa el identificador HINTERNET raíz creado por InternetOpen para establecer un identificador de sesión. Si la marca INTERNET_FLAG_ASYNC se estableció en la llamada a InternetOpen, la llamada a InternetConnect debe incluir un valor de contexto distinto de cero.
El nombre del servidor puede contener el nombre de host (por ejemplo, "www.servername.com") o el número IP del sitio en formato decimal de puntos ASCII (por ejemplo, "10.0.1.45").
El puerto del servidor es el número de puerto protocolo de control de transmisión/Protocolo de Internet (TCP/IP) al que conectarse en el servidor. InternetConnect usa el puerto predeterminado para el tipo de servicio seleccionado si se usa el valor INTERNET_INVALID_PORT_NUMBER. Las tablas siguientes contienen los valores predeterminados del puerto de servidor para WinINet.
| Valor | Significado |
|---|---|
| INTERNET_DEFAULT_FTP_PORT | Use el puerto predeterminado para los servidores ftp (puerto 21). |
| INTERNET_DEFAULT_GOPHER_PORT | Use el puerto predeterminado para los servidores gopher (puerto 70). Nota: Windows XP y Windows Server 2003 R2 y versiones anteriores. |
| INTERNET_DEFAULT_HTTP_PORT | Use el puerto predeterminado para los servidores HTTP (puerto 80). |
| INTERNET_DEFAULT_HTTPS_PORT | Use el puerto predeterminado para los servidores https (puerto 443). |
| INTERNET_DEFAULT_SOCKS_PORT | Use el puerto predeterminado para los servidores de firewall SOCKS (puerto 1080). |
Definición del nombre de usuario y la contraseña
El valor de lpszUsername es la dirección de una cadena terminada en null que contiene el nombre del usuario que inicia sesión. Si este parámetro es NULL, la función usa un valor predeterminado adecuado, excepto HTTP. Un parámetro NULL en HTTP hace que el servidor devuelva un error. Para el protocolo FTP, el valor predeterminado es anónimo.
El valor de lpszPassword es la dirección de una cadena terminada en null que contiene la contraseña de inicio de sesión. Si lpszUsername y lpszPassword son NULL, la función usa la contraseña anónima predeterminada. En el caso de FTP, la contraseña anónima predeterminada es el nombre de correo electrónico del usuario. Si lpszUsername no es NULL y lpszPassword es NULL, la función usa una contraseña en blanco. Hay cuatro opciones posibles de lpszUsername y lpszPassword, que generan los comportamientos que se muestran en la tabla siguiente.
| lpszUsername | lpszPassword | Nombre de usuario enviado al servidor FTP | Contraseña enviada al servidor FTP |
|---|---|---|---|
| NULL | NULL | "anónimo" | Nombre de correo electrónico del usuario |
| Cadena que no es NULL | NULL | lpszUsername | "" |
| NULL | Cadena que no es NULL | ERROR | ERROR |
| Cadena que no es NULL | Cadena que no es NULL | lpszUsername | lpszPassword |
Esta información se puede cambiar mediante las funciones InternetSetOption e InternetErrorDlg . InternetSetOption cambia los valores de nombre de usuario y contraseña, mientras que InternetErrorDlg muestra un cuadro de diálogo que solicita el nombre de usuario y la contraseña adecuados.
Definición de la sesión
Para definir la sesión que se establece, establezca el tipo de servicio, las marcas y el valor de contexto de InternetConnect.
Hay dos tipos de servicio disponibles para InternetConnect: INTERNET_SERVICE_FTP y INTERNET_SERVICE_HTTP. INTERNET_SERVICE_HTTP se usa para sesiones HTTP y HTTPS.
INTERNET_FLAG_PASSIVE es la única marca específica del servicio que usan las funciones winINet. Esta marca se puede establecer cuando el tipo de servicio se INTERNET_SERVICE_FTP para usar la semántica de FTP pasiva.
Para todas las operaciones sincrónicas, el valor de dwContext debe establecerse en cero. Si se establecieron operaciones asincrónicas estableciendo la marca INTERNET_FLAG_ASYNC en la llamada a InternetOpen, se debe proporcionar un valor distinto de cero para dwContext. Para obtener más información sobre las operaciones asincrónicas, consulte Configuración de operaciones asincrónicas.
En el caso de las sesiones FTP, InternetConnect intenta establecer una conexión con el servidor en Internet. Para las sesiones HTTP, InternetConnect no establece una conexión hasta que otra función intenta obtener información del servidor.
Nota:
WinINet no admite implementaciones de servidor. Además, no se debe usar desde un servicio. En el caso de las implementaciones de servidor o los servicios, use los servicios HTTP de Microsoft Windows (WinHTTP).
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de