MsgPlus::DownloadFile

The MsgPlus::DownloadFile function downloads a file asynchronously from an ftp, http or https source and generates an event when the download is complete.

Syntax

[boolean] DownloadFile(
    [string] Url,
    [string,optional] OutFile,
    [string,optional] User,
    [string.optional] Password
);

Parameters

Url

[string] Address of the file to download. The string must begin by either "ftp://", "http://" or "https://".

OutFile

[string,optional] Full path to the file that will be created to receive the downloaded data. If no path is specified, Messenger Plus! automatically generates a unique file name in the user's temporary directory.

User

[string,optional] User name sent to the server to log on, valid only for FTP connections. This parameter requires Messenger Plus! Live version 4.60 or above.

Password

[string,optional] Password sent to the server to log on, valid only for FTP connections. This parameter requires Messenger Plus! Live version 4.60 or above.

Return Value

A boolean value specifying if the download was initiated. If the returned value is true, an OnEvent_DownloadFileComplete event will be generated once the download operation has completed (whether it succeeds or not). Here is a list of possible reasons why this function may return false:

• The specified Url is empty.
• Not enough system resources to complete the operation.

Remarks

It is highly recommended to use this function whenever your script needs to download a file. This function returns as soon as the download request has been sent to a different thread of execution, guaranteeing that Messenger will not freeze while the server is being contacted. It is important as various network issues can occur while downloading a file on an external server. If the download is done synchronously with another method, it can result in Messenger freezing for an unspecified amount of time, blocking the user, disturbing Messenger's own network communications and giving the impression that the whole application crashed.

If no path is specified in OutFile, a temporary file will be created and its path will be sent in parameter of OnEvent_DownloadFileComplete. Deleting the temporary file is your responsibility, Messenger Plus! will not do it automatically.

Example

Here is an example that shows how to download a file to check for updates.

function DownloadUpdateFile()
{
        var Started = MsgPlus.DownloadFile("http://server.com/file.txt");
        if(Started)
                Debug.Trace("Downloading file, waiting for event");
        else      
                Debug.Trace("Couldn't start the download");
}

function OnEvent_DownloadFileComplete(Url, OutFile, Success)
{
        Debug.Trace("DownloadFileComplete event received for " + Url);
        Debug.Trace("   Success: " + Success);
        if(Success)
        {
                Debug.Trace("   Result file path: " + OutFile);
                /* Read the file, do what needs to be done */
                
                //Delete the temporary file
                var File = new ActiveXObject("Scripting.FileSystemObject");
                File.DeleteFile(OutFile);
        }
}

Function Information

See Also

MsgPlus Object, OnEvent_DownloadFileComplete.