runtime-service/io.matthewnelson.kmp.tor.runtime.service/TorServiceUI

TorServiceUI

abstract class TorServiceUI<C : AbstractTorServiceUI.Config, IS : AbstractTorServiceUI.InstanceState<C>> @ExperimentalKmpTorApi constructor(args: TorServiceUI.Args) : AbstractTorServiceUI<TorServiceUI.Args, C, IS> (source)

Core androidMain abstraction which enables implementors the ability to create a fully customized notification for the running instances of TorRuntime as they operate within TorService.

This class' API is designed as follows:

Factory: To be used for all TorRuntime.ServiceFactory instances and injected into TorService upon creation.

Context: SINGLETON

TorServiceUI: To be created via Factory.createProtected upon TorService start.

Context: SERVICE

InstanceState: To be created via AbstractTorServiceUI.createProtected for every instance of Lifecycle.DestroyableTorRuntime operating within TorService.

Context: INSTANCE

NOTE: This is currently an ExperimentalKmpTorApi when extending to create your own implementation. Things may change (as the annotation states), so use at your own risk! Prefer using the stable implementation via the kmp-tor:runtime-service-ui dependency.

Throws

IllegalStateException

on instantiation if args were not those which were passed to Factory.create. See Args.

Constructors

TorServiceUI

@ExperimentalKmpTorApi

protected constructor(args: TorServiceUI.Args)

Types

Args

class Args : AbstractTorServiceUI.Args.UI

androidMain implementation for passing arguments in an encapsulated manner when instantiating new instances of TorServiceUI implementations.

Companion

protected object Companion

Factory

abstract class Factory<C : AbstractTorServiceUI.Config, IS : AbstractTorServiceUI.InstanceState<C>, UI : TorServiceUI<C, IS>> @ExperimentalKmpTorApi constructor(defaultConfig: C, val info: TorServiceUI.NotificationInfo) : AbstractTorServiceUI.Factory<TorServiceUI.Args, C, IS, UI>

Core androidMain abstraction for a Factory class which is responsible for instantiating new instances of TorServiceUI when requested by TorService.

NotificationInfo

class NotificationInfo @JvmOverloads constructor(val notificationId: Short, val channelId: String, val channelName: Int, val channelDescription: Int, val channelShowBadge: Boolean = false, val channelImportanceLow: Boolean = false)

Holder for Foreground Service Notification and NotificationChannel configuration info used to instantiate Factory. Is validated upon invocation of TorServiceConfig.Foreground.Companion.Builder.

Receiver

protected fun interface Receiver

Callback for creating BroadcastReceiver that belong to the Service context, without exposing the Service to implementors of TorServiceUI.

Properties

appContext

@JvmField

protected val appContext: Context

Application Context for resolving android resources and creating Notification.Builder. This MUST NOT be utilized when posting Notification updates and registering BroadcastReceiver. Use post and register functions which will be executed within the context of the android.app.Service.

channelId

@JvmField

protected val channelId: String

The NotificationInfo.channelId for instantiating Notification.Builder.

defaultConfig

@JvmField

protected val defaultConfig: C

The default Config that was defined for Factory.defaultConfig

displayed

@get:JvmName(name = "displayed")

protected val displayed: IS?

Returns the currently displayed InstanceState.

instanceStates

@get:JvmName(name = "instanceStates")

protected val instanceStates: Collection<IS>

All InstanceState currently operating within this UI "container".

serviceChildScope

@JvmField

protected val serviceChildScope: CoroutineScope

A CoroutineScope which is configured as a child to the service object's CoroutineScope which utilizes Dispatchers.Main

Functions

createProtected

protected abstract fun createProtected(args: AbstractTorServiceUI.Args.Instance): IS

Implementors MUST utilize args to instantiate a new instance of the InstanceState implementation. If args were not consumed by the returned instance of InstanceState, an exception will be thrown by createProtected.

equals

operator override fun equals(other: Any?): Boolean

hashCode

override fun hashCode(): Int

isDestroyed

fun isDestroyed(): Boolean

onConfigurationChanged

open fun onConfigurationChanged(newConfig: Configuration)

onDestroy

protected open fun onDestroy()

onRender

protected abstract fun onRender(displayed: IS, hasPrevious: Boolean, hasNext: Boolean)

Indicates there was a stateful change that requires an update to the UI.

post

protected fun Notification.post()

Posts the Notification to NotificationManager. This MUST be called upon first onRender invocation (or sooner) to ensure that the call to Service.startForeground is had, otherwise an ANR will result for Android API 26+.

@JvmOverloads

protected fun TorServiceUI.Receiver.register(filter: IntentFilter, permission: String?, scheduler: Handler?, exported: Boolean?, flags: Int = 0): Disposable.Once?

Registers a BroadcastReceiver with the Service context and pipes the Intent from BroadcastReceiver.onReceive to Receiver.onReceive.

selectNext

protected fun selectNext()

Shifts the pointer to the "right" and calls onRender with the new parameters. If no next InstanceState is available, then nothing occurs.

selectPrevious

protected fun selectPrevious()

Shifts the pointer to the "left" and calls onRender with the new parameters. If no previous InstanceState is available, then nothing occurs.

TorServiceUI

See also

Throws

Constructors

Types

Properties

Functions