Package 

Class 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 {@code Context.bindService(...)} methods to start and bind to a service, use the provided static methods {@code 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 {@code 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, 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)

    • Constructor Summary

      Constructors 
      Constructor Description
      RootService()

    • Method Summary

      Modifier and Type Method Description
      static void bind(@NonNull() Intent intent, @NonNull() Executor executor, @NonNull() ServiceConnection conn) Bind to a root service, launching a new root process if needed.
      static void bind(@NonNull() Intent intent, @NonNull() ServiceConnection conn) Bind to a root service, launching a new root process if needed.
      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.
      static void unbind(@NonNull() ServiceConnection conn) Unbind from a root service.
      static void stop(@NonNull() Intent intent) Force stop a root service, launching a new root process if needed.
      static Shell.Task stopOrTask(@NonNull() Intent intent) Force stop a root service, creating a task to launch a new root process if needed.
      ComponentName getComponentName() Return the component name that will be used for service lookup.
      final Context getApplicationContext()
      abstract IBinder onBind(@NonNull() Intent intent)
      void onCreate()
      boolean onUnbind(@NonNull() Intent intent)
      void onRebind(@NonNull() Intent intent)
      void onDestroy()
      final void stopSelf() Force stop this root service.
      static Runnable createBindTask(@NonNull() Intent intent, @NonNull() Executor executor, @NonNull() ServiceConnection conn)

      • Methods inherited from class android.content.ContextWrapper

        bindIsolatedService, bindService, bindServiceAsUser, checkCallingOrSelfPermission, checkCallingOrSelfUriPermission, checkCallingOrSelfUriPermissions, checkCallingPermission, checkCallingUriPermission, checkCallingUriPermissions, checkPermission, checkSelfPermission, checkUriPermission, checkUriPermissions, clearWallpaper, createAttributionContext, createConfigurationContext, createContext, createContextForSplit, createDeviceContext, createDeviceProtectedStorageContext, createDisplayContext, createPackageContext, createWindowContext, databaseList, deleteDatabase, deleteFile, deleteSharedPreferences, enforceCallingOrSelfPermission, enforceCallingOrSelfUriPermission, enforceCallingPermission, enforceCallingUriPermission, enforcePermission, enforceUriPermission, fileList, getApplicationContext, getApplicationInfo, getAssets, getAttributionSource, getAttributionTag, getBaseContext, getCacheDir, getClassLoader, getCodeCacheDir, getContentResolver, getDataDir, getDatabasePath, getDeviceId, getDir, getDisplay, getExternalCacheDir, getExternalCacheDirs, getExternalFilesDir, getExternalFilesDirs, getExternalMediaDirs, getFileStreamPath, getFilesDir, getMainExecutor, getMainLooper, getNoBackupFilesDir, getObbDir, getObbDirs, getOpPackageName, getPackageCodePath, getPackageManager, getPackageName, getPackageResourcePath, getParams, getResources, getSharedPreferences, getSystemService, getSystemServiceName, getTheme, getWallpaper, getWallpaperDesiredMinimumHeight, getWallpaperDesiredMinimumWidth, grantUriPermission, isDeviceProtectedStorage, isRestricted, isUiContext, moveDatabaseFrom, moveSharedPreferencesFrom, openFileInput, openFileOutput, openOrCreateDatabase, peekWallpaper, registerComponentCallbacks, registerDeviceIdChangeListener, registerReceiver, removeStickyBroadcast, removeStickyBroadcastAsUser, revokeSelfPermissionsOnKill, revokeUriPermission, sendBroadcast, sendBroadcastAsUser, sendOrderedBroadcast, sendOrderedBroadcastAsUser, sendStickyBroadcast, sendStickyBroadcastAsUser, sendStickyOrderedBroadcast, sendStickyOrderedBroadcastAsUser, setTheme, setWallpaper, startActivities, startActivity, startForegroundService, startInstrumentation, startIntentSender, startService, stopService, unbindService, unregisterComponentCallbacks, unregisterDeviceIdChangeListener, unregisterReceiver, updateServiceGroup

      • Methods inherited from class android.content.Context

        getColor, getColorStateList, getDrawable, getString, getSystemService, getText, obtainStyledAttributes, revokeSelfPermissionOnKill, sendBroadcastWithMultiplePermissions

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • RootService

        RootService()

    • Method Detail

      • bind

        @MainThread() 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.

      • bind

        @MainThread() 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.

      • bindOrTask

        @MainThread()@Nullable() 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 immediatelyand this method will return {@code null}. Or else this method returns a Shell.Task that has to be executed to launch the root process. Binding will only happen after thedeveloper has executed the returned task with execTask.

      • stop

        @MainThread() 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 instead as this method has to potentially launchan additional root process to ensure daemon services are stopped.

        Parameters:
        intent - identifies the service to stop.

      • stopOrTask

        @MainThread()@Nullable() 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 aroot process if necessary, or else {@code null} will be returned.

      • getComponentName

        @NonNull() 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 differentcomponent name other than the actual class name is desired.

      • stopSelf

         final void stopSelf()

        Force stop this root service.