com.stericson.RootTools
Class RootTools

java.lang.Object
  extended by com.stericson.RootTools.RootTools

public class RootTools
extends java.lang.Object


Nested Class Summary
static class RootTools.Result
           
 
Field Summary
static java.lang.String customShell
          You can use this to force sendshell to use a shell other than the deafult.
static boolean debugMode
          This class is the gateway to every functionality within the RootTools library.The developer should only have access to this class and this class only.This means that this class should be the only one to be public.The rest of the classes within this library must not have the public modifier.
static int lastExitCode
           
static java.util.List<java.lang.String> lastFoundBinaryPaths
           
static int shellDelay
          Change this to a lower/higher setting to speed up/slow down shell commands if things are taking too long or you are having constant crashes or timeout exceptions.
static boolean useRoot
          Many Functions here use root by default, but there may be times that you do not want them to use root.
static java.lang.String utilPath
           
 
Constructor Summary
RootTools()
           
 
Method Summary
static boolean checkUtil(java.lang.String util)
          This will check a given binary, determine if it exists and determine that it has either the permissions 755, 775, or 777.
static boolean checkUtils(java.lang.String[] utils)
          Deprecated.  
static boolean copyFile(java.lang.String source, java.lang.String destination, boolean remountAsRw, boolean preserveFileAttributes)
          Copys a file to a destination.
static boolean findBinary(java.lang.String binaryName)
           
static void fixUtil(java.lang.String util, java.lang.String utilPath)
          This will try and fix a given binary.
static boolean fixUtils(java.lang.String[] utils)
          This will check an array of binaries, determine if they exist and determine that it has either the permissions 755, 775, or 777.
static java.util.List<java.lang.String> getBusyBoxApplets()
          This will return an List of Strings.
static java.lang.String getBusyBoxVersion()
           
static Permissions getFilePermissions(java.lang.String file)
          Deprecated.  
static Permissions getFilePermissionsSymlinks(java.lang.String file)
           
static java.lang.String getMountedAs(java.lang.String path)
          This will tell you how the specified mount is mounted.
static java.util.ArrayList<Mount> getMounts()
          This will return an ArrayList of the class Mount.
static java.util.Set<java.lang.String> getPath()
          This will return the environment variable $PATH
static long getSpace(java.lang.String path)
          Get the space for a desired partition.
static java.lang.String getSymlink(java.io.File file)
          This will return a String that represent the symlink for a specified file.
static java.util.ArrayList<Symlink> getSymlinks(java.lang.String path)
          This will return an ArrayList of the class Symlink.
static java.lang.String getWorkingToolbox()
          This will return to you a string to be used in your shell commands which will represent the valid working toolbox with correct permissions.
static boolean hasEnoughSpaceOnSdCard(long updateSize)
          Checks if there is enough Space on SDCard
static boolean hasUtil(java.lang.String util, java.lang.String box)
          Checks whether the toolbox or busybox binary contains a specific util
static boolean installBinary(android.content.Context context, int sourceId, java.lang.String binaryName)
          This method can be used to unpack a binary from the raw resources folder and store it in /data/data/app.package/files/ This is typically useful if you provide your own C- or C++-based binary.
static boolean installBinary(android.content.Context context, int sourceId, java.lang.String destName, java.lang.String mode)
          This method can be used to unpack a binary from the raw resources folder and store it in /data/data/app.package/files/ This is typically useful if you provide your own C- or C++-based binary.
static boolean isAccessGiven()
           
static boolean isAppletAvailable(java.lang.String Applet)
          This will let you know if an applet is available from BusyBox

static boolean isBusyboxAvailable()
           
static boolean isNativeToolsReady(int nativeToolsId, android.content.Context context)
           
static boolean isProcessRunning(java.lang.String processName)
          This method can be used to to check if a process is running
static boolean isRootAvailable()
           
static boolean killProcess(java.lang.String processName)
          This method can be used to kill a running process
static void log(java.lang.String msg)
          This method allows you to output debug messages only when debugging is on.
static void log(java.lang.String TAG, java.lang.String msg)
           
static void offerBusyBox(android.app.Activity activity)
          This will launch the Android market looking for BusyBox
static android.content.Intent offerBusyBox(android.app.Activity activity, int requestCode)
          This will launch the Android market looking for BusyBox, but will return the intent fired and starts the activity with startActivityForResult
static void offerSuperUser(android.app.Activity activity)
          This will launch the Android market looking for SuperUser
static android.content.Intent offerSuperUser(android.app.Activity activity, int requestCode)
          This will launch the Android market looking for SuperUser, but will return the intent fired and starts the activity with startActivityForResult
static boolean remount(java.lang.String file, java.lang.String mountType)
          This will take a path, which can contain the file name as well, and attempt to remount the underlying partition.
static void restartAndroid()
          This restarts only Android OS without rebooting the whole device.
static void runBinary(android.content.Context context, java.lang.String binaryName, java.lang.String parameter)
          Executes binary in a separated process.
static java.util.List<java.lang.String> sendShell(java.lang.String[] commands, int sleepTime, int timeout)
          Sends several shell command as su, unless useRoot is set to false
static java.util.List<java.lang.String> sendShell(java.lang.String[] commands, int sleepTime, RootTools.Result result, boolean useRoot, int timeout)
          Sends several shell command as su (attempts to) if useRoot is true; as the current user (app_xxx) otherwise.
static java.util.List<java.lang.String> sendShell(java.lang.String[] commands, int sleepTime, RootTools.Result result, int timeout)
          Sends several shell command as su (attempts to)
static java.util.List<java.lang.String> sendShell(java.lang.String command, int timeout)
          Sends one shell command as su, unless useRoot is set to false
static java.util.List<java.lang.String> sendShell(java.lang.String command, RootTools.Result result, int timeout)
          Sends one shell command as su, unless useRoot is set to false
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

debugMode

public static boolean debugMode
This class is the gateway to every functionality within the RootTools library.The developer should only have access to this class and this class only.This means that this class should be the only one to be public.The rest of the classes within this library must not have the public modifier. All methods and Variables that the developer may need to have access to should be here. If a method, or a specific functionality, requires a fair amount of code, or work to be done, then that functionality should probably be moved to its own class and the call to it done here.For examples of this being done, look at the remount functionality.


lastFoundBinaryPaths

public static java.util.List<java.lang.String> lastFoundBinaryPaths

lastExitCode

public static int lastExitCode

utilPath

public static java.lang.String utilPath

customShell

public static java.lang.String customShell
You can use this to force sendshell to use a shell other than the deafult.


shellDelay

public static int shellDelay
Change this to a lower/higher setting to speed up/slow down shell commands if things are taking too long or you are having constant crashes or timeout exceptions.


useRoot

public static boolean useRoot
Many Functions here use root by default, but there may be times that you do not want them to use root. This can be useful when running a lot of commands at once. By default, if all of these functions are requesting root access then superuser will notify the user everytime that root is requested...this can lead to a flood of toast messages from superuser notifying the user that root access is being requested. Setting this to false will cause sendShell to not use root by default. So any commands sent to the shell will not have root access unless specifically directed to obtain root access by you. Some commands will not work properly without root access, so use this with care.

Constructor Detail

RootTools

public RootTools()
Method Detail

getWorkingToolbox

public static java.lang.String getWorkingToolbox()
This will return to you a string to be used in your shell commands which will represent the valid working toolbox with correct permissions. For instance, if Busybox is available it will return "busybox", if busybox is not available but toolbox is then it will return "toolbox"

Returns:
String that indicates the available toolbox to use for accessing applets.

hasUtil

public static boolean hasUtil(java.lang.String util,
                              java.lang.String box)
Checks whether the toolbox or busybox binary contains a specific util

Parameters:
util -
box - Should contain "toolbox" or "busybox"
Returns:
true if it contains this util

checkUtils

public static boolean checkUtils(java.lang.String[] utils)
                          throws java.lang.Exception
Deprecated. 

This will check an array of binaries, determine if they exist and determine that it has either the permissions 755, 775, or 777. If an applet is not setup correctly it will try and fix it. (This is for Busybox applets or Toolbox applets)

Parameters:
String - Name of the utility to check.
Returns:
boolean to indicate whether the operation completed. Note that this is not indicative of whether the problem was fixed, just that the method did not encounter any exceptions.
Throws:
java.lang.Exception - if the operation cannot be completed.

fixUtils

public static boolean fixUtils(java.lang.String[] utils)
                        throws java.lang.Exception
This will check an array of binaries, determine if they exist and determine that it has either the permissions 755, 775, or 777. If an applet is not setup correctly it will try and fix it. (This is for Busybox applets or Toolbox applets)

Parameters:
String - Name of the utility to check.
Returns:
boolean to indicate whether the operation completed. Note that this is not indicative of whether the problem was fixed, just that the method did not encounter any exceptions.
Throws:
java.lang.Exception - if the operation cannot be completed.

checkUtil

public static boolean checkUtil(java.lang.String util)
This will check a given binary, determine if it exists and determine that it has either the permissions 755, 775, or 777.

Parameters:
String - Name of the utility to check.
Returns:
boolean to indicate whether the binary is installed and has appropriate permissions.

fixUtil

public static void fixUtil(java.lang.String util,
                           java.lang.String utilPath)
This will try and fix a given binary. (This is for Busybox applets or Toolbox applets) By "fix", I mean it will try and symlink the binary from either toolbox or Busybox and fix the permissions if the permissions are not correct.

Parameters:
String - Name of the utility to fix.
String - path to the toolbox that provides ln, rm, and chmod. This can be a blank string, a path to a binary that will provide these, or you can use RootTools.getWorkingToolbox()

getPath

public static java.util.Set<java.lang.String> getPath()
                                               throws java.lang.Exception
This will return the environment variable $PATH

Returns:
Set A Set of Strings representing the environment variable $PATH
Throws:
java.lang.Exception - if we cannot return the $PATH variable

getMountedAs

public static java.lang.String getMountedAs(java.lang.String path)
                                     throws java.lang.Exception
This will tell you how the specified mount is mounted. rw, ro, etc...

Parameters:
The - mount you want to check
Returns:
String What the mount is mounted as.
Throws:
java.lang.Exception - if we cannot determine how the mount is mounted.

getMounts

public static java.util.ArrayList<Mount> getMounts()
                                            throws java.lang.Exception
This will return an ArrayList of the class Mount. The class mount contains the following property's: device mountPoint type flags

These will provide you with any information you need to work with the mount points.

Returns:
ArrayList an ArrayList of the class Mount.
Throws:
java.lang.Exception - if we cannot return the mount points.

getSymlinks

public static java.util.ArrayList<Symlink> getSymlinks(java.lang.String path)
                                                throws java.lang.Exception
This will return an ArrayList of the class Symlink. The class Symlink contains the following property's: path SymplinkPath

These will provide you with any Symlinks in the given path.

Parameters:
The - path to search for Symlinks.
Returns:
ArrayList an ArrayList of the class Symlink.
Throws:
java.lang.Exception - if we cannot return the Symlinks.

getSymlink

public static java.lang.String getSymlink(java.io.File file)
This will return a String that represent the symlink for a specified file.

Parameters:
The - file to get the Symlink for. (must have absolute path)
Returns:
String a String that represent the symlink for a specified file or an empty string if no symlink exists.

copyFile

public static boolean copyFile(java.lang.String source,
                               java.lang.String destination,
                               boolean remountAsRw,
                               boolean preserveFileAttributes)
Copys a file to a destination. Because cp is not available on all android devices, we have a fallback on the cat command

Parameters:
source - example: /data/data/org.adaway/files/hosts
destination - example: /system/etc/hosts
remountAsRw - remounts the destination as read/write before writing to it
preserveFileAttributes - tries to copy file attributes from source to destination, if only cat is available only permissions are preserved
Returns:
true if it was successfully copied

offerBusyBox

public static void offerBusyBox(android.app.Activity activity)
This will launch the Android market looking for BusyBox

Parameters:
activity - pass in your Activity

offerBusyBox

public static android.content.Intent offerBusyBox(android.app.Activity activity,
                                                  int requestCode)
This will launch the Android market looking for BusyBox, but will return the intent fired and starts the activity with startActivityForResult

Parameters:
activity - pass in your Activity
requestCode - pass in the request code
Returns:
intent fired

offerSuperUser

public static void offerSuperUser(android.app.Activity activity)
This will launch the Android market looking for SuperUser

Parameters:
activity - pass in your Activity

offerSuperUser

public static android.content.Intent offerSuperUser(android.app.Activity activity,
                                                    int requestCode)
This will launch the Android market looking for SuperUser, but will return the intent fired and starts the activity with startActivityForResult

Parameters:
activity - pass in your Activity
requestCode - pass in the request code
Returns:
intent fired

isRootAvailable

public static boolean isRootAvailable()
Returns:
true if su was found.

isBusyboxAvailable

public static boolean isBusyboxAvailable()
Returns:
true if BusyBox was found.

findBinary

public static boolean findBinary(java.lang.String binaryName)
Parameters:
binaryName - String that represent the binary to find.
Returns:
true if the specified binary was found. Also, the path the binary was found at can be retrieved via the variable lastFoundBinaryPath, if the binary was found in more than one location this will contain all of these locations.

getFilePermissionsSymlinks

public static Permissions getFilePermissionsSymlinks(java.lang.String file)
Parameters:
file - String that represent the file, including the full path to the file and its name.
Returns:
An instance of the class permissions from which you can get the permissions of the file or if the file could not be found or permissions couldn't be determined then permissions will be null.

getFilePermissions

public static Permissions getFilePermissions(java.lang.String file)
Deprecated. 

Parameters:
file - String that represent the file, including the full path to the file and its name.
Returns:
An instance of the class permissions from which you can get the permissions of the file or if the file could not be found or permissions couldn't be determined then permissions will be null.

getBusyBoxVersion

public static java.lang.String getBusyBoxVersion()
Returns:
BusyBox version is found, "" if not found.

getBusyBoxApplets

public static java.util.List<java.lang.String> getBusyBoxApplets()
                                                          throws java.lang.Exception
This will return an List of Strings. Each string represents an applet available from BusyBox.

Returns:
List a List of strings representing the applets available from Busybox.
Throws:
java.lang.Exception - if we cannot return the applets available.

isAppletAvailable

public static boolean isAppletAvailable(java.lang.String Applet)
This will let you know if an applet is available from BusyBox

Parameters:
String - The applet to check for.
Returns:
true if applet is available, false otherwise.

isAccessGiven

public static boolean isAccessGiven()
Returns:
true if your app has been given root access.
Throws:
java.util.concurrent.TimeoutException - if this operation times out. (cannot determine if access is given)

isNativeToolsReady

public static boolean isNativeToolsReady(int nativeToolsId,
                                         android.content.Context context)

hasEnoughSpaceOnSdCard

public static boolean hasEnoughSpaceOnSdCard(long updateSize)
Checks if there is enough Space on SDCard

Parameters:
updateSize - size to Check (long)
Returns:
true if the Update will fit on SDCard, false if not enough space on SDCard. Will also return false, if the SDCard is not mounted as read/write

remount

public static boolean remount(java.lang.String file,
                              java.lang.String mountType)
This will take a path, which can contain the file name as well, and attempt to remount the underlying partition.

For example, passing in the following string: "/system/bin/some/directory/that/really/would/never/exist" will result in /system ultimately being remounted. However, keep in mind that the longer the path you supply, the more work this has to do, and the slower it will run.

Parameters:
file - file path
mountType - mount type: pass in RO (Read only) or RW (Read Write)
Returns:
a boolean which indicates whether or not the partition has been remounted as specified.

installBinary

public static boolean installBinary(android.content.Context context,
                                    int sourceId,
                                    java.lang.String destName,
                                    java.lang.String mode)
This method can be used to unpack a binary from the raw resources folder and store it in /data/data/app.package/files/ This is typically useful if you provide your own C- or C++-based binary. This binary can then be executed using sendShell() and its full path.

Parameters:
context - the current activity's Context
sourceId - resource id; typically R.raw.id
destName - destination file name; appended to /data/data/app.package/files/
mode - chmod value for this file
Returns:
a boolean which indicates whether or not we were able to create the new file.

installBinary

public static boolean installBinary(android.content.Context context,
                                    int sourceId,
                                    java.lang.String binaryName)
This method can be used to unpack a binary from the raw resources folder and store it in /data/data/app.package/files/ This is typically useful if you provide your own C- or C++-based binary. This binary can then be executed using sendShell() and its full path.

Parameters:
context - the current activity's Context
sourceId - resource id; typically R.raw.id
binaryName - destination file name; appended to /data/data/app.package/files/
Returns:
a boolean which indicates whether or not we were able to create the new file.

runBinary

public static void runBinary(android.content.Context context,
                             java.lang.String binaryName,
                             java.lang.String parameter)
Executes binary in a separated process. Before using this method, the binary has to be installed in /data/data/app.package/files/ using the installBinary method.

Parameters:
context - the current activity's Context
binaryName - name of installed binary
parameter - parameter to append to binary like "-vxf"

killProcess

public static boolean killProcess(java.lang.String processName)
This method can be used to kill a running process

Parameters:
processName - name of process to kill
Returns:
true if process was found and killed successfully

isProcessRunning

public static boolean isProcessRunning(java.lang.String processName)
This method can be used to to check if a process is running

Parameters:
processName - name of process to check
Returns:
true if process was found
Throws:
java.util.concurrent.TimeoutException - (Could not determine if the process is running)

restartAndroid

public static void restartAndroid()
This restarts only Android OS without rebooting the whole device. This does NOT work on all devices. This is done by killing the main init process named zygote. Zygote is restarted automatically by Android after killing it.

Throws:
java.util.concurrent.TimeoutException

sendShell

public static java.util.List<java.lang.String> sendShell(java.lang.String[] commands,
                                                         int sleepTime,
                                                         RootTools.Result result,
                                                         int timeout)
                                                  throws java.io.IOException,
                                                         RootToolsException,
                                                         java.util.concurrent.TimeoutException
Sends several shell command as su (attempts to)

Parameters:
commands - array of commands to send to the shell
sleepTime - time to sleep between each command, delay.
result - injected result object that implements the Result class
timeout - How long to wait before throwing TimeoutException, sometimes when running root commands on certain devices or roms ANR's may occur because a process never returns or readline never returns. This allows you to protect your application from throwing an ANR. if you pass -1, then the default timeout is 5 minutes.
Returns:
a LinkedList containing each line that was returned by the shell after executing or while trying to execute the given commands. You must iterate over this list, it does not allow random access, so no specifying an index of an item you want, not like you're going to know that anyways.
Throws:
java.lang.InterruptedException
java.io.IOException
java.util.concurrent.TimeoutException
RootToolsException

sendShell

public static java.util.List<java.lang.String> sendShell(java.lang.String[] commands,
                                                         int sleepTime,
                                                         RootTools.Result result,
                                                         boolean useRoot,
                                                         int timeout)
                                                  throws java.io.IOException,
                                                         RootToolsException,
                                                         java.util.concurrent.TimeoutException
Sends several shell command as su (attempts to) if useRoot is true; as the current user (app_xxx) otherwise.

Parameters:
commands - array of commands to send to the shell
sleepTime - time to sleep between each command, delay.
result - injected result object that implements the Result class
useRoot - whether to use root or not when issuing these commands.
timeout - How long to wait before throwing TimeoutException, sometimes when running root commands on certain devices or roms ANR's may occur because a process never returns or readline never returns. This allows you to protect your application from throwing an ANR. if you pass -1, then the default timeout is 5 minutes.
Returns:
a LinkedList containing each line that was returned by the shell after executing or while trying to execute the given commands. You must iterate over this list, it does not allow random access, so no specifying an index of an item you want, not like you're going to know that anyways.
Throws:
java.lang.InterruptedException
java.io.IOException
java.util.concurrent.TimeoutException
RootToolsException

sendShell

public static java.util.List<java.lang.String> sendShell(java.lang.String[] commands,
                                                         int sleepTime,
                                                         int timeout)
                                                  throws java.io.IOException,
                                                         RootToolsException,
                                                         java.util.concurrent.TimeoutException
Sends several shell command as su, unless useRoot is set to false

Parameters:
commands - array of commands to send to the shell
sleepTime - time to sleep between each command, delay.
timeout - How long to wait before throwing TimeoutException, sometimes when running root commands on certain devices or roms ANR's may occur because a process never returns or readline never returns. This allows you to protect your application from throwing an ANR. if you pass -1, then the default timeout is 5 minutes.
Returns:
a LinkedList containing each line that was returned by the shell after executing or while trying to execute the given commands. You must iterate over this list, it does not allow random access, so no specifying an index of an item you want, not like you're going to know that anyways.
Throws:
java.lang.InterruptedException
java.io.IOException
java.util.concurrent.TimeoutException
RootToolsException

sendShell

public static java.util.List<java.lang.String> sendShell(java.lang.String command,
                                                         RootTools.Result result,
                                                         int timeout)
                                                  throws java.io.IOException,
                                                         RootToolsException,
                                                         java.util.concurrent.TimeoutException
Sends one shell command as su, unless useRoot is set to false

Parameters:
command - command to send to the shell
result - injected result object that implements the Result class
timeout - How long to wait before throwing TimeoutException, sometimes when running root commands on certain devices or roms ANR's may occur because a process never returns or readline never returns. This allows you to protect your application from throwing an ANR. if you pass -1, then the default timeout is 5 minutes.
Returns:
a LinkedList containing each line that was returned by the shell after executing or while trying to execute the given commands. You must iterate over this list, it does not allow random access, so no specifying an index of an item you want, not like you're going to know that anyways.
Throws:
java.lang.InterruptedException
java.io.IOException
RootToolsException
java.util.concurrent.TimeoutException

sendShell

public static java.util.List<java.lang.String> sendShell(java.lang.String command,
                                                         int timeout)
                                                  throws java.io.IOException,
                                                         RootToolsException,
                                                         java.util.concurrent.TimeoutException
Sends one shell command as su, unless useRoot is set to false

Parameters:
command - command to send to the shell
timeout - How long to wait before throwing TimeoutException, sometimes when running root commands on certain devices or roms ANR's may occur because a process never returns or readline never returns. This allows you to protect your application from throwing an ANR. if you pass -1, then the default timeout is 5 minutes.
Returns:
a LinkedList containing each line that was returned by the shell after executing or while trying to execute the given commands. You must iterate over this list, it does not allow random access, so no specifying an index of an item you want, not like you're going to know that anyways.
Throws:
java.lang.InterruptedException
java.io.IOException
java.util.concurrent.TimeoutException
RootToolsException

getSpace

public static long getSpace(java.lang.String path)
Get the space for a desired partition.

Parameters:
path - The partition to find the space for.
Returns:
the amount if space found within the desired partition. If the space was not found then the value is -1
Throws:
java.util.concurrent.TimeoutException

log

public static void log(java.lang.String msg)
This method allows you to output debug messages only when debugging 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.

Parameters:
TAG - Optional parameter to define the tag that the Log will use.
msg - The message to output.

log

public static void log(java.lang.String TAG,
                       java.lang.String msg)