erview of the Win32 Internet Functions

The following table summarizes the Win32 Internet functions. Each function indicates any functions that it is dependent on. A dependent function can be called only after the related higher-level function is called. This is because the higher-level function returns a handle and sets up a state at the protocol level that is a prerequisite to the successful execution of the dependent function or functions.

General Win32 Internet Functions

InternetOpen Initializes the application's use of the Win32 Internet functions and creates the root HINTERNET handle

InternetConnect Opens an FTP, Gopher, or HTTP

session with a server. This function requires a handle created by InternetOpen .

InternetCloseHandle Closes any designated handle created

by a Win32 Internet function and any handles derived from that handle.

InternetQueryOption Queries the setting of an Internet

option.

InternetSetOption Sets an Internet option.

InternetSetStatusCallba ck

Sets a callback function that is called with status information. Assigns a callback function to the designated HINTERNET handle and all of the handles derived from it.

InternetStatusCallback This is a placeholder for the

application-defined status callback.

InternetConfirmZoneCros sing

InternetTimeFromSystemT ime

InternetTimeToSystemTim e

Checks for changes between secure and non-secure URLs.

Formats a date and time according to the specified RFC format (as specified in the HTTP version 1.0 specification).

Takes an HTTP time/date string and converts it to a SYSTEMTIME structure.

InternetAttemptConnect Allows an application to attempt to

connect to the Internet before issuing any requests.

InternetReadFile Dowloads data from the Internet.

This function requires a handle created by InternetOpenUrl , FtpOpenFile , GopherOpenFile , or HttpOpenRequest .

InternetSetFilePointer Sets the position for the next read

in a file. This function requires a handle created by InternetOpenUrl (on an HTTP URL only) or a handle created by HttpOpenRequest using the GET method.

InternetFindNextFile Continues file enumeration or

search. This function requires a handle created by FtpFindFirstFile or GopherFindFirstFile .

InternetQueryDataAvaila ble

InternetGetLastResponse Info

Queries the amount of data available. This function requires a handle created by FtpOpenFile , GopherOpenFile , or HttpOpenRequest .

Retrieves the text of the server's response to the FTP command. This function requires a handle created by InternetConnect .

InternetWriteFile Writes data to an open file. This

function requires a handle created by FtpOpenFile .

InternetCrackUrl Parses a URL string into components.

InternetCreateUrl Creates a URL string from

components.

InternetCanonicalizeUrl Converts a URL to a canonical form.

InternetCombineUrl Combines base and relative URLs.

InternetOpenUrl Begins retrieving a complete FTP, Gopher, or HTTP URL. This function requires a handle created by InternetOpen .

FTP Functions

FtpFindFirstFile Starts file enumeration or file

search in the current directory. This function requires a handle created by InternetConnect .

FtpGetFile Retrieves an entire file from the server. This function requires a handle created by InternetConnect .

FtpPutFile Writes an entire file to the server.

This function requires a handle created by InternetConnect .

FtpDeleteFile Deletes a file on the server. This function requires a handle created by InternetConnect .

FtpRenameFile Renames a file on the server. This function requires a handle created by InternetConnect .

FtpOpenFile Initiates access to a file on the server for either reading or writing. This function requires a handle created by InternetConnect .

FtpCreateDirectory Creates a new directory on the

server. This function requires a handle created by InternetConnect .

FtpRemoveDirectory Deletes a directory on the server.

This function requires a handle created by InternetConnect .

FtpSetCurrentDirectory Changes the client's current

directory on the server. This function requires a handle created by InternetConnect .

FtpGetCurrentDirectory Returns the client's current

directory on the server. This function requires a handle created by InternetConnect .

Gopher Functions

GopherFindFirstFile Starts enumerating a Gopher

directory listing. This function requires a handle created by

InternetConnect .

GopherOpenFile Starts retrieving a Gopher object.

This function requires a handle created by InternetConnect .

GopherCreateLocator Forms a Gopher locator for use in

other Gopher function calls.

GopherGetAttribute Retrieves attribute information on

the Gopher object. This function requires a handle created by InternetConnect .

HTTP (World Wide Web) Functions

HttpOpenRequest Opens an HTTP request handle. This

function requires a handle created by InternetConnect .

HttpAddRequestHeaders Adds HTTP request headers to the

HTTP request handle. This function requires a handle created by HttpOpenRequest .

HttpSendRequest Sends the specified request to the

HTTP server. This function requires a handle created by HttpOpenRequest .

HttpQueryInfo Queries information about an HTTP request. This function requires a handle created by HttpOpenRequest .

InternetErrorDlg Displays predefined dialog boxes for

common Internet error conditions. Requires the handle used in the call to the function HttpSendRequest .

Cookie Functions

InternetGetCookie Returns cookies for the specified

URL and all its parent URLs.

InternetSetCookie Sets a cookie on the specified URL.

Cache Functions

CommitUrlCacheEntry Caches data in the specified file in

the cache storage and associates it with the given URL.

CreateUrlCacheEntry Allocates the requested cache

storage and creates a local file name for saving the cache entry corresponding to the source name.

GetUrlCacheEntryInfo Retrieves information about a cache entry.

ReadUrlCacheEntryStream Reads the cached data from a stream

that has been opened using

RetrieveUrlCacheEntryStream .

RetrieveUrlCacheEntryFi le

RetrieveUrlCacheEntrySt ream

Retrieves a cache entry from the cache in the form of a file.

Provides the most efficient and implementation-independent way of

accessing the cache data.

SetUrlCacheEntryInfo Sets the specified members of the

INTERNET_CACHE_ENTRY_INFO

structure.

UnlockUrlCacheEntryFile Unlocks the cache entry that was

locked while the file was retrieved for use from the cache.

UnlockUrlCacheEntryStre am

Closes the stream that has been retrieved using RetrieveUrlCacheEntryStream .

ndles

DeleteUrlCacheEntry Removes the file associated with the

source name from the cache, if the file exists.

FindCloseUrlCache Closes the specified enumeration

handle.

FindFirstUrlCacheEntry Begins the enumeration of the cache.

FindNextUrlCacheEntry Retrieves the next entry in the

cache.

The handles that are created and used by the Win32 Internet functions are opaque handle types called HINTERNETS. These handles returned by the Win32 Internet function APIs are not interchangeable with the base Win32 handles, so they cannot be used with Win32 APIs such as ReadFile or CloseHandle. Similarly, base Win32 handles cannot be used with the Win32 Internet function APIs. For example, a handle returned by CreateFile cannot be passed to InternetReadFile.

If a callback function was registered for a handle, all operations on that handle can generate status indications, provided that the context value that was supplied when the handle was created was not zero. Providing a zero context value is a method to force an operation to complete synchronously, even though INTERNET_FLAG_ASYNC was specified in InternetOpen.

Status indications are mainly intended to give the application feedback as to the progress of an operation, and are mainly concerned with network operations, such as resolving a host name, connecting to a server, and receiving data. Three special-purpose status indications can be made for a handle:

• INTERNET_STATUS_REQUEST_COMPLETE is indicated when an asynchronous operation completes.

• INTERNET_STATUS_HANDLE_CREATED is indicated when the handle is initially created.

• INTERNET_STATUS_HANDLE_CLOSING is the last status indication that will be made for a handle.

The application must check the INTERNET_ASYNC_RESULTS structure to determine whether the operation succeeded or failed after receiving an

INTERNET_STATUS_REQUEST_COMPLETE indication.

The InternetCloseHandle function closes handles of type HINTERNET and all handles that descended from it in the Handle Hierarchy function. Note that handle values are recycled quickly; therefore, if a handle is closed and a new handle is generated immediately, there is a good chance that the new handle will have the same value as the handle just closed.

Handle Hierarchy

Handles returned from Win32 Internet functions are maintained in a tree hierarchy. The handle returned by the InternetOpen function is the root node. Handles returned from the InternetConnect function occupy the next level. Currently, handles that are returned by open or find functions, such as HttpOpenRequest and FtpFindFirstFile, are the leaf nodes. This structure can be used by InternetCloseHandle to close a single handle or an entire subtree.

Multithreaded Access

The Win32 Internet functions are "reentrant" in the sense that there can be multiple calls to an individual function from different threads. The functions complete any necessary synchronization. However, multiple simultaneous calls using the same Internet connection can lead to unpredictable results.

For example, if an application has used FtpOpenFile to begin downloading a file from an FTP server, and two threads simultaneously make calls to InternetReadFile, there is no guarantee which call will be completed first, or which thread will receive file data first. Applications that use multiple threads for the same Internet connection are responsible for synchronization between threads to ensure a predictable return of information.

Error Handling

The Win32 Internet functions return error information in the same way as Win32 functions. Return values tell whether the function is successful or not. For example, some Internet functions return a BOOL value that is TRUE if the function succeeded or FALSE if it failed, and others return a handle of type HINTERNET. A NULL handle indicates that the function failed, and any other value indicates that it succeeded.

If a function fails, the application can call the Win32 Internet function GetLastError to retrieve the specific error code for the failure. In addition, the FTP and Gopher protocols let servers return additional error information. For these protocols, applications can use the InternetGetLastResponseInfo function to retrieve error text.

Both GetLastError and InternetGetLastResponseInfo operate on a per- thread basis. If two threads call Internet functions at the same time, error information will be returned for each of the individual threads so that there is no conflict between the threads.

icode Support

The Win32 Internet functions do not currently provide support for Unicode. However, support will be provided in future versions.

I Flags

Many of the Win32 Internet functions accept a double-word array of flags as a parameter. The following is a brief description of the defined flags:

INTERNET_FLAG_RELOAD

Force a download of the requested file, object, or directory listing from the origin server, not from the cache. The GopherFindFirstFile , GopherOpenFile , FtpFindFirstFile , FtpGetFile , FtpOpenFile , FtpPutFile , HttpOpenRequest , and InternetOpenUrl functions utilize this flag.

INTERNET_FLAG_RAW_DATA

Return the data as a GOPHER_FIND_DATA structure when retrieving Gopher directory information, or as a WIN32_FIND_DATA structure when retrieving FTP directory information using the InternetOpenUrl API.

INTERNET_FLAG_EXISTING_CONNECT

Attempt to use an existing InternetConnect object if one exists with the same attributes required to make the request. Only the InternetOpenUrl function uses this flag.

INTERNET_FLAG_ASYNC

Make only asynchronous requests on handles descended from the handle returned from this function. Only the InternetOpen function uses this flag.

INTERNET_FLAG_PASSIVE

Use passive FTP semantics. Only InternetConnect and InternetOpenUrl use this flag. InternetConnect uses this flag for FTP requests, and InternetOpenUrl uses this flag for FTP files and directories.

INTERNET_FLAG_NO_CACHE_WRITE

Do not add the returned entity to the cache. This flag is used by GopherFindFirstFile , GopherOpenFile , FtpFindFirstFile , FtpGetFile , FtpPutFile , HttpOpenRequest , and InternetOpenUrl .

INTERNET_FLAG_MAKE_PERSISTENT

Add the returned entity to the cache as a persistent entity. This means that standard cache cleanup, consistency checking, or garbage collection cannot remove this item from the cache. This flag is used by GopherFindFirstFile , GopherOpenFile , FtpFindFirstFile , FtpGetFile , FtpOpenFile , FtpPutFile , HttpOpenRequest , and InternetOpenUrl .

INTERNET_FLAG_OFFLINE

Do 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. Only the InternetOpen function uses this flag.

INTERNET_FLAG_SECURE

Use secure transaction semantics. This translates to using Secure Sockets Layer/Private Communications Technology (SSL/PCT) and is only meaningful in HTTP requests. This flag is used by HttpOpenRequest and InternetOpenUrl , but this is made redundant if "https://" appears in the URL.

INTERNET_FLAG_KEEP_CONNECTION

Use keep-alive semantics, if available, for the connection. This flag is used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).

INTERNET_FLAG_NO_AUTO_REDIRECT

Do not automatically handle redirection in HttpSendRequest . This flag can also be used by InternetOpenUrl for HTTP requests.

INTERNET_FLAG_IGNORE_CERT_CN_INVALID

Disable 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. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).

INTERNET_FLAG_IGNORE_CERT_DATE_INVALID

Disable Win32 Internet function checking of SSL/PCT-based certificates for proper validity dates. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).

INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS

Disable 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. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).

INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP

Disable 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. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).

INTERNET_FLAG_READ_PREFETCH

Download the entity without requiring the application to initiate reads from the network. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).

INTERNET_FLAG_NO_COOKIES

Do not automatically add cookie headers to requests, and do not automatically add returned cookies to the cookie database. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).

INTERNET_FLAG_NO_AUTH

Do not attempt authentication automatically. This flag can be used by HttpOpenRequest and InternetOpenUrl (for HTTP requests).

INTERNET_FLAG_TRANSFER_ASCII

Transfer file as ASCII (FTP only). This flag can be used by FtpOpenFile , FtpGetFile , and FtpPutFile .

INTERNET_FLAG_TRANSFER_BINARY

Transfer file as binary (FTP only). This flag can be used by FtpOpenFile , FtpGetFile , and FtpPutFile .

INTERNET_FLAG_MUST_CACHE_REQUEST

Cause operation to fail if the downloaded file cannot be cached. This flag can be used by GopherFindFirstFile , GopherOpenFile , FtpFindFirstFile , FtpGetFile , FtpOpenFile , FtpPutFile , HttpOpenRequest , and InternetOpenUrl .

INTERNET_FLAG_RESYNCHRONIZE

Perform a conditional download of the file. This flag can be used by GopherFindFirstFile , GopherOpenFile , FtpFindFirstFile , FtpGetFile , FtpOpenFile , FtpPutFile , HttpOpenRequest , and InternetOpenUrl .

INTERNET_FLAG_HYPERLINK

Force 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. This flag can be used by GopherFindFirstFile , GopherOpenFile , FtpFindFirstFile , FtpGetFile , FtpOpenFile , FtpPutFile , HttpOpenRequest , and InternetOpenUrl .

ntext Values

Many of the Win32 Internet functions that create a handle can also accept an application-defined context value. This context value is associated with the handle until it is closed. For example, you can specify a context value to the HttpOpenRequest function that will be used in all callbacks made for requests against this handle. If the INTERNET_FLAG_ASYNC flag is specified, supplying a zero context value forces the request to be synchronous.

ynchronous Support

By default, the Win32 Internet functions operate synchronously. An application can request asynchronous operation by setting the INTERNET_FLAG_ASYNC flag in the call to the InternetOpen function. All future calls made against handles derived from the handle returned from

InternetOpen will be made asynchronously.

The rationale for asynchronous versus synchronous operation is to allow a single-threaded application to maximize its utilization of the CPU without having to wait for network I/O to complete. Therefore, depending on the request, the operation may complete synchronously or asynchronously. The application should check the return code. If a function returns FALSE or NULL, and GetLastError returns ERROR_IO_PENDING, the request has been made asynchronously, and the application will be called back with INTERNET_STATUS_REQUEST_COMPLETE when the function has completed.

For an application to be able to make requests asynchronously, it must set the INTERNET_FLAG_ASYNC flag in the call to InternetOpen, it must register a valid callback function, and it must supply a non-zero context value.

Persistent Caching

Win32 Internet functions have built-in caching support that is simple yet flexible. Any data that is retrieved from the network is cached on the hard disk and retrieved for subsequent requests. The caller has the option of controlling the caching on a per-request basis. In the case of HTTP, most headers received from the server are also cached. When an HTTP request is satisfied from the cache, the cached headers are also returned to the caller. This makes data download from Win32 Internet functions seamless, whether it is coming from the cache or from the wire.

Buffers and Buffer Parameters

For the APIs that return strings, there is an input lpszBuffer parameter and an lpdwBufferLength parameter. The lpszBuffer can be NULL, and lpdwBufferLength must be a valid pointer to a DWORD variable. If the input buffer pointed to by lpszBuffer is either too small to hold the output string or NULL, a failure indication will be returned by the API and GetLastError will return ERROR_INSUFFICIENT_BUFFER. The variable pointed to by lpdwBufferLength will contain a number that represents the number of bytes that are required by the function to return the requested string, which includes the NUL terminator. The application should allocate a buffer of this size, set the variable pointed to by lpdwBufferLength to this value, and resubmit the request. If the size of the buffer is sufficient to receive the requested string, the string is copied to the output buffer with a NUL terminator and a success indication is returned by the API. The variable pointed to by lpdwBufferLength will now contain the number of characters stored in the buffer, excluding the NUL terminator.