The following table summarizes the Win32 Internet functions. It uses indenting to show the dependencies among functions. 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 which is a prerequisite to the successful execution of the dependent function or functions.
| InternetOpen | Initializes the application's use of the Win32 Internet functions. |
| InternetOpenUrl | Begins retrieving an FTP, Gopher, or HTTP URL. |
| InternetReadFile | Reads URL data. |
| InternetSetFilePointer | Sets the position for the next read in a file. |
| InternetCloseHandle | Stops reading data from the URL. |
| InternetSetStatusCallback | Sets a callback function that is called with status information. |
| InternetQueryOption | Queries the setting of an Internet option. |
| InternetSetOption | Sets an Internet option. |
| 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. |
| InternetErrorDlg | Displays predefined dialog boxes for common Internet error conditions. |
| InternetConfirmZoneCrossing | Checks for changes between secure and non-secure URLs. |
| InternetTimeFromSystemTime | Formats a date and time according to the specified RFC format. |
| InternetAttemptConnect | Allows an applicaton to attempt to connect to the Internet before issuing any requests. |
| FTP | |
| InternetConnect | Opens an FTP session with a server and log on the user. |
| FtpFindFirstFile | Starts file enumeration in the current directory. |
| InternetFindNextFile | Continues file enumeration. |
| InternetCloseHandle | Ends directory file enumeration. |
| FtpGetFile | Retrieves an entire file from the server. |
| FtpPutFile | Writes an entire file to the server. |
| FtpDeleteFile | Deletes a file on the server. |
| FtpRenameFile | Renames a file on the server. |
| FtpOpenFile | Initiates access to a file on the server for either reading or writing. |
| InternetQueryDataAvailable | Queries the amount of data available |
| InternetReadFile | Reads data from an open file. |
| InternetWriteFile | Writes data to an open file. |
| InternetCloseHandle | Ends a read or write operation to or from a file on the server. |
| FtpCreateDirectory | Creates a new directory on the server. |
| FtpRemoveDirectory | Deletes a directory on the server. |
| FtpSetCurrentDirectory | Changes the client's current directory on the server. |
| FtpGetCurrentDirectory | Returns the client's current directory on the server. |
| InternetGetLastResponseInfo | Retrieves the text of the server's response to the FTP command. |
| InternetCloseHandle | Closes the FTP session. |
| Gopher | |
| InternetConnect | Indicates the Gopher server that the application is interested in accessing. |
| GopherFindFirstFile | Starts enumerating a Gopher directory listing. |
| InternetFindNextFile | Continues enumerating a Gopher directory listing. |
| InternetCloseHandle | Stops enumerating a Gopher directory listing. |
| GopherOpenFile | Starts retrieving a Gopher object. |
| InternetQueryDataAvailable | Queries the amount of data available. |
| InternetReadFile | Reads data from a Gopher object. |
| InternetCloseHandle | Completes the reading of a Gopher object. |
| GopherCreateLocator | Forms a Gopher locator for use in other Gopher function calls. |
| GopherGetAttribute | Retrieves attribute information on the Gopher object. |
| InternetCloseHandle | Indicates that the application is no longer interested in the server. |
| HTTP (World Wide Web) | |
| InternetConnect | Indicates the HTTP server the application is interested in accessing. |
| HttpOpenRequest | Opens an HTTP request handle. |
| HttpAddRequestHeaders | Adds HTTP request headers to the HTTP request handle. |
| HttpSendRequest | Sends the specified request to the HTTP server. |
| InternetQueryDataAvailable | Queries the amount of data available |
| InternetReadFile | Reads a block of data from an outstanding HTTP request. |
| HttpQueryInfo | Queries information about an HTTP request. |
| InternetCloseHandle | Closes an open HTTP request handle. |
| InternetCloseHandle | Indicates that the application is no longer interested in the server. |
| InternetCloseHandle | Completes the application's use of the Win32 Internet functions. |
The handles returned by the Win 32 Internet functions are not native system handles; they are only intended to control Internet functions. In other words, Win32 routines such as ReadFile and CloseHandle will not work on Internet handles. Only Internet handles can be used for the corresponding Internet functions.
Any of the handles returned from the Internet functions can be closed with the InternetCloseHandle function. If a handle is closed while there is still activity on the handle, the activity will be aborted. Note that failing to close valid handles returned from the Internet functions can result in resource leaks.
Handles returned from Win32 Internet functions are maintained in a hierarchical configuration. The first handle opened is through the InternetOpen function. A handles returned from the InternetConnect function is descended from the handle returned from InternetOpen. File and directory handles are descended from InternetConnect handles by functions such as HttpOpenRequest or FtpFindFirstFile.
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 GetLastError function 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. However, only the thread that successfully made the call will receive the error information for the function.
The Win32 Internet functions are "re-entrant" 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.
Win32 Internet functions are synchronous. Sometimes, an application can cancel an outstanding request because of user action. A request can be canceled by using the InternetCloseHandle function to close the handle. Canceling a request in this manner aborts the connection to the server and requires the application to re-establish the connection in order to communicate further.
All Win32 Internet functions using string arguments on input or output have both ANSI and Unicode versions. As with all Win32 functions, the ANSI functions have "A" as the final character of their name while the Unicode functions have "W." In Windows 95 and Windows NT, both the ANSI and Unicode versions of the functions are implemented.
Because the underlying Internet protocols pass all information in Latin 1, the Unicode versions of the Win32 Internet functions must do translations to and from ANSI. In some cases, it is not possible to convert a Unicode string to ANSI, so the Unicode functions can fail. In the cases where the translation fails, there is usually no ANSI equivalent, so the requested object could not exist.
The Win32 Internet functions do not translate sent or received content. For example, when calling a Unicode function to retrieve a file from an FTP server, the application must specify the filename in Unicode. However, the file data is returned to the application exactly as the FTP server has stored it.
Many of the Win32 Internet functions accept a double-word array of flags as a parameter. Any of the defined flags can be passed to any function that accepts flags, but typically only a subset are meaningful to a particular function. If a flag is not meaningful to a function, the function does NOT return an error value. Following is a list an brief description of the defined flags:
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.
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 the INTERNET_STATUS_REQUEST_COMPLETE when the function has completed.
For an application to be able to make requests asynchronously, it must have set the INTERNET_FLAG_ASYNC flag in the call to InternetOpen, it must have registered a valid callback function, and it must supply a non-zero context value.
WinInet has built-in caching support that is simple yet flexible. Any data that comes down the wire 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 coming down the wire 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 WinInet appear seamless, whether it is coming from the cache or from the wire.