Stellar Documentation

Stellar includes a built-in compatibility layer that allows applications written for Shizuku to work with Stellar without any code modifications.

How it works:

1. Client Compatibility: ShizukuProvider receives the Binder sent by Stellar and uses ShizukuCompat to manage connection states.
2. Server Interception: ShizukuServiceIntercept implements the IShizukuService interface and forwards Shizuku API calls to the Stellar service.
3. Permission Mapping: Automatically maps Shizuku permission requests to the Stellar shizuku permission.

Supported APIs:

• pingBinder(), getVersion(), getUid()
• checkSelfPermission(), requestPermission()
• newProcess()
• addUserService(), removeUserService()
• transactRemote()

Configuration:

• The compatibility layer is enabled by default.
• To disable it, toggle the "Shizuku 兼容层" (Shizuku Compatibility Layer) switch in the Stellar Manager settings.
• Requirement: Applications using Shizuku APIs must configure ShizukuProvider in their AndroidManifest.xml.

Stellar allows you to run your own AIDL-defined services within the Stellar environment.

1. Define an AIDL interface (e.g., IMyUserService.aidl).
2. Implement the service by extending the .Stub() class.
3. Bind the service using StellarUserService.bindUserService() with UserServiceArgs.

UserServiceArgs can be configured with a processNameSuffix, serviceMode (ONE_TIME or DAEMON), and other metadata via a builder pattern.

// Binding a ONE_TIME service
val args = UserServiceArgs.Builder(MyUserService::class.java)
    .processNameSuffix("myservice")
    .serviceMode(ServiceMode.ONE_TIME)
    .build()

StellarUserService.bindUserService(args, object : StellarUserService.ServiceCallback {
    override fun onServiceConnected(service: IBinder) {
        val myService = IMyUserService.Stub.asInterface(service)
        // Use myService
    }
    // ... other callbacks
})

You must register the StellarProvider in your AndroidManifest.xml to allow the Stellar service to communicate with your application.

Required Configuration

• android:exported="true": Must be true for the service to access the provider.
• android:multiprocess="false": Must be false because the service retrieves the UID only when the app starts.
• android:permission="android.permission.INTERACT_ACROSS_USERS_FULL": Restricts access to Shell and the app itself.
• android:authorities: Must follow the pattern ${applicationId}.stellar.

Metadata Permissions

Use <meta-data> with the name roro.stellar.permissions to define access levels:

• stellar: Required for basic Stellar API access.
• stellar,follow_stellar_startup: Includes basic access and allows your app to automatically start when the Stellar service starts.

<application>
    <provider
        android:name="roro.stellar.StellarProvider"
        android:authorities="${applicationId}.stellar"
        android:exported="true"
        android:multiprocess="false"
        android:permission="android.permission.INTERACT_ACROSS_USERS_FULL" />

    <meta-data
        android:name="roro.stellar.permissions"
        android:value="stellar,follow_stellar_startup" />
</application>

To use Stellar, you must register listeners to handle service connection, disconnection, and permission results.

Lifecycle Management

1. Register Listeners: Use Stellar.addBinderReceivedListenerSticky(...) to ensure you receive a callback even if the service is already connected. Use Stellar.addBinderDeadListener(...) and Stellar.addRequestPermissionResultListener(...) for connection loss and permission changes.
2. Check Status: Use Stellar.pingBinder() to verify the service is running and Stellar.checkSelfPermission() to verify permissions.
3. Request Permissions: Use Stellar.requestPermission(requestCode) to prompt the user for access.
4. Cleanup: Always call remove...Listener methods in onDestroy() to prevent memory leaks.

import roro.stellar.Stellar

class MainActivity : ComponentActivity() {

    private val binderReceivedListener = Stellar.OnBinderReceivedListener {
        Log.i("MyApp", "Stellar 服务已连接")
        checkServiceStatus()
    }

    private val binderDeadListener = Stellar.OnBinderDeadListener {
        Log.w("MyApp", "Stellar 服务已断开")
    }

    private val permissionResultListener =
        Stellar.OnRequestPermissionResultListener {
            requestCode, allowed, onetime ->
            if (allowed) {
                Log.i("MyApp", "权限已授予")
            } else {
                Log.w("MyApp", "权限被拒绝")
            }
        }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Use Sticky version to trigger immediately if already connected
        Stellar.addBinderReceivedListenerSticky(binderReceivedListener)
        Stellar.addBinderDeadListener(binderDeadListener)
        Stellar.addRequestPermissionResultListener(permissionResultListener)
    }

    override fun onDestroy() {
        super.onDestroy()
        Stellar.removeBinderReceivedListener(binderReceivedListener)
        Stellar.removeBinderDeadListener(binderDeadListener)
        Stellar.removeRequestPermissionResultListener(permissionResultListener)
    }

    private fun checkServiceStatus() {
        if (!Stellar.pingBinder()) {
            Log.e("MyApp", "服务未运行")
            return
        }

        if (!Stellar.checkSelfPermission()) {
            Stellar.requestPermission(requestCode = 1)
            return
        }

        Log.i("MyApp", "服务版本: ${Stellar.version}")
        Log.i("MyApp", "服务 UID: ${Stellar.uid}")
    }
}