Following global functions are defined:
Attempts to make a connection to the Internet.
Description:This function allows an application to first attempt to connect before issuing any requests. A client
program can use this to evoke the dial-up dialog box. If the attempt fails, the application should
enter offline mode.
Returns ERROR_SUCCESS if successful, or a Win32(r) error value otherwise.
Allows an application to check if a connection to the Internet can be established.
Params:URL to use to check the connection. This value can be set to NULL.
FLAG_ICC_FORCE_CONNECTION is the only flag that is currently available.
If this flag is set, it forces a connection.
Returns TRUE if a connection is made successfully, or FALSE otherwise. Use GetLastError to
retrieve the error code. ERROR_NOT_CONNECTED is returned by GetLastError if a connection
cannot be made or if the sockets database is unconditionally offline.
Closes a single Internet handle.
Params:Valid HINTERNET handle to be closed.
Remarks
The function terminates any pending operations on the handle and discards any outstanding data. If
a thread is blocking a call to Wininet.dll, another thread in the application can call
InternetCloseHandle on the Internet handle being used by the first thread to cancel the operation
and unblock the first thread.
If there is a status callback registered for the handle being closed and the handle was created with a
non-NULL context value, an INTERNET_STATUS_HANDLE_CLOSING callback will be made.
This indication will be the last callback made from a handle and indicates that the handle is being
destroyed.
If asynchronous requests are pending for the handle or any of its child handles, the handle cannot be
closed immediately, but it will be invalidated. Any new requests attempted using the handle will
return with an ERROR_INVALID_HANDLE notification. The asynchronous requests will
complete with INTERNET_STATUS_REQUEST_COMPLETE. Applications must be prepared to
receive any INTERNET_STATUS_REQUEST_COMPLETE indications on the handle before the
final INTERNET_STATUS_HANDLE_CLOSING indication is made, which indicates that the
handle is completely closed.
An application can call GetLastError to determine if requests are pending. If GetLastError
returns ERROR_IO_PENDING, there were outstanding requests when the handle was closed.
Returns TRUE if the handle is successfully closed, or FALSE otherwise. To get extended error
information, call GetLastError.
Checks for changes between secure and nonsecure URLs.
Params:Handle to the parent window for any needed dialog box.
Address of a string variable containing the URL that was viewed before the
current request was made.
Address of a string variable containing the new URL that the user has requested
to view.
Boolean value that determines if a post is being made by this request. If bPost is set
to TRUE, a post is being made in this request. This flag is ignored in this release.
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 one of the following values:
ERROR_SUCCESS The user confirmed that it was okay to continue, or there was no user
input needed.
ERROR_CANCELLED The user canceled the request.
ERROR_NOT_ENOUGH_MEMORY There is not enough memory to carry out the request.
Opens an FTP, Gopher, or HTTP session for a given site.
Params:Valid HINTERNET handle returned by a previous call to InternetOpen.
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).
Number of the TCP/IP port on the server to connect to. These flags set only the port that will be
used. The service is set by the value of dwService. This can be any one of the following values:
INTERNET_DEFAULT_FTP_PORT Uses the default port for FTP servers (port 21).
INTERNET_DEFAULT_GOPHER_PORT Uses the default port for Gopher servers (port 70).
INTERNET_DEFAULT_HTTP_PORT Uses the default port for HTTP servers (port 80).
INTERNET_DEFAULT_HTTPS_PORT Uses the default port for HTTPS servers (port 443).
INTERNET_DEFAULT_SOCKS_PORT Uses the default port for SOCKS firewall servers (port 1080).
INTERNET_INVALID_PORT_NUMBER Uses the default port for the service specified by dwService.
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".
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 password is the user's e-mail name. If lpszPassword is
NULL, but lpszUsername is not NULL, the function uses a blank password.
Unsigned long integer value that contains the type of service to access. This can be one of the
following values:
INTERNET_SERVICE_FTP FTP service.
INTERNET_SERVICE_GOPHER Gopher service.
INTERNET_SERVICE_HTTP HTTP service.
Unsigned long integer value that contains the flags specific to the service used. When the value
of dwService is INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE causes the
application to use passive FTP semantics.
Address of an unsigned long integer value that contains an application-defined value that is used
to identify the application context for the returned handle in callbacks.
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.
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.
Displays a dialog box for the error that is passed to InternetErrorDlg,if an appropriate dialog box exists.
Params:Handle to the parent window for any needed dialog box. This parameter can be NULL if nodialog box is needed.
HINTERNET handle to the Internet connection used in the call to HttpSendRequest.
Error value for which to display a dialog box. This can be one of the following 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.
ERROR_INTERNET_INVALID_CA Notifies the user that the Win32(r) Internet function does not
ERROR_INTERNET_POST_IS_NON_SECURE Displays a warning about posting data to the server through a
ERROR_INTERNET_SEC_CERT_CN_INVALID Indicates that the SSL certificate Common Name (hostname field)
ERROR_INTERNET_SEC_CERT_DATE_INVALID Tells the user that the SSL certificate has expired.
Unsigned long integer value that contains the action flags. This can be a combination of these
values:
FLAGS_ERROR_UI_FILTER_FOR_ERRORS cans the returned headers for errors. Call after using
FLAGS_ERROR_UI_FLAGS_CHANGE_OPTIONS If the function succeeds, stores the results of the dialog box in
FLAGS_ERROR_UI_FLAGS_GENERATE_DATA Queries the Internet handle for needed information. The function
FLAGS_ERROR_UI_SERIALIZE_DIALOGS Serializes authentication dialog boxes for concurrent requests on a
Address of pointer to a data structure. The structure can be different for each error that needs to
be handled.
If the FLAGS_ERROR_UI_FILTER_FOR_ERRORS flag is used, the function also checks the
headers for any hidden errors and displays a dialog box if needed.
Remarks
Authentication errors are hidden, because the call to HttpSendRequest will complete
successfully. However, the status code would indicate that the proxy or server requires
authentication. The FLAGS_ERROR_UI_FILTER_FOR_ERRORS flag causes the function to
search the headers for status codes that indicate user input is needed.
Returns one of the following values, or an error code otherwise.
ERROR_SUCCESS The function completed successfully.
ERROR_CANCELLED The function was canceled by the user.
ERROR_INTERNET_FORCE_RETRY The Win32 function needs to redo its request.
ERROR_INVALID_HANDLE The handle to the parent window is invalid.
Continues a file search started as a result of a previous call to
FtpFindFirstFile or GopherFindFirstFile.
Valid HINTERNET handle returned from either FtpFindFirstFile or
GopherFindFirstFile, or from InternetOpenUrl (directories only).
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.
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.
Retrieves the last Win32(r) Internet function error description or server
response on the thread calling this function.
Remarks
The FTP and Gopher protocols can return additional text information along
with most errors. This extended error information can be retrieved by
using the InternetGetLastResponseInfo function whenever GetLastError
returns ERROR_INTERNET_EXTENDED_ERROR (occurring after an unsuccessful
function call).
The buffer pointed to by lpszBuffer must be large enough to hold both the
error string and a zero terminator at the end of the string. However, note
that the value returned in lpdwBufferLength does not include the
terminating zero.
InternetGetLastResponseInfo can be called multiple times until another
Win32 Internet function is called on this thread. When another function
is called, the internal buffer that is storing the last response
information is cleared.
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.
Allows the user to place a lock on the file that is being used.
Params:HINTERNET handle returned by FtpOpenFile, GopherOpenFile,
HttpOpenRequest, or InternetOpenUrl.
Address of a handle to store the lock request handle.
Remarks
If the HINTERNET handle passed to hInternet was created using
INTERNET_FLAG_NO_CACHE_WRITE or INTERNET_FLAG_DONT_CACHE, the function
creates a temporary file with the extension .tmp, unless it is an HTTPS
resource. If the handle was created using INTERNET_FLAG_NO_CACHE_WRITE or
INTERNET_FLAG_DONT_CACHE and it is accessing an HTTPS resource,
InternetLockRequestFile fails.
Returns TRUE if successful, or FALSE otherwise. To get a specific error
message, call GetLastError.
Initializes an application's use of the Win32(r) Internet functions.
String variable that contains the name of the application
or entity calling the Internet functions (for example, Microsoft(r)
Internet Explorer). This name is used as the user agent in the HTTP
protocol.
Type of access required. This can be one of the following values:
INTERNET_OPEN_TYPE_DIRECT Resolves all host names locally.
INTERNET_OPEN_TYPE_PRECONFIG Retrieves the proxy or direct
configurationfrom the registry.
INTERNET_OPEN_TYPE_PRECONFIG_WITH_NO_AUTOPROXY Retrieves the proxy or
direct configurationfrom the registry and
prevents the use of a startup JScript(r)
(compatible with ECMA 262 language
specification) or Internet Setup (INS)
file.
INTERNET_OPEN_TYPE_PROXY Passes requests to the proxy unless a
proxybypass list is supplied and the name
to be resolved bypasses the proxy. In this
case, the function uses
INTERNET_OPEN_TYPE_DIRECT.
String variable that contains the name of the proxy
server(s) to use when proxy access is specified by setting dwAccessType
to INTERNET_OPEN_TYPE_PROXY. Do not use an empty string, because
InternetOpen will use it as the proxy name. The Win32 Internet functions
recognize only CERN type proxies (HTTP only) and the TIS FTP gateway
(FTP only). If Internet Explorer is installed, the Win32 Internet
functions also support SOCKS proxies. FTP and Gopher requests can be
made through a CERN type proxy either by changing them to an HTTP request
or by using InternetOpenUrl. If dwAccessType is not set to
INTERNET_OPEN_TYPE_PROXY, this parameter is ignored and should be set to
NULL. For more information about listing proxy servers, see Listing Proxy
Servers section of the Enabling Internet Functionality article.
String variable that contains an optional list of host names
or IP addresses, or both, that should not be routed through the proxy
when dwAccessType is set to INTERNET_OPEN_TYPE_PROXY. The list can
contain wildcards. Do not use an empty string, because InternetOpen will
use it as the proxy bypass list. If this parameter specifies the
"
that does not contain a period. If dwAccessType is not set to
INTERNET_OPEN_TYPE_PROXY, this parameter is ignored and should be set
to NULL.
Unsigned long integer value that contains the flags that indicate various
options affecting the behavior of the function. This can be a combination
of these values:
INTERNET_FLAG_ASYNC
INTERNET_FLAG_FROM_CACHE
INTERNET_FLAG_OFFLINE
Remarks
InternetOpen is the first Win32 Internet function called by an application.
It tells the Internet DLL to initialize internal data structures and
prepare for future calls from the application. When the application
finishes using the Internet functions, it should call InternetCloseHandle
to free the handle and any associated resources.
The application can make any number of calls to InternetOpen, although a
single call is normally sufficient. The application might need to have
separate behaviors defined for each InternetOpen instance, such as
different proxy servers configured for each.
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 message, call GetLastError.
This function returns the number of bytes of data that are available to be
read immediately by a subsequent call to InternetReadFile.
Valid HINTERNET handle, as returned by InternetOpenUrl, FtpOpenFile,
GopherOpenFile, or HttpOpenRequest.
Remarks
If there is currently no data available and the end of the file has not been
reached, the request waits until data becomes available. The amount of data
remaining will not be recalculated until all available data indicated by
the call to InternetQueryDataAvailable is read.
For HINTERNET handles created by HttpOpenRequest and sent by
HttpSendRequestEx, a call to HttpEndRequest must be made on the handle
before InternetQueryDataAvailable can be used.
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.
Queries an Internet option on the specified handle.
HINTERNET handle on which to query information.
Unsigned long integer value that contains the Internet option to query.
This can be one of the Option Flags values.
Remarks
GetLastError will return the ERROR_INVALID_PARAMETER if an option flag that
is invalid for the specified handle type is passed to the dwOption
parameter.
Returns TRUE if successful, or FALSE otherwise. To get a specific error
message, call GetLastError.
Reads data from a handle opened by the InternetOpenUrl, FtpOpenFile,
GopherOpenFile, or HttpOpenRequest function.
Valid HINTERNET handle returned from a previous call to InternetOpenUrl,
FtpOpenFile, GopherOpenFile, or HttpOpenRequest.
Number of bytes to read.
Remarks
If the return value is an empty string, the transfer has been completed and
there are no more bytes to read on the handle.
This is analogous to reaching end-of-file in a local file.
The buffer is not always filled by calls to InternetReadFile (sufficient data
might not have arrived from the server). When reading HTML data, for the
first read posted, the buffer must be large enough to hold the HTML headers.
When reading HTML-encoded directory entries, the buffer must be large enough
to hold at least one complete entry.
When the item being read is also being cached by a Win32(r) Internet
function, the application must ensure that a read is made for end-of-file
so the cache file is committed correctly.
This function always fulfills the user's request. If more data is requested
than is available, the function waits until enough data to complete the
request is available. The only time that less data is returned than
requested is when the end of the file has been reached.
This function can also be used to retrieve FTP and Gopher directory
listings as an HTML document on a handle opened by InternetOpenUrl. The
INTERNET_FLAG_RAW_DATA value must not have been specified in the call to
InternetOpenUrl.
If the HINTERNET handle stored in hFile was created by HttpOpenRequest and
sent by HttpSendRequestEx, a call to HttpEndRequest must be made on the
handle before InternetReadFile is used.
Returns data read if successful, or FALSE otherwise. To get extended error
information, call GetLastError. An application can also use
InternetGetLastResponseInfo when necessary.
Reads data from a handle opened by the InternetOpenUrl, FtpOpenFile,
GopherOpenFile, or HttpOpenRequest function.
HINTERNET handle returned by the InternetOpenUrl, FtpOpenFile,
GopherOpenFile, or HttpOpenRequest function.
Address of an INTERNET_BUFFERS structure that contains the data downloaded.
Unsigned long integer variable that contains the flags controlling the
download. This can be one of the following values:
IRF_ASYNC Identical to WININET_API_FLAG_ASYNC.
IRF_SYNC Identical to WININET_API_FLAG_SYNC.
IRF_USE_CONTEXT Identical to WININET_API_FLAG_USE_CONTEXT.
IRF_NO_WAIT Do not wait for data. If there is data available, the
function returns either the amount of data requested or
the amount of data available (whichever is smaller).
Unsigned long integer variable that contains the context value used for
asynchronous operations.
Returns TRUE if successful, or FALSE otherwise. To get extended error
information, call GetLastError. An application can also use
InternetGetLastResponseInfo when necessary.
Sets a file position for InternetReadFile.
Params:Valid HINTERNET handle returned from a previous call to InternetOpenUrl
(on an HTTP or HTTPS URL) or HttpOpenRequest (using the GET or HEAD
method and passed to HttpSendRequest or HttpSendRequestEx). This handle
must not have been created with the INTERNET_FLAG_DONT_CACHE or
INTERNET_FLAG_NO_CACHE_WRITE value set.
Long integer value that contains the number of bytes to move the file
pointer. A positive value moves the pointer forward in the file; a
negative value moves it backward.
Unsigned long integer value that indicates the starting point for the
file pointer move. This can be one of the following values:
FILE_BEGIN 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 Current value of the file pointer is the starting point.
FILE_END Current end-of-file position is the starting point. This
method fails if the content length is unknown.
This is a synchronous call; however, subsequent calls to InternetReadFile might
block or return pending if the data is not available from the cache and the
server does not support random access.
Remarks
This function cannot be used once the end of the file has been reached by
InternetReadFile.
For HINTERNET handles created by HttpOpenRequest and sent by
HttpSendRequestEx, a call to HttpEndRequest must be made on the handle
before InternetSetFilePointer is used.
InternetSetFilePointer cannot be used reliably if the content length is
unknown, and it cannot be used reliably with chunked transfers.
Returns the current file position if the function succeeds, or -1
otherwise.
Sets an Internet option.
Params:HINTERNET handle on which to set information.
Contains the Internet option to set.
This can be one of the Option Flags values.
Address of a buffer that contains the option setting.
Unsigned long integer value that contains the length of the lpBuffer
buffer in TCHAR.
Remarks
GetLastError will return the error ERROR_INVALID_PARAMETER if an option
flag that cannot be set is specified.
Returns TRUE if successful, or FALSE otherwise. To get a specific error
message, call GetLastError.
Sets up a callback function that Win32(r) Internet functions can call as
progress is made during an operation.
HINTERNET handle for which the callback is to be set.
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 INTERNET_STATUS_CALLBACK.
Remarks
Both synchronous and asynchronous functions use the callback function to
indicate the progress of the request, such as resolving a name, connecting
to a server, and so on. The callback function is required for an
asynchronous operation. The asynchronous request will call back to the
application with INTERNET_STATUS_REQUEST_COMPLETE to indicate the request
has been completed.
A callback function can be set on any handle, and is inherited by derived
handles. A callback function can be changed using
InternetSetStatusCallback, providing there are no pending requests that
need to use the previous callback value. Note, however, that changing the
callback function on a handle does not change the callbacks on derived
handles, such as that returned by InternetConnect. You must change the
callback function at each level.
Many of the Win32 Internet functions perform several operations on the
network. Each operation can take time to complete, and each can fail.
It is sometimes desirable to display status information during a long-term
operation. You can display status information by setting up an Internet
status callback function that cannot be removed as long as any callbacks or
any asynchronous functions are pending.
After initiating InternetSetStatusCallback, the callback function can be
accessed from within any Win32 Internet function for monitoring
time-intensive network operations.
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.
Takes an HTTP time/date string and converts it to a SYSTEMTIME structure.
Date/time string to convert.
Address of SYSTEMTIME structure that receives the converted time.
Returns Address of SYSTEMTIME structure if the string was converted, or FALSE
otherwise. To get extended error information, call GetLastError.
Unlocks a file that was locked using InternetLockRequestFile.
Lock request handle that was returned by InternetLockRequestFile.
Returns TRUE if successful, or FALSE otherwise. To get a specific error
message, call GetLastError.
Writes data to an open Internet file.
Params:Valid HINTERNET handle returned from a previous call to FtpOpenFile or an
HINTERNET handle sent by HttpSendRequestEx.
Contains the data to be written to the file.
Remarks
When the application is sending data, it must call InternetCloseHandle to
end the data transfer.
Returns TRUE if the function succeeds, or FALSE otherwise. To get extended
error information, call GetLastError. An application can also use
InternetGetLastResponseInfo when necessary.
Causes the modem to automatically dial the default Internet connection.
Unsigned long integer value that contains the flags controlling this
operation. This can be one of the following values:
INTERNET_AUTODIAL_FAILIFSECURITYCHECK Causes InternetAutodial to fail
if file and printer sharing is
disabled for Microsoft(r)
Windows(r) 95/98.
INTERNET_AUTODIAL_FORCE_ONLINE Forces an online Internet
connection.
INTERNET_AUTODIAL_FORCE_UNATTENDED Forces an unattended Internet
dial-up.
Handle to the parent window.
Returns TRUE if successful, or FALSE otherwise.
Disconnects an automatic dial-up connection.
Returns TRUE if successful, or FALSE otherwise.
Initiates a connection to the Internet using a modem.
Params:Handle to the parent window.
String variable containing the name of the dial-up connection to use.
Contains the flags to use. This can be one of the following values:
INTERNET_AUTODIAL_FORCE_ONLINE Forces an online connection.
INTERNET_AUTODIAL_FORCE_UNATTENDED Forces an unattended Internet dial-up. If user
intervention is required, the function will fail.
INTERNET_DIAL_FORCE_PROMPT Ignores the "dial automatically" setting and
forces the dialing user interface to be displayed.
INTERNET_DIAL_UNATTENDED Connects to the Internet through a modem,
without displaying a user interface, if possible.
Otherwise, the function will wait for user input.
INTERNET_DIAL_SHOW_OFFLINE Shows the Work Offline button instead of Cancel
button in the dialing user interface.
Address of an unsigned long integer value containing the number associated to the connection.
Returns ERROR_SUCCESS if successful, or an error code otherwise. The error code can be one of
the following:
ERROR_INVALID_PARAMETER One or more of the parameters are incorrect.
ERROR_NO_CONNECTION There is a problem with the dial-up connection.
ERROR_USER_DISCONNECTION The user clicked either the Work Offline or Cancel
button on the Internet connection dialog box.
Retrieves the connected state of the local system.
Return:integer: can be a combination of the following values:
INTERNET_CONNECTION_CONFIGURED Local system has a valid connection to the
Internet, but it may or may not be currently
connected.
INTERNET_CONNECTION_LAN Local system uses a local area network to
connect to the Internet.
INTERNET_CONNECTION_MODEM Local system uses a modem to connect to the
Internet.
INTERNET_CONNECTION_MODEM_BUSY No longer used.
INTERNET_CONNECTION_OFFLINE Local system is in offline mode.
INTERNET_CONNECTION_PROXY Local system uses a proxy server to connect to
the Internet.
INTERNET_RAS_INSTALLED Local system has RAS installed.
Instructs the modem to disconnect from the Internet.
Params:Number assigned to the connection to be disconnected.
Returns ERROR_SUCCESS if successful, or an error code otherwise.
Begins reading a complete FTP, Gopher, or HTTP URL. Use
InternetCanonicalizeUrl first if the URL being used contains a relative URL
and a base URL separated by blank spaces.
HINTERNET handle to the current Internet session. The handle must have
been returned by a previous call to InternetOpen.
String variable that contains the URL to begin reading. Only
URLs beginning with ftp:, gopher:, http:, or https: are supported.
String variable that contains the headers to be sent to the
HTTP server. (For more information, see the description of the
lpszHeaders parameter in the HttpSendRequest function.)
Unsigned long integer value that contains the API flags. This can be one
of the following values:
INTERNET_FLAG_EXISTING_CONNECT
INTERNET_FLAG_HYPERLINK
INTERNET_FLAG_IGNORE_CERT_CN_INVALID
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS
INTERNET_FLAG_KEEP_CONNECTION
INTERNET_FLAG_NEED_FILE
INTERNET_FLAG_NO_AUTH
INTERNET_FLAG_NO_AUTO_REDIRECT
INTERNET_FLAG_NO_CACHE_WRITE
INTERNET_FLAG_NO_COOKIES
INTERNET_FLAG_NO_UI
INTERNET_FLAG_PASSIVE
INTERNET_FLAG_PRAGMA_NOCACHE
INTERNET_FLAG_RAW_DATA
INTERNET_FLAG_RELOAD
INTERNET_FLAG_RESYNCHRONIZE
INTERNET_FLAG_SECURE
Address of an unsigned long integer value that contains the application-
defined value that is passed, along with the returned handle, to any
callback functions.
Remarks
This is a general function that an application can use to retrieve data
over any of the protocols that the Win32(r) Internet functions support.
This function is especially 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 (for
files) or InternetFindNextFile (for directories) 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).
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 message, call GetLastError. To determine why access to the
service was denied, call InternetGetLastResponseInfo.
Deletes a file stored on the FTP server.
Params:Name of the file to delete on the remote system.
Remarks
The FileName parameter can be either partially or fully qualified file names relative to the
current directory.
Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call
GetLastError.
Searches the specified directory of the given FTP session. File and directory entries are returned to the
application in the WIN32_FIND_DATA structure.
Valid handle to an FTP session returned from InternetConnect.
Valid directory path or file name for the FTP server's file system. The string can contain
wildcards, but no blank spaces are allowed. If SearchFile is an empty string, it will
find the first file in the current directory on the server.
Address of a WIN32_FIND_DATA structure that receives information about the found file or
directory.
Unsigned long integer value that contains the flags that control the behavior of this function.
This can be a combination of the following values:
INTERNET_FLAG_HYPERLINK
INTERNET_FLAG_NEED_FILE
INTERNET_FLAG_NO_CACHE_WRITE
INTERNET_FLAG_RELOAD
INTERNET_FLAG_RESYNCHRONIZE
Address of an unsigned long integer value that contains the application-defined value that
associates this search with any application data. This parameter is used only if the application
has already called InternetSetStatusCallback to set up a status callback function.
Remarks
For FtpFindFirstFile, file times returned in the WIN32_FIND_DATA structure are in the local
time zone, not in a time zone independent (UTC) format.
FtpFindFirstFile is similar to the Win32(r) FindFirstFile function. Note, however, that only one
FtpFindFirstFile can occur at a time within a given FTP session. The enumerations, therefore, are
correlated with the FTP session handle. This is because the FTP protocol allows only a single
directory enumeration per session.
After calling FtpFindFirstFile and until calling InternetCloseHandle, the application cannot call
FtpFindFirstFile again on the given FTP session handle. If a call is made to FtpFindFirstFile on
that handle, the function will fail with ERROR_FTP_TRANSFER_IN_PROGRESS.
After beginning a directory enumeration with FtpFindFirstFile, the InternetFindNextFile
function can be used to continue the enumeration.
Because the FTP protocol provides no standard means of enumerating, some of the common
information about files, such as file creation date and time, is not always available or correct. When
this happens, FtpFindFirstFile and InternetFindNextFile fill in unavailable information with a
best guess based on available information. For example, creation and last access dates will often be
the same as the file's modification date.
The application cannot call FtpFindFirstFile between calls to FtpOpenFile and
InternetCloseHandle.
Returns a valid handle for the request if the directory enumeration was started successfully, or
returns NULL otherwise. To get a specific error message, call GetLastError. If the function finds
no matching files, GetLastError returns ERROR_NO_MORE_FILES.
Retrieves the current directory for the specified FTP session.
Valid handle to an FTP session.
Absolute path to the current directory.
Address of a variable that specifies the length, in characters, of the buffer for the current
directory string. The buffer length must include room for a terminating null character. Using a
length of MAX_PATH is sufficient for all paths. When the function returns, the variable receives
the number of characters copied into the buffer.
Remarks
If the lpszCurrentDirectory buffer is not large enough, lpdwCurrentDirectory receives the number
of bytes required to retrieve the full, current directory name.
Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call
GetLastError.
Retrieves a file from the FTP server and stores it under the specified file name, creating a new local
file in the process.
Valid handle to an FTP session.
Name of the file to retrieve from the remote system.
Name of the file to create on the local system.
Boolean flag that indicates whether the function should proceed if a local file of the specified
name already exists. If fFailIfExists is TRUE and the local file exists, FtpGetFile fails.
Unsigned long integer value that contains the file attributes for the new file. This can be any
combination of the FILE_ATTRIBUTE_* flags used by the CreateFile function. For more
information on FILE_ATTRIBUTE_* attributes, see CreateFile in the Platform SDK.
Unsigned long integer value that contains the flags that control how the function will handle the
file download. The first set of flag values indicates the conditions under which the transfer
occurs. These transfer type flags can be used in combination with the second set of flags that
control caching. The application can select one of these transfer type values:
FTP_TRANSFER_TYPE_ASCII Transfers the file using FTP's ASCII (Type A) transfer method.
Control and formatting information is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY Transfers the file using FTP's Image (Type I) transfer method.
The file is transferred exactly as it exists with no changes.
This is the default transfer method.
FTP_TRANSFER_TYPE_UNKNOWN Defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY Transfers the file as binary.
The following flags determine how the caching of this file will be done. Any combination of the
following flags can be used with the transfer type flag. The possible values are:
INTERNET_FLAG_HYPERLINK
INTERNET_FLAG_NEED_FILE
INTERNET_FLAG_RELOAD
INTERNET_FLAG_RESYNCHRONIZE
Address of an unsigned long integer value that contains the application-defined value that
associates this search with any application data. This is used only if the application has already
called InternetSetStatusCallback to set up a status callback function.
Remarks
FtpGetFile is a high-level routine that handles all the bookkeeping and overhead associated with
reading a file from an FTP server and storing it locally. An application that needs to retrieve file
data only or that requires close control over the file transfer should use the FtpOpenFile and
InternetReadFile functions.
If the dwFlags parameter specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data
converts control and formatting characters to local equivalents. The default transfer is binary mode,
where the file is downloaded in the same format as it is stored on the server.
Both lpszRemoteFile and lpszNewFile can be either partially or fully qualified file names relative to
the current directory.
Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call
GetLastError.
Retrieves the file size of the requested FTP resource.
HINTERNET handle returned from a call to FtpOpenFile.
Returns the low-order unsigned long integer of the file size, in TCHAR,
of the requested FTP resource.
Initiates access to a remote file on an FTP server for reading or writing.
Valid HINTERNET handle to an FTP session.
Name of the file to access on the remote system.
Determines how the file will be accessed. This can be GENERIC_READ or
GENERIC_WRITE, but not both.
Conditions under which the transfers occur. The application should select one
transfer type and any of the flags that indicate how the caching of the file
will be controlled. The transfer type can be any one of the following values:
FTP_TRANSFER_TYPE_ASCII Transfers the file using FTP's ASCII (Type A)
transfer method. Control and formatting
information is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY Transfers the file using FTP's Image (Type I)
transfer method. The file is transferred
exactly as it exists with no changes.
This is the default transfer method.
FTP_TRANSFER_TYPE_UNKNOWN Defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY Transfers the file as binary.
The following values are used to control the caching of the file.
The application can use one or more of these.
INTERNET_FLAG_HYPERLINK
INTERNET_FLAG_NEED_FILE
INTERNET_FLAG_RELOAD
INTERNET_FLAG_RESYNCHRONIZE
Address of the application-defined value that associates this search with
any application data. This is only used if the application has already
called InternetSetStatusCallback to set up a status callback function.
Remarks
After calling FtpOpenFile and until calling InternetCloseHandle, all other calls to FTP functions
on the same FTP session handle will fail and set the error message to
ERROR_FTP_TRANSFER_IN_PROGRESS.
Only one file can be open in a single FTP session. Therefore, no file handle is returned and the
application simply uses the FTP session handle when necessary.
The lpszFileName parameter can be either partially or fully qualified file names relative to the
current directory.
Returns a handle if successful, or NULL otherwise. To get a specific error message, call
GetLastError.
Stores a file on the FTP server.
Valid HINTERNET handle to an FTP session.
Name of the file to send from the local system.
Name of the file to create on the remote system.
Conditions under which the transfers occur. The application should select one
transfer type and any of the flags that control how the caching of the file
will be controlled. The transfer type can be any one of the following values:
FTP_TRANSFER_TYPE_ASCII Transfers the file using FTP's ASCII (Type A)
transfer method. Control and formatting
information is converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY Transfers the file using FTP's Image (Type I)
transfer method. The file is transferred
exactly as it exists, with no changes.
This is the default transfer method.
FTP_TRANSFER_TYPE_UNKNOWN Defaults to FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII Transfers the file as ASCII.
INTERNET_FLAG_TRANSFER_BINARY Transfers the file as binary.
The following values are used to control the caching of the file. The application can use one or
more of the following values:
INTERNET_FLAG_HYPERLINK
INTERNET_FLAG_NEED_FILE
INTERNET_FLAG_RELOAD
INTERNET_FLAG_RESYNCHRONIZE
Address of the application-defined value that associates this search with any
application data. This parameter is used only if the application has
already called InternetSetStatusCallback to set up a status callback.
Remarks
FtpPutFile is a high-level routine that handles all the bookkeeping and overhead associated with
reading a file locally and storing it on an FTP server. An application that needs to send file data
only, or that requires close control over the file transfer, should use the FtpOpenFile and
InternetWriteFile functions.
If the dwFlags parameter specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data
converts control and formatting characters to local equivalents.
Both lpszNewRemoteFile and lpszLocalFile can be either partially or fully qualified file names
relative to the current directory.
Returns TRUE if successful, or FALSE otherwise. To get a specific error message, call
GetLastError.
Changes to a different working directory on the FTP server.
Valid HINTERNET handle to an FTP session.
Name of the directory to change to on the remote system. This can be either a
fully qualified path or a name relative to the current directory.
Remarks
An application should use FtpGetCurrentDirectory to determine the remote
site's current working directory, instead of assuming that the remote
system uses a hierarchical naming scheme for directories.
The lpszDirectory parameter can be either partially or fully qualified file
names relative to the current directory.
Returns TRUE if successful, or FALSE otherwise. To get a specific error
message, call GetLastError. If the error message indicates that the FTP
server denied the request to change a directory, use
InternetGetLastResponseInfo to determine why.
Adds one or more HTTP request headers to the HTTP request handle.
Params:HINTERNET handle returned by a call to the HttpOpenRequest function.
Headers to append to the request. Each header must be terminated by a CR/LF
(carriage return/line feed) pair.
Flags used to modify the semantics of this function.
Can be a combination of the following values:
HTTP_ADDREQ_FLAG_ADD Adds the header if it does not exist. Used with
HTTP_ADDREQ_FLAG_REPLACE.
HTTP_ADDREQ_FLAG_ADD_IF_NEW Adds the header only if it does not already exist;
otherwise, an error is returned.
HTTP_ADDREQ_FLAG_COALESCE Coalesces headers of the same name.
HTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA Coalesces headers of the same name. For example, adding
"Accept: text/*" followed by "Accept: audio/*" with this
flag results in the formation of the single header
"Accept: text/*, audio/*". This causes the first header
found to be coalesced. It is up to the calling application
to ensure a cohesive scheme with respect to coalesced/
separate headers.
HTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON Coalesces headers of the same name using a semicolon.
HTTP_ADDREQ_FLAG_REPLACE Replaces or removes a header. If the header value is empty
and the header is found, it is removed. If not empty, the
header value is replaced.
Remarks
HttpAddRequestHeaders appends additional, free-format headers to the HTTP
request handle and is intended for use by sophisticated clients that need
detailed control over the exact request sent to the HTTP server.
Note that for basic HttpAddRequestHeaders, the application can pass in multiple
headers in a single buffer. If the application is trying to remove or replace a
header, only one header can be supplied in lpszHeaders.
Returns TRUE if successful, or FALSE otherwise. To get extended error information, call
GetLastError.
Ends an HTTP request that was initiated by HttpSendRequestEx.
Params:HINTERNET handle returned by HttpOpenRequest and sent by HttpSendRequestEx.
Unsigned long integer value that contains the flags that control this
function. Can be one of the following values:
HSR_ASYNC Identical to WININET_API_FLAG_ASYNC.
HSR_SYNC Identical to WININET_API_FLAG_SYNC.
HSR_USE_CONTEXT Identical to WININET_API_FLAG_USE_CONTEXT.
HSR_INITIATE Iterative operation (completed by HttpEndRequest).
HSR_DOWNLOAD Download resource to file.
HSR_CHUNKED Send chunked data.
Unsigned long integer variable that contains the application-defined context
value for applications that register a status callback function.
Returns TRUE if successful, or FALSE otherwise. To get extended error
information, call GetLastError.
Creates an HTTP request handle.
Params:HINTERNET handle to an HTTP session returned by InternetConnect.
Verb to use in the request. If this parameter is NULL, the function uses GET as the verb.
Name of the target object of the specified verb. This is generally a file name,
an executable module, or a search specifier.
HTTP version. If this parameter is NULL, the function uses HTTP/1.0 as the version.
URL of the document from which the URL in the request (lpszObjectName) was obtained.
If this parameter is NULL, no "referrer" is specified.
Media types accepted by the client. If NULL, no types are accepted by the client.
Servers interpret a lack of accept types to indicate that the client accepts only documents
of type "text/*" (that is, only text documents, and not pictures or other binary files).
For a listing of valid media types, see Media Types at
ftp.isi.edu/in-notes/iana/assignments/media-types/media-types.
Unsigned long integer value that contains the Internet flag values. This can be any of the
following values:
INTERNET_FLAG_CACHE_IF_NET_FAIL
INTERNET_FLAG_HYPERLINK
INTERNET_FLAG_IGNORE_CERT_CN_INVALID
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS
INTERNET_FLAG_KEEP_CONNECTION
INTERNET_FLAG_NEED_FILE
INTERNET_FLAG_NO_AUTH
INTERNET_FLAG_NO_AUTO_REDIRECT
INTERNET_FLAG_NO_CACHE_WRITE
INTERNET_FLAG_NO_COOKIES
INTERNET_FLAG_NO_UI
INTERNET_FLAG_PRAGMA_NOCACHE
INTERNET_FLAG_RELOAD
INTERNET_FLAG_RESYNCHRONIZE
INTERNET_FLAG_SECURE
Address of an unsigned long integer value that contains the application-defined value that
associates this operation with any application data.
Remarks
HttpOpenRequest creates a new HTTP request handle and stores the specified parameters in that
handle. An HTTP request handle holds a request to be sent to an HTTP server and contains all
RFC822/MIME/HTTP headers to be sent as part of the request.
Beginning with Microsoft(r) Internet Explorer 5, if lpszVerb is set to "HEAD", the Content-Length
header is ignored on responses from HTTP/1.1 servers.
Returns a valid (non-NULL) HTTP request handle if successful, or NULL otherwise. To get
extended error information, call GetLastError.
Retrieves header information associated with an HTTP request.
Params:HINTERNET request handle returned by HttpOpenRequest or InternetOpenUrl.
Unsigned long integer value that contains a combination of an attribute to retrieve and the flags
that modify the request. The attribute can be any one of the Attributes, and the flag can be any
one of the Modifiers on the Query Info Flags page.
Buffer that receives the information.
Remarks
You can retrieve different types of data from HttpQueryInfo:
* Strings (default)
* SYSTEMTIME (for Data: Expires:, headers)
* DWORD (for STATUS_CODE, CONTENT_LENGTH, and so on, if HTTP_QUERY_FLAG_NUMBER has been used)
If your application needs the data returned as a data type other than a string, you must include the
appropriate modifier with the attribute passed to dwInfoLevel.
Returns data if successful, or FALSE otherwise. To get extended error information, call
GetLastError.
bRet = HttpQueryInfo(hResource, HTTP_QUERY_RAW_HEADERS_CRLF, lpvSomeBuffer)
Sends the specified request to the HTTP server.
Params:HINTERNET handle returned by HttpOpenRequest.
String variable that contains the additional headers to be appended to the request.
This parameter can be NULL if there are no additional headers to append.
Optional data to send immediately after the request headers.
This parameter is generally used for POST and PUT operations. The optional data can be the
resource or information being posted to the server. This parameter can be NULL if there is no
optional data to send.
Remarks
HttpSendRequest sends the specified request to the HTTP server and allows the client to specify
additional headers to send along with the request.
The function also lets the client specify optional data to send to the HTTP server immediately
following the request headers. This feature is generally used for "write" operations such as PUT and
POST.
After the request is sent, the status code and response headers from the HTTP server are read. These
headers are maintained internally and are available to client applications through the
HttpQueryInfo function.
An application can use the same HTTP request handle in multiple calls to HttpSendRequest, but
the application must read all data returned from the previous call before calling the function again.
In offline mode, HttpSendRequest will return ERROR_FILE_NOT_FOUND if the resource is
not found in the Internet cache.
Returns TRUE if successful, or FALSE otherwise. To get extended error information, call
GetLastError.
Sends the specified request to the HTTP server and allows chunked transfers.
Params:HINTERNET handle returned by HttpOpenRequest.
Optional. Address of an INTERNET_BUFFERS structure.
Optional. Address of an INTERNET_BUFFERS structure.
One of the following values:
HSR_ASYNC Identical to WININET_API_FLAG_ASYNC.
HSR_SYNC Identical to WININET_API_FLAG_SYNC.
HSR_USE_CONTEXT Identical to WININET_API_FLAG_USE_CONTEXT.
HSR_INITIATE Iterative operation (completed by HttpEndRequest).
HSR_DOWNLOAD Download resource to file.
HSR_CHUNKED Send chunked data.
Unsigned long integer variable that contains the application-defined context value, if a status
callback function has been registered.
Returns TRUE if successful, or FALSE otherwise. To get extended error information, call
GetLastError.
URL to get cookies for.
Name of the cookie to get for the specified URL. This has not been implemented in this release.
Remarks
InternetGetCookie does not require a call to InternetOpen.
InternetGetCookie checks in the windows\cookies directory for persistent
cookies that have an expiration date set sometime in the future.
InternetGetCookie also searches memory for any session cookies (cookies
that do not have an expiration date) that were created in the same process
by InternetSetCookie, since these cookies are not written to any files.
Rules for creating cookie files are internal to Win32(r) Internet functions
and might change in the future.
Returns TRUE if successful, or FALSE otherwise. To get a specific error
value, call GetLastError. The following error values apply to
InternetGetCookie:
ERROR_NO_MORE_ITEMS There is no cookie for the specified URL and
all its parents.
ERROR_INSUFFICIENT_BUFFER The value passed in lpdwSize is insufficient
to copy all the cookie data. The value returned
in lpdwSize is the size of the buffer
necessary to get all the data.
Creates a cookie associated with the specified URL.
Params:URL for which the cookie should be set.
Name to associate with the cookie data. If this parameter is NULL, no name is associated with the cookie.
Actual data to associate with the URL.
Remarks
Cookies created by InternetSetCookie without an expiration date are stored
in memory and are available only in the same process that created them.
Cookies that include an expiration date are stored in the windows\cookies
directory.
Creating a new cookie might cause a dialog box to appear on the screen if
the appropriate registry value, AllowCookies, is set. There is no way to
change the registry value from a Win32(r) Internet function.
Returns TRUE if successful, or FALSE otherwise. To get a specific error
message, call GetLastError.