InternetConnect Function

---

Opens an FTP, Gopher, or HTTP session for a given site.

Syntax

HINTERNET InternetConnect(
    IN HINTERNET hInternet,
    IN LPCTSTR lpszServerName,
    IN INTERNET_PORT nServerPort,
    IN LPCTSTR lpszUserName,
    IN LPCTSTR lpszPassword,
    IN DWORD dwService,
    IN DWORD dwFlags,
    IN DWORD_PTR dwContext
);

The actual syntax of this function varies between its ANSI and Unicode implementations. For more information, see Win32 Internet Functions Syntax.

Parameters

hInternet

Valid HINTERNET handle returned by a previous call to InternetOpen.

lpszServerName

Address of a null-terminated string that contains the host name of an Internet server. Alternately, the string can contain the IP number of the site, in ASCII dotted-decimal format (for example, 11.0.1.45).

nServerPort

Number of the TCP/IP port on the server to connect to. These flags set only the port that will be used. The service is set by the value of dwService. This can be any one of the following values:

INTERNET_DEFAULT_FTP_PORT

Uses the default port for FTP servers (port 21).

INTERNET_DEFAULT_GOPHER_PORT

Uses the default port for Gopher servers (port 70).

INTERNET_DEFAULT_HTTP_PORT

Uses the default port for HTTP servers (port 80).

INTERNET_DEFAULT_HTTPS_PORT

Uses the default port for HTTPS servers (port 443).

INTERNET_DEFAULT_SOCKS_PORT

Uses the default port for SOCKS firewall servers (port 1080).

INTERNET_INVALID_PORT_NUMBER

Uses the default port for the service specified by dwService.

lpszUsername

Address of a null-terminated string that contains the name of the user to log on. If this parameter is NULL, the function uses an appropriate default, except for HTTP; a NULL parameter in HTTP causes the server to return an error. For the FTP protocol, the default is "anonymous".

lpszPassword

Address of a null-terminated string that contains the password to use to log on. If both lpszPassword and lpszUsername are NULL, the function uses the default "anonymous" password. In the case of FTP, the default password is the user's e-mail name. If lpszPassword is NULL, but lpszUsername is not NULL, the function uses a blank password.

dwService

Unsigned long integer value that contains the type of service to access. This can be one of the following values:

INTERNET_SERVICE_FTP

FTP service.

INTERNET_SERVICE_GOPHER

Gopher service.

INTERNET_SERVICE_HTTP

HTTP service.

dwFlags

Unsigned long integer value that contains the flags specific to the service used. When the value of dwService is INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE causes the application to use passive FTP semantics.

dwContext

Address of an unsigned long integer value that contains an application-defined value that is used to identify the application context for the returned handle in callbacks.

Return Value

Returns a valid handle to the FTP, Gopher, or HTTP session if the connection is successful, or NULL otherwise. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfo to determine why access to the service was denied.

Remarks

The following table describes the behavior for the four possible settings of lpszUsername and lpszPassword.

lpszUsername	lpszPassword	User name sent to FTP server	Password sent to FTP server
NULL	NULL	"anonymous"	User's e-mail name
Non-NULL string	NULL	lpszUsername	""
NULL	Non-NULL string	ERROR	ERROR
Non-NULL string	Non-NULL string	lpszUsername	lpszPassword

For FTP sites, InternetConnect actually establishes a connection with the server; for others, such as Gopher, the actual connection is not established until the application requests a specific transaction.

For maximum efficiency, applications using the Gopher and HTTP protocols should try to minimize calls to InternetConnect and avoid calling this function for every transaction requested by the user. One way to accomplish this is to keep a small cache of handles returned from InternetConnect; when the user makes a request to a previously accessed server, that session handle is still available.

Function Information

Windows NT	Use version 4.0. Implemented as ANSI and Unicode functions.
Windows	Use Windows 95 and later. Implemented as ANSI and Unicode functions.
Header	Wininet.h
Import library	Wininet.lib
Minimum availability	Internet Explorer 3.0 (ANSI only), 5 (ANSI and Unicode)

Windows CE

Windows CE	Use version 2.12 and later. Implemented as ANSI and Unicode functions.
Minimum availability	Internet Explorer 4.0

See Also

Microsoft Win32 Internet Functions Overview, Enabling Internet Functionality, Microsoft Win32 Internet Functions Reference, General Win32 Internet Functions