Package com.topjohnwu.superuser.ipc

Class RootService

java.lang.Object

android.content.Context

android.content.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:

• Bound services
• Android Interface Definition Language (AIDL)

Field Summary

Fields

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

Fields inherited from class android.content.Context

ACCESSIBILITY_SERVICE, ACCOUNT_SERVICE, ACTIVITY_SERVICE, ALARM_SERVICE, APP_OPS_SERVICE, APP_SEARCH_SERVICE, APPWIDGET_SERVICE, AUDIO_SERVICE, BATTERY_SERVICE, BIND_ABOVE_CLIENT, BIND_ADJUST_WITH_ACTIVITY, BIND_ALLOW_OOM_MANAGEMENT, BIND_AUTO_CREATE, BIND_DEBUG_UNBIND, BIND_EXTERNAL_SERVICE, BIND_IMPORTANT, BIND_INCLUDE_CAPABILITIES, BIND_NOT_FOREGROUND, BIND_NOT_PERCEPTIBLE, BIND_WAIVE_PRIORITY, BIOMETRIC_SERVICE, BLOB_STORE_SERVICE, BLUETOOTH_SERVICE, BUGREPORT_SERVICE, CAMERA_SERVICE, CAPTIONING_SERVICE, CARRIER_CONFIG_SERVICE, CLIPBOARD_SERVICE, COMPANION_DEVICE_SERVICE, CONNECTIVITY_DIAGNOSTICS_SERVICE, CONNECTIVITY_SERVICE, CONSUMER_IR_SERVICE, CONTEXT_IGNORE_SECURITY, CONTEXT_INCLUDE_CODE, CONTEXT_RESTRICTED, CROSS_PROFILE_APPS_SERVICE, DEVICE_POLICY_SERVICE, DISPLAY_HASH_SERVICE, DISPLAY_SERVICE, DOMAIN_VERIFICATION_SERVICE, DOWNLOAD_SERVICE, DROPBOX_SERVICE, EUICC_SERVICE, FILE_INTEGRITY_SERVICE, FINGERPRINT_SERVICE, GAME_SERVICE, HARDWARE_PROPERTIES_SERVICE, INPUT_METHOD_SERVICE, INPUT_SERVICE, IPSEC_SERVICE, JOB_SCHEDULER_SERVICE, KEYGUARD_SERVICE, LAUNCHER_APPS_SERVICE, LAYOUT_INFLATER_SERVICE, LOCALE_SERVICE, LOCATION_SERVICE, MEDIA_COMMUNICATION_SERVICE, MEDIA_METRICS_SERVICE, MEDIA_PROJECTION_SERVICE, MEDIA_ROUTER_SERVICE, MEDIA_SESSION_SERVICE, MIDI_SERVICE, MODE_APPEND, MODE_ENABLE_WRITE_AHEAD_LOGGING, MODE_NO_LOCALIZED_COLLATORS, MODE_PRIVATE, NETWORK_STATS_SERVICE, NFC_SERVICE, NOTIFICATION_SERVICE, NSD_SERVICE, PEOPLE_SERVICE, PERFORMANCE_HINT_SERVICE, POWER_SERVICE, PRINT_SERVICE, RECEIVER_EXPORTED, RECEIVER_NOT_EXPORTED, RECEIVER_VISIBLE_TO_INSTANT_APPS, RESTRICTIONS_SERVICE, ROLE_SERVICE, SEARCH_SERVICE, SENSOR_SERVICE, SHORTCUT_SERVICE, STATUS_BAR_SERVICE, STORAGE_SERVICE, STORAGE_STATS_SERVICE, SYSTEM_HEALTH_SERVICE, TELECOM_SERVICE, TELEPHONY_IMS_SERVICE, TELEPHONY_SERVICE, TELEPHONY_SUBSCRIPTION_SERVICE, TEXT_CLASSIFICATION_SERVICE, TEXT_SERVICES_MANAGER_SERVICE, TV_INPUT_SERVICE, TV_INTERACTIVE_APP_SERVICE, UI_MODE_SERVICE, USAGE_STATS_SERVICE, USB_SERVICE, USER_SERVICE, VIBRATOR_MANAGER_SERVICE, VPN_MANAGEMENT_SERVICE, WALLPAPER_SERVICE, WIFI_AWARE_SERVICE, WIFI_P2P_SERVICE, WIFI_RTT_RANGING_SERVICE, WIFI_SERVICE, WINDOW_SERVICE

Constructor Summary

Constructors

Constructor	Description
RootService()

Method Summary

Modifier and Type	Method	Description
protected final void	attachBaseContext(Context base)
static void	bind(Intent intent, ServiceConnection conn)	Bind to a root service, launching a new root process if needed.
static void	bind(Intent intent, Executor executor, 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 android.content.ContextWrapper

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

Methods inherited from class android.content.Context

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

Methods inherited from class java.lang.Object

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

Field Details

CATEGORY_DAEMON_MODE

public static final String CATEGORY_DAEMON_MODE

Launch the service in "Daemon Mode".

Add this category in the intent passed to bind(Intent, ServiceConnection), bind(Intent, Executor, ServiceConnection), or bindOrTask(Intent, Executor, ServiceConnection) to have the service launch in "Daemon Mode". This category also has to be added in the intent passed to stop(Intent) and stopOrTask(Intent) in order to refer to a daemon service instead of a regular root service.

See Also:

• Constant Field Values

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:

• bind(Intent, Executor, ServiceConnection)

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:

• stop(Intent)

attachBaseContext

protected final void attachBaseContext(Context base)

Overrides:

attachBaseContext in class ContextWrapper

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()

Overrides:

getApplicationContext in class ContextWrapper

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.