InternetConnect

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function opens an FTP or HTTP session for a specified site.

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

Parameters

hInternet

Handle to the current Internet session. The handle must have been returned by a previous call to InternetOpen.

lpszServerName

Long pointer to 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. It is one of the following values. These flags set only the port that will be used. The service is set by the value of dwService.

Value	Description
INTERNET_DEFAULT_FTP_PORT	Uses the default port for FTP servers (port 21).
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

Long pointer to 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

Long pointer to a null-terminated string that contains the password to use to log on. If both lpszPasswordand lpszUserNameare NULL, the function uses the default "anonymous" password. In the case of FTP, the default password is the user's e-mail name. If lpszPasswordis NULL, but lpszUserNameis not NULL, the function uses a blank password. The behavior for the four possible settings of lpszUserNameand lpszPasswordis described in the following table.

dwService

Specifies the type of service to access. It is one of the following values:

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

Value	Description
INTERNET_SERVICE_FTP	FTP service.
INTERNET_SERVICE_HTTP	HTTP service.

dwFlags

Flags specific to the service used. When the value of dwServiceis INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE causes the application to use passive FTP semantics.

dwContext

Specifies the application-defined value that is used to identify the application context for the returned handle in callbacks.

Return Values

A valid handle to the FTP or HTTP session if the connection indicates success. NULL indicates failure. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfoto determine why access to the service was denied.

Windows CE Remarks

The InternetConnectfunction returns a valid handle to the FTP or HTTP session if the connection is successful, or NULL otherwise.

The dwServiceparameter accepts INTERNET_SERVICE_FTP and INTERNET_SERVICE_HTTP as the types of service/protocol for use in the connection. However, it does not accept INTERNET_SERVICE_GOPHER, as GOPHER is not supported in Windows CE.

If DwFlagsis set with INTERNET_FLAG_PASSIVE, the data transfers for the current FTP session occur in passive mode. INTERNET_FLAG_SECURE is not supported.

The dwContextparameter allows for progress status callbacks to the application, but all requests are handled synchronously.

When establishing a Secure Sockets Layer (SSL) or Private Communications Technology, InternetConnectuses INTERNET_DEFAULT_HTTPS_PORT instead of INTERNET_INVALID_PORT_NUMBER or INTERNET_DEFAULT_HTTP_PORT.

Remarks

The InternetConnectfunction is required before communicating with any Internet service.

Having a connect function for all protocols, even those that do not use persistent connections, lets an application communicate common information about several requests by using a single function call. In addition, this allows for future versions of Internet protocols that do not require a connection to be established for every client request.

For FTP sites, InternetConnectactually establishes a connection with the server.

For maximum efficiency, applications using the HTTP protocols should try to minimize calls to InternetConnectand 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.

An application that needs to display multiline text information sent by an FTP server can use InternetGetLastResponseInfoto retrieve the text.

For FTP connections, if lpszUsernameis NULL, InternetConnectsends the string "anonymous" as the user name. If lpszPasswordis NULL, InternetConnectattempts to use the user's e-mail name as the password.

To close the handle returned from InternetConnect, the application should call InternetCloseHandle. This function disconnects the client from the server and frees all resources associated with the connection.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Wininet.h		Wininet.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.