android/dev.kindling.android.natif/BackgroundHelper

BackgroundHelper

class BackgroundHelper(context: Context)(source)

Unified helper for running tasks in the background.

Picks the right Android mechanism automatically based on BackgroundMode:

// 1. Short async work tied to a ViewModel
backgroundHelper.run(
    mode = BackgroundMode.Coroutine(viewModelScope),
    task = { fetchData() }
)

// 2. One-shot deferred task (survives app kill)
backgroundHelper.registerWorker("sync") { syncContacts() }
backgroundHelper.run(
    mode = BackgroundMode.WorkManagerOnce(
        uniqueName  = "sync",
        constraints = Constraints.Builder()
            .setRequiredNetworkType(NetworkType.CONNECTED)
            .build()
    )
)

// 3. Periodic sync every 15 minutes
backgroundHelper.registerWorker("periodic-sync") { syncData() }
backgroundHelper.run(
    mode = BackgroundMode.WorkManagerPeriodic(
        uniqueName      = "periodic-sync",
        intervalMinutes = 15
    )
)

// 4. Long-running foreground service (music, GPS, download)
backgroundHelper.registerWorker("download") { downloadFile() }
backgroundHelper.run(
    mode = BackgroundMode.Foreground(
        channelId   = "downloads",
        channelName = "Downloads",
        title       = "Downloading…",
        icon        = R.drawable.ic_download
    ),
    taskKey = "download"
)

single { BackgroundHelper(androidContext()) }

Declare in AndroidManifest.xml:

<service
    android:name="dev.kindling.android.natif.KForegroundService"
    android:foregroundServiceType="dataSync"
    android:exported="false" />

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />

Constructors

BackgroundHelper

constructor(context: Context)

Types

Companion

object Companion

Functions

cancel

fun cancel(uniqueName: String)

Cancels a scheduled WorkManager task by uniqueName.

registerWorker

fun registerWorker(key: String, task: BackgroundTask)

Registers a suspend task under a key so it can be referenced by BackgroundMode.WorkManagerOnce, BackgroundMode.WorkManagerPeriodic, or BackgroundMode.Foreground.

run

fun run(mode: BackgroundMode, task: BackgroundTask? = null, taskKey: String? = null)

Runs task (or the pre-registered worker at taskKey) using the given mode.

scheduleNext

fun scheduleNext(mode: BackgroundMode.WorkManagerScheduled, taskKey: String)

Schedules the next occurrence of a WorkManagerScheduled task. Called automatically by run — call it again inside your worker to re-schedule for the following week:

stateOf

suspend fun stateOf(uniqueName: String): WorkInfo.State?

Returns the current WorkInfo.State of a WorkManager task, or null if not found.

stopForeground

fun stopForeground()

Stops the foreground service if running.