Función InternetConnectA (wininet.h)
Abre una sesión de Protocolo de transferencia de archivos (FTP) o HTTP para un sitio determinado.
Sintaxis
HINTERNET InternetConnectA(
[in] HINTERNET hInternet,
[in] LPCSTR lpszServerName,
[in] INTERNET_PORT nServerPort,
[in] LPCSTR lpszUserName,
[in] LPCSTR lpszPassword,
[in] DWORD dwService,
[in] DWORD dwFlags,
[in] DWORD_PTR dwContext
);
Parámetros
[in] hInternet
Identificador devuelto por una llamada anterior a InternetOpen.
[in] lpszServerName
Puntero a una cadena terminada en null que especifica el nombre de host de un servidor de Internet. Como alternativa, la cadena puede contener el número IP del sitio, en formato decimal con puntos ASCII (por ejemplo, 11.0.1.45).
[in] nServerPort
Puerto protocolo de control de transmisión/Protocolo de Internet (TCP/IP) en el servidor. Estas marcas establecen solo el puerto que se usa. El servicio se establece mediante el valor de dwService. Este parámetro puede ser uno de los valores siguientes.
| Valor | Significado |
|---|---|
|
Usa el puerto predeterminado para los servidores FTP (puerto 21). |
|
Usa el puerto predeterminado para los servidores gopher (puerto 70). Nota Windows XP y Windows Server 2003 R2 y versiones anteriores.
|
|
Usa el puerto predeterminado para los servidores HTTP (puerto 80). |
|
Usa el puerto predeterminado para servidores de Protocolo de transferencia de hipertexto seguro (HTTPS) (puerto 443). |
|
Usa el puerto predeterminado para los servidores de firewall SOCKS (puerto 1080). |
|
Usa el puerto predeterminado para el servicio especificado por dwService. |
[in] lpszUserName
Puntero a una cadena terminada en null que especifica el nombre del usuario en el que iniciar sesión. Si este parámetro es NULL, la función usa un valor predeterminado adecuado. Para el protocolo FTP, el valor predeterminado es "anónimo".
[in] lpszPassword
Puntero a una cadena terminada en null que contiene la contraseña que se va a usar para iniciar sesión. Si lpszPassword y lpszUsername son NULL, la función usa la contraseña "anónima" predeterminada. En el caso de FTP, la contraseña predeterminada es el nombre de correo electrónico del usuario. Si lpszPassword es NULL, pero lpszUsername no es NULL, la función usa una contraseña en blanco.
[in] dwService
Tipo de servicio al que se va a acceder. Este parámetro puede ser uno de los valores siguientes.
| Valor | Significado |
|---|---|
|
Servicio FTP. |
|
Servicio Gopher. Nota Windows XP y Windows Server 2003 R2 y versiones anteriores.
|
|
Servicio HTTP. |
[in] dwFlags
Opciones específicas del servicio usado. Si
dwService se INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE hace que la aplicación use la semántica de FTP pasiva.
[in] dwContext
Puntero a una variable que contiene un valor definido por la aplicación que se usa para identificar el contexto de la aplicación para el identificador devuelto en devoluciones de llamada.
Valor devuelto
Devuelve un identificador válido a la sesión si la conexión es correcta o NULL de lo contrario. Para recuperar información de error extendida, llame a GetLastError. Una aplicación también puede usar InternetGetLastResponseInfo para determinar por qué se denegó el acceso al servicio.
Comentarios
En la tabla siguiente se describe el comportamiento de las cuatro opciones posibles de lpszUsername y lpszPassword.
| 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 |
En el caso de los sitios FTP, InternetConnect establece realmente una conexión con el servidor; para otros, la conexión real no se establece hasta que la aplicación solicita una transacción específica.
Para lograr la máxima eficacia, las aplicaciones que usan los protocolos HTTP deben intentar minimizar las llamadas a InternetConnect y evitar llamar a esta función para cada transacción solicitada por el usuario. Una manera de lograrlo es mantener una pequeña caché de identificadores devueltos desde InternetConnect; cuando el usuario realiza una solicitud a un servidor al que se ha accedido anteriormente, ese identificador de sesión sigue estando disponible.
Una vez finalizada la aplicación que realiza la llamada mediante el identificador HINTERNET devuelto por InternetConnect, debe cerrarse mediante la función InternetCloseHandle .
Nota Cuando se envía una solicitud en modo asincrónico (el parámetro dwFlags de InternetOpen especifica INTERNET_FLAG_ASYNC) y el parámetro dwContext es cero (INTERNET_NO_CALLBACK), no se llamará a la función de devolución de llamada establecida con InternetSetStatusCallback en el identificador de conexión, pero la llamada se seguirá realizando en modo asincrónico.
Puede encontrar ejemplos de uso de InternetConnect en los temas siguientes.
Al igual que todos los demás aspectos de la API de WinINet, esta función no se puede llamar de forma segura desde DllMain ni desde los constructores y destructores de objetos globales.
Nota
El encabezado wininet.h define InternetConnect como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | wininet.h |
| Library | Wininet.lib |
| Archivo DLL | Wininet.dll |