Class: FTP

FTP

new FTP(config, connect)

The main FTP API object
Parameters:
Name Type Description
config null | object The ftp connection settings (optional)
connect boolean Whether or not to start the connection automatically; default is true;
Mixes In:
Source:
To Do:
  • The major functions have been added and this current version is more stable and geared for asynchronous NodeJS. The following commands need to be added:
  • Add FTP.stou
  • Add FTP.rein
  • Add FTP.site
  • Add FTP.mode
  • Add FTP.acct
  • Add FTP.appe
  • Add FTP.help
  • Add ability to opt into an active port connection for data transfers FTP extends the NodeJS EventEmitter - see

Classes

Queue
StatObject
StatObject.Dummy
Handle
SimpleQueue

Namespaces

debug

Members

(static) CMD :object

The command module
Type:
  • object
Source:

ascii :array

List of files to get and put in ASCII
Type:
  • array
Source:

baseDir :string

The user defined directory set by the FTP admin.
Type:
  • string
Source:

config :string

The FTP log in information.
Type:
  • string
Source:

currentType :string

Holds the current file transfer type [ascii, binary, ecbdic, local]
Type:
  • string
Source:

cwd :string

Current working directory.
Type:
  • string
Source:

isReady :boolean

Set once the ftp connection is established
Type:
  • boolean
Source:

pipe :object

Refernce to the socket created for data transfers
Type:
  • object
Source:

pipeAborted :object

Set by the ftp.abort method to tell the pipe to close any open data connection
Type:
  • object
Source:

pipeActive :object

Set by the ftp.put method while the pipe is connecting and while connected
Type:
  • object
Source:

pipeClosed :object

Set by the ftp.openDataPort method to tell the process that the pipe has been closed
Type:
  • object
Source:

queue :object

Establishes a queue to provide synchronicity to ftp processes that would otherwise fail from concurrency. This function is done automatically when using the FTP#run method to queue commands.
Type:
  • object
Properties:
Name Type Description
queue._queue array Stores registered procedures and holds them until called by the queue.run method
queue.processing boolean Returns true if there are items running in the queue
queue.register function Registers a new callback function to be triggered after the queued command completes
queue.run function If there is something in the queue and queue.processing is false, than the first item stored in queue._queue will be removed from the queue and processed.
Source:
Fires:

(readonly) secondTypeMap :string

Type:
  • string
Properties:
Name Type Description
nonprint string
telnet string
asa string
Source:

socket :object

Refernce to the socket created for data transfers
Type:
  • object
Source:

socket

Holds the connected socket object
Source:

(readonly) typeMap :string

Values that are used with FTP#setType and FTP#type to set the transfer type of data
Type:
  • string
Properties:
Name Type Description
ascii string
binary string
ebcdic string
local string
Source:

Methods

(static) create(config, connect) → {object}

Initializes the main FTP sequence ftp will emit a ready event once the server connection has been established
Parameters:
Name Type Description
config null | object The ftp connection settings (optional)
connect boolean Whether or not to start the connection automatically; default is true;
Source:
Returns:
FTP - return new FTP instance object
Type
object

abort(callback)

Runs the FTP command ABOR - Abort a file transfer, this takes place in parallel
Parameters:
Name Type Description
callback function The callback function to be issued.
Source:

chdir(dirpath, callback, runLevel, holdQueueopt)

Runs the FTP command CWD - Change Working Directory
Parameters:
Name Type Attributes Default Description
dirpath string The directory name to change to.
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

connect(callback)

Creates a new socket connection for sending commands to the ftp server and runs an optional callback when logged in
Parameters:
Name Type Description
callback function The callback function to be issued. (optional)
Source:

exit(sig)

Logout from the ftp server
Parameters:
Name Type Description
sig number the signal code, if not 0, then socket will be destroyed to force closing
Source:

filemtime(filepath, callback) → {number}

Runs the FTP command MDTM - Return the modification time of a file
Parameters:
Name Type Description
filepath string The location of the remote file to stat.
callback function The callback function to be issued.
Source:
Returns:
filemtime - File modified time in milliseconds
Type
number
Example
//getting a date object from the file modified time
ftp.filemtime('foo.js', function (err, filemtime) {
    if (err) {
        dbg(err);
    } else {
        dbg(filemtime);
        //1402849093000
        var dateObject = new Date(filemtime);
        //Sun Jun 15 2014 09:18:13 GMT-0700 (PDT)
    }
});

get(filepath, callback)

Runs the FTP command RETR - Retrieve a remote file
Parameters:
Name Type Description
filepath string The location of the remote file to fetch.
callback function The callback function to be issued.
Source:

getcwd(callback, runLevel, holdQueueopt)

Runs the FTP command PWD - Print Working Directory
Parameters:
Name Type Attributes Default Description
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

info(callback, runLevel, holdQueueopt)

Runs the FTP command SYST - return system type
Parameters:
Name Type Attributes Default Description
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

init()

Ran at beginning to start a connection, can be overriden
Source:
Example
//Overriding the ftpimp.init instance method
var FTP = require('ftpimp'),
    //get connection settings
    config = {
        host: 'localhost',
        port: 21,
        user: 'root',
        pass: ''
    },
    ftp,
    //override init
    MyFTP = function(){
        this.init();
    };
//override the prototype
MyFTP.prototype = FTP.prototype;
//override the init method
MyFTP.prototype.init = function () {
    dbg('Initializing!');
    ftp.handle = ftp.Handle.create();
    ftp.connect();
};
//start new MyFTP instance
ftp = new MyFTP(config);

ls(filepath, callback, runLevel)

Runs the FTP command LIST - List remote files
Parameters:
Name Type Description
filepath string The location of the remote file or directory to list.
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
Source:

lsnames(dirpath, callback)

Runs the FTP command NLST - Name list of remote directory.
Parameters:
Name Type Description
dirpath string The location of the remote directory to list.
callback function The callback function to be issued.
Source:

mkdir(dirpath, callback, recursive, runLevel, holdQueueopt)

Runs the FTP command MKD - Make a remote directory. Creates a directory and returns the directory name. Optionally creates directories recursively.
Parameters:
Name Type Attributes Default Description
dirpath string The directory name to be created.
callback function The callback function to be issued.
recursive boolean Recursively create directories. (default: false)
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

mode(type)

Runs the FTP command MODE - Set transfer mode (default Stream) - will be added in next patch
Parameters:
Name Type Description
type string set to this type: 'stream', 'block', 'compressed'
Source:
To Do:
  • - This still needs to be added - should create an object of methods

openDataPort(callback, runLevel)

Opens a new data port to the remote server - pasv connection which allows for file transfers
Parameters:
Name Type Description
callback function The callback function to be issued
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
Source:
To Do:
  • Add in useActive parameter to choose how to handle data transfers

pass(pass, callback, holdQueueopt)

Runs the FTP command PASS - Send password.
Parameters:
Name Type Attributes Default Description
pass string The password for the user.
callback function The callback function to be issued.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

pasv(pasv, callback, runLevel, holdQueueopt)

Runs the FTP command PASV - Open a data port in passive mode.
Parameters:
Name Type Attributes Default Description
pasv string The pasv parameter a1,a2,a3,a4,p1,p2 where a1.a2.a3.a4 is the IP address and p1*256+p2 is the port number
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

ping(callback, runLevel, holdQueueopt)

Runs the FTP command NOOP - Do nothing; Keeps the connection from timing out; determine latency(ms), the latency will be passed as the data(second) parameter of the callback
Parameters:
Name Type Attributes Default Description
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

port(port, callback, runLevel, holdQueueopt)

Runs the FTP command PORT - Open a data port in active mode.
Parameters:
Name Type Attributes Default Description
port string The port parameter a1,a2,a3,a4,p1,p2. This is interpreted as IP address a1.a2.a3.a4, port p1*256+p2.
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

put(paths, callback)

Asynchronously queues files for transfer, and transfers them in order to the server.
Parameters:
Name Type Description
paths string | array The path to read and send the file, if you are sending to the same (relative) location you are reading from then you can supply a string as a shortcut. Otherwise, use an array [from, to]
callback function The callback function to be issued once the file has been successfully written to the remote
Source:
To Do:
  • - rewrite needed, can be simplified at this point

quit(callback, runLevel, holdQueueopt)

Runs the FTP command QUIT - Terminate the connection.
Parameters:
Name Type Attributes Default Description
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

raw(command, callback)

Issues a single raw request to the server and calls the callback function once data is received
Parameters:
Name Type Description
command string The command to send to the FTP server
callback function The callback function to be fired once on a data event
Source:
Example
//say hi to the server
var FTP = require('ftpimp'),
    config = require('./myconfig'),
    ftp = FTP.connect(config);

ftp.on('ready', function () {
    ftp.raw('NOOP', function (data) {
        dbg(data);
    });
});

rename(paths, callback, runLevel, holdQueueopt)

Runs the FTP command RNFR and RNTO - Rename from and rename to; Rename a remote file
Parameters:
Name Type Attributes Default Description
paths array The path of the current file and the path you wish to rename it to; eg: ['from', 'to']
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

rmdir(dirpath, callback, recursive, runLevel, holdQueueopt)

Runs the FTP command RMD - Remove a remote directory
Parameters:
Name Type Attributes Default Description
dirpath string The location of the directory to be deleted.
callback function The callback function to be issued.
recursive string Recursively delete files and subfolders.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

root(callback, runLevel, holdQueueopt)

Changes the current directory to the root / restricted directory
Parameters:
Name Type Attributes Default Description
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

run(command, callback, runLevelopt, holdQueueopt)

Run a raw ftp command and issue callback on success/error.
Functions created with this provide a sequential queue that is asynchronous, so items will be processed in the order they are received, but this will happen immediately. Meaning, if you make a dozen sequential calls of "ftp.run('MDTM', callback);" they will all be read immediately, queued in order, and then processed one after the other. Unless you set the optional parameter runLevel to true
Parameters:
Name Type Attributes Default Description
command string The command that will be issued ie: "CWD foo"
callback function The callback function to be issued on success/error
runLevel number <optional>
 0 TL;DR see Queue.RunLevels FTP#run will invoke a queueing process, callbacks will be stacked to maintain synchronicity. How they stack will depend on the value you set for the runLevel
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

runNext(command, callback, holdQueueopt)

Run a raw ftp command and issue callback on success/error. Same as FTP#run except this command will be will be prioritized to be the next to run in the queue. - calls made with this provide a sequential queue
Parameters:
Name Type Attributes Default Description
command string The command that will be issued ie: "CWD foo"
callback function The callback function to be issued on success/error
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

runNow(command, callback, holdQueueopt)

Run a raw ftp command and issue callback on success/error. Same as FTP#run except this command will be ran immediately (in parallel) and will overrun any current queue action in place.
Parameters:
Name Type Attributes Default Description
command string The command that will be issued ie: "CWD foo"
callback function The callback function to be issued on success/error
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

save(paths, callback)

Runs the FTP command RETR - Retrieve a remote file and then saves the file locally
Parameters:
Name Type Description
paths string | array An array of [from, to] paths, as in read from "remote/location/foo.txt" and save to "local/path/bar.txt"
if you are saving to the same relative location you are reading from then you can supply a string as a shortcut.
callback function The callback function to be issued.
Source:

setType(runLevel, holdQueueopt)

Sets the type of file transfer that should be used based on the path provided
Parameters:
Name Type Attributes Default Description
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

site(command, parameters, runLevel, holdQueueopt)

Runs the FTP command SITE - Run site specific command - will be added in next patch
Parameters:
Name Type Attributes Default Description
command string The command that will be issued
parameters string The parameters to be passed with the command
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:
To Do:
  • - This still needs to be added - should create an object of methods

size(filepath, callback)

Runs the FTP command SIZE - Get size of remote file
Parameters:
Name Type Description
filepath string The location of the file to retrieve size from.
callback function The callback function to be issued.
Source:

stat(callback, runLevel, holdQueueopt)

Runs the FTP command STAT - Return server status
Parameters:
Name Type Attributes Default Description
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

type(type, secondType, runLevel, holdQueueopt)

Runs the FTP command TYPE - Set transfer type (default ASCII) - will be added in next patch
Parameters:
Name Type Attributes Default Description
type string set to this type: 'ascii', 'ebcdic', 'binary', 'local'
secondType string 'nonprint', 'telnet', 'asa'
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:
Runs the FTP command DELE - Delete remote file
Parameters:
Name Type Attributes Default Description
filepath string The location of the file to be deleted.
callback function The callback function to be issued.
runLevel boolean execution priority; @see FTP.Queue.RunLevels.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

user(username, callback, holdQueueopt)

Runs the FTP command USER - Send username.
Parameters:
Name Type Attributes Default Description
username string The name of the user to log in.
callback function The callback function to be issued.
holdQueue boolean <optional>
 false Prevents the queue from firing an endproc event, user must end manually
Source:

Events

fileTransferComplete

Fired when we receive a remote acknowledgement of the files successful transfer
Source:

queueEmpty

Fired when the primary queue is empty
Source: