Brought to you by the
RFC INDEX PAGE
Google
 


Microsoft Win32 Internet Programmer's Reference


General Win32 Internet Functions

The general Win32 Internet functions perform basic Internet file manipulations.

InternetAttemptConnect

DWORD InternetAttemptConnect(
    DWORD dwReserved
);

Attempts to make a connection to the Internet. This function allows an application to first attempt to connect before issuing any requests. If the connection fails, the application can enter off-line mode.

dwReserved
Reserved; must be zero.

InternetCanonicalizeUrl

BOOL InternetCanonicalizeUrl(
    IN LPCTSTR lpszUrl,
    OUT LPTSTR lpszBuffer,
    IN OUT LPDWORD lpdwBufferLength,
    IN DWORD dwFlags
);

Converts a URL to a canonical form, which includes converting unsafe characters into escape sequences.

lpszUrl
Address of the input URL to canonicalize.
lpszBuffer
Address of the buffer that receives the resulting canonicalized URL.
lpdwBufferLength
Length, in bytes, of the lpszBuffer buffer. If the function succeeds, this parameter receives the length of the lpszBuffer buffer--the length does not include the terminating null. If the function fails, this parameter receives the required length, in bytes, of the lpszBuffer buffer--the required length includes the terminating null.
dwFlags
Flags that control canonicalization. Can be one of these values:
Value Meaning
ICU_DECODE Convert %XX escape sequences to characters.
ICU_NO_ENCODE Do not convert unsafe characters to escape sequence.
ICU_NO_META Do not remove meta sequences (such as "." and "..") from the URL.
ICU_ENCODE_SPACES_ONLY Encode spaces only.
ICU_BROWSER_MODE Do not encode or decode characters after #' or '?', and do not remove trailing white space after '?'. If this value is not specified, the entire URL is encoded and trailing white space is removed.

If no flags are specified, the function converts all unsafe characters and meta sequences (such as \.,\ .., and \...) to escape sequences.

InternetCanonicalizeUrl always encodes by default, even if the ICU_DECODE flag has been specified. To decode without re-encoding, use ICU_DECODE | ICU_NO_ENCODE. If the ICU_DECODE flag is used without ICU_NO_ENCODE, the URL is decoded before being parsed; unsafe characters then are re-encoded after parsing. This function will handle arbitrary protocol schemes, but to do so it must make inferences from the unsafe character set.

InternetCloseHandle

BOOL InternetCloseHandle(
    IN HINTERNET hInet
);

Closes a single Internet handle or a subtree of Internet handles.

hInet
Valid Internet handle to be closed.

This function can be used to close any Internet handle or subtree of handles of the type HINTERNET and free any associated resources. 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.

InternetCloseHandle should be used to close the handle returned from InternetOpen when the application has finished using the Internet DLL.

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, InternetOpen

InternetCombineUrl

BOOL InternetCombineUrl(
    IN LPCTSTR lpszBaseUrl,
    IN LPCTSTR lpszRelativeUrl,
    OUT LPTSTR lpszBuffer,
    IN OUT LPDWORD lpdwBufferLength,
    IN DWORD dwFlags
);

Combines a base and relative URL into a single URL. The resultant URL will be canonicalized (see InternetCanonicalizeUrl).

lpszBaseUrl
Address of the base URL to be combined.
lpszRelativeUrl
Address of the relative URL to be combined.
lpszBuffer
Address of a buffer that receives the resulting URL.
lpdwBufferLength
Size, in bytes, of the lpszBuffer buffer. If the function succeeds, this parameter receives the length, in characters, of the resultant combined URL--the length does not include the null terminator. If the function fails, this parameter receives the length, in bytes, of the required buffer--the length includes the null terminator.
dwFlags
Flags controlling the operation of the function. For a description of the flags, see InternetCanonicalizeUrl.

InternetConnect

HINTERNET InternetConnect(
    IN HINTERNET hInternetSession,
    IN LPCTSTR lpszServerName,
    IN INTERNET_PORT nServerPort,
    IN LPCTSTR lpszUsername OPTIONAL,
    IN LPCTSTR lpszPassword OPTIONAL,
    IN DWORD dwService,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Opens an FTP, Gopher, or HTTP session for a given site.

hInternetSession
Handle of the current Internet session. The handle must have been returned by a previous call to InternetOpen.
lpszServerName
Address of a null-terminated string that contains the host name of an Internet server. Alternately, the string can contain the IP number of the site in ASCII dotted-decimal format (for example, 11.0.1.45).
nServerPort
Number of the TCP/IP port on the server to connect to. Can be one of the values in the following list. If this parameter is set to INTERNET_INVALID_PORT_NUMBER, the function uses the default port for the specified service. These values do not cause the function to use this protocol. The value sets the port to be used. A flag must be used to set the service.
Value Meaning
INTERNET_DEFAULT_FTP_PORT Use the default port for FTP servers (port 21).
INTERNET_DEFAULT_GOPHER_PORT Use the default port for Gopher servers (port 70).
INTERNET_DEFAULT_HTTP_PORT Use the default port for HTTP servers (port 80).
INTERNET_DEFAULT_HTTPS_PORT Use the default port for HTTPS servers (port 443).
lpszUsername
Address of a null-terminated string that contains the name of the user to log on. If this parameter is NULL, the function uses an appropriate default, except for HTTP. A NULL parameter in HTTP causes the server to return an error. For the FTP protocol, the default is anonymous.
lpszPassword
Address of a null-terminated string that contains the password to use to log on. If both lpszPassword and lpszUsername are NULL, the function uses the default anonymous password. In the case of FTP, the default anonymous password is the user's e-mail name. If lpszPassword is NULL, but lpszUsername is not NULL, the function uses a blank password. The following table describes the behavior for the four possible settings of lpszUsername and lpszPassword:
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
dwService
Type of service to access. Can be one of these values:
Value Meaning
INTERNET_SERVICE_FTP FTP service.
INTERNET_SERVICE_GOPHER Gopher service.
INTERNET_SERVICE_HTTP HTTP service.
dwFlags
Flags specific to the service used. Can be one of these values:
If dwService is: dwFlags supported
INTERNET_SERVICE_FTP INTERNET_CONNECT_FLAG_PASSIVE (Use passive mode in all data connections for this FTP session.)
dwContext
An application-defined value that is used to identify the application context for the returned handle in callbacks.

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 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.

See also InternetCloseHandle, InternetOpen

InternetConfirmZoneCrossing

DWORD InternetConfirmZoneCrossing(
    IN HWND hWnd,
    IN LPSTR szUrlPrev,
    IN LPSTR szUrlNew,
    IN BOOL bPost
); 

Checks for changes between secure and non-secure 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.

hWnd
Handle of the parent window for any needed dialog box.
szUrlPrev
URL that was viewed before the current request was made.
szUrlNew
New URL that the user has requested to view.
bPost
TRUE if a post is being made in this request. This flag is ignored in this release.

InternetCrackUrl

BOOL InternetCrackUrl(
    IN LPCSTR lpszUrl,
    IN DWORD dwUrlLength,
    IN DWORD dwFlags,
    IN OUT LPURL_COMPONENTS lpUrlComponents
);

Cracks a URL into its component parts.

lpszUrl
Address of a string that contains the canonical URL to crack. If you are not sure that the URL is canonical, use the InternetCanonicalizeUrl function to canonicalize the URL before passing it to InternetCrackUrl.
dwUrlLength
Length of the lpszUrl string, or zero if lpszUrl is an ASCIIZ string.
dwFlags
Flags controlling the operation. Can be one of these values:
Value Meaning
ICU_ESCAPE Converts unsafe characters in the URL-path component to escape sequences.
ICU_DECODE Converts encoded characters back to their normal form. This can be used only if the user provides buffers to copy the components into.
ICU_USERNAME Not currently implemented.
lpUrlComponents
Address of a URL_COMPONENTS structure that receives the URL components.

The required components are indicated by members of the URL_COMPONENTS structure. Each component has a pointer to the value, and has a member that stores the length of the stored value. If both the value and the length for a component are equal to zero, that component is not returned. If the pointer to the value of the component is NULL, the address of the corresponding component in the lpszUrl string is stored in the pointer, and the length of the component is stored in the length member. Otherwise, the pointer contains the address of the user-supplied buffer where the component is copied, and the length member is updated with the length of the copied component, minus 1 for the trailing string terminator.

See also FtpOpenFile, InternetCloseHandle, InternetFindNextFile, InternetSetStatusCallback

InternetCreateUrl

BOOL InternetCreateUrl( 
    IN LPURL_COMPONENTS lpUrlComponents,
    IN DWORD dwFlags,
    OUT LPSTR lpszUrl,
    IN OUT LPDWORD lpdwUrlLength
);

Creates a URL from its component parts.

lpUrlComponents
Address of a URL_COMPONENTS structure that contains the components from which to create the URL.
dwFlags
Flags that control the operation of this function. Can be a combination of these values:
Value Meaning
ICU_ESCAPE Convert unsafe characters in the URL-path component to escape sequences.
ICU_USERNAME When adding the user name, use the name that was specified at login time.
lpszUrl
Address of a buffer that receives the URL.
lpdwUrlLength
Length, in bytes, of the lpszUrl buffer. When the function returns, this parameter receives the length, in bytes, of the URL string, minus 1 for the terminating character. If GetLastError returns ERROR_INSUFFICIENT_BUFFER, this parameter receives the number of bytes required to hold the created URL.

InternetErrorDlg

DWORD InternetErrorDlg(
    IN HWND hWnd,
    IN OUT HINTERNET hInternet,
    IN DWORD dwError,
    IN DWORD dwFlags,
    IN OUT LPVOID *lppvData
);
 

Displays a dialog box that explains why an error occurred with an HttpSendRequest Win32 Internet function. An application can call this function for several different error codes, and can do bookkeeping based on the user's response to the dialog box.

hWnd
Handle of the parent window for any needed dialog box. This parameter can be NULL if no dialog box is needed.
hInternet
Handle of the Internet connection used in the call to HttpSendRequest.
dwError
Error value for which to display a dialog box. Can be one of these values:
ERROR_INTERNET_HTTP_TO_HTTPS_ON_REDIR
Notifies the user of the zone crossing to and from a secure site.
ERROR_INTERNET_INCORRECT_PASSWORD
Displays a dialog box for obtaining the user's name and password. (On Windows 95, the function attempts to use the network caching user interface and disk cache.)
ERROR_INTERNET_INVALID_CA
Notifies the user that the Win32 Internet function does not have a certificate for this SSL site.
ERROR_INTERNET_POST_IS_NON_SECURE
Displays a warning about posting data to the server through a non-secure connection.
ERROR_INTERNET_SEC_CERT_CN_INVALID
Displays an Invalid SSL Common Name dialog box, and lets the user view the incorrect certificate. Also allows the user to select a certificate in response to a server request.
ERROR_INTERNET_SEC_CERT_DATE_INVALID
Tells the user that the SSL certificate has expired.
dwFlags
Action flags. Can be a combination of these values:
FLAGS_ERROR_UI_FLAGS_CHANGE_OPTIONS
If the function succeeds, store the results of the dialog box in the Internet handle.
FLAGS_ERROR_UI_FLAGS_GENERATE_DATA
Query the Internet handle for needed information. The function constructs the appropriate data structure for the error. (For example, for Cert CN failures, the function will grab the certificate.)
FLAGS_ERROR_UI_FILTER_FOR_ERRORS
Scan the returned headers for errors. Call after every HttpSendRequest. The function detects any hidden errors, such as an authentication error.
lppvData
Address of a yet-to-be-defined structure. The structure may be different for each error that needs to be handled

InternetFindNextFile

BOOL InternetFindNextFile(
    IN HINTERNET hFind,
    OUT LPVOID lpvFindData
);

Continues a file search started as a result of a previous call to FtpFindFirstFile or GopherFindFirstFile.

hFind
Valid handle returned from either FtpFindFirstFile or GopherFindFirstFile.
lpvFindData
Address of the buffer that receives information about the found file or directory. The format of the information placed in the buffer depends on the protocol in use. The FTP protocol returns a WIN32_FIND_DATA structure, and the Gopher protocol returns a GOPHER_FIND_DATA structure.

See also FtpFindFirstFile, GopherFindFirstFile

InternetGetLastResponseInfo

BOOL InternetGetLastResponseInfo(
    OUT LPDWORD lpdwError,
    OUT LPTSTR lpszBuffer OPTIONAL,
    IN OUT LPDWORD lpdwBufferLength
);

Retrieves the last Win32 Internet function error description or server response on the thread calling this API.

lpdwError
Address of a variable that receives an error code pertaining to the operation that failed.
lpszBuffer
Address of a buffer that receives the error text.
lpdwBufferLength
Size of the lpszBuffer buffer. When the function returns, this parameter contains the size of the string written to the buffer.

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 API is called on this thread. When another API is called, the internal buffer that is storing the last response information is cleared.

InternetOpen

HINTERNET InternetOpen(
    IN LPCTSTR lpszAgent,
    IN DWORD dwAccessType,
    IN LPCTSTR lpszProxyName OPTIONAL,
    IN LPCSTR lpszProxyBypass OPTIONAL,
    IN DWORD dwFlags
);

Initializes an application's use of the Win32 Internet functions.

lpszAgent
Address of a string that contains the name of the application or entity calling the Internet functions (for example, Microsoft Internet Explorer). This name is used as the user agent in the HTTP protocol.
dwAccessType
Type of access required. Can be one of these values:
INTERNET_OPEN_TYPE_DIRECT
Resolve all host names locally.
INTERNET_OPEN_TYPE_PROXY
Pass requests to the proxy unless a proxy bypass list is supplied and the name to be resolved bypasses the proxy. In this case, the function proceeds as for INTERNET_OPEN_TYPE_DIRECT.
INTERNET_OPEN_TYPE_PRECONFIG
Retrieve the proxy or direct configuration from the registry.
lpszProxyName
Address of a string that contains the name of the proxy server (or servers) to use if proxy access was specified. If this parameter is NULL, the function reads proxy information from the registry. For more information about this parameter, see the comments below.
lpszProxyBypass
Address of an optional list of host names or IP addresses, or both, that are known locally. Requests to these names are not routed through the proxy. The list can contain wildcards, such as "157.55.* *int*", meaning any IP address starting with 157.55, or any name containing the substring "int", will bypass the proxy.

If this parameter specifies the "<local>" macro as the only entry, the function bypasses any host name that does not contain a period. For example, "www.microsoft.com" would be routed to the proxy, whereas "internet" would not.

If this parameter is NULL, the function reads the bypass list from the registry.

dwFlags
Flag that indicates various options affecting the behavior of the function. Can be a combination of these values:
INTERNET_FLAG_OFFLINE
Satisfy download operations on this handle through the persistent cache only. If the item does not exist in the cache, the function returns an appropriate error code.
INTERNET_FLAG_ASYNC
Future operations on this handle may fail with ERROR_IO_PENDING. A status callback will be made with INTERNET_STATUS_REQUEST_COMPLETE. This callback will be on a thread other than the one for the original request. A status callback routine must be registered or the functions will be completed synchronously.

This function 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.

If dwFlags includes INTERNET_FLAG_ASYNC, all handles derived from this handle will have asynchronous behavior as long as a status callback routine is registered. For a function to be completed synchronously, dwContext must be set to zero for that call.

By default, the function assumes that the proxy specified by lpszProxyName is a CERN proxy. For example, "proxy" defaults to a CERN proxy called "proxy" that listens at port 80 (decimal). An application can specify more than one proxy, including different proxies for the different protocols. For example, if you specify "ftp=ftp://ftp-gw gopher=http://jericho:99 proxy", FTP requests are made through the FTP proxy "ftp-gw", which listens at port 21 (default for FTP), and Gopher requests are made through a CERN proxy called "jericho", which listens at port 99. All other requests (for example, HTTP requests) are made through the CERN proxy called "proxy", which listens at port 80. Note that if the application is only using FTP, for example, it would not need to specify "ftp=ftp://ftp-gw:21". It could specify just "ftp-gw". An application must specify the protocol names only if it will be using more than one protocol per handle returned by InternetOpen.

The application can make any number of calls to InternetOpen, although a single call is normally sufficient. The application may need to have separate behaviors defined for each InternetOpen instance, such as different proxy servers configured for each.

See also InternetCloseHandle

InternetOpenUrl

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

Begins reading a complete FTP, Gopher, or HTTP Universal Resource Locator (URL). Use InternetCanonicalizeUrl first if the URL being used contains a relative URL and a base URL separated by blank spaces.

hInternetSession
Handle of the current Internet session. The handle must have been returned by a previous call to InternetOpen.
lpszUrl
Address of a string that contains the URL to begin reading. Only URLs beginning with ftp:, gopher:, http:, or https: are supported.
lpszHeaders
Address of a string that contains the headers to be sent to the HTTP server. (For more information, see the description of the lpszHeaders parameter to HttpSendRequest.)
dwHeadersLength
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.
dwFlags
Action flags. Can be one of these values:
INTERNET_FLAG_RELOAD
Get the data from the wire even if it is locally cached.
INTERNET_FLAG_DONT_CACHE
Do not cache the data, either locally or in any gateways.
INTERNET_FLAG_RAW_DATA
Return raw data (WIN32_FIND_DATA structures for FTP, and GOPHER_FIND_DATA structures for Gopher). If this flag is not specified, InternetOpenUrl returns HTML formatted for directories.
INTERNET_FLAG_SECURE
Request secure transactions on the wire with Secure Sockets Layer or PCT. This flag applies to HTTP requests only.
INTERNET_FLAG_EXISTING_CONNECT
If possible, reuse the existing connections to the server for new requests generated by InternetOpenUrl instead of creating a new session for each request.
dwContext
An application-defined value that is passed, along with the returned handle, to any callback functions.

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 InternetOpenUrl 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 to retrieve the URL data. It is not necessary to call InternetConnect before InternetOpenUrl.

InternetOpenUrl disables Gopher on ports less than 1024, except for port 70 (the standard Gopher port) and port 105 (typically used for Central Services Organization [CSO] name searches).

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.

See also HttpSendRequest, InternetCloseHandle, InternetOpen, InternetReadFile

InternetQueryDataAvailable

BOOL InternetQueryDataAvailable( 
    IN HINTERNET hFile,
    OUT LPDWORD lpdwNumberOfBytesAvailable,
    IN DWORD dwFlags,
    IN DWORD dwContext
);

Queries the amount of data available.

hFile
Valid Internet file handle, as returned by FtpOpenFile, GopherOpenFile, or HttpOpenRequest.
lpdwNumberOfBytesAvailable
Address of a variable that receives the number of available bytes.
dwFlags
Reserved; must be zero.
dwContext
Reserved; must be zero.

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 of the available data indicated by the call to InternetQueryDataAvailable is read.

See also FtpFindFirstFile, GopherFindFirstFile

InternetQueryOption

BOOL InternetQueryOption(
    IN HINTERNET hInternet OPTIONAL,
    IN DWORD dwOption,
    OUT LPVOID lpBuffer OPTIONAL,
    IN OUT LPDWORD lpdwBufferLength
);

Queries an Internet option on the specified handle.

hInternet
Internet handle on which to query information.
dwOption
Internet option to query. Can be one of these values:
INTERNET_OPTION_CALLBACK
Returns the address of the callback function defined for this handle.
INTERNET_OPTION_CONNECT_TIMEOUT
Returns the time-out value in milliseconds to use for Internet connection requests. If a connection request takes longer than this time-out value, the request is canceled. The default time-out value is infinite.
INTERNET_OPTION_CONNECT_RETRIES
Returns the retry count to use for Internet connection requests. If a connection attempt still fails after the specified number of tries, the request is canceled. The default is five retries.
INTERNET_OPTION_CONNECT_BACKOFF
Returns the delay value, in milliseconds, to wait between connection retries. (This flag is currently not implemented.)
INTERNET_OPTION_CONTROL_SEND_TIMEOUT
Returns the time-out value, in milliseconds, to use for non-data (control) Internet send requests. If a non-data send request takes longer than this time-out, the request is canceled. The default time-out is infinite. Currently, this value has meaning only for FTP sessions.
INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
Returns the time-out value, in milliseconds, to use for non-data (control) Internet receive requests. If a non-data receive request takes longer than this time-out value, the request is canceled. The default time-out is infinite. Currently, this value has meaning only for FTP sessions.
INTERNET_OPTION_DATA_SEND_TIMEOUT
Returns the time-out value, in milliseconds, to use for Internet data send requests. If a data send request takes longer than this time-out value, the request is canceled. The default time-out value is infinite.
INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
Returns the time-out value, in milliseconds, to use for Internet data receive requests. If a data receive request takes longer than this time-out value, the request is canceled. The default time-out value is infinite.
INTERNET_OPTION_HANDLE_TYPE
Returns the type of the Internet handle passed in. Possible return values include:
INTERNET_HANDLE_TYPE_INTERNET
INTERNET_HANDLE_TYPE_CONNECT_FTP
INTERNET_HANDLE_TYPE_CONNECT_GOPHER
INTERNET_HANDLE_TYPE_CONNECT_HTTP
INTERNET_HANDLE_TYPE_FTP_FIND
INTERNET_HANDLE_TYPE_FTP_FIND_HTML
INTERNET_HANDLE_TYPE_FTP_FILE
INTERNET_HANDLE_TYPE_FTP_FILE_HTML
INTERNET_HANDLE_TYPE_GOPHER_FIND
INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML
INTERNET_HANDLE_TYPE_GOPHER_FILE
INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML
INTERNET_HANDLE_TYPE_HTTP_REQUEST
INTERNET_OPTION_CONTEXT_VALUE
Returns the context value associated with this Internet handle.
INTERNET_OPTION_READ_BUFFER_SIZE
Returns the size of the read buffer (for example, the buffer used by FtpGetFile).
INTERNET_OPTION_WRITE_BUFFER_SIZE
Returns the size of the write buffer (for example, the buffer used by FtpPutFile).
INTERNET_OPTION_ASYNC_PRIORITY
Returns the priority of this download if it is an asynchronous download.
INTERNET_OPTION_PARENT_HANDLE
Returns the parent handle of this handle.
INTERNET_OPTION_KEEP_CONNECTION
Returns an indication whether this handle uses persistent connections. Can be one of these values:
INTERNET_KEEP_ALIVE_UNKNOWN
INTERNET_KEEP_ALIVE_ENABLED
INTERNET_KEEP_ALIVE_DISABLED
INTERNET_OPTION_USERNAME
Returns the user name associated with a handle returned by InternetConnect.
INTERNET_OPTION_PASSWORD
Returns the password associated with the handle returned by InternetConnect.
INTERNET_OPTION_REQUEST_FLAGS
Returns special status flags about the current download in progress. The only flag that is returned at this time is INTERNET_REQFLAG_FROM_CACHE. This is the way for the caller to find out whether a request is being satisfied from the cache.
INTERNET_OPTION_EXTENDED_ERROR
Returns the Windows Sockets error code that was mapped to the ERROR_INTERNET_ error codes last returned in this thread context.
INTERNET_OPTION_SECURITY_CERTIFICATE_STRUCT
Returns the certificate for an SSL/PCT server into the INTERNET_CERTIFICATE_INFO structure.
INTERNET_OPTION_SECURITY_CERTIFICATE
Returns the certificate for an SSL/PCT server into a formatted string.
INTERNET_OPTION_SECURITY_KEY_BITNESS
Returns the bit size of the encryption key. The larger the number, the greater the encryption strength being used.
INTERNET_OPTION_OFFLINE_MODE
Not currently implemented.
INTERNET_OPTION_CACHE_STREAM_HANDLE
Returns the file handle being used to write the cached data.
INTERNET_OPTION_ASYNC
Not currently implemented.
INTERNET_OPTION_SECURITY_FLAGS
Returns the security flags for a handle. Can be a combination of these values:
SECURITY_FLAG_128BIT
SECURITY_FLAG_40BIT
SECURITY_FLAG_56BIT
SECURITY_FLAG_IETFSSL4
SECURITY_FLAG_IGNORE_CERT_CN_INVALID
SECURITY_FLAG_IGNORE_CERT_DATE_INVALID
SECURITY_FLAG_IGNORE_REDIRECT_TO_HTTP
SECURITY_FLAG_IGNORE_REDIRECT_TO_HTTPS
SECURITY_FLAG_NORMALBITNESS
SECURITY_FLAG_PCT
SECURITY_FLAG_PCT4
SECURITY_FLAG_SECURE
SECURITY_FLAG_SSL
SECURITY_FLAG_SSL3
SECURITY_FLAG_UNKNOWNBIT
INTERNET_OPTION_DATAFILE_NAME
Returns the name of the file backing a downloaded entity.
INTERNET_OPTION_URL
Returns the full URL of a downloaded entity.
INTERNET_OPTION_REFRESH
Returns TRUE if variables are allowed to be re-read from the registry for a handle.
INTERNET_OPTION_PROXY
Returns the proxy information on an existing InternetOpen handle when the process handle is not NULL. If the process handle is NULL, the API sets or queries the global proxy information. The lpBuffer parameter is an INTERNET_PROXY_INFO structure that contains the proxy information.
INTERNET_OPTION_VERSION
Returns the version number of Wininet.dll. The lpBuffer parameter is the address of an INTERNET_VERSION_INFO structure.
INTERNET_OPTION_USER_AGENT
Returns the user agent string on handles supplied by InternetOpen and used in subsequent HttpSendRequest, so long as it is not overridden by a header added by HttpAddRequestHeaders or HttpSendRequest.
lpBuffer
Address of a buffer that receives the option setting.
lpdwBufferLength
Address of a variable that contains the length of lpBuffer. When the function returns, this parameter receives the length of the data placed into lpBuffer. If GetLastError returns ERROR_INSUFFICIENT_BUFFER, this parameter receives the number of bytes required to hold the created URL.

See also FtpGetFile, FtpPutFile, InternetConnect, InternetOpen, InternetSetOption

InternetReadFile

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.

hFile
Valid handle returned from a previous call to InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest.
lpBuffer
Address of a buffer that receives the data read.
dwNumberOfBytesToRead
Number of bytes to read.
lpNumberOfBytesRead
Address of a variable that receives the number of bytes read. The InternetReadFile function sets this value to zero before doing any work or error checking.

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 up the connection to the server.

The buffer pointed to by lpBuffer is not always filled by calls to InternetReadFile (sufficient data may 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.

See also FtpOpenFile, GopherOpenFile, HttpOpenRequest, InternetCloseHandle, InternetOpenUrl

InternetSetFilePointer

BOOL InternetSetFilePointer(
    IN HINTERNET hFile,
    IN LONG IDistanceToMove,
    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.

hFile
Valid handle returned from a previous call to InternetOpenUrl on an HTTP URL, or to HttpOpenRequest using the GET method and passed to HttpSendRequest. The INTERNET_FLAG_DONT_CACHE value must not have been specified when the handle was created.
IDistanceToMove
Number of bytes to move the file pointer. A positive value moves the pointer forward in the file, and a negative value moves it backward.
pReserved
Reserved, must be NULL.
dwMoveMethod
Starting point for the file pointer move. Can be one of these values:
Value Meaning
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.
dwContext
Reserved, must be zero.

See also HttpOpenRequest, HttpSendRequest, InternetOpenUrl, InternetReadFile

InternetSetOption

BOOL InternetSetOption(
    IN HINTERNET hInternet OPTIONAL,
    IN DWORD dwOption,
    IN LPVOID lpBuffer,
    IN DWORD dwBufferLength
);

Sets an Internet option on the specified handle.

hInternet
Internet handle on which to set information.
dwOption
Internet option to set. Can be a combination of these values:
Value
Meaning
INTERNET_OPTION_CALLBACK
Sets the address of the callback function defined for this handle.
INTERNET_OPTION_CONNECT_TIMEOUT
Sets the time-out value, in milliseconds, to use for Internet connection requests. If a connection request takes longer than this time-out value, the request is canceled. The default time-out value is infinite.
INTERNET_OPTION_CONNECT_RETRIES
Sets the retry count to use for Internet connection requests. If a connection attempt still fails after the specified number of tries, the request is canceled. The default is five retries.
INTERNET_OPTION_CONNECT_BACKOFF
Sets the delay value, in milliseconds, to wait between connection retries.
INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
Sets the time-out value, in milliseconds, to use for non-data (control) Internet receive requests. If a non-data receive request takes longer than this time-out value, the request is canceled. The default time-out is infinite. Currently, this value has meaning only for FTP sessions.
INTERNET_OPTION_CONTROL_SEND_TIMEOUT
Sets the time-out value, in milliseconds, to use for non-data (control) Internet send requests. If a non-data send request takes longer than this time-out value, the request is canceled. The default time-out value is infinite. Currently, this value has meaning only for FTP sessions.
INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
Sets the time-out value, in milliseconds, to use for non-data (control) Internet receive requests. If a non-data receive request takes longer than this time-out value, the request is canceled. The default time-out value is infinite. Currently, this value has meaning only for FTP sessions.
INTERNET_OPTION_DATA_SEND_TIMEOUT
Sets the time-out value, in milliseconds, to use for data Internet send requests. If a data send request takes longer than this time-out value, the request is canceled. The default time-out value is infinite.
INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
Sets the time-out value, in milliseconds, to use for data Internet receive requests. If a data receive-request takes longer than this time-out value, the request is canceled. The default time-out value is infinite.
INTERNET_OPTION_ASYNC_PRIORITY
Sets the priority of this download if it is an asynchronous download. This option has not been implemented.
INTERNET_OPTION_CONTEXT_VALUE
Sets the context value associated with this Internet handle.
INTERNET_OPTION_REFRESH
Allows variables to be re-read from the registry for a handle.
INTERNET_OPTION_PROXY
Sets the proxy information on an existing InternetOpen handle when the process handle is not NULL. If the process handle is NULL, the API sets or queries the global proxy information. The lpBuffer parameter is an INTERNET_PROXY_INFO structure that contains the proxy information.
INTERNET_OPTION_USER_AGENT
Sets the user agent string on handles supplied by InternetOpen and used in subsequent HttpSendRequest functions, as long as it is not overridden by a header added by HttpAddRequestHeaders or HttpSendRequest.
INTERNET_OPTION_USERNAME
Sets the user name associated with a handle returned by InternetConnect.
INTERNET_OPTION_PASSWORD
Sets the password associated with a handle returned by InternetConnect.
INTERNET_OPTION_READ_BUFFER_SIZE
Sets the size, in bytes, of the buffer to use to read the data.
INTERNET_OPTION_WRITE_BUFFER_SIZE
Sets the size of the write buffer (for example, the buffer used by FtpPutFile).
INTERNET_OPTION_WRITE_DATA
Sets the size, in bytes, of the buffer to use while writing out the data.
lpBuffer
Address of a buffer that contains the option setting.
dwBufferLength
Length of the lpBuffer buffer.

See also FtpGetFile, FtpPutFile, InternetConnect, InternetOpen, InternetQueryOption

InternetSetOptionEx

BOOL InternetSetOption(
    IN HINTERNET hInternet OPTIONAL,
    IN DWORD dwOption,
    IN LPVOID lpBuffer,
    IN DWORD dwBufferLength,
    IN DWORD dwFlags
); 

Sets an Internet option on the specified handle.

hInternet
Internet handle on which to set information.
dwOption
Internet option to set. For a list of possible values, see InternetSetOption.
lpBuffer
Address of a buffer that contains the option setting.
dwBufferLength
Length of the lpBuffer buffer.
dwFlags
Action flags. Can be one of these values:
Value Meaning
ISO_GLOBAL Modify the option globally.
ISO_REGISTRY Write the option to the registry (where applicable).

InternetSetStatusCallback

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.

hInternet
Handle for which the callback is to be set.
lpfnInternetCallback
Address of the callback function to call when progress is made, or to return NULL to remove the existing callback function. For more information about the callback function, see InternetStatusCallback.

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, it can be accessed from within any Win32 Internet function for monitoring time-intensive network operations.

InternetStatusCallback

VOID InternetStatusCallback(
    IN HINTERNET hInternet,
    IN DWORD dwContext,
    IN DWORD dwInternetStatus,
    IN LPVOID lpvStatusInformation OPTIONAL,
    IN DWORD dwStatusInformationLength
);

This is a placeholder for the application-defined status callback

hInternet
Handle for which the callback function is being called.
dwContext
Application-defined context value associated with hInternet
dwInternetStatus
Status code that indicates why the callback function is being called. Can be one of these values:
INTERNET_STATUS_RESOLVING_NAME>
Looking up the IP address of the name contained in lpvStatusInformation.
INTERNET_STATUS_NAME_RESOLVED
Successfully found the IP address of the name contained in lpvStatusInformation.
INTERNET_STATUS_CONNECTING_TO_SERVER
Connecting to the socket address (SOCKADDR) pointed to by lpvStatusInformation.
INTERNET_STATUS_CONNECTED_TO_SERVER
Successfully connected to the socket address (SOCKADDR) pointed to by lpvStatusInformation.
INTERNET_STATUS_SENDING_REQUEST
Sending the information request to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_ REQUEST_SENT
Successfully sent the information request to the server. The lpvStatusInformation parameter points to a DWORD containing the number of bytes sent.
INTERNET_STATUS_RECEIVING_RESPONSE
Waiting for the server to respond to a request. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_RESPONSE_RECEIVED
Successfully received a response from the server. The lpvStatusInformation parameter points to a DWORD containing the number of bytes received.
INTERNET_STATUS_REDIRECT
Indicates that an HTTP request is about to automatically redirect the request. The lpvStatusInformation parameter points to the new URL. At this point, the application may read any data returned by the server with the redirect response, and may query the response headers. It may also cancel the operation by closing the handle. This callback is not made if the original request specified INTERNET_FLAG_NO_AUTO_REDIRECT.
INTERNET_STATUS_CLOSING_CONNECTION
Closing the connection to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_CONNECTION_CLOSED
Successfully closed the connection to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_HANDLE_CREATED
Used by InternetConnect to indicate it has created the new handle. This lets the application call InternetCloseHandle from another thread, if the connect is taking too long.
INTERNET_STATUS_HANDLE_CLOSING
This handle value is now terminated
INTERNET_STATUS_REQUEST_COMPLETE
An asynchronous operation has been completed. See InternetOpen for details on INTERNET_FLAG_ASYNC.

The lpvStatusInformation parameter points to an INTERNET_ASYNC_RESULT structure. The dwStatusInformationLength parameter contains the final completion status of the asynchronous function. If this is ERROR_INTERNET_EXTENDED_ERROR, the application can retrieve the server error information by using InternetGetLastResponseInfo.

lpvStatusInformation
Address of a buffer that contains information pertinent to this call to the callback function.
dwStatusInformationLength
Size of the lpvStatusInformation buffer.

In the case of INTERNET_STATUS_REQUEST_COMPLETE, lpvStatusInformation is the address of an INTERNET_ASYNC_RESULT structure.

An application uses the callback function to indicate the progress of synchronous and asynchronous functions, and to indicate the completion of an asynchronous request.

Because callbacks are made during processing of the request, the application should spend as little time as possible in the callback function to avoid degrading data throughput on the network. For example, displaying a dialog box in a callback function may be such a lengthy operation that the server terminates the request.

The callback function may be called in a thread context different from the thread that initiated the request.

See also InternetCloseHandle, InternetConnect, InternetGetLastResponseInfo, InternetOpen

InternetTimeFromSystemTime

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).

pst
Address of a SYSTEMTIME structure that contains the date and time to format.
dwRFC
RFC format.
lpszTime
Address of a buffer that receives the formatted data and time.
cbTime
Size, in bytes, of the lpszTime buffer.

InternetTimeToSystemTime

BOOL InternetTimeToSystemTime(
    IN LPCSTR lpszTime,
    OUT SYSTEMTIME *pst,
    IN DWORD dwReserved
);

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

lpszTime
Pointer to a null-terminated date/time string to convert
pst
Address of the pointer to the converted time.
dwReserved
Reserved; must be zero.

InternetWriteFile

BOOL InternetWriteFile(
    IN HINTERNET hFile,
    IN LPCVOID lpBuffer,
    IN DWORD dwNumberOfBytesToWrite,
    OUT LPDWORD lpdwNumberOfBytesWritten
);

Writes data to an open Internet file.

hFile
Valid handle returned from a previous call to FtpOpenFile.
lpBuffer
Address of a buffer that contains the data to be written to the file.
dwNumberOfBytesToWrite
Number of bytes to write to the file.
lpdwNumberOfBytesWritten
Address of a variable that receives the number of bytes written to the buffer. The InternetWriteFile function sets this value to zero before doing any work or error checking.

When the application is sending data, it must call InternetCloseHandle to end the data transfer.

See also FtpOpenFile, InternetCloseHandle

© 1996 Microsoft Corporation