Usage

Introduction

Here is an overview of what methods are provided by the RootTools 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.

For more information on methods available within the RootTools Library please look at this Javadoc:

http://roottools.googlecode.com/svn/trunk/Developmental/doc/index.html

Including the Library in Eclipse

Including the RootTools 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 RootTools .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"

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.RootTools.* OR import com.stericson.RootTools.RootTools 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:

RootTools.debugMode = true; //ON

OR

RootTools.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 RootTools.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:

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

OR

RootTools.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:

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 busybox

Busybox is quite possibly the single most useful and versitile tool in the root developer's arsenal. The problem is that not every ROM has busybox installed by default. The RootTools library has a method for checking for busybox. Using it is as simple as:

if (RootTools.isBusyboxAvailable()) {
    // busybox exists, do something
} else {
    // do something else
}

It is recommended that if busybox is not found that you alert the user to this and give them the a way to install it, usually with the [http://market.android.com/details?id=stericson.busybox BusyBox] app from the market. !RootTools provides an easy way to go about this. You have two options:

RootTools.offerBusyBox(activity);

or

Intent intent = RootTools.offerBusyBox(activity, requestCode);

The first method simply launches an intent that will bring up the market page for the BusyBox app. The second method does the same thing, except it uses {{{startActivityForResult()}}}, allowing you to get back from the market app what the user did. When using the second method, requestCode is used exactly as it is with {{{startActivityForResult()}}}, and the Intent returned is the Intent returned from the same. Both methods take an Activity as their paramater, this should be the activity that is calling the method.

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 (RootTools.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 (RootTools.isAccessGiven()) {
    // your app has been granted root access
}

RootTools.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.

Checking the SD Card for available space

If you have the need to store things on the SD card, it's usually a good idea to make sure that there's room to hold them. !RootTools has a simple method for doing so:

if (RootTools.hasEnoughSpaceOnSdCard(updateSize)) {
    // there's enough space, go ahead
} else {
    // not enough space, plan b?
}

the method takes a long of how much space you need in blocks and returns true if there is enough space, and the SD card is writable. This method will also return false if the SD card is mounted by the user.

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");
try {
    RootTools.getShell(true).add(command);
}catch (IOException | RootDeniedException | TimeoutException ex) {
    ex.printStackTrace();
}

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 you are running 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) {
            super.commandOutput(id, line);
        }

        @Override
        public void commandTerminated(int id, String reason) {
            super.commandTerminated(id, reason);
        }

        @Override
        public void commandCompleted(int id, int exitcode) {
            super.commandCompleted(id, exitcode);
        }
};
RootTools.getShell(true).add(command);