FTP

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:

EventEmitter

Source:

index.js, line 43

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
Handle
SimpleQueue

Namespaces

debug

Members

(static) CMD :object

The command module

Type:

object

Source:

index.js, line 109

ascii :array

List of files to get and put in ASCII

Type:

array

Source:

index.js, line 138

baseDir :boolean

Set when the next transfer is data and not file specific.

Type:

boolean

Source:

index.js, line 259

baseDir :string

The user defined directory set by the FTP admin.

Type:

string

Source:

index.js, line 252

config :string

The FTP log in information.

Type:

string

Source:

index.js, line 232

currentType :string

Holds the current file transfer type [ascii, binary, ecbdic, local]

Type:

string

Source:

index.js, line 132

cwd :string

Current working directory.

Type:

string

Source:

index.js, line 245

dataTransferHook :object

Stored procedures for data transfer types; automatically managed.

Type:

object

Source:

index.js, line 273

dataTransferTypes :array

A list of registered data transfer types; happens automatically.

Type:

array

Source:

index.js, line 266

isReady :boolean

Set once the ftp connection is established

Type:

boolean

Source:

index.js, line 190

pipe :object

Refernce to the socket created for data transfers

Type:

object

Source:

index.js, line 197

pipeAborted :object

Set by the ftp.abort method to tell the pipe to close any open data connection

Type:

object

Source:

index.js, line 204

pipeActive :object

Set by the ftp.put method while the pipe is connecting and while connected

Type:

object

Source:

index.js, line 218

pipeClosed :object

Set by the ftp.openDataPort method to tell the process that the pipe has been closed

Type:

object

Source:

index.js, line 211

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:

index.js, line 522

Fires:

FTP#event:queueEmpty

(readonly) secondTypeMap :string

Type:

string

Properties:

Name	Type	Description
`nonprint`	string
`telnet`	string
`asa`	string

Source:

index.js, line 2004

socket :object

Refernce to the socket created for data transfers

Type:

object

Source:

index.js, line 225

socket

Holds the connected socket object

Source:

index.js, line 958

(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:

index.js, line 1992

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:

index.js, line 99

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:

index.js, line 1457

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:

index.js, line 1421

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:

index.js, line 957

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:

index.js, line 938

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:

index.js, line 1742

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:

index.js, line 1482

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:

index.js, line 1403

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:

index.js, line 1882

init()

Ran at beginning to start a connection, can be overriden

Source:

index.js, line 313

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:

index.js, line 1721

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:

index.js, line 1775

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:

index.js, line 1245

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:

index.js, line 2022

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:

index.js, line 985

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:

index.js, line 1805

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:

index.js, line 1819

ping(callback, runLevel, holdQueueopt)

Runs the FTP command NOOP – Do nothing; Keeps the connection from timing out

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:

index.js, line 1857

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:

index.js, line 1833

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:

index.js, line 1036

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:

index.js, line 1845

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:

index.js, line 1211

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:

index.js, line 1896

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:

index.js, line 1329

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:

index.js, line 1226

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:

index.js, line 488

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:

index.js, line 451

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:

index.js, line 465

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:

index.js, line 1495

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:

index.js, line 1953

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:

index.js, line 2034

To Do:

- This still needs to be added – should create an object of methods

size(filepath, callback)

Runs the FTP command SIZE – Name list of remote directory.

Parameters:

Name	Type	Description
`filepath`	string	The location of the file to retrieve size from.
`callback`	function	The callback function to be issued.

Source:

index.js, line 1784

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:

index.js, line 1870

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:

index.js, line 1924

unlink(filepath, callback, runLevel, holdQueueopt)

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:

index.js, line 1443

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