How to install

Include the plugin on your project executing the following command in the CLI

cordova plugin add https://github.com/sdkcarlos/cordova-ourcodeworld-sftpplugin.git

Remember that you need an active android platform, this plugin only is available on android. Then in your document a global variable will be accesible with OurCodeWorldSFTP

1) Create a SFTP Client

It's important to understand the structure of the plugin, to start a connection to a sftp server, we need to create a client which will be assigned to a variable.

// Now we have a sftp client in javascript ! Cool isn't ?
var client = OurCodeWorldSFTP.createSFTPClient();

We need to execute this code in (or after) the deviceready event.

2) Set authentication credentials

Without credentials we cannot access any server ! use setCredentials method first.

// Set the credentials like this : ip-sftp-server , your user, the password
client.setCredentials("00.000.00.00","user","password");
// or client.setCredentials("myserver.domain.com","user","password");

// If your sftp server doesn't use the port 22 you can change it with setCredentials method
// in this case we will change the port to the 21
client.setCredentials("00.000.00.00","user","password","21");

3) setPath & getPath

You need to store the remote path (default path will be /root if you don't change the path) in the client, this will be used to execute tasks like list a folder

// Set the relative remote path
client.setPath("/var/www/vhosts/myproject/");

//You can retrieve the active path with
console.log(client.getPath()); // Output: /var/www/vhosts/myproject/

Now you'll able to execute any of the functions of the plugin

List remote path

Get all the folders and files of the client path :

var client = OurCodeWorldSFTP.createSFTPClient();
// Or 
// client.setCredentials("0000.000.00","myuser","password");
client.setCredentials("myserver.something.com","myuser","password");
client.setPath("/var/www/vhosts/myproject");


/**
 * Receives an array with objects with all the content of a path (files and folders)
 */
var success = function(data) {
    console.info(data);
    /**
    Outputs : 
    [
        {
            name:"Folder/File name",
            filepath: "/var/www/vhosts/myproject/something.txt",
            isDir:false, // is Folder = true, is File = false
            isLink:false,
            size:"123", // bytes
            permissions: "????",
            permissions_string:"xxxxx",
        }
    ];
    */
}

// Oops .. something failed :| , may be the path ? or credentials ?
var failure = function(e) {
    console.error(e);
}

client.list(success, failure);

Download a file

Download a remote file to your device :

// Do not include file:// to the local path, you can change the local filename if you want
client.downloadFile("/var/www/vhosts/myproject/file.txt","/storage/emulated/0/file.txt",{
    success:function(download){
        // see the object info
        console.log(download);

        if(download.finished == true){
            console.info("The file has been succesfully downloaded");
        }else{
            //Display the progress
            console.log("Progress download : "+download.progress+"%. "+ download.bytesprogress +" bytes downloaded of " + download.filesizebytes + "total");
        }
    },
    error:function(er){
        // snap ! An error :(
        console.error(er);
    }
});

Upload a file

Upload a local file to the server :

// Do not include file:// to the local path, you can change the remote filename if you want
client.uploadFile("/storage/emulated/0/file.txt","/var/www/vhosts/myproject/file.txt",{
    success:function(download){
        // see the object info
        console.log(download);

        if(download.finished == true){
            console.info("The file has been succesfully uploaded");
        }else{
            //Display the progress
            console.log("Progress upload : "+download.progress+"%. "+ download.bytesprogress +" bytes uploaded of " + download.filesizebytes + "total");
        }
    },
    error:function(er){
        // snap ! An error :(
        console.error(er);
    }
});

Delete a remote file

Delete a remote file:

client.removeFile("/var/www/vhosts/myproject/file.txt",{
    success:function(removed){
        // see the object info
        console.log(removed);

        if(download.deleted == true){
            console.log("File removed from the server");
        }
    },
    error:function(er){
        // snap ! An error :( maybe doesnt exist?
        console.error(er);
    }
});

Using a private key to connect

If your server needs a Private key to connect, you can use setIdentity method, Public key authentication uses a public-private , your private key must use OpenSSH format.

var client = OurCodeWorldSFTP.createSFTPClient();
client.setCredentials("myserver.something.com","myuser","password");
client.setPath("/var/www/vhosts/myproject");
client.setIdentity("/storage/emulated/0/id_dsa.pub");

// Do anything what you want

Using a private key to connect

It's recommendable to set a Known Hosts file to your sftp connection, otherwise your connection can be victim of a Man In the Middle Attack (MITM), just use setKnownHosts method giving the path of the local file. If you don't use this file, the plugin will work anyway, but is better use a known hosts.

// Set local known_hosts file
client.setKnownHosts("/storage/emulated/0/known_hosts");