 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
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, InternetCanonicalizeUrlmust be invoked first.
HINTERNET InternetOpenUrl( HINTERNET hInternetSession , LPCTSTR lpszUrl , LPCTSTR lpszHeaders , DWORD dwHeadersLength , DWORD dwFlags , DWORD dwContext );
Parameters
- hInternetSession
- Handle to the current Internet session. The handle must have been returned by a previous call to InternetOpen.
- lpszUrl
- 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
- 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 lpszHeadersparameter in the HttpSendRequestfunction.)
- dwHeadersLength
- Specifies the length, in characters, of the additional headers. If this parameter is -1L and lpszHeadersis not NULL, lpszHeadersis assumed to be zero-terminated (ASCIIZ) and the length is calculated.
- dwFlags
- Specifies a bitmask of action flags. It is one of the following
values:
Value Description INTERNET_FLAG_DONT_CACHE Does not cache the data, either locally or in any gateways. Identical to the preferred value INTERNET_FLAG_NO_CACHE_WRITE. INTERNET_FLAG_EXISTING_CONNECT If possible, reuses the existing connections to the server for new requests generated by InternetOpenUrlinstead of creating a new session for each request. This flag is useful only for FTP connections, since FTP is the only protocol that typically performs multiple operations during the same session. The Win32 Internet API caches a single connection handle for each HINTERNEThandle generated by InternetOpen. INTERNET_FLAG-HYPERLINK Forces a reload if there was no Expires time and no Last-Modified time returned from the server when determining whether to reload the item from the network. INTERNET_FLAG_IGNORE_CERT_CN_INVALID Disables Win32 Internet function checking of SSL/PCT-based certificates that are returned from the server against the host name given in the request. Win32 Internet functions use a simple check against certificates by comparing for matching host names and simple wildcarding rules for HTTP requests. INTERNET_FLAG_IGNORE_CERT_DATE_INVALID Disables Win32 Internet function checking of SSL/PCT-based certificates for proper validity dates for HTTP requests. INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTPS to HTTP URLs. INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS Disables the ability of the Win32 Internet functions to detect this special type of redirect. When this flag is used, Win32 Internet functions transparently allow redirects from HTTP to HTTPS URLs. INTERNET_FLAG_KEEP_CONNECTION Uses keep-alive semantics, if available, for the connection for HTTP requests. This flag is required for Microsoft Network (MSN), NT LAN Manager (NTLM), and other types of authentication. INTERNET_FLAG_MAKE_PERSISTENT No longer supported. INTERNET_FLAG_MUST_CACHE_REQUEST Causes a temporary file to be created if the file cannot be cached. Identical to the preferred value INTERNET_FLAG_NEED_FILE. 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 for HTTP requests. INTERNET_FLAG_NO_AUTO_REDIRECT Does not automatically handle redirection for HTTP requests only. INTERNET_FLAG_NO_CACHE_WRITE Does not cache the data, either locally or in any gateways. INTERNET_FLAG_NO_COOKIES Does not automatically add cookie headers to requests, and does not automatically add returned cookies to the cookie database for HTTP requests. INTERNET_FLAG_NO_UI Disables the cookie dialog box. INTERNET_FLAG_PASSIVE Uses passive FTP semantics for FTP files and directories. INTERNET_FLAG_RAW_DATA Returns the data as a WIN32_FIND_DATAstructure when retrieving FTP directory information. If this flag is not specified or if the call was made through a CERN proxy, InternetOpenUrlreturns an HTML version of the directory. 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_READ_PREFETCH This flag is currently disabled. INTERNET_FLAG_RELOAD Gets the data from the wire even if it is locally cached. INTERNET_FLAG_RESYNCHRONIZE Reloads HTTP resources if the resource has been modified since the last time it was downloaded. All FTP resources are reloaded. INTERNET_FLAG_SECURE Requests secure transactions on the wire with SSL or PCT. This flag applies to HTTP requests only. - dwContext
- Application-defined value that is passed, along with the
returned handle, to any callback functions.
Return Values
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.
Windows CE Remarks
Windows CE supports only FTP and HTTP protocols. Only URLs beginning with FTP:, HTTP:, or secure HTTP (HTTPS:): are supported.
Windows CE supports only the following values for the dwFlagsparameter:
- INTERNET_FLAG_RAW_DATA
- INTERNET_FLAG_RELOAD
- INTERNET_FLAG_SECURE
The dwContextparameter allows for progress status callbacks to the application, but all requests are handled synchronously.
When establishing a Secure Sockets Layer (SSL) or Private Communications Technology, the following two options can be used in InternetOpenUrlto ignore invalid certificate errors:
- INTERNET_FLAG_IGNORE_CERT_CN_INVALID
- This ignores errors caused when the certificate host name of the server does not match the host name in the request.
- INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
- This ignores errors caused by an expired server certificate.
Remarks
This is a general function that an application can use to retrieve data over any of the protocols that the Win32 Internet 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 InternetOpenUrlfunction 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 InternetConnectbefore InternetOpenUrl.
Use InternetCloseHandleto 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
Runs on Versions Defined in Include Link to Windows CE OS 2.0 and later Wininet.h Wininet.lib Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also
HINTERNET, GetLastError, HttpSendRequest, InternetCloseHandle, InternetConnect, InternetFindNextFile, InternetGetLastResponseInfo, InternetOpen, InternetReadFile, WIN32_FIND_DATA