Using the SashXB FTP Extension

The Sash.FTP extensions provides the most common FTP (File Transfer Protocol) functionality to weblication developers.

1. Sash.FTP

All Sash.FTP provides is a constructor for Sash.FTP.Connection and an error-handling event. All relevant functionality is in Sash.FTP.Connection.

Constructor
Connection	Create a new FTP connection.

Event	Receiver prototype	Description
onError	handler(`sashIFTPConnection` ftpconn, `string` errorMessage)	This event is called when an error occurs. For more specific error events, refer to Sash.FTP.Connection

2. Sash.FTP.Connection

Event	Receiver prototype	Description
OnFileSendStart	handler(`sashIFTPConnection` ftpConnection, `string` fileName)	Invoked when a file upload starts
OnFileReceiveStart	handler(`sashIFTPConnection` ftpConnection, `string` fileName)	Invoked when a file download starts
OnFileSent	handler(`sashIFTPConnection` ftpConn, `string` fName, `long` amountTransferred, `long` secondsElapsed)	Invoked when a file upload is finished
OnFileReceived	handler(`sashIFTPConnection` ftpConn, `string` fName, `long` amountTransferred, `long` secondsElapsed)	Invoked when a file download is finished
OnFileSendError	handler(`sashIFTPConnection` ftpConn, `string` fName, `string` errorMessage)	Signals if a file upload request failed
OnFileReceiveError	handler(`sashIFTPConnection` ftpConn, `string` fName, `string` errorMessage)	Signals if a file download failed
OnProgress	handler(`sashIFTPConnection` ftpConn, `string` fName, `long` amountTransferred, `long` secondsElapsed)	Invoked periodically to give updates on the progress of a file upload/download
OnStatusMessage	handler(`sashIFTPConnection` ftpConn, `string` statusMessage)	Periodically provides status messages about a connection
OnDefaultError	handler(`sashIFTPConnection` ftpConn, `string` errorMessage)	Signals when a non-fatal error occurs
OnFatalError	handler(`sashIFTPConnection` ftpConn, `string` errorMessage)	Signals when a fatal error occurs
OnLogin	handler(`sashIFTPConnection` ftpConn, `boolean` isSuccessful)	Invoked after a login request is processed. isSuccessful holds true if everything went fine, false otherwise
OnTimeout	handler(`sashIFTPConnection` ftpConn, `long` waitTime)	If NormalTimeout seconds have elapsed since the last time a command was sent to the FTP server, this event is triggered. The FTP connection may have been lost.
OnConnectionTimeout	handler(`sashIFTPConnection` ftpConn, `long` waitTime)	If ConnectionTimeout seconds have elapsed since a connection to the server was initiated, this event is triggered. The server may be unreachable.

Properties
`readonly boolean` Connected	This read-only boolean property holds true if the connection is currently active
`readonly boolean` LoggedIn	This read-only property is true if there is an active user on the connection
`readonly boolean` TimedOut	This read-only property is true if the connection timed out while waiting for a response from the FTP server.
`long` NormalTimeout	The number of seconds to wait for the FTP server to send a response to a command. If no response has been received after this amount of time has elapsed, an OnTimeout callback is made.
`long` ConnectionTimeout	The number of seconds to wait to make a connection to the FTP server. If no connection has been made after this amount of time has elapsed, an OnConnectionTimeout callback is made.
`long` NotifyInterval_K	Specifies how often OnProgress events are sent in terms of (integer) Kbytes downloaded / uploaded.
`long` NotifyInterval_S	Specifies how often OnProgress events are sent in terms of (integer) seconds.
`string` CurrentDirectory	Read-only string property that holds the current directory. The empty string signifies an error while reading the current directory
`boolean` IsASCII	Boolean property that specifies ASCII (true) or Binary (false) file transfer mode. NOTE: This is true by default, and cannot be changed to false until the connection is made and the user is logged on.
`boolean` ShowDotFiles	Boolean property that specifies whether dot files should be displayed in the file listings. Most FTP servers will not show dot files by default.
`boolean` IsPassive	Boolean property that specifies whether file transfer operations are passive (server specifies data port) or "active" (user specified server-side data port). NOTE: This property is currently read-only and is always true as Sash.FTP supports only passive connections
`boolean` IsTransferring	Read-only boolean property that specifies whether a file transfer is in progress
`string` Id	A string ID for the connection
`readonly array` TransferQueue	Read-only array of filenames that are pending transfer (both upload / download). Does not include files that are currently being transferred
Methods
`boolean` Connect(`string` remoteAddress [, `long` remotePort])	Opens a connection to the server specified by remoteAddress. The optional parameter remotePort specifies a port for the FTP connection (default 21)
`void` Disconnect()	Reinitializes the connection. Appropriate for closing the socket connection when a login attempt has failed. The Logout() method also disconnects the connection as well.
`void` Login(`string` username, `string` password)	Logs on to the server - the connection is not ready until an OnLogin event is received. Call only once after connecting
`boolean` Logout()	Disconnects from the server. Returns true on success.
`long` Get(`{string, array}` fileNames [, `string` localDirectory])	Initiates downloading of the files given in the array fileNames. If fileNames is just a string, transfers one file only. The optional parameter localDirectory specifies a target local directory for all transfers. Returns the number of files to be transferred
`long` Put(`{string, array}` fileNames [, `string` remoteDirectory])	Initiates uploading of the files given in the array fileNames. If fileNames is just a string, transfers one file only. The optional parameter remoteDirectory specifies a target server directory for all transfers. Returns the number of files to be transferred
`boolean` RemoveFromQueue(`{string, long}` file)	Removes a file from the transfer queue - does not stop transfers currently in progress. If file is an integer, it is used as an index in the queue, otherwise it should be a file name. Returns true on success
`boolean` Cd(`string` directory)	Changes the remote directory. Returns true on success
`array` List([`string` directory])	Returns the contents of a remote directory as an array of file names. If the optional argument is omitted acts on the current directory
`array` DetailedList([`string` directory ])	Same as List(), but returns strings that include file size, date etc. information
`boolean` Del(`string` fileName)	Deletes the remote file specified by fileName. Returns true on success
`boolean` Mkdir(`string` remoteDirName)	Creates a remote directory with name specified by remoteDirName. Returns true on success
`boolean` Rmdir(`string` remoteDirName)	Deletes the remote directory specified by remoteDirName. Returns true on success
`boolean` Rename(`string` oldFileName, `string` newFileName)	Renames (moves) the remote file oldFileName to newFileName. Returns true on success
`boolean` StopCurrentTransfer()	Aborts the transfer currently in progress. Returns true on success

3. Quick example

This is a quick example of how to make a connection and download a file, with no error handling whatsoever.


function OnLuck(ftpConn, isOK) {
	if (isOK) ftpConn.Get('files.X');
}

function WhenDone(ftpConn, fname) {
	// Delete the remote copy of the file.
	ftpConn.Del(fname);
	ftpConn.Logout();
}

var conn= new Sash.FTP.Connection();
conn.OnLogin= OnLuck;
conn.OnFileReceived= WhenDone;
conn.Connect('ftp.fbi.gov');
conn.Login('mulder', 'scully');

Wing Yung, Stefan Atev

Last modified: Tue Jun 11 17:03:47 EDT 2002