Usage

Introduction

Here is an overview of what methods are provided by the RootShell library and how to use them. Everything below is subject to change at any time, and it fact will be changing. This library is constantly evolving and becoming better. When we change things, we will try and make it as pain free for you as possible.

Including the Library in Eclipse

Including the RootShell library into your project so that you can utilize it is simple!

1. In Eclipse, right click your project, navigate to "Build Path", then to "configure build path"
2. Now choose "add External Jar"
3. Navigate to the RootShell.jar file you download and choose it.
4. Navigate to "Order and Export" make sure the box is ticked next to the library, and move it to the top of the list.
5. Finish up by choosing "ok"

Including the Library in Android Studio

1. In Android Studio, right click your project, navigate to "Open Module Settings", then to "libraries"
2. Click the "+" button and select "java"
3. Navigate to the RootShell.jar file you download and choose it.
4. Navigate to "Modules", select your projects module and then choose the tab "Dependencies"
5. Ensure that the library you just added is visible under dependencies. A. If not visible, click the "+" button, choose "libraries", and select the library you just added
6. Finish up by choosing "ok"

That's all there is to it! The library should now be ready for use in your Android project. Now that you have the library included into your Android project all you need to do is import it into the desired java file. You can do this by putting import com.stericson.RootShell.* OR import com.stericson.RootShell.RootShell at the top of your java file, right under the package name for your Android app.

Setting Debug Mode

To turn debug mode on and off, simply do the following in your app:

RootShell.debugMode = true; //ON

OR

RootShell.debugMode = false; //OFF

Using log()

This method allows you to output debug messages only when debug mode is on. This will allow you to add a debug option to your app, which by default can be left off for performance. However, when you need debugging information, a simple switch can enable it and provide you with detailed logging.

This method handles whether or not to log the information you pass it depending whether or not RootShell.debugMode is on. So you can use this and not have to worry about handling it yourself.

To use the log function you can do the following:

RootShell.log("this is a log message"); //The TAG for this log will be "RootShell"

OR

RootShell.log("OurTag", "this is a log message");

This method uses log.d by default since this is intended for debug code.

If you want to change the type of logging you can do so like this:

RootShell.log(TAG, msg, 3, null);

Here you can pass the TAG you want to use for the log, the message, the type of logging to perform, and the exception if you want.

The types available are as such:

1 = log.v

2 = log.e

3 = log.d

Checking for su

su is the binary that is used to grant root access. It being on the phone is usually a good sign that the phone is rooted. You can check for the su binary like so:

if (RootShell.isRootAvailable()) {
    // su exists, do something
} else {
    // do something else
}

Note that this only check that su exists. A more complete check can also be run:

if (RootShell.isAccessGiven()) {
    // your app has been granted root access
}

RootShell.isAccessGiven() not only checks that a device is rooted, it also calls su for your app, requests permission, and returns true if your app was successfully granted root permissions. This can be used as the first check in your app to make sure that you will be granted access when you need it.

Running root commands

Running a command as root is simple! Here is an example:

Command command = new Command(0, "echo this is a command", "echo this is another command");
RootShell.getShell(true).add(command);

You can see that with this command you can run as many commands as you want.

If you need to log the output from the commands or know when your command finishes you can do the following:

Command command = new Command(0, "echo this is a command", "echo this is another command")
{
	@Override
	public void commandOutput(int id, String line)
	{
            (Do something with the output here)

            //MUST call the super method when overriding!
            super.commandOutput(id, line);
	}

        @Override
	public void commandTerminated(int id, String reason) {
            (Do something here)
        }

        @Override
	public void commandCompleted(int id, int exitcode) {
            (Do something here)
        }

};
RootShell.getShell(true).add(command);