MsgPlus::UploadFileFTP

The MsgPlus::UploadFileFTP function uploads a file asynchronously to a FTP server. An event is automatically generated when the upload is complete. The function can also be used to test an FTP connection without uploading anything.

Syntax

[boolean] UploadFileFTP(
    [string] SourceFile,
    [string] Server,
    [string] User,
    [string] Password,
    [string] Destination,
    [boolean,optional] PassiveMode,
    [number,optional] Port
);

Parameters

SourceFile

[string] Full path of the file to upload. The file must exist for the upload to succeed. If an empty string is sent in this parameter, the function only checks if the FTP server can be contacted properly.

Server

[string] Host name of the FTP server. It can be an IP address.

User

[string] User name sent to the server to log on.

Password

[string] Password sent to the server to log on.

Destination

[string] Name of the file to create on the FTP server. If SourceFile is empty, this parameter represents the path to check on the server (it can be empty). See remarks.

PassiveMode

[boolean,optional] Specifies if passive mode should be used to connect to the server. Default is true.

Port

[number,optional] Port to connect to on the FTP server. Default is 21.

Return Value

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

• The specified SourceFile does not exist.
• The specified Server is empty.
• The specified Destination is empty and a SourceFile is specified.
• Not enough system resources to complete the operation.

Remarks

It is highly recommended to use this function whenever your script needs to upload a file to a FTP server. This function returns as soon as the upload 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 uploading a file on an external server. If the upload 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.

When uploading a file, the specified destination can include a path valid on the server. For example, to create a file called "newfile.dat" in "/dir1/dir2", you would need to specify "/dir1/dir2/newfile.dat" in the Destination parameter. Note that if a path is specified, it must exist on the server. Directories are not created by this function. If a file already exists on the server at the specified destination, it is deleted before the upload of the new file begins. When testing an FTP connection, only directories can be specified here, if needed, to check if a given path exists on the server.

Example

Here is an example that shows how to upload a file to a known FTP server.

function UploadFileToServer(SrcFile)
{
	var Started = MsgPlus.UploadFileFTP(SrcFile, "ftp.srv.com", "user", "pwd", "dest.dat");
	if(Started)
		Debug.Trace("Uploading file, waiting for event");
	else	
		Debug.Trace("Couldn't start the upload");
}

function OnEvent_UploadFileComplete(Server, Destination, Source, Success)
{
	Debug.Trace("UploadFileComplete event received for " + Destination);
	Debug.Trace("   Success: " + Success);
}

Function Information

See Also

MsgPlus Object, OnEvent_UploadFileComplete.