Función InternetConnectA (wininet.h)

  • Artículo

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
INTERNET_DEFAULT_FTP_PORT
 Usa el puerto predeterminado para los servidores FTP (puerto 21).
INTERNET_DEFAULT_GOPHER_PORT
 Usa el puerto predeterminado para los servidores gopher (puerto 70).
Nota Windows XP y Windows Server 2003 R2 y versiones anteriores.
 
INTERNET_DEFAULT_HTTP_PORT
 Usa el puerto predeterminado para los servidores HTTP (puerto 80).
INTERNET_DEFAULT_HTTPS_PORT
 Usa el puerto predeterminado para servidores de Protocolo de transferencia de hipertexto seguro (HTTPS) (puerto 443).
INTERNET_DEFAULT_SOCKS_PORT
 Usa el puerto predeterminado para los servidores de firewall SOCKS (puerto 1080).
INTERNET_INVALID_PORT_NUMBER
 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
INTERNET_SERVICE_FTP
 Servicio FTP.
INTERNET_SERVICE_GOPHER
 Servicio Gopher.
Nota Windows XP y Windows Server 2003 R2 y versiones anteriores.
 
INTERNET_SERVICE_HTTP
 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 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).
 

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

Consulte también

Habilitación de la funcionalidad de Internet

Funciones de WinINet