HTTP.Download

HTTP.Download ( 

string   URL,

string   Filename,

number   Mode = MODE_BINARY,

number   Timeout = 20,

number   Port = 80,

table    AuthData = nil,

table    ProxyData = nil,

function CallbackFunction = nil )

Description

Downloads a file from an Internet Web site.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for the download by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to download.

Filename

(string) The destination path and filename of the file you want to download. For example, C:\\MyFolder\\patch.zip.

Mode

(number) The mode you want to use to save the file. Choose from:

CONSTANT

VALUE

DESCRIPTION

MODE_BINARY

0

Save the file exactly as downloaded. (Default)

MODE_TEXT

1

Convert the file from Unix to Windows text mode, if necessary.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Note: Timeout values are interpreted in multiple ways during client server communication. As a result the actual timeout used by the connection may differ from the value specified.

Port

(number) The port to connect to. In most cases the default value of 80 is fine.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the download does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY

TYPE

DESCRIPTION

UserName

string

The user name to be used during HTTP authentication.

Password

string

The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)  

The table is indexed by the following keys:

KEY

TYPE

DESCRIPTION

PUserName

string

The proxy user name.

PPassword

string

The proxy password.

PServerAddress

string

The proxy server address.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the download operation. (You can use this callback function to display the progress of the download in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

BytesRead

(number) The number of bytes that have been downloaded so far.

FileSize

(number) The file size in bytes or 0 if the file size could not be retrieved from the server.

TransferRate

(number) The current transfer rate in Kilobytes per second.

SecondsLeft

(number) The estimated number of seconds left in the download.

SecondsLeftFormat

(string) The estimated number of seconds left formatted as a string in the form of: ""MM:SS".

Message

(string) Either a blank string ("") or an information message being sent by the server, such as "Resolving host name" or "Connecting to Server."

Note: If this parameter is not a blank string, it means that it is in a busy state, either before the download has begun, or at the end of the download. In this case all other parameters will be ignored.

The callback function should return a boolean value (true or false) indicating whether the download should continue:

VALUE

DESCRIPTION

true

Continue with the file download.

false

Stop the file download as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

See also:  Related Actions