app/org.scottishtecharmy.soundscape.services/SoundscapeService

SoundscapeService

class SoundscapeService : MediaSessionService, GeoEngineListener, MediaControllableService

Foreground service that provides location updates, device orientation updates, requests tiles, data persistence with realmDB. It inherits from MediaSessionService so that we can receive Media Transport button presses to act as a remote control whilst the phone is locked.

Constructors

SoundscapeService

constructor()

Types

Companion

object Companion

Properties

actions

var actions: SoundscapeActionExecutor?

Entry point for assistant commands, shared with iOS's Siri App Intents. Nullable like audioMenu because both are built when the service starts, and a command can arrive before that.

activeCalloutFlow

open override val activeCalloutFlow: StateFlow<TourButton?>

application

val application: Application?

applicationContext

open val applicationContext: Context?

applicationInfo

open val applicationInfo: ApplicationInfo?

assets

open val assets: AssetManager?

attributionSource

open val attributionSource: AttributionSource

attributionTag

open val attributionTag: String?

audioEngine

var audioEngine: NativeAudioEngine

audioFocusGained

var audioFocusGained: Boolean

audioMenu

var audioMenu: AudioMenu?

baseContext

open val baseContext: Context?

beaconFlow

open override val beaconFlow: StateFlow<BeaconState>

cacheDir

open val cacheDir: File?

classLoader

open val classLoader: ClassLoader?

codeCacheDir

open val codeCacheDir: File?

contentResolver

open val contentResolver: ContentResolver?

currentRouteFlow

open override val currentRouteFlow: StateFlow<RoutePlayerState>

dataDir

open val dataDir: File?

deviceId

open val deviceId: Int

directionProvider

lateinit var directionProvider: DirectionProvider

display

open val display: Display?

duckingAllowed

var duckingAllowed: Boolean

externalCacheDir

open val externalCacheDir: File?

externalCacheDirs

open val externalCacheDirs: Array<out File?>?

externalMediaDirs

open val externalMediaDirs: Array<out File?>?

filesDir

open val filesDir: File?

filteredLocationFlow

open override val filteredLocationFlow: StateFlow<SoundscapeLocation?>

foregroundServiceType

val foregroundServiceType: Int

gridStateFlow

open override val gridStateFlow: StateFlow<GridState?>

headHeadingFlow

open override val headHeadingFlow: StateFlow<HeadHeading?>

headsetBatteryPercentFlow

open override val headsetBatteryPercentFlow: StateFlow<Int?>

isDeviceProtectedStorage

open val isDeviceProtectedStorage: Boolean

isPlaybackOngoing

@get:UnstableApi

val isPlaybackOngoing: Boolean

isRestricted

open val isRestricted: Boolean

isUiContext

open val isUiContext: Boolean

lifecycle

open override val lifecycle: Lifecycle

listener

@set:UnstableApi

private open var listener: MediaSessionService.Listener?

localizedContext

lateinit var localizedContext: Context

locationFlow

open override val locationFlow: StateFlow<SoundscapeLocation?>

locationProvider

lateinit var locationProvider: LocationProvider

mainExecutor

open val mainExecutor: Executor?

mainLooper

open val mainLooper: Looper?

menuActive

open override var menuActive: Boolean

True while the user is actively navigating the audio menu. Suppresses auto callouts.

noBackupFilesDir

open val noBackupFilesDir: File?

obbDir

open val obbDir: File?

obbDirs

open val obbDirs: Array<out File?>?

opPackageName

open val opPackageName: String

orientationFlow

open override val orientationFlow: StateFlow<DeviceDirection?>

packageCodePath

open val packageCodePath: String?

packageManager

open val packageManager: PackageManager?

packageName

open val packageName: String?

packageResourcePath

open val packageResourcePath: String?

params

open val params: ContextParams?

resources

open val resources: Resources?

routePlayer

lateinit var routePlayer: RoutePlayer

running

var running: Boolean

sessions

val sessions: List<MediaSession?>?

sharedPreferences

lateinit var sharedPreferences: SharedPreferences

snoozing

var snoozing: Boolean

True while sleep mode's wake on leave is waiting for the user to move off. The service runs in the foreground only so that the app keeps receiving locations with the phone locked, and so that waking is a call into it rather than a foreground service start from the background, which Android 12+ refuses. The geo engine isn't started until wakeFromSnooze.

started

var started: Boolean

streetPreviewFlow

open override val streetPreviewFlow: StateFlow<StreetPreviewState>

theme

open val theme: Resources.Theme?

updateableFlags

open val updateableFlags: Context.BindServiceFlags

wallpaper

open val wallpaper: Drawable?

wallpaperDesiredMinimumHeight

open val wallpaperDesiredMinimumHeight: Int

wallpaperDesiredMinimumWidth

open val wallpaperDesiredMinimumWidth: Int

Functions

abandonAudioFocus

fun abandonAudioFocus()

addSession

fun addSession(session: MediaSession?)

aheadOfMe

open override fun aheadOfMe()

announceStreetPreviewBestChoice

open override fun announceStreetPreviewBestChoice(bestChoice: StreetPreviewChoice)

appInForeground

fun appInForeground(foreground: Boolean)

applyHeadTrackingEnabled

fun applyHeadTrackingEnabled()

beaconMoreInfo

open override fun beaconMoreInfo()

bindIsolatedService

open fun bindIsolatedService(service: Intent, flags: Context.BindServiceFlags, instanceName: String, executor: Executor, conn: ServiceConnection): Boolean

open fun bindIsolatedService(service: Intent, flags: Int, instanceName: String, executor: Executor, conn: ServiceConnection): Boolean

bindService

open fun bindService(service: Intent, conn: ServiceConnection, flags: Context.BindServiceFlags): Boolean

open fun bindService(service: Intent, conn: ServiceConnection, flags: Int): Boolean

open fun bindService(service: Intent, flags: Context.BindServiceFlags, executor: Executor, conn: ServiceConnection): Boolean

open fun bindService(service: Intent, flags: Int, executor: Executor, conn: ServiceConnection): Boolean

bindServiceAsUser

open fun bindServiceAsUser(service: Intent, conn: ServiceConnection, flags: Context.BindServiceFlags, user: UserHandle): Boolean

open fun bindServiceAsUser(service: Intent, conn: ServiceConnection, flags: Int, user: UserHandle): Boolean

callbackHoldOff

open override fun callbackHoldOff()

calloutBeacon

open override fun calloutBeacon()

cancelCallout

open override fun cancelCallout()

checkCallingOrSelfPermission

open fun checkCallingOrSelfPermission(permission: String): Int

checkCallingOrSelfUriPermission

open fun checkCallingOrSelfUriPermission(uri: Uri?, modeFlags: Int): Int

checkCallingOrSelfUriPermissions

open fun checkCallingOrSelfUriPermissions(uris: List<Uri?>, modeFlags: Int): IntArray

checkCallingPermission

open fun checkCallingPermission(permission: String): Int

checkCallingUriPermission

open fun checkCallingUriPermission(uri: Uri?, modeFlags: Int): Int

checkCallingUriPermissions

open fun checkCallingUriPermissions(uris: List<Uri?>, modeFlags: Int): IntArray

checkContentUriPermissionFull

open fun checkContentUriPermissionFull(uri: Uri, pid: Int, uid: Int, modeFlags: Int): Int

checkPermission

open fun checkPermission(permission: String, pid: Int, uid: Int): Int

checkSelfPermission

open fun checkSelfPermission(permission: String): Int

checkUriPermission

open fun checkUriPermission(uri: Uri?, pid: Int, uid: Int, modeFlags: Int): Int

open fun checkUriPermission(uri: Uri?, readPermission: String?, writePermission: String?, pid: Int, uid: Int, modeFlags: Int): Int

checkUriPermissions

open fun checkUriPermissions(uris: List<Uri?>, pid: Int, uid: Int, modeFlags: Int): IntArray

clearListener

@UnstableApi

fun clearListener()

clearTextToSpeechQueue

open override fun clearTextToSpeechQueue()

clearWallpaper

open fun ~~clearWallpaper~~()

createAttributionContext

open fun createAttributionContext(attributionTag: String?): Context

createBeacon

open override fun createBeacon(location: LngLatAlt?, headingOnly: Boolean)

createConfigurationContext

open fun createConfigurationContext(overrideConfiguration: Configuration): Context?

createContext

open fun createContext(contextParams: ContextParams): Context

createContextForSplit

open fun createContextForSplit(splitName: String?): Context?

createDeviceContext

open fun createDeviceContext(deviceId: Int): Context

createDeviceProtectedStorageContext

open fun createDeviceProtectedStorageContext(): Context?

createDisplayContext

open fun createDisplayContext(display: Display): Context?

createPackageContext

open fun createPackageContext(packageName: String?, flags: Int): Context?

createWindowContext

open fun createWindowContext(type: Int, options: Bundle?): Context

open fun createWindowContext(display: Display, type: Int, options: Bundle?): Context

cycleCalloutDetail

open override fun cycleCalloutDetail(): CalloutVerbosity

databaseList

open fun databaseList(): Array<out String?>?

deleteDatabase

open fun deleteDatabase(name: String?): Boolean

deleteFile

open fun deleteFile(name: String?): Boolean

deleteSharedPreferences

open fun deleteSharedPreferences(name: String?): Boolean

destroyBeacon

open override fun destroyBeacon()

enforceCallingOrSelfPermission

open fun enforceCallingOrSelfPermission(permission: String, message: String?)

enforceCallingOrSelfUriPermission

open fun enforceCallingOrSelfUriPermission(uri: Uri?, modeFlags: Int, message: String?)

enforceCallingPermission

open fun enforceCallingPermission(permission: String, message: String?)

enforceCallingUriPermission

open fun enforceCallingUriPermission(uri: Uri?, modeFlags: Int, message: String?)

enforcePermission

open fun enforcePermission(permission: String, pid: Int, uid: Int, message: String?)

enforceUriPermission

open fun enforceUriPermission(uri: Uri?, pid: Int, uid: Int, modeFlags: Int, message: String?)

open fun enforceUriPermission(uri: Uri?, readPermission: String?, writePermission: String?, pid: Int, uid: Int, modeFlags: Int, message: String?)

fileList

open fun fileList(): Array<out String?>?

getColor

fun getColor(id: Int): Int

getColorStateList

fun getColorStateList(id: Int): ColorStateList

getDatabasePath

open fun getDatabasePath(name: String?): File?

getDir

open fun getDir(name: String?, mode: Int): File?

getDrawable

fun getDrawable(id: Int): Drawable?

getExternalFilesDir

open fun getExternalFilesDir(type: String?): File?

getExternalFilesDirs

open fun getExternalFilesDirs(type: String?): Array<out File?>?

getFileStreamPath

open fun getFileStreamPath(name: String?): File?

getLocationDescription

open override fun getLocationDescription(location: LngLatAlt): LocationDescription

getOfflineAddress

open suspend override fun getOfflineAddress(location: LngLatAlt): LocationDescription?

getRecordingShareUri

fun getRecordingShareUri(context: Context): Uri?

getSharedPreferences

open fun getSharedPreferences(name: String?, mode: Int): SharedPreferences?

getStreetPreviewBestChoice

open override fun getStreetPreviewBestChoice(): StreetPreviewChoice?

getStreetPreviewChoices

open override fun getStreetPreviewChoices(): List<StreetPreviewChoice>

getString

fun getString(resId: Int): String

fun getString(resId: Int, vararg formatArgs: Any?): String

getSystemService

fun <T : Any?> getSystemService(serviceClass: Class<T?>): T?

open fun getSystemService(name: String): Any?

getSystemServiceName

open fun getSystemServiceName(serviceClass: Class<*>): String?

getText

fun getText(resId: Int): CharSequence

grantUriPermission

open fun grantUriPermission(toPackage: String?, uri: Uri?, modeFlags: Int)

isAudioEngineBusy

open override fun isAudioEngineBusy(): Boolean

isAudioEngineBusy returns true if there is more than one entry in the audio engine queue. The queue consists of earcons and text-to-speech.

isSessionAdded

fun isSessionAdded(session: MediaSession?): Boolean

moveDatabaseFrom

open fun moveDatabaseFrom(sourceContext: Context?, name: String?): Boolean

moveSharedPreferencesFrom

open fun moveSharedPreferencesFrom(sourceContext: Context?, name: String?): Boolean

myLocation

open override fun myLocation()

nearbyMarkers

open override fun nearbyMarkers()

obtainStyledAttributes

fun obtainStyledAttributes(attrs: IntArray): TypedArray

fun obtainStyledAttributes(set: AttributeSet?, attrs: IntArray): TypedArray

fun obtainStyledAttributes(resid: Int, attrs: IntArray): TypedArray

fun obtainStyledAttributes(set: AttributeSet?, attrs: IntArray, defStyleAttr: Int, defStyleRes: Int): TypedArray

onBind

open override fun onBind(intent: Intent?): IBinder

onConfigurationChanged

open fun onConfigurationChanged(newConfig: Configuration)

onCreate

open override fun onCreate()

onDestroy

open override fun onDestroy()

onGetSession

open override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaSession?

onLowMemory

open fun onLowMemory()

onRebind

open fun onRebind(intent: Intent?)

onStart

@CallSuper

open override fun ~~onStart~~(intent: Intent?, startId: Int)

onStartCommand

open override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int

onTaskRemoved

open override fun onTaskRemoved(rootIntent: Intent?)

onTimeout

open fun onTimeout(startId: Int)

open fun onTimeout(startId: Int, fgsType: Int)

onTrimMemory

open fun onTrimMemory(level: Int)

onUnbind

open fun onUnbind(intent: Intent?): Boolean

onUpdateNotification

open fun ~~onUpdateNotification~~(session: MediaSession?)

open override fun onUpdateNotification(session: MediaSession, startInForegroundRequired: Boolean)

Media3's default implementation posts its own media notification and, every time the notification is refreshed, calls Context.startForegroundService() on this service followed by startForeground() with only the mediaPlayback type (or stopForeground() when it decides playback has stopped). Those calls are posted asynchronously, so one that lands after stopSelf() re-creates the service record with a pending "must call startForeground()", and the system then kills the app with a RemoteServiceException as soon as that record is stopped again (e.g. stopWithTask on exit). We own the foreground state and the notification ourselves, so Media3 must not touch either.

openFileInput

open fun openFileInput(name: String?): FileInputStream?

openFileOutput

open fun openFileOutput(name: String?, mode: Int): FileOutputStream?

openOrCreateDatabase

open fun openOrCreateDatabase(name: String?, mode: Int, factory: SQLiteDatabase.CursorFactory?): SQLiteDatabase?

open fun openOrCreateDatabase(name: String?, mode: Int, factory: SQLiteDatabase.CursorFactory?, errorHandler: DatabaseErrorHandler?): SQLiteDatabase?

pauseAllPlayersAndStopSelf

@UnstableApi

fun pauseAllPlayersAndStopSelf()

peekWallpaper

open fun ~~peekWallpaper~~(): Drawable?

rebindService

open fun rebindService(conn: ServiceConnection, flags: Context.BindServiceFlags)

refreshOfflineMaps

fun refreshOfflineMaps()

registerComponentCallbacks

open fun registerComponentCallbacks(callback: ComponentCallbacks?)

registerDeviceIdChangeListener

open fun registerDeviceIdChangeListener(executor: Executor, listener: IntConsumer)

registerReceiver

open fun registerReceiver(receiver: BroadcastReceiver?, filter: IntentFilter?): Intent?

open fun registerReceiver(receiver: BroadcastReceiver?, filter: IntentFilter?, flags: Int): Intent?

open fun registerReceiver(receiver: BroadcastReceiver?, filter: IntentFilter?, broadcastPermission: String?, scheduler: Handler?): Intent?

open fun registerReceiver(receiver: BroadcastReceiver?, filter: IntentFilter?, broadcastPermission: String?, scheduler: Handler?, flags: Int): Intent?

removeSession

fun removeSession(session: MediaSession?)

removeStickyBroadcast

open fun ~~removeStickyBroadcast~~(intent: Intent?)

removeStickyBroadcastAsUser

open fun ~~removeStickyBroadcastAsUser~~(intent: Intent?, user: UserHandle?)

requestAudioFocus

open override fun requestAudioFocus(): Boolean

revokeSelfPermissionOnKill

open fun revokeSelfPermissionOnKill(permName: String)

revokeSelfPermissionsOnKill

open fun revokeSelfPermissionsOnKill(permissions: Collection<String?>)

revokeUriPermission

open fun revokeUriPermission(uri: Uri?, modeFlags: Int)

open fun revokeUriPermission(targetPackage: String?, uri: Uri?, modeFlags: Int)

routeMute

open override fun routeMute(): Boolean

routeSkipNext

open override fun routeSkipNext(): Boolean

routeSkipPrevious

open override fun routeSkipPrevious(): Boolean

routeStartById

open override fun routeStartById(routeId: Long)

routeStartReverse

open override fun routeStartReverse(routeId: Long)

routeStop

open override fun routeStop()

searchIsOfflineWithoutMaps

open override fun searchIsOfflineWithoutMaps(): Boolean

searchResult

open suspend override fun searchResult(query: String): List<LocationDescription>?

sendBroadcast

open fun sendBroadcast(intent: Intent?)

open fun sendBroadcast(intent: Intent?, receiverPermission: String?)

open fun sendBroadcast(intent: Intent, receiverPermission: String?, options: Bundle?)

sendBroadcastAsUser

open fun sendBroadcastAsUser(intent: Intent?, user: UserHandle?)

open fun sendBroadcastAsUser(intent: Intent?, user: UserHandle?, receiverPermission: String?)

sendBroadcastWithMultiplePermissions

open fun sendBroadcastWithMultiplePermissions(intent: Intent, receiverPermissions: Array<out String?>)

sendOrderedBroadcast

open fun sendOrderedBroadcast(intent: Intent?, receiverPermission: String?)

open fun sendOrderedBroadcast(intent: Intent, receiverPermission: String?, options: Bundle?)

open fun sendOrderedBroadcast(intent: Intent, receiverPermission: String?, resultReceiver: BroadcastReceiver?, scheduler: Handler?, initialCode: Int, initialData: String?, initialExtras: Bundle?)

open fun sendOrderedBroadcast(intent: Intent, receiverPermission: String?, options: Bundle?, resultReceiver: BroadcastReceiver?, scheduler: Handler?, initialCode: Int, initialData: String?, initialExtras: Bundle?)

open fun sendOrderedBroadcast(intent: Intent, receiverPermission: String?, receiverAppOp: String?, resultReceiver: BroadcastReceiver?, scheduler: Handler?, initialCode: Int, initialData: String?, initialExtras: Bundle?)

open fun sendOrderedBroadcast(intent: Intent, initialCode: Int, receiverPermission: String?, receiverAppOp: String?, resultReceiver: BroadcastReceiver?, scheduler: Handler?, initialData: String?, initialExtras: Bundle?, options: Bundle?)

sendOrderedBroadcastAsUser

open fun sendOrderedBroadcastAsUser(intent: Intent?, user: UserHandle?, receiverPermission: String?, resultReceiver: BroadcastReceiver?, scheduler: Handler?, initialCode: Int, initialData: String?, initialExtras: Bundle?)

sendStickyBroadcast

open fun ~~sendStickyBroadcast~~(intent: Intent?)

open fun ~~sendStickyBroadcast~~(intent: Intent, options: Bundle?)

sendStickyBroadcastAsUser

open fun ~~sendStickyBroadcastAsUser~~(intent: Intent?, user: UserHandle?)

sendStickyOrderedBroadcast

open fun ~~sendStickyOrderedBroadcast~~(intent: Intent?, resultReceiver: BroadcastReceiver?, scheduler: Handler?, initialCode: Int, initialData: String?, initialExtras: Bundle?)

sendStickyOrderedBroadcastAsUser

open fun ~~sendStickyOrderedBroadcastAsUser~~(intent: Intent?, user: UserHandle?, resultReceiver: BroadcastReceiver?, scheduler: Handler?, initialCode: Int, initialData: String?, initialExtras: Bundle?)

setCalloutVerbosity

open override fun setCalloutVerbosity(verbosity: CalloutVerbosity)

setForegroundServiceTimeoutMs

@UnstableApi

fun setForegroundServiceTimeoutMs(foregroundServiceTimeoutMs: Long)

setShowNotificationForIdlePlayer

@UnstableApi

fun setShowNotificationForIdlePlayer(showNotificationForIdlePlayerMode: Int)

setStreetPreviewMode

open override fun setStreetPreviewMode(on: Boolean, location: LngLatAlt?)

setTheme

open fun setTheme(resid: Int)

setWallpaper

open fun ~~setWallpaper~~(bitmap: Bitmap?)

open fun ~~setWallpaper~~(data: InputStream?)

speak2dText

open override fun speak2dText(text: String, clearQueue: Boolean, earcon: String?)

speakCallout

open override fun speakCallout(callout: TrackedCallout?, addModeEarcon: Boolean): Long

speakText

open override fun speakText(text: String, type: AudioType, latitude: Double, longitude: Double, heading: Double)

startActivities

open fun startActivities(intents: Array<out Intent?>?)

open fun startActivities(intents: Array<out Intent?>?, options: Bundle?)

startActivity

open fun startActivity(intent: Intent?)

open fun startActivity(intent: Intent?, options: Bundle?)

startBeacon

open override fun startBeacon(location: LngLatAlt, name: String)

startBeaconPreview

fun startBeaconPreview(beaconType: String)

startForeground

fun startForeground(id: Int, notification: Notification?)

fun startForeground(id: Int, notification: Notification, foregroundServiceType: Int)

startForegroundService

open fun startForegroundService(service: Intent?): ComponentName?

startInstrumentation

open fun startInstrumentation(className: ComponentName, profileFile: String?, arguments: Bundle?): Boolean

startIntentSender

open fun startIntentSender(intent: IntentSender?, fillInIntent: Intent?, flagsMask: Int, flagsValues: Int, extraFlags: Int)

open fun startIntentSender(intent: IntentSender?, fillInIntent: Intent?, flagsMask: Int, flagsValues: Int, extraFlags: Int, options: Bundle?)

startService

open fun startService(service: Intent?): ComponentName?

stopBeaconPreview

fun stopBeaconPreview(commit: Boolean, chosenBeaconType: String?)

stopForeground

fun ~~stopForeground~~(removeNotification: Boolean)

fun stopForeground(notificationBehavior: Int)

stopForegroundService

fun stopForegroundService(forSleep: Boolean = false)

Stops the foreground service and removes the notification. Can be called from inside or outside the service.

stopSelf

fun stopSelf()

fun stopSelf(startId: Int)

stopSelfResult

fun stopSelfResult(startId: Int): Boolean

stopService

open fun stopService(name: Intent?): Boolean

stopSnooze

fun stopSnooze()

Stops a snoozing service when the user turns wake on leave off, going back to plain sleep. Unlike stopForegroundService this doesn't save the playback state: sleep already did, and nothing has played since, so saving again would forget what to resume.

streetPreviewGo

open override fun streetPreviewGo()

streetPreviewGo is called when the 'GO' button is pressed when in StreetPreview mode. It indicates that the user has selected the direction of travel in which they which to move.

tileGridUpdated

open override fun tileGridUpdated()

triggerNotificationUpdate

@UnstableApi

fun triggerNotificationUpdate()

unbindService

open fun unbindService(conn: ServiceConnection)

unregisterComponentCallbacks