Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

feat(setup): ask for the permissions the app needs, with a reason for each

ExTv8d2701e13c25
diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml
index decef39..c1c1a2a 100644
--- a/app/src/main/AndroidManifest.xml
+++ b/app/src/main/AndroidManifest.xml
@@ -34,6 +34,10 @@
<!-- Required on Android 13+ to show the foreground service notification -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+ <!-- Lets the setup wizard and Home permissions card show the direct battery
+ exemption dialog instead of the general system list -->
+ <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+
<!-- Full storage access to share the Downloads folder with the VM -->
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE"
tools:ignore="ScopedStorage" />
diff --git a/app/src/main/java/com/excp/podroid/ui/components/PermissionRows.kt b/app/src/main/java/com/excp/podroid/ui/components/PermissionRows.kt
new file mode 100644
index 0000000..98de176
--- /dev/null
+++ b/app/src/main/java/com/excp/podroid/ui/components/PermissionRows.kt
@@ -0,0 +1,77 @@
+package com.excp.podroid.ui.components
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.unit.dp
+import com.excp.podroid.R
+import com.excp.podroid.ui.theme.PodroidTokens
+import com.excp.podroid.util.AppPermission
+
+/**
+ * One row per applicable permission: title + why on the left, a "Granted" label
+ * or a compact Grant button on the right. Owns no permission logic - the caller
+ * decides which permissions apply, how to check them, and what Grant does.
+ */
+@Composable
+fun PermissionRows(
+ permissions: List<AppPermission>,
+ isGranted: (AppPermission) -> Boolean,
+ onGrant: (AppPermission) -> Unit,
+ modifier: Modifier = Modifier,
+) {
+ Column(modifier = modifier) {
+ permissions.forEachIndexed { index, permission ->
+ Row(
+ modifier = Modifier
+ .fillMaxWidth()
+ .padding(vertical = PodroidTokens.Spacing.MD),
+ verticalAlignment = Alignment.CenterVertically,
+ horizontalArrangement = Arrangement.SpaceBetween,
+ ) {
+ Column(modifier = Modifier.weight(1f)) {
+ Text(
+ text = stringResource(permission.titleRes),
+ style = MaterialTheme.typography.bodyMedium,
+ color = MaterialTheme.colorScheme.onSurface,
+ )
+ Text(
+ text = stringResource(permission.whyRes),
+ style = MaterialTheme.typography.bodyMedium,
+ color = MaterialTheme.colorScheme.onSurfaceVariant,
+ )
+ }
+ Spacer(Modifier.width(PodroidTokens.Spacing.SM))
+ if (isGranted(permission)) {
+ Text(
+ text = stringResource(R.string.perm_granted),
+ style = MaterialTheme.typography.bodyMedium,
+ color = MaterialTheme.colorScheme.onSurfaceVariant,
+ )
+ } else {
+ TextButton(onClick = { onGrant(permission) }) {
+ Text(stringResource(R.string.perm_grant))
+ }
+ }
+ }
+ if (index != permissions.lastIndex) {
+ HorizontalDivider(
+ color = MaterialTheme.colorScheme.outline,
+ thickness = 1.dp,
+ )
+ }
+ }
+ }
+}
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/home/HomeScreen.kt b/app/src/main/java/com/excp/podroid/ui/screens/home/HomeScreen.kt
index 7d16bb4..08f1bf0 100644
--- a/app/src/main/java/com/excp/podroid/ui/screens/home/HomeScreen.kt
+++ b/app/src/main/java/com/excp/podroid/ui/screens/home/HomeScreen.kt
@@ -1,7 +1,12 @@
package com.excp.podroid.ui.screens.home
+import android.Manifest
+import android.app.Activity
import android.content.Intent
import android.net.Uri
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts.RequestPermission
+import androidx.compose.animation.AnimatedContent
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
@@ -34,8 +39,10 @@ import androidx.compose.material3.windowsizeclass.WindowSizeClass
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
+import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
@@ -43,6 +50,7 @@ import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.unit.dp
+import androidx.core.app.ActivityCompat
import androidx.hilt.lifecycle.viewmodel.compose.hiltViewModel
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleEventObserver
@@ -54,6 +62,7 @@ import com.excp.podroid.engine.VmState
import com.excp.podroid.engine.avf.AvfFailureGuidance
import com.excp.podroid.service.PodroidService
import com.excp.podroid.ui.components.AdaptiveContainer
+import com.excp.podroid.ui.components.PermissionRows
import com.excp.podroid.ui.components.PodroidDestructiveButton
import com.excp.podroid.ui.components.PodroidGhostButton
import com.excp.podroid.ui.components.PodroidListRow
@@ -63,6 +72,12 @@ import com.excp.podroid.ui.components.PodroidStatus
import com.excp.podroid.ui.components.PodroidStatusColors
import com.excp.podroid.ui.components.PodroidTopBar
import com.excp.podroid.ui.theme.PodroidTokens
+import com.excp.podroid.util.AppPermission
+import com.excp.podroid.util.AppPermissions
+import com.excp.podroid.util.isGranted
+import com.excp.podroid.util.missing
+import com.excp.podroid.util.openAppDetailsSettings
+import com.excp.podroid.util.requestBatteryOptimizationExemption
@OptIn(ExperimentalMaterial3Api::class)
@Composable
@@ -101,18 +116,43 @@ fun HomeScreen(
// Wi-Fi / hotspot change (the headline SSH use case) shows the new address
// instead of a stale one for the screen's lifetime.
var phoneIp by remember { mutableStateOf(viewModel.phoneIp()) }
+ // Bumped on ON_RESUME (and after a grant attempt) so the missing-permissions
+ // list is re-read from the live OS grant state, e.g. after the user comes
+ // back from the system settings screen.
+ var permissionsGrantVersion by remember { mutableIntStateOf(0) }
+ val missingPermissions = remember(permissionsGrantVersion) { AppPermissions.missing(context) }
+ var permissionsCardDismissed by rememberSaveable { mutableStateOf(false) }
val lifecycleOwner = LocalLifecycleOwner.current
DisposableEffect(lifecycleOwner) {
val observer = LifecycleEventObserver { _, event ->
if (event == Lifecycle.Event.ON_RESUME) {
phoneIp = viewModel.phoneIp()
viewModel.refreshContainerCount()
+ permissionsGrantVersion++
}
}
lifecycleOwner.lifecycle.addObserver(observer)
onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
}
+ val notifPermLauncher = rememberLauncherForActivityResult(RequestPermission()) { granted ->
+ if (!granted) {
+ val activity = context as? Activity
+ if (activity != null &&
+ !ActivityCompat.shouldShowRequestPermissionRationale(activity, Manifest.permission.POST_NOTIFICATIONS)
+ ) {
+ AppPermissions.openAppDetailsSettings(context)
+ }
+ }
+ permissionsGrantVersion++
+ }
+ fun grantPermission(permission: AppPermission) {
+ when (permission) {
+ AppPermission.NOTIFICATIONS -> notifPermLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
+ AppPermission.BATTERY_OPTIMIZATION -> AppPermissions.requestBatteryOptimizationExemption(context)
+ }
+ }
+
updateInfo?.let { info ->
AlertDialog(
onDismissRequest = { viewModel.dismissUpdate() },
@@ -180,6 +220,13 @@ fun HomeScreen(
.padding(end = PodroidTokens.Spacing.XL2)
.verticalScroll(rememberScrollState()),
) {
+ if (missingPermissions.isNotEmpty() && !permissionsCardDismissed) {
+ PermissionsNeededCard(
+ permissions = missingPermissions,
+ onGrant = ::grantPermission,
+ onDismiss = { permissionsCardDismissed = true },
+ )
+ }
if (showAvfHint) {
AvfHintBanner(onDismiss = { viewModel.dismissAvfHint() })
}
@@ -229,6 +276,13 @@ fun HomeScreen(
verticalArrangement = Arrangement.spacedBy(PodroidTokens.Spacing.MD),
) {
Spacer(Modifier.height(PodroidTokens.Spacing.XL))
+ if (missingPermissions.isNotEmpty() && !permissionsCardDismissed) {
+ PermissionsNeededCard(
+ permissions = missingPermissions,
+ onGrant = ::grantPermission,
+ onDismiss = { permissionsCardDismissed = true },
+ )
+ }
if (showAvfHint) {
AvfHintBanner(onDismiss = { viewModel.dismissAvfHint() })
}
@@ -272,6 +326,46 @@ fun HomeScreen(
}
}
+@Composable
+private fun PermissionsNeededCard(
+ permissions: List<AppPermission>,
+ onGrant: (AppPermission) -> Unit,
+ onDismiss: () -> Unit,
+) {
+ val context = LocalContext.current
+ Card(
+ modifier = Modifier
+ .fillMaxWidth()
+ .padding(bottom = PodroidTokens.Spacing.MD),
+ colors = CardDefaults.cardColors(
+ containerColor = MaterialTheme.colorScheme.surfaceVariant,
+ ),
+ ) {
+ Column(
+ modifier = Modifier.padding(PodroidTokens.Spacing.MD),
+ verticalArrangement = Arrangement.spacedBy(PodroidTokens.Spacing.SM),
+ ) {
+ Text(
+ stringResource(R.string.permissions_needed),
+ style = MaterialTheme.typography.titleSmall,
+ )
+ PermissionRows(
+ permissions = permissions,
+ isGranted = { it.isGranted(context) },
+ onGrant = onGrant,
+ )
+ Row(
+ horizontalArrangement = Arrangement.End,
+ modifier = Modifier.fillMaxWidth(),
+ ) {
+ TextButton(onClick = onDismiss) {
+ Text(stringResource(R.string.not_now))
+ }
+ }
+ }
+ }
+}
+
@Composable
private fun AvfHintBanner(onDismiss: () -> Unit) {
Card(
@@ -351,21 +445,25 @@ private fun HomeStatusBlock(
onRetry: () -> Unit = {},
) {
PodroidSectionLabel(stringResource(R.string.vm_status))
- Text(
- text = when {
- isStopping -> stringResource(R.string.status_stopping)
- isStarting -> stringResource(R.string.status_starting)
- isRunning -> stringResource(R.string.status_running)
- else -> stringResource(R.string.status_stopped)
- },
- style = MaterialTheme.typography.displayLarge,
- color = when {
- isStopping -> MaterialTheme.colorScheme.tertiary
- isRunning -> MaterialTheme.colorScheme.primary
- isStarting -> MaterialTheme.colorScheme.tertiary
- else -> MaterialTheme.colorScheme.onSurface
- },
- )
+ val statusText = when {
+ isStopping -> stringResource(R.string.status_stopping)
+ isStarting -> stringResource(R.string.status_starting)
+ isRunning -> stringResource(R.string.status_running)
+ else -> stringResource(R.string.status_stopped)
+ }
+ val statusColor = when {
+ isStopping -> MaterialTheme.colorScheme.tertiary
+ isRunning -> MaterialTheme.colorScheme.primary
+ isStarting -> MaterialTheme.colorScheme.tertiary
+ else -> MaterialTheme.colorScheme.onSurface
+ }
+ AnimatedContent(targetState = statusText to statusColor, label = "home_vm_status") { (text, color) ->
+ Text(
+ text = text,
+ style = MaterialTheme.typography.displayLarge,
+ color = color,
+ )
+ }
Spacer(Modifier.height(PodroidTokens.Spacing.SM))
Row(
modifier = Modifier.fillMaxWidth(),
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupScreen.kt b/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupScreen.kt
index 655704c..764216a 100644
--- a/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupScreen.kt
+++ b/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupScreen.kt
@@ -1,6 +1,7 @@
package com.excp.podroid.ui.screens.setup
import android.Manifest
+import android.app.Activity
import android.content.Intent
import android.content.pm.PackageManager
import android.net.Uri
@@ -51,11 +52,16 @@ import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.semantics.clearAndSetSemantics
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.unit.dp
+import androidx.core.app.ActivityCompat
import androidx.hilt.lifecycle.viewmodel.compose.hiltViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import com.excp.podroid.R
import com.excp.podroid.ui.components.AdaptiveContainer
+import com.excp.podroid.ui.components.PermissionRows
import com.excp.podroid.ui.components.PodroidGhostButton
import com.excp.podroid.ui.components.PodroidListRow
import com.excp.podroid.ui.components.PodroidPrimaryButton
@@ -66,7 +72,12 @@ import com.excp.podroid.ui.components.VmCpuChips
import com.excp.podroid.ui.components.VmRamChips
import com.excp.podroid.ui.components.VmStorageChips
import com.excp.podroid.ui.theme.PodroidTokens
+import com.excp.podroid.util.AppPermission
+import com.excp.podroid.util.AppPermissions
import com.excp.podroid.util.DeviceResourcePolicy
+import com.excp.podroid.util.isGranted
+import com.excp.podroid.util.openAppDetailsSettings
+import com.excp.podroid.util.requestBatteryOptimizationExemption
import kotlinx.coroutines.launch
private const val DEFAULT_STORAGE_GB = 8
@@ -101,7 +112,7 @@ fun SetupScreen(
var usbPassthroughEnabled by rememberSaveable { mutableStateOf(false) }
val usbPassthroughAvailable = remember { viewModel.usbPassthroughAvailable() }
val setupComplete by viewModel.setupComplete.collectAsStateWithLifecycle()
- val pagerState = rememberPagerState(pageCount = { 4 })
+ val pagerState = rememberPagerState(pageCount = { 5 })
val scope = rememberCoroutineScope()
fun applyLoadBalance() {
@@ -116,24 +127,8 @@ fun SetupScreen(
if (loadBalanceEnabled) applyLoadBalance()
}
- // Request the notification permission BEFORE navigating away; using
- // rememberLauncherForActivityResult registers it while the composable is still
- // alive, so the result actually arrives. ActivityCompat.requestPermissions
- // after onSetupComplete() fires against a transitioning Activity and is dropped
- // on some OEMs.
- val notifPermLauncher = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
- rememberLauncherForActivityResult(RequestPermission()) { /* grant result: no-op */ }
- } else null
-
LaunchedEffect(setupComplete) {
if (setupComplete) {
- if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
- if (ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS)
- != PackageManager.PERMISSION_GRANTED
- ) {
- notifPermLauncher?.launch(Manifest.permission.POST_NOTIFICATIONS)
- }
- }
onSetupComplete()
}
}
@@ -162,6 +157,16 @@ fun SetupScreen(
onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
}
+ // Announced to TalkBack on both the progress bar and the page dots below,
+ // since neither conveys the step number on its own.
+ val stepLabel = when (pagerState.currentPage) {
+ 0 -> stringResource(R.string.step_1_of_5)
+ 1 -> stringResource(R.string.step_2_of_5)
+ 2 -> stringResource(R.string.step_3_of_5)
+ 3 -> stringResource(R.string.step_4_of_5)
+ else -> stringResource(R.string.step_5_of_5)
+ }
+
Scaffold { innerPadding ->
Column(
modifier = Modifier
@@ -170,8 +175,10 @@ fun SetupScreen(
) {
// Step progress bar
LinearProgressIndicator(
- progress = { (pagerState.currentPage + 1) / 4f },
- modifier = Modifier.fillMaxWidth(),
+ progress = { (pagerState.currentPage + 1) / 5f },
+ modifier = Modifier
+ .fillMaxWidth()
+ .semantics { contentDescription = stepLabel },
trackColor = MaterialTheme.colorScheme.surfaceVariant,
)
@@ -246,6 +253,11 @@ fun SetupScreen(
available = usbPassthroughAvailable,
onUsbPassthroughToggle = { usbPassthroughEnabled = it },
onBack = { scope.launch { pagerState.animateScrollToPage(2) } },
+ onNext = { scope.launch { pagerState.animateScrollToPage(4) } },
+ )
+ 4 -> PermissionsPage(
+ windowSizeClass = windowSizeClass,
+ onBack = { scope.launch { pagerState.animateScrollToPage(3) } },
onGetStarted = {
viewModel.completeSetup(
storageSizeGb = selectedGb,
@@ -266,11 +278,12 @@ fun SetupScreen(
Row(
modifier = Modifier
.fillMaxWidth()
- .padding(vertical = 16.dp),
+ .padding(vertical = 16.dp)
+ .clearAndSetSemantics { contentDescription = stepLabel },
horizontalArrangement = Arrangement.Center,
verticalAlignment = Alignment.CenterVertically,
) {
- repeat(4) { index ->
+ repeat(5) { index ->
val isSelected = pagerState.currentPage == index
val dotWidth by animateDpAsState(
targetValue = if (isSelected) 24.dp else 8.dp,
@@ -392,7 +405,7 @@ private fun StoragePage(
) {
SetupPageLayout(
windowSizeClass = windowSizeClass,
- stepLabel = stringResource(R.string.step_1_of_4),
+ stepLabel = stringResource(R.string.step_1_of_5),
title = stringResource(R.string.persistent_storage),
description = stringResource(R.string.storage_description),
bottomBar = { SetupNextBar(onNext = onNext) },
@@ -435,7 +448,7 @@ private fun VmConfigPage(
) {
SetupPageLayout(
windowSizeClass = windowSizeClass,
- stepLabel = stringResource(R.string.step_2_of_4),
+ stepLabel = stringResource(R.string.step_2_of_5),
title = stringResource(R.string.configure_vm),
description = stringResource(R.string.vm_config_description),
bottomBar = { SetupNavBar(onBack = onBack, onNext = onNext, nextLabel = stringResource(R.string.continue_label)) },
@@ -514,7 +527,7 @@ private fun StorageAccessPage(
SetupPageLayout(
windowSizeClass = windowSizeClass,
- stepLabel = stringResource(R.string.step_3_of_4),
+ stepLabel = stringResource(R.string.step_3_of_5),
title = stringResource(R.string.downloads_sharing),
description = stringResource(R.string.storage_access_description),
bottomBar = { SetupNavBar(onBack = onBack, onNext = onNext, nextLabel = stringResource(R.string.continue_label)) },
@@ -561,14 +574,14 @@ private fun UsbPassthroughPage(
available: Boolean,
onUsbPassthroughToggle: (Boolean) -> Unit,
onBack: () -> Unit,
- onGetStarted: () -> Unit,
+ onNext: () -> Unit,
) {
SetupPageLayout(
windowSizeClass = windowSizeClass,
- stepLabel = stringResource(R.string.step_4_of_4),
+ stepLabel = stringResource(R.string.step_4_of_5),
title = stringResource(R.string.usb_passthrough),
description = stringResource(R.string.usb_passthrough_description),
- bottomBar = { SetupNavBar(onBack = onBack, onNext = onGetStarted, nextLabel = stringResource(R.string.get_started)) },
+ bottomBar = { SetupNavBar(onBack = onBack, onNext = onNext, nextLabel = stringResource(R.string.continue_label)) },
) {
PodroidSectionLabel(stringResource(R.string.usb_devices_section))
PodroidListRow(
@@ -594,6 +607,61 @@ private fun UsbPassthroughPage(
}
}
+// ── Page 5: Permissions ───────────────────────────────────────────────────────
+
+@Composable
+private fun PermissionsPage(
+ windowSizeClass: WindowSizeClass,
+ onBack: () -> Unit,
+ onGetStarted: () -> Unit,
+) {
+ val context = LocalContext.current
+ val permissions = remember { AppPermissions.applicable(Build.VERSION.SDK_INT) }
+ // Bumped after a grant attempt and on ON_RESUME so a row flips from Grant to
+ // Granted without waiting for anything else to recompose this page.
+ var grantVersion by remember { mutableIntStateOf(0) }
+
+ val notifPermLauncher = rememberLauncherForActivityResult(RequestPermission()) { granted ->
+ if (!granted) {
+ val activity = context as? Activity
+ if (activity != null &&
+ !ActivityCompat.shouldShowRequestPermissionRationale(activity, Manifest.permission.POST_NOTIFICATIONS)
+ ) {
+ AppPermissions.openAppDetailsSettings(context)
+ }
+ }
+ grantVersion++
+ }
+
+ val lifecycleOwner = LocalLifecycleOwner.current
+ DisposableEffect(lifecycleOwner) {
+ val observer = LifecycleEventObserver { _, event ->
+ if (event == Lifecycle.Event.ON_RESUME) grantVersion++
+ }
+ lifecycleOwner.lifecycle.addObserver(observer)
+ onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
+ }
+
+ SetupPageLayout(
+ windowSizeClass = windowSizeClass,
+ stepLabel = stringResource(R.string.step_5_of_5),
+ title = stringResource(R.string.permissions),
+ description = stringResource(R.string.permissions_description),
+ bottomBar = { SetupNavBar(onBack = onBack, onNext = onGetStarted, nextLabel = stringResource(R.string.get_started)) },
+ ) {
+ PermissionRows(
+ permissions = permissions,
+ isGranted = { grantVersion; it.isGranted(context) },
+ onGrant = { permission ->
+ when (permission) {
+ AppPermission.NOTIFICATIONS -> notifPermLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
+ AppPermission.BATTERY_OPTIMIZATION -> AppPermissions.requestBatteryOptimizationExemption(context)
+ }
+ },
+ )
+ }
+}
+
// ── Setup bottom bars ─────────────────────────────────────────────────────────
@Composable
diff --git a/app/src/main/java/com/excp/podroid/util/AppPermissions.kt b/app/src/main/java/com/excp/podroid/util/AppPermissions.kt
new file mode 100644
index 0000000..3ffba2b
--- /dev/null
+++ b/app/src/main/java/com/excp/podroid/util/AppPermissions.kt
@@ -0,0 +1,128 @@
+/*
+ * Podroid - Rootless Podman for Android
+ * Copyright (C) 2024-2026 Podroid contributors
+ *
+ * Single source of truth for the app's user-promptable permissions: what they
+ * are, whether they apply on this SDK level, whether they are currently
+ * granted, and how to ask for them.
+ */
+package com.excp.podroid.util
+
+import android.Manifest
+import android.content.ActivityNotFoundException
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.net.Uri
+import android.os.Build
+import android.os.PowerManager
+import android.provider.Settings
+import android.util.Log
+import androidx.core.content.ContextCompat
+import com.excp.podroid.R
+
+/**
+ * One permission (or special-access grant) the app may ask the user for.
+ *
+ * @property manifestPermission the runtime permission to check/request, or
+ * null when this is special access granted through a system Intent rather
+ * than a runtime permission (e.g. battery-optimization exemption).
+ * @property minSdk the first SDK_INT this entry applies on; below it the
+ * permission doesn't exist or isn't needed.
+ */
+enum class AppPermission(
+ val manifestPermission: String?,
+ val titleRes: Int,
+ val whyRes: Int,
+ val minSdk: Int,
+) {
+ NOTIFICATIONS(
+ Manifest.permission.POST_NOTIFICATIONS,
+ R.string.perm_notifications_title,
+ R.string.perm_notifications_why,
+ Build.VERSION_CODES.TIRAMISU,
+ ),
+ BATTERY_OPTIMIZATION(
+ null,
+ R.string.perm_battery_title,
+ R.string.perm_battery_why,
+ Build.VERSION_CODES.M,
+ ),
+}
+
+/**
+ * Pure logic for which permissions apply and which are missing. No `Context`
+ * and no `Build.VERSION.SDK_INT` read here, so this stays a plain JVM unit
+ * test - the Android-side pieces live in the extension functions below.
+ */
+object AppPermissions {
+
+ /** Entries applicable on [sdkInt], in declaration (display) order. */
+ fun applicable(sdkInt: Int): List<AppPermission> =
+ AppPermission.entries.filter { it.minSdk <= sdkInt }
+
+ /** Applicable entries for which [isGranted] returns false, in order. */
+ fun missing(sdkInt: Int, isGranted: (AppPermission) -> Boolean): List<AppPermission> =
+ applicable(sdkInt).filterNot(isGranted)
+}
+
+private const val TAG = "AppPermissions"
+
+/** Whether this permission is currently granted on [context]. */
+fun AppPermission.isGranted(context: Context): Boolean =
+ when (this) {
+ AppPermission.NOTIFICATIONS, -> {
+ val permission = manifestPermission
+ ?: error("NOTIFICATIONS must declare a manifestPermission")
+ ContextCompat.checkSelfPermission(context, permission) == PackageManager.PERMISSION_GRANTED
+ }
+ AppPermission.BATTERY_OPTIMIZATION -> {
+ val powerManager = context.getSystemService(Context.POWER_SERVICE) as PowerManager
+ powerManager.isIgnoringBatteryOptimizations(context.packageName)
+ }
+ }
+
+/** Applicable permissions on this device that are not currently granted, in order. */
+fun AppPermissions.missing(context: Context): List<AppPermission> =
+ missing(Build.VERSION.SDK_INT) { it.isGranted(context) }
+
+/**
+ * Asks the system to exempt this app from battery optimization directly. Some
+ * OEMs strip the direct-request screen, so a missing handler falls back to
+ * the general exemption list rather than leaving the user stuck.
+ */
+fun AppPermissions.requestBatteryOptimizationExemption(context: Context) {
+ val directIntent = Intent(
+ Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS,
+ Uri.parse("package:${context.packageName}"),
+ ).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+ try {
+ context.startActivity(directIntent)
+ } catch (e: ActivityNotFoundException) {
+ Log.w(TAG, "Direct battery-optimization request unavailable, opening the system list", e)
+ val listIntent = Intent(Settings.ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS)
+ .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+ try {
+ context.startActivity(listIntent)
+ } catch (e2: ActivityNotFoundException) {
+ Log.e(TAG, "No battery-optimization settings screen available on this device", e2)
+ }
+ }
+}
+
+/**
+ * Opens this app's system details screen, the fallback when POST_NOTIFICATIONS
+ * was denied without a rationale (permanently denied) - without it the Grant
+ * button on the permissions card would be dead after the second denial.
+ */
+fun AppPermissions.openAppDetailsSettings(context: Context) {
+ val intent = Intent(
+ Settings.ACTION_APPLICATION_DETAILS_SETTINGS,
+ Uri.parse("package:${context.packageName}"),
+ ).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+ try {
+ context.startActivity(intent)
+ } catch (e: ActivityNotFoundException) {
+ Log.e(TAG, "No app details settings screen available on this device", e)
+ }
+}
diff --git a/app/src/main/res/values-zh/strings.xml b/app/src/main/res/values-zh/strings.xml
index bccc6ba..1b9ad60 100644
--- a/app/src/main/res/values-zh/strings.xml
+++ b/app/src/main/res/values-zh/strings.xml
@@ -40,6 +40,7 @@
<string name="back">返回</string>
<string name="continue_label">继续</string>
<string name="get_started">开始使用</string>
+ <string name="not_now">暂不</string>
<!-- Storage -->
<string name="persistent_storage">持久化存储</string>
@@ -95,6 +96,8 @@
<string name="extra_kernel_cmdline">额外的内核命令行</string>
<string name="kernel_cmdline_helper">在 console=ttyAMA0 之后追加 - 控制调度器、缓解措施、日志级别等。</string>
<string name="qemu_args_helper">-cpu, -accel, -object, -device, -overcommit 等。空格分隔。</string>
+ <string name="reset_field_confirm_title">重置%1$s?</string>
+ <string name="reset_field_confirm_body">这将清除您的自定义设置并恢复默认值。</string>
<string name="about">关于</string>
<string name="architecture">架构</string>
<string name="linux_distro">Linux 发行版</string>
@@ -181,6 +184,7 @@
<string name="container_backup_on_phone">手机上的备份</string>
<string name="container_backup_refresh">刷新列表</string>
<string name="container_backup_none">Downloads/Podroid/backups 中尚未找到备份归档。</string>
+ <string name="container_backup_list_error">无法读取备份文件夹,请点击刷新重试。</string>
<string name="container_backup_copied">命令已复制</string>
<!-- Home -->
@@ -209,11 +213,23 @@
<string name="backend_fallback_reason_service">系统服务不可达</string>
<string name="backend_fallback_reason_protected_only">此设备仅支持受保护虚拟机</string>
+ <!-- Permissions -->
+ <string name="permissions">权限</string>
+ <string name="permissions_description">Podroid 需要以下权限才能稳定运行虚拟机。</string>
+ <string name="permissions_needed">需要授权</string>
+ <string name="perm_notifications_title">通知</string>
+ <string name="perm_notifications_why">显示虚拟机状态,并可从通知栏停止虚拟机。</string>
+ <string name="perm_battery_title">后台不受限制</string>
+ <string name="perm_battery_why">让虚拟机在应用退到后台时继续运行。</string>
+ <string name="perm_grant">授权</string>
+ <string name="perm_granted">已授权</string>
+
<!-- Setup Steps -->
- <string name="step_1_of_4">第 1 步,共 4 步</string>
- <string name="step_2_of_4">第 2 步,共 4 步</string>
- <string name="step_3_of_4">第 3 步,共 4 步</string>
- <string name="step_4_of_4">第 4 步,共 4 步</string>
+ <string name="step_1_of_5">第 1 步,共 5 步</string>
+ <string name="step_2_of_5">第 2 步,共 5 步</string>
+ <string name="step_3_of_5">第 3 步,共 5 步</string>
+ <string name="step_4_of_5">第 4 步,共 5 步</string>
+ <string name="step_5_of_5">第 5 步,共 5 步</string>
<!-- Dialogs -->
<string name="update_available">有新版本可用</string>
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index 53b4979..d52e7f7 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -40,6 +40,7 @@
<string name="back">Back</string>
<string name="continue_label">Continue</string>
<string name="get_started">Get Started</string>
+ <string name="not_now">Not now</string>
<!-- Storage -->
<string name="persistent_storage">Persistent Storage</string>
@@ -95,6 +96,8 @@
<string name="extra_kernel_cmdline">Extra kernel cmdline</string>
<string name="kernel_cmdline_helper">Appended after console=ttyAMA0 — controls scheduler, mitigations, log level, etc.</string>
<string name="qemu_args_helper">-cpu, -accel, -object, -device, -overcommit, etc. Whitespace-separated.</string>
+ <string name="reset_field_confirm_title">Reset %1$s?</string>
+ <string name="reset_field_confirm_body">This clears your customization and restores the default value.</string>
<string name="about">About</string>
<string name="architecture">Architecture</string>
<string name="linux_distro">Linux distro</string>
@@ -181,6 +184,7 @@
<string name="container_backup_on_phone">Backups on phone</string>
<string name="container_backup_refresh">Refresh list</string>
<string name="container_backup_none">No backup archives found in Downloads/Podroid/backups yet.</string>
+ <string name="container_backup_list_error">Couldn\'t read the backup folder. Try Refresh.</string>
<string name="container_backup_copied">Command copied</string>
<!-- Home -->
@@ -209,11 +213,23 @@
<string name="backend_fallback_reason_service">the system service is unreachable</string>
<string name="backend_fallback_reason_protected_only">this device only supports protected virtual machines</string>
+ <!-- Permissions -->
+ <string name="permissions">Permissions</string>
+ <string name="permissions_description">Podroid needs these to run the VM reliably.</string>
+ <string name="permissions_needed">Permissions needed</string>
+ <string name="perm_notifications_title">Notifications</string>
+ <string name="perm_notifications_why">Shows the VM\'s state and lets you stop it from the notification shade.</string>
+ <string name="perm_battery_title">Unrestricted background</string>
+ <string name="perm_battery_why">Keeps the VM running when the app is in the background.</string>
+ <string name="perm_grant">Grant</string>
+ <string name="perm_granted">Granted</string>
+
<!-- Setup Steps -->
- <string name="step_1_of_4">Step 1 of 4</string>
- <string name="step_2_of_4">Step 2 of 4</string>
- <string name="step_3_of_4">Step 3 of 4</string>
- <string name="step_4_of_4">Step 4 of 4</string>
+ <string name="step_1_of_5">Step 1 of 5</string>
+ <string name="step_2_of_5">Step 2 of 5</string>
+ <string name="step_3_of_5">Step 3 of 5</string>
+ <string name="step_4_of_5">Step 4 of 5</string>
+ <string name="step_5_of_5">Step 5 of 5</string>
<!-- Dialogs -->
<string name="update_available">Update available</string>
diff --git a/app/src/test/java/com/excp/podroid/util/AppPermissionsTest.kt b/app/src/test/java/com/excp/podroid/util/AppPermissionsTest.kt
new file mode 100644
index 0000000..19ca1fa
--- /dev/null
+++ b/app/src/test/java/com/excp/podroid/util/AppPermissionsTest.kt
@@ -0,0 +1,39 @@
+package com.excp.podroid.util
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class AppPermissionsTest {
+
+ @Test
+ fun applicable_excludesNotificationsBelowTiramisu() {
+ assertEquals(false, AppPermissions.applicable(32).contains(AppPermission.NOTIFICATIONS))
+ assertEquals(true, AppPermissions.applicable(33).contains(AppPermission.NOTIFICATIONS))
+ }
+
+ @Test
+ fun applicable_includesBatteryOptimizationOnMarshmallow() {
+ assertEquals(true, AppPermissions.applicable(26).contains(AppPermission.BATTERY_OPTIMIZATION))
+ }
+
+ @Test
+ fun missing_returnsAllApplicableInDeclarationOrder_whenNoneGranted() {
+ assertEquals(
+ listOf(AppPermission.NOTIFICATIONS, AppPermission.BATTERY_OPTIMIZATION),
+ AppPermissions.missing(33) { false },
+ )
+ }
+
+ @Test
+ fun missing_returnsEmpty_whenAllGranted() {
+ assertEquals(emptyList<AppPermission>(), AppPermissions.missing(33) { true })
+ }
+
+ @Test
+ fun missing_excludesOnlyTheGrantedOnes() {
+ assertEquals(
+ listOf(AppPermission.BATTERY_OPTIMIZATION),
+ AppPermissions.missing(33) { it == AppPermission.NOTIFICATIONS },
+ )
+ }
+}