Package com.topjohnwu.superuser.ipc

Class RootService

java.lang.Object
ContextWrapper
com.topjohnwu.superuser.ipc.RootService
public abstract class RootService extends ContextWrapper
A remote root service using native Android Binder IPC.

Important: while developing an app with RootServices, modify the run/debug configuration and check the "Always install with package manager" option if testing on Android 11+, or else the code changes will not be reflected after Android Studio's deployment.

This class is almost a complete recreation of a bound service running in a root process. Instead of using the original Context.bindService(...) methods to start and bind to a service, use the provided static methods RootService.bind(...). Because the service will not run in the same process as your application, you have to use either Messenger or AIDL to define the IPC interface for communication. Please read the official documentations for more details.

Even though a RootService is a Context of your application, the ContextImpl is not constructed in a normal way, so the functionality is much more limited compared to the normal case. Be aware of this and do not expect all context methods to work.

All RootServices launched from the same process will run in the same root process. A root service will be destroyed as soon as there are no clients bound to it. This means all services will be destroyed immediately when the client process is terminated. The library will NOT attempt to automatically restart and bind to a service after it was unbound.

Daemon Mode:
If you want the service to run in the background independent from the application lifecycle, launch the service in "Daemon Mode". Check the description of CATEGORY_DAEMON_MODE for instructions on how to do so. All services running in "Daemon Mode" will run in a daemon process created per-package that is separate from regular root services. This daemon process will be used across application re-launches, and even across different users on the device. A root service running in "Daemon Mode" will be destroyed when any client called stop(Intent), or the root service itself called stopSelf().

A root service process, including the daemon process, will terminate under these conditions:

  • When the application is updated or deleted
  • When all services running in the process are destroyed (after onDestroy() is called)
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    CATEGORY_DAEMON_MODE
    Launch the service in "Daemon Mode".

  • Constructor Summary

    Constructors
    Constructor
    Description
    RootService()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final void
    attachBaseContext(Context base)
     
    static void
    bind(Intent intent, Executor executor, ServiceConnection conn)
    Bind to a root service, launching a new root process if needed.
    static void
    bind(Intent intent, ServiceConnection conn)
    Bind to a root service, launching a new root process if needed.
    static Shell.Task
    bindOrTask(Intent intent, Executor executor, ServiceConnection conn)
    Bind to a root service, creating a task to launch a new root process if needed.
    final Context
    getApplicationContext()
     
    ComponentName
    getComponentName()
    Return the component name that will be used for service lookup.
    protected Context
    onAttach(Context base)
    Called when the RootService is getting attached with a Context.
    abstract IBinder
    onBind(Intent intent)
     
    void
    onCreate()
     
    void
    onDestroy()
     
    void
    onRebind(Intent intent)
     
    boolean
    onUnbind(Intent intent)
     
    static void
    stop(Intent intent)
    Force stop a root service, launching a new root process if needed.
    static Shell.Task
    stopOrTask(Intent intent)
    Force stop a root service, creating a task to launch a new root process if needed.
    final void
    stopSelf()
    Force stop this root service.
    static void
    unbind(ServiceConnection conn)
    Unbind from a root service.

    Methods inherited from class java.lang.Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • RootService

      public RootService()

  • Method Details

    • bind

      @MainThread public static void bind(@NonNull Intent intent, @NonNull Executor executor, @NonNull ServiceConnection conn)
      Bind to a root service, launching a new root process if needed.
      Parameters:
      intent - identifies the service to connect to.
      executor - callbacks on ServiceConnection will be called on this executor.
      conn - receives information as the service is started and stopped.
      See Also:
      • Context#bindService(Intent, int, Executor, ServiceConnection)

    • bind

      @MainThread public static void bind(@NonNull Intent intent, @NonNull ServiceConnection conn)
      Bind to a root service, launching a new root process if needed.
      Parameters:
      intent - identifies the service to connect to.
      conn - receives information as the service is started and stopped.
      See Also:
      • Context#bindService(Intent, ServiceConnection, int)

    • bindOrTask

      @MainThread @Nullable public static Shell.Task bindOrTask(@NonNull Intent intent, @NonNull Executor executor, @NonNull ServiceConnection conn)
      Bind to a root service, creating a task to launch a new root process if needed.

      If the application is already connected to a root process, binding will happen immediately and this method will return null. Or else this method returns a Shell.Task that has to be executed to launch the root process. Binding will only happen after the developer has executed the returned task with Shell.execTask(Shell.Task).

      Returns:
      the task to launch a root process. If there is no need to launch a new root process, null is returned.
      See Also:

    • unbind

      @MainThread public static void unbind(@NonNull ServiceConnection conn)
      Unbind from a root service.
      Parameters:
      conn - the connection interface previously supplied to bind(Intent, ServiceConnection)
      See Also:
      • Context#unbindService(ServiceConnection)

    • stop

      @MainThread public static void stop(@NonNull Intent intent)
      Force stop a root service, launching a new root process if needed.

      This method is used to immediately stop a root service regardless of its state. ONLY use this method to stop a daemon root service; for normal root services, please use unbind(ServiceConnection) instead as this method has to potentially launch an additional root process to ensure daemon services are stopped.

      Parameters:
      intent - identifies the service to stop.

    • stopOrTask

      @MainThread @Nullable public static Shell.Task stopOrTask(@NonNull Intent intent)
      Force stop a root service, creating a task to launch a new root process if needed.

      This method returns a Shell.Task that has to be executed to launch a root process if necessary, or else null will be returned.

      See Also:

    • attachBaseContext

      protected final void attachBaseContext(Context base)

    • onAttach

      @NonNull protected Context onAttach(@NonNull Context base)
      Called when the RootService is getting attached with a Context.
      Parameters:
      base - the context being attached.
      Returns:
      the passed in context by default.

    • getComponentName

      @NonNull public ComponentName getComponentName()
      Return the component name that will be used for service lookup.

      Overriding this method is only for very unusual use cases when a different component name other than the actual class name is desired.

      Returns:
      the desired component name.

    • getApplicationContext

      public final Context getApplicationContext()

    • onBind

      public abstract IBinder onBind(@NonNull Intent intent)
      See Also:
      • Service#onBind(Intent)

    • onCreate

      public void onCreate()
      See Also:
      • Service#onCreate()

    • onUnbind

      public boolean onUnbind(@NonNull Intent intent)
      See Also:
      • Service#onUnbind(Intent)

    • onRebind

      public void onRebind(@NonNull Intent intent)
      See Also:
      • Service#onRebind(Intent)

    • onDestroy

      public void onDestroy()
      See Also:
      • Service#onDestroy()

    • stopSelf

      public final void stopSelf()
      Force stop this root service.