
The general Win32 Internet functions described in this section perform basic Internet file manipulations.
DWORD InternetAttemptConnect(
IN DWORD dwReserved
);
Attempts to make a connection to the Internet.
This function allows an application to first attempt to connect before issuing any requests. A client program can use this to evoke the dialup dialog box. If the attempt fails, the application should enter offline mode.
BOOL InternetCheckConnection(
IN LPCSTR lpszUrl,
IN DWORD dwFlags,
IN DWORD dwReserved
);
Allows an application to check if a connection to the Internet can be established.
BOOL InternetCloseHandle(
IN HINTERNET hInet
);
Closes a single Internet handle.
The function terminates any pending operations on the handle and discards any outstanding data. If a thread is blocking a call to Wininet.dll, another thread in the application can call InternetCloseHandle on the Internet handle being used by the first thread to cancel the operation and unblock the first thread.
If there is a status callback registered for the handle being closed and the handle was created with a non-NULL context value, an INTERNET_STATUS_HANDLE_CLOSING callback will be made. This indication will be the last callback made from a handle and indicates that the handle is being destroyed.
If asynchronous requests are pending for the handle or any of its child handles, the handle cannot be closed immediately, but it will be invalidated. Any new requests attempted using the handle will return with an ERROR_INVALID_HANDLE notification. The asynchronous requests will complete with INTERNET_STATUS_REQUEST_COMPLETE. Applications must be prepared to receive any INTERNET_STATUS_REQUEST_COMPLETE indications on the handle before the final INTERNET_STATUS_HANDLE_CLOSING indication is made, which indicates that the handle is completely closed.
An application can call GetLastError to determine if requests are pending. If GetLastError returns ERROR_IO_PENDING, there were outstanding requests when the handle was closed.
See also FtpFindFirstFile, FtpOpenFile, GopherFindFirstFile, HttpOpenRequest, InternetConnect
DWORD InternetConfirmZoneCrossing(
IN HWND hWnd,
IN LPSTR szUrlPrev,
IN LPSTR szUrlNew,
IN BOOL bPost
);
Checks for changes between secure and nonsecure URLs. When a change occurs in security between two URLs, an application should allow the user to acknowledge this change, typically by displaying a dialog box.
| ERROR_SUCCESS | The user confirmed that it was okay to continue or there was no user input needed. |
| ERROR_CANCELLED | The user canceled the request. |
| ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to carry out the request. |
HINTERNET InternetConnect(
IN HINTERNET hInternetSession,
IN LPCSTR lpszServerName,
IN INTERNET_PORT nServerPort,
IN LPCSTR lpszUsername,
IN LPCSTR lpszPassword,
IN DWORD dwService,
IN DWORD dwFlags,
IN DWORD dwContext
);
Opens an FTP, Gopher, or HTTP session for a given site.
| INTERNET_DEFAULT_FTP_PORT | Uses the default port for FTP servers (port 21). |
| INTERNET_DEFAULT_GOPHER_PORT | Uses the default port for Gopher servers (port 70). |
| INTERNET_DEFAULT_HTTP_PORT | Uses the default port for HTTP servers (port 80). |
| INTERNET_DEFAULT_HTTPS_PORT | Uses the default port for HTTPS servers (port 443). |
| INTERNET_DEFAULT_SOCKS_PORT | Uses the default port for SOCKS firewall servers (port 1080). |
| INTERNET_INVALID_PORT_NUMBER | Uses the default port for the service specified by dwService. |
| lpszUsername | lpszPassword | User name sent to FTP server | Password sent to FTP server |
| NULL | NULL | "anonymous" | User's e-mail name |
| Non-NULL string | NULL | lpszUsername | "" |
| NULL | Non-NULL string | ERROR | ERROR |
| Non-NULL string | Non-NULL string | lpszUsername | lpszPassword |
| INTERNET_SERVICE_FTP | FTP service. |
| INTERNET_SERVICE_GOPHER | Gopher service. |
| INTERNET_SERVICE_HTTP | HTTP service. |
The InternetConnect function is required before communicating with any Internet service.
Having a connect function for all protocols, even those that do not use persistent connections, lets an application communicate common information about several requests by using a single function call. In addition, this allows for future versions of Internet protocols that do not require a connection to be established for every client request.
For FTP sites, InternetConnect actually establishes a connection with the server; for others, such as Gopher, the actual connection is not established until the application requests a specific transaction.
For maximum efficiency, applications using the Gopher and HTTP protocols should try to minimize calls to InternetConnect and avoid calling this function for every transaction requested by the user. One way to accomplish this is to keep a small cache of handles returned from InternetConnect; when the user makes a request to a previously accessed server, that session handle is still available.
An application that needs to display multiline text information sent by an FTP server can use InternetGetLastResponseInfo to retrieve the text.
For FTP connections, if lpszUsername is NULL, InternetConnect sends the string "anonymous" as the user name. If lpszPassword is NULL, InternetConnect attempts to use the user's e-mail name as the password.
To close the handle returned from InternetConnect, the application should call InternetCloseHandle. This function disconnects the client from the server and frees all resources associated with the connection.
DWORD InternetErrorDlg(
IN HWND hWnd,
IN OUT HINTERNET hInternet,
IN DWORD dwError,
IN DWORD dwFlags,
IN OUT LPVOID *lppvData
);
Displays a dialog box for the error that is passed to InternetErrorDlg, if an appropriate dialog box exists. If the FLAGS_ERROR_UI_FILTER_FOR_ERRORS flag is used, the function also checks the headers for any hidden errors and displays a dialog box if needed.
Authentication errors are hidden, since the call to HttpSendRequest will complete successfully, but the status code would indicate that the proxy or server requires authentication. The FLAGS_ERROR_UI_FILTER_FOR_ERRORS flag causes the function to search the headers for status codes that indicate that user input is needed.
BOOL InternetFindNextFile(
IN HINTERNET hFind,
OUT LPVOID lpvFindData
);
Continues a file search started as a result of a previous call to FtpFindFirstFile or GopherFindFirstFile.
BOOL InternetGetLastResponseInfo(
OUT LPDWORD lpdwError,
OUT LPSTR lpszBuffer,
IN OUT LPDWORD lpdwBufferLength
);
Retrieves the last Win32 Internet function error description or server response on the thread calling this function.
The FTP and Gopher protocols can return additional text information along with most errors. This extended error information can be retrieved by using the InternetGetLastResponseInfo function whenever GetLastError returns ERROR_INTERNET_EXTENDED_ERROR (occurring after an unsuccessful function call).
The buffer pointed to by lpszBuffer must be large enough to hold both the error string and a zero terminator at the end of the string. However, note that the value returned in lpdwBufferLength does not include the terminating zero.
InternetGetLastResponseInfo can be called multiple times until another Win32 Internet function is called on this thread. When another function is called, the internal buffer that is storing the last response information is cleared.
BOOL InternetLockRequestFile (
IN HINTERNET hInternet,
OUT HANDLE *lphLockReqHandle
);
Allows the user to place a lock on the file that is being used.
If the HINTERNET handle passed to hInternet was created using INTERNET_FLAG_NO_CACHE_WRITE or INTERNET_FLAG_DONT_CACHE, the function creates a temporary file with the extension TMP, unless it is an HTTPS resource. If the handle was created using INTERNET_FLAG_NO_CACHE_WRITE or INTERNET_FLAG_DONT_CACHE and it is accessing an HTTPS resource, InternetLockRequestFile fails.
See also InternetUnlockRequestFile
HINTERNET InternetOpen(
IN LPCSTR lpszAgent,
IN DWORD dwAccessType,
IN LPCSTR lpszProxyName,
IN LPCSTR lpszProxyBypass,
IN DWORD dwFlags
);
Initializes an application's use of the Win32 Internet functions.
InternetOpen is the first Win32 Internet function called by an application. It tells the Internet DLL to initialize internal data structures and prepare for future calls from the application. When the application finishes using the Internet functions, it should call InternetCloseHandle to free the handle and any associated resources.
The application can make any number of calls to InternetOpen, although a single call is normally sufficient. The application might need to have separate behaviors defined for each InternetOpen instance, such as different proxy servers configured for each.
BOOL InternetQueryDataAvailable(
IN HINTERNET hFile,
OUT LPDWORD lpdwNumberOfBytesAvailable,
IN DWORD dwFlags,
IN DWORD dwContext
);
Queries the amount of data available.
This function returns the number of bytes of data that are available to be read immediately by a subsequent call to InternetReadFile. If there is currently no data available and the end of the file has not been reached, the request waits until data becomes available. The amount of data remaining will not be recalculated until all available data indicated by the call to InternetQueryDataAvailable is read.
For HINTERNET handles created by HttpOpenRequest and sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the handle before InternetQueryDataAvailable can be used.
BOOL InternetQueryOption(
IN HINTERNET hInternet,
IN DWORD dwOption,
OUT LPVOID lpBuffer,
IN OUT LPDWORD lpdwBufferLength
);
Queries an Internet option on the specified handle.
See also FtpGetFile, FtpPutFile, InternetConnect, InternetOpen, InternetSetOption
BOOL InternetReadFile(
IN HINTERNET hFile,
IN LPVOID lpBuffer,
IN DWORD dwNumberOfBytesToRead,
OUT LPDWORD lpNumberOfBytesRead
);
Reads data from a handle opened by the InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest function.
If the return value is TRUE and the number of bytes read is zero, the transfer has been completed and there are no more bytes to read on the handle. This is analogous to reaching EOF in a local file. Call InternetCloseHandle to free the connection to the server.
The buffer pointed to by lpBuffer is not always filled by calls to InternetReadFile (sufficient data might not have arrived from the server). When reading HTML data, for the first read posted, the buffer must be large enough to hold the HTML headers. When reading HTML-encoded directory entries, the buffer must be large enough to hold at least one complete entry.
When the item being read is also being cached by a Win32 Internet function, the application must ensure that a read is made for end-of-file so the cache file is committed correctly.
This function always fulfills the user's request. If more data is requested than is available, the function waits until enough data to complete the request is available. The only time that less data is returned than requested is when the end of the file has been reached.
This function can also be used to retrieve FTP and Gopher directory listings as an HTML document on a handle opened by InternetOpenUrl. The INTERNET_FLAG_RAW_DATA value must not have been specified in the call to InternetOpenUrl.
If the HINTERNET handle stored in hFile was created by HttpOpenRequest and sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the handle before InternetReadFile is used.
InternetReadFileEx(
IN HINTERNET hFile,
OUT LPINTERNET_BUFFERS lpBuffersOut,
IN DWORD dwFlags,
IN DWORD dwContext
);
Reads data from a handle opened by the InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest function.
| IRF_ASYNC | Identical to WININET_API_FLAG_ASYNC. |
| IRF_SYNC | Identical to WININET_API_FLAG_SYNC. |
| IRF_USE_CONTEXT | Identical to WININET_API_FLAG_USE_CONTEXT. |
| IRF_NO_WAIT | Do not wait for data. If there is data available, the function returns either the amount of data requested or the amount of data available (whichever is smaller). |
DWORD InternetSetFilePointer(
IN HINTERNET hFile,
IN LONG lDistanceToMove,
IN PVOID pReserved,
IN DWORD dwMoveMethod,
IN DWORD dwContext
);
Sets a file position for InternetReadFile. This is a synchronous call; however, subsequent calls to InternetReadFile may block or return pending if the data is not available from the cache and the server does not support random access.
| FILE_BEGIN | The starting point is zero or the beginning of the file. If FILE_BEGIN is specified, lDistanceToMove is interpreted as an unsigned location for the new file pointer. |
| FILE_CURRENT | The current value of the file pointer is the starting point. |
| FILE_END | The current end-of-file position is the starting point. This method fails if the content length is unknown. |
This function cannot be used once the end of file has been reached by InternetReadFile.
For HINTERNET handles created by HttpOpenRequest and sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the handle before InternetSetFilePointer is used.
InternetSetFilePointer cannot be used reliably if the content length is unknown and with chunked transfers.
BOOL InternetSetOption(
IN HINTERNET hInternet,
IN DWORD dwOption,
IN LPVOID lpBuffer,
IN DWORD dwBufferLength
);
Sets an Internet option.
See also FtpGetFile, FtpPutFile, InternetConnect, InternetOpen, InternetQueryOption
Not currently implemented.
INTERNET_STATUS_CALLBACK InternetSetStatusCallback(
IN HINTERNET hInternet,
IN INTERNET_STATUS_CALLBACK lpfnInternetCallback
);
Sets up a callback function that Win32 Internet functions can call as progress is made during an operation.
Both synchronous and asynchronous functions use the callback function to indicate the progress of the request, such as resolving a name, connecting to a server, and so on. The callback function is required for an asynchronous operation. The asynchronous request will call back to the application with INTERNET_STATUS_REQUEST_COMPLETE to indicate the request has been completed.
A callback function can be set on any handle, and is inherited by derived handles. A callback function can be changed using InternetSetStatusCallback, providing there are no pending requests that need to use the previous callback value. Note, however, that changing the callback function on a handle does not change the callbacks on derived handles, such as that returned by InternetConnect. You must change the callback function at each level.
Many of the Win32 Internet functions perform several operations on the network. Each operation can take time to complete, and each can fail.
It is sometimes desirable to display status information during a long-term operation. You can display status information by setting up an Internet status callback function that cannot be removed as long as any callbacks or any asynchronous functions are pending.
After initiating InternetSetStatusCallback, the callback function can be accessed from within any Win32 Internet function for monitoring time-intensive network operations.
BOOL InternetTimeFromSystemTime(
IN CONST SYSTEMTIME *pst,
IN DWORD dwRFC,
OUT LPSTR lpszTime,
IN DWORD cbTime
);
Formats a date and time according to the specified RFC format (as specified in the HTTP version 1.0 specification).
BOOL InternetTimeToSystemTime(
IN LPCSTR lpszTime,
OUT SYSTEMTIME *pst,
IN DWORD dwReserved
);
Takes an HTTP time/date string and converts it to a SYSTEMTIME structure.
BOOL InternetUnlockRequestFile (
IN HANDLE hLockHandle
);
Unlocks a file that was locked using InternetLockRequestFile.
BOOL InternetWriteFile(
IN HINTERNET hFile,
IN LPCVOID lpBuffer,
IN DWORD dwNumberOfBytesToWrite,
OUT LPDWORD lpdwNumberOfBytesWritten
);
Writes data to an open Internet file.
When the application is sending data, it must call InternetCloseHandle to end the data transfer.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.