As a developer, you have two main tools at your disposal for interacting with JuiceSSH from your plugin.


     PluginClient -  A library for launching and interacting with existing JuiceSSH connections.
     PluginContract - A content provider contract for CRUD (create, read, update, delete) operations on the JuiceSSH database. 


If your plugin only manipulates the JuiceSSH database (e.g. creating/deleting connections) then you do not need to worry about implementing the PluginClient or any of the methods documented here. You’ll want the <PluginContract> content provider documentation located here.


PluginClient Overview

The following diagram shows the flow of a plugin that:

  • Binds to the PluginClient service with PluginClient.start()
  • Queries the JuiceSSH database for a connection and it’s ID
  • Launches a JuiceSSH session to that connection. This will:
    • Pass control back to JuiceSSH
    • JuiceSSH will launch the session and deal with all authentication (two-factor, private keys etc)
    • Once connected, JuiceSSH will return control back to the plugin and pass a unique session id (integer) and session key (string)
    • This session id and key are required to further interact with the JuiceSSH session
  • Runs a command on the JuiceSSH session. This will:
    • Spawn a new “exec” channel on the SSH session
    • Execute the command required
    • Return the exit status code of the command via OnSessionExecuteListener.onCompleted(int returnCode)
    • Returns the stdout output of the command line by line via OnSessionExecuteListener.onOutputLine(String line)
  • Disconnects the JuiceSSH session
  • Stops/unbinds the PluginClient




Initiating a new PluginClient

To start using the JuiceSSH PluginClient in your project, just define the following class field:
final PluginClient client = new PluginClient();


public void start(Context context, OnClientStartedListener listener);


@param context  ( Context )  Context for which to start the PluginService with.

@param listener  ( OnClientStartListener )  Listener for returning service start status


This method should be called in your Activity.onStart();
It binds to the JuiceSSH PluginService and calls OnClientStartedListener.onClientStarted() once connected.
If you have a “Connect” button or similar in your plugin, you should have it disabled by default, and enable it inside OnClientStartedListener.onClientStarted();
This prevents situations where the user of the plugin trying to connect before the plugin has bound to the JuiceSSH plugin service.

Example:

class MyActivity extends Activity {
 
  final PluginClient client = new PluginClient();

  @Override
  protected void onStart() {
    super.onStart();

    client.start(this, new OnClientStartedListener() {
      @Override
      public void onClientStarted() {
          connectButton.setEnabled(true);
      }

      @Override
      public void onClientStopped() {
          connectButton.setEnabled(false);
      }
    });
  } 

For a full working example please see the following example project: https://github.com/Sonelli/juicessh-exampleplugin/


public void connect(Activity activity, UUID connectionId, OnSessionStartedListener listener, int requestId);


@param activity  ( Activity )  Context used for launching the connect action.

@param connectionId  ( UUID )  Unique Connection ID, found by querying the content provider.

@param listener  ( OnSessionStartedListener )  Listener used for returning sessionId and sessionKey.

@param requestId  ( int )  Request ID used when starting connection activity for result.


The PluginClient has the ability to launch JuiceSSH sessions.

All JuiceSSH sessions started by the PluginClient are launched in the background.

If you want to bring the session to the foreground you need to use the PluginClient.attach(sessionId, sessionKey) method.


The process is asynchronous - it will take an indeterminate amount of time as the user may be required to authenticate and action any keyboard-interactive authentication steps.
When the connection is connected you will receive a callback on the OnSessionStartedListener.onSessionStarted(int sessionId, String sessionKey).
You can use this session identifier and key to further interact with the JuiceSSH session (e.g. to run commands and disconnect the session).


public void gotActivityResult(int requestCode, int resultCode, Intent data);


@param requestCode  ( int )  Request code matching one of the previously used request codes when initiating a connect request.

@param resultCode  ( int )  Activity result status.

@param data  ( data )  Activity result bundle.


In order for the above onSessionStarted() callback to function properly, the JuiceSSH plugin client utilises the onResultForActivity() functionality within Android.

In your activity class you will need to implement the following in order to pass the required information back to the JuiceSSH plugin client:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);

    // This is important if you want to be able to interact with JuiceSSH sessions that you
    // have started otherwise the plugin won't have access.
    if(requestCode == MY_JUICESSH_REQUEST_ID){
        client.gotActivityResult(requestCode, resultCode, data);
    }
} 

If you fail to implement the above method in your activity, then the OnSessionStartedListener.onSessionStarted(int sessionId, String sessionKey) callback will never be called.
If your plugin only launches connections and never needs to interact or disconnect them, then you do not need to implement this method.


public void addOnSessionFinishedListener(int sessionId, String sessionKey, OnSessionFinishedListener listener);


@param sessionId  ( int )  Session ID of finishing session

@param sessionKey  ( String )  Session Key of finishing session

@param listener  ( OnSessionFinishedListener )  listens for end of session events.


You can use this method to add a callback listener for when session are disconnected or closed (e.g. by network comms, or manually by the user).


public void attach(int sessionId, String sessionKey);


@param sessionId  ( int )  The session ID of the connection you wish to attach to.

@param sessionKey  ( String ) The session key of the connection you wish to attach to.


Brings a previously established JuiceSSH session to the foreground.


public void executeCommandOnSession(int sessionId, String sessionKey, String command, OnSessionExecuteListener listener);


@param sessionId  ( int )  The session ID of the connection you wish to run a command on.

@param sessionKey  ( String )  The session key of the connection you wish to run a command on.

@param command  ( String )  The command you want to run on the session.

@param listener  ( OnSessionExecuteListener )  Receives callbacks for command exit status code and any stdout lines outputted by the command.


Executes a command on a new ‘exec’ channel of an existing SSH connection.


public void disconnect(int sessionId, String sessionKey);


@param sessionId  ( int )  The session ID of the connection you wish to disconnect

@param sessionKey  ( String ) The session key of the connection you wish to disconnect


Disconnects a JuiceSSH session.


public void stop(Activity activity);


@param activity  ( Activity )  Activity context used for unbinding from the JuiceSSH PluginService


Unbinds from the JuiceSSH plugin service.
You should call this in your Activity.onStop() method.