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.

• Returns ERROR_SUCCESS if successful, or a Win32 error value otherwise.

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.

• Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError . Possible errors include:

ERROR_INVALID_PARAMETER

ERROR_INSUFFICIENT_BUFFER

ERROR_BAD_PATHNAME

ERROR_INTERNET_INVALID_URL

Bad string, buffer, buffer size, or flags parameter.

Canonicalized URL is too large to fit in the buffer provided. The

*lpdwBufferLength parameter is set to the size, in bytes, of the buffer required to hold the resultant, canonicalized URL.

The URL could not be canonicalized.

The format of the URL is invalid.

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梩he length

does not include the terminating null. If the function fails, this

parameter receives the required length, in bytes, of the lpszBuffer

buffer梩he 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.

• Returns TRUE if the handle is successfully closed, or FALSE otherwise. To get extended error information, call GetLastError .

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

• Returns TRUE if successful, or FALSE otherwise. To get extended error information, call GetLastError . Possible error codes include:

ERROR_INVALID_PARAMETER

ERROR_INSUFFICIENT_BUFFER

ERROR_BAD_PATHNAME ERROR_INTERNET_INVALID_URL

Bad string, buffer, buffer size, or flags parameter.

The *lpdwBufferLength parameter, in bytes, of the buffer required to hold the resultant, combined URL.

The URLs could not be combined. The format of the URL is invalid.

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 梩 he length does not include the null terminator. If the function fails, this parameter receives the length, in bytes, of the required buffer梩he 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.

• Returns a valid handle to the FTP, Gopher, or HTTP session if the connection is successful, or NULL otherwise. To get extended error information, call GetLastError . An application can also use InternetGetLastResponseInfo to determine why access to the service was denied.

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.

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 lpszPasswor

d

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

Non-NULL string Non-NULL

string

ERROR ERROR

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.

• Returns ERROR_SUCCESS if the user confirmed that it was okay to continue or there was no user input needed, ERROR_CANCELLED if the user canceled, or ERROR_NOT_ENOUGH_MEMORY if there is not enough memory to carry out the request.

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.

• Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError .

lpszUrl

Address of a string that contains the canonical URL to crack.

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:

ICU_ESCAPE Convert unsafe characters in the URL-path component to escape sequences.

ICU_DECODE Convert 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 and the value of its

corresponding length member is non-zero, the address of the first character 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

IN LPURL_COMPONENTS lpUrlComponents, IN DWORD dwFlags,

OUT LPSTR lpszUrl,

IN OUT LPDWORD lpdwUrlLength

);

Creates a URL from its component parts.

• Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError . If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.

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.

• Returns ERROR_SUCCESS, ERROR_CANCELLED, or ERROR_INTERNET_FORCE_RETRY.

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.

• Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError . If the function finds no matching files, GetLastError returns ERROR_NO_MORE_FILES.

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.

• Returns TRUE if error text was successfully written to the buffer, or FALSE otherwise. To get extended error information, call GetLastError . If the buffer is too small to hold all the error text, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the lpdwBufferLength parameter contains the minimum buffer size required to return all the error text.

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.

• Returns a valid handle that the application passes on to subsequent Win32 Internet functions. If InternetOpen fails, it returns NULL. To get a specific error code, call GetLastError .

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.

• Returns a valid handle to the FTP, Gopher, or HTTP URL if the connection is successfully established, or NULL if the connection fails. To get a specific error code, call GetLastError . To determine why access to the service was denied, call InternetGetLastResponseInfo .

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

IN HINTERNET hFile,

OUT LPDWORD lpdwNumberOfBytesAvailable, IN DWORD dwFlags,

IN DWORD dwContext

);

Queries the amount of data available.

• Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError . If the function finds no matching files, the GetLastError function returns ERROR_NO_MORE_FILES.

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.

• Returns TRUE if successful, or FALSE otherwise. To get a specific error code, call GetLastError .

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_INTE RNET

INTERNET_HANDLE_TYPE_CONN ECT_FTP

INTERNET_HANDLE_TYPE_CONN ECT_GOPHER

INTERNET_HANDLE_TYPE_CONN ECT_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_GOPH ER_FIND

INTERNET_HANDLE_TYPE_GOPH ER_FIND_HTML

INTERNET_HANDLE_TYPE_GOPH ER_FILE

INTERNET_HANDLE_TYPE_GOPH ER_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_UNKNO WN

INTERNET_KEEP_ALIVE_ENABL ED

INTERNET_KEEP_ALIVE_DISAB LED

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_REDI RECT_TO_HTTP

SECURITY_FLAG_IGNORE_REDI RECT_TO_HTTPS

SECURITY_FLAG_NORMALBITNE SS

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

• Returns TRUE if successful or FALSE otherwise. To get extended error information, call GetLastError . An application can also use InternetGetLastResponseInfo when necessary.

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.

• Returns the current file position if the function succeeds, or -1 otherwise.

hFile

Valid handle returned from a previous call to FtpOpenFile , GopherOpenFile , InternetOpenUrl on an HTTP URL, or to HttpOpenRequest (using the GET or HEAD method and passed to HttpSendRequest ). This handle must not have been created with the INTERNET_FLAG_DONT_CACHE or INTERNET_FLAG_NO_CACHE_WRITE value set.

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:

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 FtpOpenFile, GopherOpenFile, 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.

• Returns TRUE if successful, or FALSE otherwise. To get a specific error code, call GetLastError .

hInternet

Internet handle on which to set information.

dwOption

Internet option to set. Can be a combination of these values: 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. Currently, this sets the context value to the address stored in the pointer, DWORD(lpBuffer). For Internet Explorer 4.0, this will be corrected so that the value stored in the buffer will be used, and this flag will be reassigned a new value. The old value, 10, will be preserved so that applications that are written for the old behavior will still be supported.

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 InternetSetOptionEx(

IN HINTERNET hInternet OPTIONAL,

IN DWORD dwOption, IN LPVOID lpBuffer,

IN DWORD dwBufferLength, IN DWORD dwFlags

);

Sets an Internet option on the specified handle.

• Returns TRUE if successful, or FALSE otherwise. To get a specific error code, call GetLastError .

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.

• Returns the previously defined status callback function if successful, NULL if there was no previously defined status callback function, or INTERNET_INVALID_STATUS_CALLBACK if the callback function is not valid.

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

• No return value.

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

• Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError .

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.

• Returns TRUE if the string was converted, or FALSE otherwise. To get extended error information, call GetLastError .

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.

• Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError . An application can also use InternetGetLastResponseInfo , when necessary.

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