Initializes an application's use of the WinINet functions.

Syntax

HINTERNET InternetOpen(
  __in  LPCTSTR lpszAgent,
  __in  DWORD dwAccessType,
  __in  LPCTSTR lpszProxyName,
  __in  LPCTSTR lpszProxyBypass,
  __in  DWORD dwFlags
);

Parameters

lpszAgent

Pointer to a null-terminated string that specifies the name of the application or entity calling the WinINet functions. This name is used as the user agent in the HTTP protocol.

dwAccessType

Type of access required. This parameter can be one of the following values.

Value	Meaning
INTERNET_OPEN_TYPE_DIRECT	Resolves all host names locally.
INTERNET_OPEN_TYPE_PRECONFIG	Retrieves the proxy or direct configuration from the registry.
INTERNET_OPEN_TYPE_PRECONFIG_WITH_NO_AUTOPROXY	Retrieves the proxy or direct configuration from the registry and prevents the use of a startup Microsoft JScript or Internet Setup (INS) file.
INTERNET_OPEN_TYPE_PROXY	Passes requests to the proxy unless a proxy bypass list is supplied and the name to be resolved bypasses the proxy. In this case, the function uses INTERNET_OPEN_TYPE_DIRECT.

lpszProxyName

Pointer to a null-terminated string that specifies the name of the proxy server(s) to use when proxy access is specified by setting dwAccessType to INTERNET_OPEN_TYPE_PROXY. Do not use an empty string, because InternetOpen will use it as the proxy name. The WinINet functions recognize only CERN type proxies (HTTP only) and the TIS FTP gateway (FTP only). If Microsoft Internet Explorer is installed, these functions also support SOCKS proxies. FTP and Gopher requests can be made through a CERN type proxy either by changing them to an HTTP request or by using InternetOpenUrl. If dwAccessType is not set to INTERNET_OPEN_TYPE_PROXY, this parameter is ignored and should be NULL. For more information about listing proxy servers, see the Listing Proxy Servers section of Enabling Internet Functionality.

lpszProxyBypass

Pointer to a null-terminated string that specifies an optional list of host names or IP addresses, or both, that should not be routed through the proxy when dwAccessType is set to INTERNET_OPEN_TYPE_PROXY. The list can contain wildcards. Do not use an empty string, because InternetOpen will use it as the proxy bypass list. If this parameter specifies the "<local>" macro as the only entry, the function bypasses any host name that does not contain a period. If dwAccessType is not set to INTERNET_OPEN_TYPE_PROXY, this parameter is ignored and should be NULL.

dwFlags

Options. This parameter can be a combination of the following values.

Value	Meaning
INTERNET_FLAG_ASYNC	Makes only asynchronous requests on handles descended from the handle returned from this function.
INTERNET_FLAG_FROM_CACHE	Does not make network requests. All entities are returned from the cache. If the requested item is not in the cache, a suitable error, such as ERROR_FILE_NOT_FOUND, is returned.
INTERNET_FLAG_OFFLINE	Identical to INTERNET_FLAG_FROM_CACHE. Does not make network requests. All entities are returned from the cache. If the requested item is not in the cache, a suitable error, such as ERROR_FILE_NOT_FOUND, is returned.

Return Value

Returns a valid handle that the application passes to subsequent WinINet functions. If InternetOpen fails, it returns NULL. To retrieve a specific error message, call GetLastError.

Remarks

InternetOpen is the first WinINet function called by an application. It tells the Internet DLL to initialize internal data structures and prepare for future calls from the application. When the application finishes using the Internet functions, it should call InternetCloseHandle to free the handle and any associated resources.

The application can make any number of calls to InternetOpen, though a single call is normally sufficient. The application might need to define separate behaviors for each InternetOpen instance, such as different proxy servers configured for each.

After the calling application has finished using the HINTERNET handle returned by InternetOpen, it must be closed using the InternetCloseHandle function.

Requirements

See Also

Enabling Internet Functionality
WinINet Functions

Send comments about this topic to Microsoft

Build date: 5/15/2008