Edit

Share via

InternetOpenUrlA function (wininet.h)

  • Article

Opens a resource specified by a complete FTP or HTTP URL.

Syntax

HINTERNET InternetOpenUrlA(
  [in] HINTERNET hInternet,
  [in] LPCSTR    lpszUrl,
  [in] LPCSTR    lpszHeaders,
  [in] DWORD     dwHeadersLength,
  [in] DWORD     dwFlags,
  [in] DWORD_PTR dwContext
);

Parameters

[in] hInternet

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

[in] lpszUrl

A pointer to a null-terminated string variable that specifies the URL to begin reading. Only URLs beginning with ftp:, http:, or https: are supported.

[in] lpszHeaders

A pointer to a null-terminated string that specifies the headers to be sent to the HTTP server. For more information, see the description of the lpszHeaders parameter in the HttpSendRequest function.

[in] dwHeadersLength

The size of the additional headers, in TCHARs. If this parameter is -1L and lpszHeaders is not NULL, lpszHeaders is assumed to be zero-terminated (ASCIIZ) and the length is calculated.

[in] dwFlags

This parameter can be one of the following values.

Value Meaning
INTERNET_FLAG_EXISTING_CONNECT
 Attempts to use an existing InternetConnect object if one exists with the same attributes required to make the request. This is useful only with FTP operations, since FTP is the only protocol that typically performs multiple operations during the same session. The WinINet API caches a single connection handle for each HINTERNET handle generated by InternetOpen. InternetOpenUrl uses this flag for HTTP and FTP connections.
INTERNET_FLAG_HYPERLINK
 Forces a reload if there was no Expires time and no LastModified time returned from the server when determining whether to reload the item from the network.
INTERNET_FLAG_IGNORE_CERT_CN_INVALID
 Disables checking of SSL/PCT-based certificates that are returned from the server against the host name given in the request. WinINet functions use a simple check against certificates by comparing for matching host names and simple wildcarding rules.
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
 Disables checking of SSL/PCT-based certificates for proper validity dates.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP
 Disables detection of this special type of redirect. When this flag is used, WinINet transparently allows redirects from HTTPS to HTTP URLs.
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS
 Disables the detection of this special type of redirect. When this flag is used, WinINet transparently allows redirects from HTTP to HTTPS URLs.
INTERNET_FLAG_KEEP_CONNECTION
 Uses keep-alive semantics, if available, for the connection. This flag is required for Microsoft Network (MSN), NTLM, and other types of authentication.
INTERNET_FLAG_NEED_FILE
 Causes a temporary file to be created if the file cannot be cached.
INTERNET_FLAG_NO_AUTH
 Does not attempt authentication automatically.
INTERNET_FLAG_NO_AUTO_REDIRECT
 Does not automatically handle redirection in HttpSendRequest.
INTERNET_FLAG_NO_CACHE_WRITE
 Does not add the returned entity to the cache.
INTERNET_FLAG_NO_COOKIES
 Does not automatically add cookie headers to requests, and does not automatically add returned cookies to the cookie database.
INTERNET_FLAG_NO_UI
 Disables the cookie dialog box.
INTERNET_FLAG_PASSIVE
 Uses passive FTP semantics. InternetOpenUrl uses this flag for FTP files and directories.
INTERNET_FLAG_PRAGMA_NOCACHE
 Forces the request to be resolved by the origin server, even if a cached copy exists on the proxy.
INTERNET_FLAG_RAW_DATA
 Returns the data as a WIN32_FIND_DATA structure when retrieving FTP directory information. If this flag is not specified or if the call was made through a CERN proxy, InternetOpenUrl returns the HTML version of the directory.

Windows XP and Windows Server 2003 R2 and earlier:  Also returns data as a GOPHER_FIND_DATA structure when retrieving Gopher directory information.
INTERNET_FLAG_RELOAD
 Forces a download of the requested file, object, or directory listing from the origin server, not from the cache.
INTERNET_FLAG_RESYNCHRONIZE
 Reloads HTTP resources if the resource has been modified since the last time it was downloaded. All FTP resources are reloaded.

Windows XP and Windows Server 2003 R2 and earlier:  Gopher resources are also reloaded.
INTERNET_FLAG_SECURE
 Uses secure transaction semantics. This translates to using Secure Sockets Layer/Private Communications Technology (SSL/PCT) and is only meaningful in HTTP requests.

[in] dwContext

A pointer to a variable that specifies the application-defined value that is passed, along with the returned handle, to any callback functions.

Return value

Returns a valid handle to the URL if the connection is successfully established, or NULL if the connection fails. To retrieve a specific error message, call GetLastError. To determine why access to the service was denied, call InternetGetLastResponseInfo.

Remarks

Call InternetCanonicalizeUrl first if the URL being used contains a relative URL and a base URL separated by blank spaces.

This is a general function that an application can use to retrieve data over any of the protocols that WinINet supports. This function is especially useful when the application does not need to access the particulars of a protocol, but only requires the data corresponding to a URL. The InternetOpenUrl function parses the URL string, establishes a connection to the server, and prepares to download the data identified by the URL. The application can then use InternetReadFile (for files) or InternetFindNextFile (for directories) to retrieve the URL data. It is not necessary to call InternetConnect before InternetOpenUrl.

Windows XP and Windows Server 2003 R2 and earlier:  InternetOpenUrl disables Gopher on ports less than 1024, except for port 70—the standard Gopher port—and port 105—typically used for Central Services Organization (CSO) name searches.

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

Note  When working in asynchronous mode (the dwFlags parameter of InternetOpen specifies INTERNET_FLAG_ASYNC), and the dwContext parameter is zero (INTERNET_NO_CALLBACK), the callback function set with InternetSetStatusCallback on the session handle will not be invoked, however, the call will still be performed in asynchronous mode

Like all other aspects of the WinINet API, this function cannot be safely called from within DllMain or the constructors and destructors of global objects.

Note  WinINet does not support server implementations. In addition, it should not be used from a service. For server implementations or services use Microsoft Windows HTTP Services (WinHTTP).
 

Note

The wininet.h header defines InternetOpenUrl as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header wininet.h
Library Wininet.lib
DLL Wininet.dll

See also

Handling Uniform Resource Locators

WinINet Functions