CarAppService


abstract class CarAppService : Service


The base class for implementing a car app that runs in the car

Service Declaration The app must extend the CarAppService to be bound by the car host. The service must also respond to Intent actions coming from the host, by adding an intent-filter to the service in the AndroidManifest.xml that handles the SERVICE_INTERFACE action. The app must also declare what category of application it is (e.g. CATEGORY_NAVIGATION_APP). For example:
<service
  android:name=".YourAppService"
  android:exported="true">
  <intent-filter>
    <action android:name="androidx.car.app.CarAppService" />
    <category android:name="androidx.car.app.category.NAVIGATION"/>
  </intent-filter>
</service>

For a list of all the supported categories see Supported App Categories.

Accessing Location When the app is running in the car display, the system will not consider it as being in the foreground, and hence it will be considered in the background for the purpose of retrieving location as described here.

To reliably get location for your car app, we recommended that you use a foreground service. If you have a service other than your CarAppService that accesses location, run the service and your `CarAppService` in the same process. Also note that accessing location may become unreliable when the phone is in the battery saver mode.

Summary

Constants

const String!
@ExperimentalCarApi
CATEGORY_CALLING_APP = "androidx.car.app.category.CALLING"

Used in the app manifest to declare that this app supports calling.

const String!
CATEGORY_CHARGING_APP = "androidx.car.app.category.CHARGING"

This property is deprecated.

use CATEGORY_POI_APP instead

const String!
@RequiresCarApi(value = 6)
CATEGORY_FEATURE_CLUSTER = "androidx.car.app.category.FEATURE_CLUSTER"

Used to declare that this app supports cluster in the manifest.

const String!
@ExperimentalCarApi
CATEGORY_IOT_APP = "androidx.car.app.category.IOT"

Used in the app manifest.

const String!
@ExperimentalCarApi
CATEGORY_MESSAGING_APP = "androidx.car.app.category.MESSAGING"

Used to declare that this app is a messaging app in the manifest.

const String!
CATEGORY_NAVIGATION_APP = "androidx.car.app.category.NAVIGATION"

Used to declare that this app is a navigation app in the manifest.

const String!
CATEGORY_PARKING_APP = "androidx.car.app.category.PARKING"

This property is deprecated.

use CATEGORY_POI_APP instead

const String!
CATEGORY_POI_APP = "androidx.car.app.category.POI"

Used in the app manifest.

const String!
@ExperimentalCarApi
CATEGORY_SETTINGS_APP = "androidx.car.app.category.SETTINGS"

Used to declare that this app is a settings app in the manifest.

const String!
@ExperimentalCarApi
CATEGORY_WEATHER_APP = "androidx.car.app.category.WEATHER"

Used to declare that this app is a weather app in the manifest.

const String!
SERVICE_INTERFACE = "androidx.car.app.CarAppService"

The full qualified name of the CarAppService class.

Public constructors

Public functions

abstract HostValidator

Returns the HostValidator this service will use to accept or reject host connections.

Unit
@CallSuper
dump(fd: FileDescriptor, writer: PrintWriter, args: Array<String!>?)
Session?

This function is deprecated.

use getSession

HostInfo?

Returns information about the host attached to this service.

Session?
getSession(sessionInfo: SessionInfo)

Returns the Session associated to the given SessionInfo, or null if one doesn't exist.

IBinder

Handles the host binding to this car app.

Session

Creates a new Session for the application.

Session
@RequiresCarApi(value = 6)
onCreateSession(sessionInfo: SessionInfo)

Creates a new Session.

Unit
Boolean
onUnbind(intent: Intent)

Handles the host unbinding from this car app.

Inherited Constants

From android.content.ComponentCallbacks2
From android.content.Context
const String!
ACCESSIBILITY_SERVICE = "accessibility"
const String!
ACCOUNT_SERVICE = "account"
const String!
ACTIVITY_SERVICE = "activity"
const String!
ALARM_SERVICE = "alarm"
const String!
APPWIDGET_SERVICE = "appwidget"
const String!
APP_OPS_SERVICE = "appops"
const String!
APP_SEARCH_SERVICE = "app_search"
const String!
AUDIO_SERVICE = "audio"
const String!
BATTERY_SERVICE = "batterymanager"
const Int
const Int
const Int
const Int
const Int
const Int
const Int
BIND_EXTERNAL_SERVICE = -2147483648
const Long
BIND_EXTERNAL_SERVICE_LONG = 4611686018427387904
const Int
const Int
const Int
const Int
const Int
const Int
const String!
BIOMETRIC_SERVICE = "biometric"
const String!
BLOB_STORE_SERVICE = "blob_store"
const String!
BLUETOOTH_SERVICE = "bluetooth"
const String!
BUGREPORT_SERVICE = "bugreport"
const String!
CAMERA_SERVICE = "camera"
const String!
CAPTIONING_SERVICE = "captioning"
const String!
CARRIER_CONFIG_SERVICE = "carrier_config"
const String!
CLIPBOARD_SERVICE = "clipboard"
const String!
COMPANION_DEVICE_SERVICE = "companiondevice"
const String!
CONNECTIVITY_DIAGNOSTICS_SERVICE = "connectivity_diagnostics"
const String!
CONNECTIVITY_SERVICE = "connectivity"
const String!
CONSUMER_IR_SERVICE = "consumer_ir"
const Int
const Int
const Int
const String!
CREDENTIAL_SERVICE = "credential"
const String!
CROSS_PROFILE_APPS_SERVICE = "crossprofileapps"
const Int
const Int
const String!
DEVICE_LOCK_SERVICE = "device_lock"
const String!
DEVICE_POLICY_SERVICE = "device_policy"
const String!
DISPLAY_HASH_SERVICE = "display_hash"
const String!
DISPLAY_SERVICE = "display"
const String!
DOMAIN_VERIFICATION_SERVICE = "domain_verification"
const String!
DOWNLOAD_SERVICE = "download"
const String!
DROPBOX_SERVICE = "dropbox"
const String!
EUICC_SERVICE = "euicc"
const String!
FILE_INTEGRITY_SERVICE = "file_integrity"
const String!
FINGERPRINT_SERVICE = "fingerprint"
const String!
GAME_SERVICE = "game"
const String!
GRAMMATICAL_INFLECTION_SERVICE = "grammatical_inflection"
const String!
HARDWARE_PROPERTIES_SERVICE = "hardware_properties"
const String!
HEALTHCONNECT_SERVICE = "healthconnect"
const String!
INPUT_METHOD_SERVICE = "input_method"
const String!
INPUT_SERVICE = "input"
const String!
IPSEC_SERVICE = "ipsec"
const String!
JOB_SCHEDULER_SERVICE = "jobscheduler"
const String!
KEYGUARD_SERVICE = "keyguard"
const String!
LAUNCHER_APPS_SERVICE = "launcherapps"
const String!
LAYOUT_INFLATER_SERVICE = "layout_inflater"
const String!
LOCALE_SERVICE = "locale"
const String!
LOCATION_SERVICE = "location"
const String!
MEDIA_COMMUNICATION_SERVICE = "media_communication"
const String!
MEDIA_METRICS_SERVICE = "media_metrics"
const String!
MEDIA_PROJECTION_SERVICE = "media_projection"
const String!
MEDIA_ROUTER_SERVICE = "media_router"
const String!
MEDIA_SESSION_SERVICE = "media_session"
const String!
MIDI_SERVICE = "midi"
const Int
MODE_APPEND = 32768
const Int
const Int

This property is deprecated.

const Int
const Int
const Int

This property is deprecated.

const Int

This property is deprecated.

const String!
const String!
NFC_SERVICE = "nfc"
const String!
NOTIFICATION_SERVICE = "notification"
const String!
NSD_SERVICE = "servicediscovery"
const String!
OVERLAY_SERVICE = "overlay"
const String!
PEOPLE_SERVICE = "people"
const String!
PERFORMANCE_HINT_SERVICE = "performance_hint"
const String!
POWER_SERVICE = "power"
const String!
PRINT_SERVICE = "print"
const Int
const Int
const Int
const String!
RESTRICTIONS_SERVICE = "restrictions"
const String!
ROLE_SERVICE = "role"
const String!
SEARCH_SERVICE = "search"
const String!
SENSOR_SERVICE = "sensor"
const String!
SHORTCUT_SERVICE = "shortcut"
const String!
STATUS_BAR_SERVICE = "statusbar"
const String!
STORAGE_SERVICE = "storage"
const String!
STORAGE_STATS_SERVICE = "storagestats"
const String!
SYSTEM_HEALTH_SERVICE = "systemhealth"
const String!
TELECOM_SERVICE = "telecom"
const String!
TELEPHONY_IMS_SERVICE = "telephony_ims"
const String!
const String!
TELEPHONY_SUBSCRIPTION_SERVICE = "telephony_subscription_service"
const String!
TEXT_CLASSIFICATION_SERVICE = "textclassification"
const String!
const String!
TV_INPUT_SERVICE = "tv_input"
const String!
TV_INTERACTIVE_APP_SERVICE = "tv_interactive_app"
const String!
UI_MODE_SERVICE = "uimode"
const String!
USAGE_STATS_SERVICE = "usagestats"
const String!
USB_SERVICE = "usb"
const String!
USER_SERVICE = "user"
const String!
VIBRATOR_MANAGER_SERVICE = "vibrator_manager"
const String!
VIBRATOR_SERVICE = "vibrator"

This property is deprecated.

const String!
VIRTUAL_DEVICE_SERVICE = "virtualdevice"
const String!
VPN_MANAGEMENT_SERVICE = "vpn_management"
const String!
WALLPAPER_SERVICE = "wallpaper"
const String!
WIFI_AWARE_SERVICE = "wifiaware"
const String!
WIFI_P2P_SERVICE = "wifip2p"
const String!
const String!
WIFI_SERVICE = "wifi"
const String!
WINDOW_SERVICE = "window"
From android.app.Service

Inherited functions

From android.content.Context
From android.content.ContextWrapper
Boolean
bindIsolatedService(
    service: Intent!,
    flags: Int,
    instanceName: String!,
    executor: Executor!,
    conn: ServiceConnection!
)
Boolean
bindService(service: Intent!, conn: ServiceConnection!, flags: Int)
Boolean
bindServiceAsUser(
    service: Intent!,
    conn: ServiceConnection!,
    flags: Int,
    user: UserHandle!
)
Int
Int
IntArray<Int>!
checkCallingOrSelfUriPermissions(
    uris: (Mutable)List<Uri!>!,
    modeFlags: Int
)
Int
Int
checkCallingUriPermission(uri: Uri!, modeFlags: Int)
IntArray<Int>!
checkCallingUriPermissions(uris: (Mutable)List<Uri!>!, modeFlags: Int)
Int
checkPermission(permission: String!, pid: Int, uid: Int)
Int
Int
checkUriPermission(uri: Uri!, pid: Int, uid: Int, modeFlags: Int)
IntArray<Int>!
checkUriPermissions(
    uris: (Mutable)List<Uri!>!,
    pid: Int,
    uid: Int,
    modeFlags: Int
)
Unit

This function is deprecated.

Context!
createAttributionContext(attributionTag: String!)
Context!
createConfigurationContext(overrideConfiguration: Configuration!)
Context!
createContext(contextParams: ContextParams!)
Context!
Context!
Context!
Context!
Context!
createPackageContext(packageName: String!, flags: Int)
Context!
createWindowContext(type: Int, options: Bundle!)
Array<String!>!
Boolean
Boolean
Boolean
Unit
enforceCallingOrSelfPermission(permission: String!, message: String!)
Unit
enforceCallingOrSelfUriPermission(
    uri: Uri!,
    modeFlags: Int,
    message: String!
)
Unit
enforceCallingPermission(permission: String!, message: String!)
Unit
enforceCallingUriPermission(uri: Uri!, modeFlags: Int, message: String!)
Unit
enforcePermission(permission: String!, pid: Int, uid: Int, message: String!)
Unit
enforceUriPermission(
    uri: Uri!,
    pid: Int,
    uid: Int,
    modeFlags: Int,
    message: String!
)
Array<String!>!
Context!
ApplicationInfo!
AssetManager!
AttributionSource!
String!
Context!
File!
ClassLoader!
File!
ContentResolver!
File!
File!
Int
File!
getDir(name: String!, mode: Int)
Display!
File!
Array<File!>!
File!
Array<File!>!
Array<File!>!

This function is deprecated.

File!
File!
Executor!
Looper!
File!
File!
Array<File!>!
String!
String!
PackageManager!
String!
String!
ContextParams!
Resources!
SharedPreferences!
getSharedPreferences(name: String!, mode: Int)
Any!
String!
getSystemServiceName(serviceClass: Class<Any!>!)
Resources.Theme!
Drawable!

This function is deprecated.

Int

This function is deprecated.

Int

This function is deprecated.

Unit
grantUriPermission(toPackage: String!, uri: Uri!, modeFlags: Int)
Boolean
Boolean
Boolean
Boolean
moveDatabaseFrom(sourceContext: Context!, name: String!)
Boolean
moveSharedPreferencesFrom(sourceContext: Context!, name: String!)
FileInputStream!
FileOutputStream!
openFileOutput(name: String!, mode: Int)
SQLiteDatabase!
openOrCreateDatabase(
    name: String!,
    mode: Int,
    factory: SQLiteDatabase.CursorFactory!
)
Drawable!

This function is deprecated.

Unit
Unit
Intent!
Unit

This function is deprecated.

Unit

This function is deprecated.

Unit
Unit
revokeUriPermission(uri: Uri!, modeFlags: Int)
Unit
Unit
Unit
sendOrderedBroadcast(intent: Intent!, receiverPermission: String!)
Unit
sendOrderedBroadcastAsUser(
    intent: Intent!,
    user: UserHandle!,
    receiverPermission: String!,
    resultReceiver: BroadcastReceiver!,
    scheduler: Handler!,
    initialCode: Int,
    initialData: String!,
    initialExtras: Bundle!
)
Unit

This function is deprecated.

Unit

This function is deprecated.

Unit
sendStickyOrderedBroadcast(
    intent: Intent!,
    resultReceiver: BroadcastReceiver!,
    scheduler: Handler!,
    initialCode: Int,
    initialData: String!,
    initialExtras: Bundle!
)

This function is deprecated.

Unit
sendStickyOrderedBroadcastAsUser(
    intent: Intent!,
    user: UserHandle!,
    resultReceiver: BroadcastReceiver!,
    scheduler: Handler!,
    initialCode: Int,
    initialData: String!,
    initialExtras: Bundle!
)

This function is deprecated.

Unit
setTheme(resid: Int)
Unit
setWallpaper(bitmap: Bitmap!)

This function is deprecated.

Unit
Unit
ComponentName!
Boolean
startInstrumentation(
    className: ComponentName!,
    profileFile: String!,
    arguments: Bundle!
)
Unit
startIntentSender(
    intent: IntentSender!,
    fillInIntent: Intent!,
    flagsMask: Int,
    flagsValues: Int,
    extraFlags: Int
)
ComponentName!
startService(service: Intent!)
Boolean
Unit
Unit
Unit
Unit
Unit
updateServiceGroup(conn: ServiceConnection!, group: Int, importance: Int)
From android.app.Service
Unit
Application!
Int
Unit
Unit
Unit
Unit
onRebind(intent: Intent!)
Unit
onStart(intent: Intent!, startId: Int)

This function is deprecated.

Int
onStartCommand(intent: Intent!, flags: Int, startId: Int)
Unit
onTaskRemoved(rootIntent: Intent!)
Unit
onTimeout(startId: Int)
Unit
onTrimMemory(level: Int)
Unit
startForeground(id: Int, notification: Notification!)
Unit
stopForeground(removeNotification: Boolean)

This function is deprecated.

Unit
Boolean
stopSelfResult(startId: Int)

Constants

CATEGORY_CALLING_APP

Added in 1.4.0
@ExperimentalCarApi
const val CATEGORY_CALLING_APP = "androidx.car.app.category.CALLING": String!

Used in the app manifest to declare that this app supports calling.

CATEGORY_CHARGING_APP

Added in 1.0.0
Deprecated in 1.3.0
const val CATEGORY_CHARGING_APP = "androidx.car.app.category.CHARGING": String!

Used to declare that this app is a charging app in the manifest.

CATEGORY_FEATURE_CLUSTER

Added in 1.3.0
@RequiresCarApi(value = 6)
const val CATEGORY_FEATURE_CLUSTER = "androidx.car.app.category.FEATURE_CLUSTER": String!

Used to declare that this app supports cluster in the manifest.

CATEGORY_IOT_APP

Added in 1.3.0
@ExperimentalCarApi
const val CATEGORY_IOT_APP = "androidx.car.app.category.IOT": String!

Used in the app manifest. It declares that this app declares physical objects with sensors, that connect and exchange data with other devices and systems.

CATEGORY_MESSAGING_APP

Added in 1.3.0
@ExperimentalCarApi
const val CATEGORY_MESSAGING_APP = "androidx.car.app.category.MESSAGING": String!

Used to declare that this app is a messaging app in the manifest.

This app can be used to send and receive short-form chat messages (IM/SMS).

CATEGORY_NAVIGATION_APP

Added in 1.0.0
const val CATEGORY_NAVIGATION_APP = "androidx.car.app.category.NAVIGATION": String!

Used to declare that this app is a navigation app in the manifest.

CATEGORY_PARKING_APP

Added in 1.0.0
Deprecated in 1.3.0
const val CATEGORY_PARKING_APP = "androidx.car.app.category.PARKING": String!

Used to declare that this app is a parking app in the manifest.

CATEGORY_POI_APP

Added in 1.3.0
const val CATEGORY_POI_APP = "androidx.car.app.category.POI": String!

Used in the app manifest. It declares that this app finds points of interests (POI).

CATEGORY_SETTINGS_APP

Added in 1.2.0
@ExperimentalCarApi
const val CATEGORY_SETTINGS_APP = "androidx.car.app.category.SETTINGS": String!

Used to declare that this app is a settings app in the manifest. This app can be used to provide screens corresponding to the settings page and/or any error resolution screens e.g. sign-in screen.

CATEGORY_WEATHER_APP

Added in 1.4.0
@ExperimentalCarApi
const val CATEGORY_WEATHER_APP = "androidx.car.app.category.WEATHER": String!

Used to declare that this app is a weather app in the manifest.

SERVICE_INTERFACE

Added in 1.0.0
const val SERVICE_INTERFACE = "androidx.car.app.CarAppService": String!

The full qualified name of the CarAppService class.

This is the same name that must be used to declare the action of the intent filter for the app's CarAppService in the app's manifest.

See also
CarAppService

Public constructors

CarAppService

Added in 1.0.0
CarAppService()

Public functions

createHostValidator

Added in 1.0.0
abstract fun createHostValidator(): HostValidator

Returns the HostValidator this service will use to accept or reject host connections.

By default, the provided HostValidator.Builder would produce a validator that only accepts connections from hosts holding TEMPLATE_RENDERER_PERMISSION permission.

Application developers are expected to also allow connections from known hosts which don't hold the aforementioned permission (for example, Android Auto and Android Automotive OS hosts below API level 31), by allow-listing the signatures of those hosts.

Refer to androidx.car.app.R.array.hosts_allowlist_sample to obtain a list of package names and signatures that should be allow-listed by default.

It is also advised to allow connections from unknown hosts in debug builds to facilitate debugging and testing.

Below is an example of this method implementation:

@Override
@NonNull
public HostValidator createHostValidator() {
    if ((getApplicationInfo().flags & ApplicationInfo.FLAG_DEBUGGABLE) != 0) {
        return HostValidator.ALLOW_ALL_HOSTS_VALIDATOR;
    } else {
        return new HostValidator.Builder(context)
            .addAllowedHosts(androidx.car.app.R.array.hosts_allowlist_sample)
            .build();
    }
}

dump

Added in 1.0.0
@CallSuper
fun dump(fd: FileDescriptor, writer: PrintWriter, args: Array<String!>?): Unit

getCurrentSession

Added in 1.0.0
Deprecated in 1.3.0
fun getCurrentSession(): Session?

Returns the current Session for the main display if one exists, otherwise returns null.

getHostInfo

Added in 1.0.0
fun getHostInfo(): HostInfo?

Returns information about the host attached to this service.

See also
HostInfo

getSession

Added in 1.3.0
fun getSession(sessionInfo: SessionInfo): Session?

Returns the Session associated to the given SessionInfo, or null if one doesn't exist.

onBind

Added in 1.0.0
@CallSuper
fun onBind(intent: Intent): IBinder

Handles the host binding to this car app.

This method is final to ensure this car app's lifecycle is handled properly.

Use onCreateSession and onNewIntent instead to handle incoming Intents.

onCreateSession

Added in 1.0.0
fun onCreateSession(): Session

Creates a new Session for the application.

This method is invoked the first time the app is started, or if the previous Session instance has been destroyed and the system has not yet destroyed this service.

Once the method returns, onCreateScreen will be called on the Session returned.

Called by the system, do not call this method directly.

See also
startCarApp

onCreateSession

Added in 1.3.0
@RequiresCarApi(value = 6)
fun onCreateSession(sessionInfo: SessionInfo): Session

Creates a new Session.

This method is invoked once per app-supported physical display with a unique SessionInfo identifying the type of display. Support for displays is declared within the AndroidManifest.xml. This method can also be invoked if the previous instance has been destroyed (ie. due to memory pressure) and the system has not yet destroyed this service.

This method is called by the system and should not be called directly.

See also
startCarApp

onDestroy

@CallSuper
fun onDestroy(): Unit

onUnbind

Added in 1.0.0
fun onUnbind(intent: Intent): Boolean

Handles the host unbinding from this car app.

This method is final to ensure this car app's lifecycle is handled properly.