InternetConnect (Windows Embedded CE 6.0)

  • Article

1/6/2010

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

Syntax

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

Parameters

  • hInternet
    [in] Handle to the current Internet session. The handle must have been returned by a previous call to InternetOpen.
  • lpszServerName
    [in] 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
    [in] Number of the TCP/IP port on the server to connect to. The following table shows the possible 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
    [in] 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
    [in] Long pointer to 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. The following table shows 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

  • dwService
    [in] Specifies the type of service to access. The following table shows the possible values. This parameter is one of these values.

    Value Description

    INTERNET_SERVICE_FTP

    FTP service.

    INTERNET_SERVICE_HTTP

    HTTP service.
  • dwFlags
    [in] 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
    [in] Specifies the application-defined value that is used to identify the application context for the returned handle in callbacks.

Return Value

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

Remarks

The dwService parameteraccepts INTERNET_SERVICE_FTP and INTERNET_SERVICE_HTTP asthe types of service/protocol for use in the connection. However, itdoes not accept INTERNET_SERVICE_GOPHER, as GOPHER is not supported in Windows Embedded CE.

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

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

When establishing a Secure Sockets Layer (SSL) or Transport Layer Security, this function uses INTERNET_DEFAULT_HTTPS_PORT instead of INTERNET_INVALID_PORT_NUMBER or INTERNET_DEFAULT_HTTP_PORT.

This function 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, InternetConnect actually establishes a connection with the server.

For maximum efficiency, applications using the HTTP protocols should try to minimize calls to InternetConnect and avoid calling it for every transaction requested by the user. One way to accomplish this is to keep a small cache of handles returned from this function; 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 InternetGetLastResponseInfo to retrieve the text.

For FTP connections, if lpszUsername is NULL, InternetConnect sends the string "anonymous" as the user name. If lpszPassword is NULL, the function attempts to use the user's e-mail name as the password.

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

Requirements

Header wininet.h
Library wininet.lib
Windows Embedded CE Windows CE 2.0 and later

See Also

Reference

WinInet Functions
InternetCloseHandle
InternetGetLastResponseInfo
InternetOpen