Enabling Internet Functionality


		Contents Index Topic Contents
	Previous Topic: Establishing a Dial-Up Connection to the Internet Next Topic: Common Functions

Enabling Internet Functionality

To compile programs that utilize the Win32 Internet functions, the header file, Wininet.h, must be in the include directory, and the library file, Wininet.lib, must be in the library directory of the C/C++ compiler being used.
Before using the Win32 Internet 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.
The InternetCheckConnection function can be used to check the connection to the Internet. It attempts to ping the server designated by the Uniform Resource Locator (URL) that is passed to the function. If the FLAG_ICC_FORCE_CONNECTION flag is set and NULL was given as the URL, the function checks to see if there is an entry in the WinInet server database for the nearest server. If one exists, the function pings that server.
To begin using the Win32 Internet functions, use the InternetOpen function to establish the characteristics of the Internet connection being used. InternetOpen creates the root HINTERNET handle that is used to establish HTTP, FTP, and Gopher 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 an FTP, Gopher, or HTTP 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, GopherFindFirstFile, GopherOpenFile, and HttpOpenRequest functions use the handle created by InternetConnect to establish a connection to the specified site.
The following diagram illustrates the hierarchy of the HINTERNET handles.

The InternetOpen function, which creates the root HINTERNET handle, is at the top level. The next level contains the InternetOpenUrl function and the InternetConnect function. The functions that use the HINTERNET handle returned by InternetConnect make up the last level. For more information about HINTERNET handles and the handle hierarchy, see Appendix A: HINTERNET Handles.
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 lpszAgent parameter of InternetOpen should be given a string that contains the name of the application or entity accessing the Internet. This string is used as the user agent in the HTTP protocol. For example, 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.

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 Win32 Internet functions provide support for SOCKS type proxies only if Microsoft Internet Explorer is installed. The installation of Internet Explorer installs the Wsock32n.dll, which the Win32 Internet functions need to support SOCKS proxies. The Wsock32n.dll is not redistributable.
Listing proxy servers

The Win32 Internet functions recognize two types of proxies: CERN type proxies (HTTP only) and TIS FTP proxies (FTP only). If Internet Explorer is installed, the Win32 Internet functions 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, ftp, and gopher. 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=http://http_proxy other" would use "http_proxy" for any HTTP operations, while all other protocols (such as FTP and Gopher) would use "other".
Listing the proxy bypass

Host names or IP addresses that are known locally can be listed in the proxy bypass. 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 blank spaces in the proxy bypass string. If the "<local>" macro is specified, the function bypasses any host name that does not contain a period.
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.
/* bypass the proxy for any host name that does not 
    contain a period */
hInternetRoot = InternetOpen("WinInet Example", 
    INTERNET_OPEN_TYPE_PROXY,"proxy","<local>", 0);

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

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

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

To begin a Gopher, FTP, or HTTP 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 be a constant string or a variable containing a string value of type LPSTR. This string can contain either the host name (for example, www.servername.com) or IP number of the site in ASCII dotted-decimal format (for example, 11.0.1.45).
The server port is the 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. There are four server port defaults included with the Win32 Internet functions.

Value Meaning

INTERNET_DEFAULT_FTP_PORT Use the default port for FTP servers (port 21).

INTERNET_DEFAULT_GOPHER_PORT Use the default port for Gopher servers (port 70).

INTERNET_DEFAULT_HTTP_PORT Use the default port for HTTP servers (port 80).

INTERNET_DEFAULT_HTTPS_PORT Use the default port for HTTPS servers (port 443).

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

Defining the user name and password

The user name is the 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.
The password is the address of a NULL-terminated string that contains the password to use to log on. 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 e-mail 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.

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

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 requesting the proper user name and password.
Defining the session

To define the session that is being established, InternetConnect must have the service type, flags, and context value set.
There are three service types available to InternetConnect: INTERNET_SERVICE_FTP, INTERNET_SERVICE_GOPHER, 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 Win32 Internet 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. HTTP and Gopher sessions do not establish a connection until a function attempts to get information from the server.

Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.

Value	Meaning
INTERNET_DEFAULT_FTP_PORT	Use the default port for FTP servers (port 21).
INTERNET_DEFAULT_GOPHER_PORT	Use the default port for Gopher servers (port 70).
INTERNET_DEFAULT_HTTP_PORT	Use the default port for HTTP servers (port 80).
INTERNET_DEFAULT_HTTPS_PORT	Use the default port for HTTPS servers (port 443).
INTERNET_DEFAULT_SOCKS_PORT	Uses the default port for SOCKS firewall servers (port 1080).

*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