Enabling Internet Functionality

Before using the WinINet functions, the application should attempt to make a connection to the Internet by using the InternetAttemptConnect function. This function calls the dial-up dialog box to initiate a connection to the Internet or check if a connection already exists. If this function fails, the application can enter offline mode, which allows it to access information that was cached during previous connections to the Internet.

Use the InternetCheckConnection function to check the connection to the Internet. It attempts to ping the server designated by the URL that is passed to the function. If the FLAG_ICC_FORCE_CONNECTION flag is set and the URL is NULL, the function checks to see if there is an entry in the server database for the nearest server. If one exists, the function pings that server.

Next, use the InternetOpen function to establish the characteristics of the Internet connection the client application is using. InternetOpen creates the root HINTERNET handle that is used to establish httpftp sessions. InternetOpen does not test the connection to the Internet to verify that the characteristics passed to the function are correct.

Use the InternetConnect function to create a specific session. InternetConnect initializes a session for the specified site using the arguments passed to it and creates an HINTERNET handle that is a branch off the root handle. InternetConnect does not attempt to access or establish a connection to the specified site, except in the case of an FTP session. FtpFindFirstFile, FtpOpenFile, and HttpOpenRequest functions use the handle created by InternetConnect to establish a connection to the specified site.

Using InternetOpen

To enable a connection to the Internet, a root HINTERNET handle must be created by using InternetOpen. Information about the user agent (the application calling the Internet functions), the type of access to the Internet, the proxy names, the hosts and addresses that bypass the proxy, and the behavior are passed to InternetOpen.

Setting the User Agent

The calling application should give a string that contains the name of the application or entity accessing the Internet to the lpszAgent parameter of InternetOpen. This string is used as the user agent in the HTTP protocol. For example, Microsoft Internet Explorer uses "Microsoft Internet Explorer".

Setting Access Types

InternetOpen supports three access types:

• Use INTERNET_OPEN_TYPE_DIRECT if the system on which the application is running uses a direct connection to the Internet. The lpszProxyName and lpszProxyBypass parameters of InternetOpen are not used and should be set to NULL.
• Use INTERNET_OPEN_TYPE_PROXY if the system on which the application is running uses one or more proxy servers to access the Internet. InternetOpen uses the proxy servers indicated by lpszProxyName and bypasses the proxy for any host names or IP addresses specified by lpszProxyBypass.
• Use INTERNET_OPEN_TYPE_PRECONFIG to instruct your application to retrieve the configuration from the registry. This is typically the best choice, as most applications including web browsers use this option.

INTERNET_OPEN_TYPE_PRECONFIG looks at the registry values ProxyEnable, ProxyServer, and ProxyOverride. These values are located under "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings".

If ProxyEnable is zero, the application uses INTERNET_OPEN_TYPE_DIRECT. Otherwise, the application uses INTERNET_OPEN_TYPE_PROXY and uses the ProxyServer and ProxyOverride information.

The WinINet functions provide support for SOCKS type proxies only if Internet Explorer is installed. The installation of Internet Explorer includes the Wsock32n.dll file, which is needed to support SOCKS proxies. Wsock32n.dll is not redistributable.

Listing Proxy Servers

WinINet recognizes two types of proxies: CERN type proxies (HTTP only) and TIS FTP proxies (FTP only). If Internet Explorer is installed, WinINet also support SOCKS type proxies. InternetConnect assumes, by default, that the specified proxy is a CERN proxy. If the access type is set to INTERNET_OPEN_TYPE_DIRECT or INTERNET_OPEN_TYPE_PRECONFIG, the lpszProxyName parameter of InternetOpen should be set to NULL. Otherwise, the value passed to lpszProxyName must contain the proxies in a space-delimited string. The proxy listings can contain the port number that is used to access the proxy.

To list a proxy for a specific protocol, the string must follow the format ""<protocol><protocol>://<proxy_name>"". The valid protocols are HTTP, HTTPS and FTP. For example, to list an FTP proxy, a valid string would be ""ftp=ftp://ftp_proxy_name:21"", where ftp_proxy_name is the name of the FTP proxy and 21 is the port number that must be used to access the proxy. If the proxy uses the default port number for that protocol, the port number can be omitted. If a proxy name is listed by itself, it is used as the default proxy for any protocols that do not have a specific proxy specified. For example, ""http=https://http_proxy other"" would use http_proxy for any HTTP operations, while all other protocols would use other.

By default, the function assumes that the proxy specified by lpszProxyName is a CERN proxy. An application can specify more than one proxy, including different proxies for the different protocols. For example, if you specify ""ftp=ftp://ftp-gw HTTP=https://jericho:99 proxy"", FTP requests are made through the ftp-gw proxy, which listens at port 21, and HTTP requests are made through a CERN proxy called jericho, which listens at port 99. Otherwise, HTTP requests would be made through the CERN proxy called proxy, which listens at port 80. Note that if the application is only using FTP, for example, it would not need to specify ""ftp=ftp://ftp-gw:21"". It could specify just ""ftp-gw"". An application is only required to specify the protocol names if it is using more than one protocol per handle returned by InternetOpen.

Listing the Proxy Bypass

Host names or IP addresses that should not be sent to the proxy can be listed in the proxy bypass list. This list can contain wildcards, "*", which cause the application to bypass the proxy server for addresses that fit the specified pattern. To list multiple addresses and host names, separate them with semicolons in the proxy bypass string. If the "<local>" macro is specified, the function bypasses the proxy for any host name that does not contain a period.

By default, WinINet will bypass the proxy for requests that use the host names "localhost", "loopback", "127.0.0.1", or "[::1]". This behavior exists because a remote proxy server typically will not resolve these addresses properly.

Internet Explorer 9: You can remove the local computer from the proxy bypass list using the "<-loopback>" macro.

The following example shows sample calls to InternetOpen using different proxy bypass strings. The comments above each call describe what effect the bypass string has on the host names that are accessed from the HINTERNET handle it creates.

HINTERNET hInternetRoot;

/* bypass the proxy for any host name that does not 
    contain a period */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("<local>"), 0);

/* bypass the proxy for any host name that starts with the 
    letters "ms" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("ms*"), 0);

/* bypass the proxy for any host name that contains "int", 
    such as "internet" and "painter" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("*int*"), 0);

/* bypass the proxy for the host name "example" and any 
    host name that contains "test" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("example *test*"), 0);

/* Disable the loopback proxy bypass for localhost */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("127.0.0.1:8888"),TEXT("<-loopback>"), 0);

Using InternetConnect

To begin a session, the InternetConnect function must create a handle off the root handle returned by the InternetOpen function. InternetConnect sets the server address, port number, user name, password, and type of service.

InternetConnect uses the root HINTERNET handle created by InternetOpen to establish a session handle. If the INTERNET_FLAG_ASYNC flag was set in the call to InternetOpen, the call to InternetConnect should include a nonzero context value.

The server name can contain either the host name (for example, "www.servername.com") or IP number of the site in ASCII dotted-decimal format (for example, "10.0.1.45").

The server port is the Transmission Control Protocol/Internet Protocol (TCP/IP) port number to connect to on the server. InternetConnect uses the default port for the selected service type if the INTERNET_INVALID_PORT_NUMBER value is used. The following tables contain the server port defaults for WinINet.

Defining the User Name and Password

The value of lpszUsername is the address of a null-terminated string that contains the name of the user who is logging 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.

The value of lpszPassword is the address of a null-terminated string that contains the log-on password. If both lpszUsername and lpszPassword are NULL, the function uses the default anonymous password. In the case of FTP, the default anonymous password is the user's email name. If lpszUsername is not NULL and lpszPassword is NULL, the function uses a blank password. There are four possible settings of lpszUsername and lpszPassword, which produce the behaviors shown in the following table.

This information can be changed by using the InternetSetOption and InternetErrorDlg functions. InternetSetOption changes the user name and password values, while InternetErrorDlg displays a dialog box that requests the proper user name and password.

Defining the Session

To define the session that is being established, set the service type, flags, and context value for InternetConnect.

There are two service types available to InternetConnect: INTERNET_SERVICE_FTP and INTERNET_SERVICE_HTTP. INTERNET_SERVICE_HTTP is used for both HTTP and HTTPS sessions.

INTERNET_FLAG_PASSIVE is the only service-specific flag used by the WinINet functions. This flag can be set when the service type is INTERNET_SERVICE_FTP in order to use passive FTP semantics.

For all synchronous operations, the value of dwContext should be set to zero. If asynchronous operations were established by setting the INTERNET_FLAG_ASYNC flag in the call to InternetOpen, a nonzero value should be supplied for dwContext. For more information on asynchronous operations, see Setting Up Asynchronous Operations.

For FTP sessions, InternetConnect tries to establish a connection to the server on the Internet. For HTTP sessions, InternetConnect does not establish a connection until another function attempts to get information from the server.