InternetOpenUrl

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function begins reading a complete FTP or HTTP Universal Resource Locator (URL). For a relative URL and a base URL separated by blank spaces, InternetCanonicalizeUrl must be invoked first.

Syntax

HINTERNET InternetOpenUrl( 
  HINTERNET hInternetSession, 
  LPCTSTR lpszUrl, 
  LPCTSTR lpszHeaders, 
  DWORD dwHeadersLength, 
  DWORD dwFlags, 
  DWORD dwContext
);

Parameters

• hInternetSession
  [in] Handle to the current Internet session. The handle must have been returned by a previous call to InternetOpen.

• lpszUrl
  [in] Long pointer to a null-terminated string that contains the URL to begin reading. Only URLs beginning with ftp:, http:, or https: are supported.

• lpszHeaders
  [in] Long pointer to a null-terminated string that contains the headers to be sent to the HTTP server. (For more information, see the description of the lpszHeaders parameter in the HttpSendRequest function.)

• dwHeadersLength
  [in] Specifies the length, in characters, of the additional headers. If this parameter is -1L and lpszHeaders is not NULL, lpszHeaders is assumed to be zero-terminated (ASCIIZ) and the length is calculated. The length of header must not include the null terminator at the end of the string. If the null character is included, the headers will not be parsed correctly.

• dwFlags
  [in] Specifies a bitmask of action flags. The following table shows the possible values.

  Value	Description
  INTERNET_FLAG_EXISTING_CONNECT	If possible, reuses the existing connections to the server for new requests generated by InternetOpenUrl instead of creating a new session for each request. This flag is useful only for FTP connections, because FTP is the only protocol that typically performs multiple operations during the same session. The WinInet function caches a single connection handle for each HINTERNET handle generated by InternetOpen.
  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 an HTML version of the directory.

• dwContext
  [in] Application-defined value that is passed, along with the returned handle, to any callback functions.

Return Value

A valid handle to the FTP or HTTP URL indicates that the connection is successfully established. NULL indicates that the connection fails. To get extended error information, call GetLastError. To determine why access to the service was denied, call InternetGetLastResponseInfo.

Remarks

Windows Embedded CE supports only FTP and HTTP protocols. Only URLs beginning with FTP:, HTTP:, or secure HTTP (HTTPS:): are supported.

The following list shows the values that Windows Embedded CE supports for the dwFlags parameter:

• INTERNET_FLAG_RAW_DATA
• INTERNET_FLAG_RELOAD
• INTERNET_FLAG_SECURE

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, two options can be used in InternetOpenUrl to ignore invalid certificate errors. The following table shows these values.

InternetOpenUrl is a general function that an application can use to retrieve data over any of the protocols that the WinInet functions support. This function is particularly useful when the application does not need to access the particulars of a protocol, but only requires the data corresponding to a URL. The 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.

Use InternetCloseHandle to close the handle returned from InternetOpenUrl. However, note that closing the handle before all the URL data has been read results in the connection being terminated.

Requirements

See Also

Reference

HttpSendRequest
InternetCloseHandle
InternetConnect
InternetFindNextFile
InternetGetLastResponseInfo
InternetOpen
InternetReadFile
WinInet Functions

Concepts

About HINTERNET Handles

Other Resources

WIN32_FIND_DATA