CarContext

Added in 1.0.0

Kotlin |Java

class CarContext : ContextWrapper

kotlin.Any
↳	android.content.Context
	↳	android.content.ContextWrapper
		↳	androidx.car.app.CarContext

Known direct subclasses

TestCarContext

TestCarContext

The CarContext that is used for testing.

The CarContext class is a ContextWrapper subclass accessible to your CarAppService and Screen instances, which provides access to car services such as the ScreenManager for managing the screen stack, the AppManager for general app-related functionality such as accessing a surface for drawing your navigation app's map, and the NavigationManager used by turn-by-turn navigation apps to communicate navigation metadata and other navigation-related events with the host. See Access the navigation templates for a comprehensive list of library functionality available to navigation apps.

Whenever you use a CarContext to load resources, the following configuration elements come from the car screen's configuration, and not the phone:

Screen width.
Screen height.
Screen pixel density (DPI).
Night mode (See isDarkMode).

Please refer here, on how to use configuration qualifiers in your resources.

See also
`getCarService`

Summary

Constants
`const String!`	`ACTION_NAVIGATE = "androidx.car.app.action.NAVIGATE"` Standard action for navigating to a location.
`const String!`	`APP_SERVICE = "app"` Manages all app events such as invalidating the UI, showing a toast, etc.
`const String!`	`CAR_SERVICE = "car"` Internal usage only.
`const String!`	`@RequiresCarApi(value = 2) CONSTRAINT_SERVICE = "constraints"` Manages constraints for the app as enforced by the connected host.
`const String!`	`EXTRA_START_CAR_APP_BINDER_KEY = "androidx.car.app.extra.START_CAR_APP_BINDER_KEY"` Key for including a IStartCarApp in the notification `Intent`, for starting the app if it has not been opened yet.
`const String!`	`@RequiresCarApi(value = 3) HARDWARE_SERVICE = "hardware"` Manages access to androidx.car.app.hardware properties, sensors and actions.
`const String!`	`@ExperimentalCarApi MEDIA_PLAYBACK_SERVICE = "media_playback"` Manages the media requests from 3p apps such as providing a media session token,
`const String!`	`NAVIGATION_SERVICE = "navigation"` Manages all navigation events such as starting navigation when focus is granted, abandoning navigation when focus is lost, etc.
`const String!`	`SCREEN_SERVICE = "screen"` Manages the screens of the app, including the screen stack.
`const String!`	`SUGGESTION_SERVICE = "suggestion"` Manages posting suggestion events

Public functions
`Unit`	`finishCarApp()` Requests to finish the car app.
`ComponentName?`	`@RequiresCarApi(value = 2) getCallingComponent()` Return the component (service or activity) that invoked this car app.
`Int`	`getCarAppApiLevel()` Retrieves the API level negotiated with the host.
`Any`	`getCarService(name: String)` Provides a car service by name.
`T`	`<T> getCarService(serviceClass: Class<T!>)` Returns a car service by class.
`String`	`getCarServiceName(serviceClass: Class<Any!>)` Gets the name of the car service that is represented by the specified class.
`HostInfo?`	`getHostInfo()` Returns information about the host attached to this service.
`OnBackPressedDispatcher`	`getOnBackPressedDispatcher()` Returns the `OnBackPressedDispatcher` that will be triggered when the user clicks a back button.
`Boolean`	`isDarkMode()` Returns `true` if the car is set to dark mode.
`Unit`	`requestPermissions( permissions: (Mutable)List<String!>, listener: OnRequestPermissionsListener )` Requests the provided `permissions` from the user, calling the provided `listener` in the main thread.
`Unit`	`requestPermissions( permissions: (Mutable)List<String!>, executor: Executor, listener: OnRequestPermissionsListener )` Requests the provided `permissions` from the user.
`Unit`	`@RequiresCarApi(value = 2) setCarAppResult(resultCode: Int, data: Intent?)` Sets the result of this car app.
`Unit`	`startCarApp(intent: Intent)` Starts a car app on the car screen.
`java-static Unit`	`startCarApp(notificationIntent: Intent, appIntent: Intent)` This function is deprecated. use `getCarApp` to create the pending intent for the notification action.

Inherited Constants

From android.content.Context

`const String!`	`ACCESSIBILITY_SERVICE = "accessibility"`
`const String!`	`ACCOUNT_SERVICE = "account"`
`const String!`	`ACTIVITY_SERVICE = "activity"`
`const String!`	`ADVANCED_PROTECTION_SERVICE = "advanced_protection"`
`const String!`	`ALARM_SERVICE = "alarm"`
`const String!`	`APPWIDGET_SERVICE = "appwidget"`
`const String!`	`APP_FUNCTION_SERVICE = "app_function"`
`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`	`BIND_ABOVE_CLIENT = 8`
`const Int`	`BIND_ADJUST_WITH_ACTIVITY = 128`
`const Int`	`BIND_ALLOW_ACTIVITY_STARTS = 512`
`const Int`	`BIND_ALLOW_OOM_MANAGEMENT = 16`
`const Int`	`BIND_AUTO_CREATE = 1`
`const Int`	`BIND_DEBUG_UNBIND = 2`
`const Int`	`BIND_EXTERNAL_SERVICE = -2147483648`
`const Long`	`BIND_EXTERNAL_SERVICE_LONG = 4611686018427387904`
`const Int`	`BIND_IMPORTANT = 64`
`const Int`	`BIND_INCLUDE_CAPABILITIES = 4096`
`const Int`	`BIND_NOT_FOREGROUND = 4`
`const Int`	`BIND_NOT_PERCEPTIBLE = 256`
`const Int`	`BIND_PACKAGE_ISOLATED_PROCESS = 16384`
`const Int`	`BIND_SHARED_ISOLATED_PROCESS = 8192`
`const Int`	`BIND_WAIVE_PRIORITY = 32`
`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 String!`	`CONTACT_KEYS_SERVICE = "contact_keys"`
`const Int`	`CONTEXT_IGNORE_SECURITY = 2`
`const Int`	`CONTEXT_INCLUDE_CODE = 1`
`const Int`	`CONTEXT_RESTRICTED = 4`
`const String!`	`CREDENTIAL_SERVICE = "credential"`
`const String!`	`CROSS_PROFILE_APPS_SERVICE = "crossprofileapps"`
`const Int`	`DEVICE_ID_DEFAULT = 0`
`const Int`	`DEVICE_ID_INVALID = -1`
`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!`	`KEYSTORE_SERVICE = "keystore"`
`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_QUALITY_SERVICE = "media_quality"`
`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`	`MODE_ENABLE_WRITE_AHEAD_LOGGING = 8`
`const Int`	`MODE_MULTI_PROCESS = 4` This property is deprecated.
`const Int`	`MODE_NO_LOCALIZED_COLLATORS = 16`
`const Int`	`MODE_PRIVATE = 0`
`const Int`	`MODE_WORLD_READABLE = 1` This property is deprecated.
`const Int`	`MODE_WORLD_WRITEABLE = 2` This property is deprecated.
`const String!`	`NETWORK_STATS_SERVICE = "netstats"`
`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!`	`PERSISTENT_DATA_BLOCK_SERVICE = "persistent_data_block"`
`const String!`	`POWER_SERVICE = "power"`
`const String!`	`PRINT_SERVICE = "print"`
`const String!`	`PROFILING_SERVICE = "profiling"`
`const Int`	`RECEIVER_EXPORTED = 2`
`const Int`	`RECEIVER_NOT_EXPORTED = 4`
`const Int`	`RECEIVER_VISIBLE_TO_INSTANT_APPS = 1`
`const String!`	`RESTRICTIONS_SERVICE = "restrictions"`
`const String!`	`ROLE_SERVICE = "role"`
`const String!`	`SATELLITE_SERVICE = "satellite"`
`const String!`	`SEARCH_SERVICE = "search"`
`const String!`	`SECURITY_STATE_SERVICE = "security_state"`
`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!`	`TELEPHONY_SERVICE = "phone"`
`const String!`	`TELEPHONY_SUBSCRIPTION_SERVICE = "telephony_subscription_service"`
`const String!`	`TETHERING_SERVICE = "tethering"`
`const String!`	`TEXT_CLASSIFICATION_SERVICE = "textclassification"`
`const String!`	`TEXT_SERVICES_MANAGER_SERVICE = "textservices"`
`const String!`	`TV_AD_SERVICE = "tv_ad"`
`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!`	`WIFI_RTT_RANGING_SERVICE = "wifirtt"`
`const String!`	`WIFI_SERVICE = "wifi"`
`const String!`	`WINDOW_SERVICE = "window"`

Inherited functions

From android.content.Context

`Int`	`getColor(id: Int)`
`ColorStateList!`	`getColorStateList(id: Int)`
`Drawable!`	`getDrawable(id: Int)`
`String!`	`getString(resId: Int)`
`T!`	`<T> getSystemService(serviceClass: Class<T!>!)`
`CharSequence!`	`getText(resId: Int)`
`TypedArray!`	`obtainStyledAttributes(set: AttributeSet!, attrs: IntArray!)`
`Unit`	`revokeSelfPermissionOnKill(permName: String!)`
`Unit`	`sendBroadcastWithMultiplePermissions( intent: Intent!, receiverPermissions: Array<String!>! )`

From android.content.ContextWrapper

`Unit`	`attachBaseContext(base: Context!)`
`Boolean`	`bindIsolatedService( service: Intent!, flags: Int, instanceName: String!, executor: Executor!, conn: ServiceConnection! )`
`Boolean`	`bindService( service: Intent!, flags: Context.BindServiceFlags!, executor: Executor!, conn: ServiceConnection! )`
`Boolean`	`bindServiceAsUser( service: Intent!, conn: ServiceConnection!, flags: Context.BindServiceFlags!, user: UserHandle! )`
`Int`	`checkCallingOrSelfPermission(permission: String!)`
`Int`	`checkCallingOrSelfUriPermission(uri: Uri!, modeFlags: Int)`
`IntArray<Int>!`	`checkCallingOrSelfUriPermissions( uris: (Mutable)List<Uri!>!, modeFlags: Int )`
`Int`	`checkCallingPermission(permission: String!)`
`Int`	`checkCallingUriPermission(uri: Uri!, modeFlags: Int)`
`IntArray<Int>!`	`checkCallingUriPermissions(uris: (Mutable)List<Uri!>!, modeFlags: Int)`
`Int`	`checkContentUriPermissionFull(uri: Uri!, pid: Int, uid: Int, modeFlags: Int)`
`Int`	`checkPermission(permission: String!, pid: Int, uid: Int)`
`Int`	`checkSelfPermission(permission: String!)`
`Int`	`checkUriPermission(uri: Uri!, pid: Int, uid: Int, modeFlags: Int)`
`IntArray<Int>!`	`checkUriPermissions( uris: (Mutable)List<Uri!>!, pid: Int, uid: Int, modeFlags: Int )`
`Unit`	`clearWallpaper()` This function is deprecated.
`Context!`	`createAttributionContext(attributionTag: String!)`
`Context!`	`createConfigurationContext(overrideConfiguration: Configuration!)`
`Context!`	`createContext(contextParams: ContextParams!)`
`Context!`	`createContextForSplit(splitName: String!)`
`Context!`	`createDeviceContext(deviceId: Int)`
`Context!`	`createDeviceProtectedStorageContext()`
`Context!`	`createDisplayContext(display: Display!)`
`Context!`	`createPackageContext(packageName: String!, flags: Int)`
`Context!`	`createWindowContext(display: Display!, type: Int, options: Bundle!)`
`Array<String!>!`	`databaseList()`
`Boolean`	`deleteDatabase(name: String!)`
`Boolean`	`deleteFile(name: String!)`
`Boolean`	`deleteSharedPreferences(name: String!)`
`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!>!`	`fileList()`
`Context!`	`getApplicationContext()`
`ApplicationInfo!`	`getApplicationInfo()`
`AssetManager!`	`getAssets()`
`AttributionSource!`	`getAttributionSource()`
`String!`	`getAttributionTag()`
`Context!`	`getBaseContext()`
`File!`	`getCacheDir()`
`ClassLoader!`	`getClassLoader()`
`File!`	`getCodeCacheDir()`
`ContentResolver!`	`getContentResolver()`
`File!`	`getDataDir()`
`File!`	`getDatabasePath(name: String!)`
`Int`	`getDeviceId()`
`File!`	`getDir(name: String!, mode: Int)`
`Display!`	`getDisplay()`
`File!`	`getExternalCacheDir()`
`Array<File!>!`	`getExternalCacheDirs()`
`File!`	`getExternalFilesDir(type: String!)`
`Array<File!>!`	`getExternalFilesDirs(type: String!)`
`Array<File!>!`	`getExternalMediaDirs()` This function is deprecated.
`File!`	`getFileStreamPath(name: String!)`
`File!`	`getFilesDir()`
`Executor!`	`getMainExecutor()`
`Looper!`	`getMainLooper()`
`File!`	`getNoBackupFilesDir()`
`File!`	`getObbDir()`
`Array<File!>!`	`getObbDirs()`
`String!`	`getOpPackageName()`
`String!`	`getPackageCodePath()`
`PackageManager!`	`getPackageManager()`
`String!`	`getPackageName()`
`String!`	`getPackageResourcePath()`
`ContextParams!`	`getParams()`
`Resources!`	`getResources()`
`SharedPreferences!`	`getSharedPreferences(name: String!, mode: Int)`
`Any!`	`getSystemService(name: String!)`
`String!`	`getSystemServiceName(serviceClass: Class<Any!>!)`
`Resources.Theme!`	`getTheme()`
`Drawable!`	`getWallpaper()` This function is deprecated.
`Int`	`getWallpaperDesiredMinimumHeight()` This function is deprecated.
`Int`	`getWallpaperDesiredMinimumWidth()` This function is deprecated.
`Unit`	`grantUriPermission(toPackage: String!, uri: Uri!, modeFlags: Int)`
`Boolean`	`isDeviceProtectedStorage()`
`Boolean`	`isRestricted()`
`Boolean`	`isUiContext()`
`Boolean`	`moveDatabaseFrom(sourceContext: Context!, name: String!)`
`Boolean`	`moveSharedPreferencesFrom(sourceContext: Context!, name: String!)`
`FileInputStream!`	`openFileInput(name: String!)`
`FileOutputStream!`	`openFileOutput(name: String!, mode: Int)`
`SQLiteDatabase!`	`openOrCreateDatabase( name: String!, mode: Int, factory: SQLiteDatabase.CursorFactory! )`
`Drawable!`	`peekWallpaper()` This function is deprecated.
`Unit`	`registerComponentCallbacks(callback: ComponentCallbacks!)`
`Unit`	`registerDeviceIdChangeListener(executor: Executor!, listener: IntConsumer!)`
`Intent!`	`registerReceiver(receiver: BroadcastReceiver!, filter: IntentFilter!)`
`Unit`	`removeStickyBroadcast(intent: Intent!)` This function is deprecated.
`Unit`	`removeStickyBroadcastAsUser(intent: Intent!, user: UserHandle!)` This function is deprecated.
`Unit`	`revokeSelfPermissionsOnKill(permissions: (Mutable)Collection<String!>!)`
`Unit`	`revokeUriPermission(uri: Uri!, modeFlags: Int)`
`Unit`	`sendBroadcast(intent: Intent!)`
`Unit`	`sendBroadcastAsUser(intent: Intent!, user: UserHandle!)`
`Unit`	`sendOrderedBroadcast( intent: Intent!, initialCode: Int, receiverPermission: String!, receiverAppOp: String!, resultReceiver: BroadcastReceiver!, scheduler: Handler!, initialData: String!, initialExtras: Bundle!, options: Bundle! )`
`Unit`	`sendOrderedBroadcastAsUser( intent: Intent!, user: UserHandle!, receiverPermission: String!, resultReceiver: BroadcastReceiver!, scheduler: Handler!, initialCode: Int, initialData: String!, initialExtras: Bundle! )`
`Unit`	`sendStickyBroadcast(intent: Intent!)` This function is deprecated.
`Unit`	`sendStickyBroadcastAsUser(intent: Intent!, user: UserHandle!)` 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`	`startActivities(intents: Array<Intent!>!)`
`Unit`	`startActivity(intent: Intent!)`
`ComponentName!`	`startForegroundService(service: Intent!)`
`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`	`stopService(name: Intent!)`
`Unit`	`unbindService(conn: ServiceConnection!)`
`Unit`	`unregisterComponentCallbacks(callback: ComponentCallbacks!)`
`Unit`	`unregisterDeviceIdChangeListener(listener: IntConsumer!)`
`Unit`	`unregisterReceiver(receiver: BroadcastReceiver!)`
`Unit`	`updateServiceGroup(conn: ServiceConnection!, group: Int, importance: Int)`

Constants

ACTION_NAVIGATE

Added in 1.0.0

const val ACTION_NAVIGATE = "androidx.car.app.action.NAVIGATE": String!

Standard action for navigating to a location.

Used as the Intent's action for starting a navigation via startCarApp.

APP_SERVICE

Added in 1.0.0

const val APP_SERVICE = "app": String!

Manages all app events such as invalidating the UI, showing a toast, etc.

CAR_SERVICE

Added in 1.0.0

const val CAR_SERVICE = "car": String!

Internal usage only. Top level binder to host.

CONSTRAINT_SERVICE

Added in 1.1.0

@RequiresCarApi(value = 2)
const val CONSTRAINT_SERVICE = "constraints": String!

Manages constraints for the app as enforced by the connected host.

EXTRA_START_CAR_APP_BINDER_KEY

Added in 1.0.0

const val EXTRA_START_CAR_APP_BINDER_KEY = "androidx.car.app.extra.START_CAR_APP_BINDER_KEY": String!

Key for including a IStartCarApp in the notification Intent, for starting the app if it has not been opened yet.

HARDWARE_SERVICE

Added in 1.1.0

@RequiresCarApi(value = 3)
const val HARDWARE_SERVICE = "hardware": String!

Manages access to androidx.car.app.hardware properties, sensors and actions.

MEDIA_PLAYBACK_SERVICE

Added in 1.4.0

@ExperimentalCarApi
const val MEDIA_PLAYBACK_SERVICE = "media_playback": String!

Manages the media requests from 3p apps such as providing a media session token,

NAVIGATION_SERVICE

Added in 1.0.0

const val NAVIGATION_SERVICE = "navigation": String!

Manages all navigation events such as starting navigation when focus is granted, abandoning navigation when focus is lost, etc.

SCREEN_SERVICE

Added in 1.0.0

const val SCREEN_SERVICE = "screen": String!

Manages the screens of the app, including the screen stack.

SUGGESTION_SERVICE

Added in 1.3.0

const val SUGGESTION_SERVICE = "suggestion": String!

Manages posting suggestion events

Public functions

finishCarApp

Added in 1.0.0

fun finishCarApp(): Unit

Requests to finish the car app.

Call this when your app is done and should be closed. The Session corresponding to this CarContext will become State.DESTROYED.

At some point after this call, the OS will destroy your CarAppService.

This method should not be called until the Lifecycle.State of the context's Session is at least CREATED.

getCallingComponent

Added in 1.1.0

@RequiresCarApi(value = 2)
fun getCallingComponent(): ComponentName?

Return the component (service or activity) that invoked this car app.

This is who the data in setCarAppResult will be sent to. You can use this information to validate that the recipient is allowed to receive the data.

Starting applications for result is not implemented in Android Auto, and this method will always return null for that platform.

Returns
`ComponentName?`	the `ComponentName` of the component that will receive your reply, or `null` if none

getCarAppApiLevel

Added in 1.0.0

fun getCarAppApiLevel(): Int

Retrieves the API level negotiated with the host.

API levels are used during client and host connection handshake to negotiate a common set of elements that both processes can understand. Different devices might have different host versions. Each of these hosts will support a range of API levels, as a way to provide backwards compatibility.

Applications can also provide forward compatibility, by declaring support for a getMinCarAppApiLevel lower than getLatestCarAppApiLevel. See getMinCarAppApiLevel for more details.

Clients must ensure no elements annotated with a RequiresCarApi value higher than returned by this method is used at runtime.

Refer to RequiresCarApi description for more details on how to implement forward compatibility.

This method should not be called until the Lifecycle.State of the context's Session is at least CREATED.

Returns
`Int`	a value between `getMinCarAppApiLevel` and `getLatestCarAppApiLevel`. In case of incompatibility, the host will disconnect from the service before completing the handshake

Throws
`java.lang.IllegalStateException`	if invoked before the connection handshake with the host has been completed (for example, before `onCreateScreen`)

getCarService

Added in 1.0.0

fun getCarService(name: String): Any

Provides a car service by name.

The class of the returned object varies by the requested name.

Currently supported car services, and their respective classes, are:

APP_SERVICE: An AppManager for communication between the app and the host.
NAVIGATION_SERVICE: A NavigationManager for management of navigation updates.
SCREEN_SERVICE: A ScreenManager for management of Screens.
CONSTRAINT_SERVICE: A ConstraintManager for management of content limits.
HARDWARE_SERVICE: A CarHardwareManager for interacting with car hardware (e.g. sensors) data.
SUGGESTION_SERVICE: A SuggestionManager for posting androidx.car.app.suggestion.model.Suggestions.

This method should not be called until the Lifecycle.State of the context's Session is at least CREATED.

Parameters
`name: String`	The name of the car service requested. This should be one of `APP_SERVICE`, `NAVIGATION_SERVICE` or `SCREEN_SERVICE`

Returns
`Any`	The car service instance

Throws
`java.lang.IllegalArgumentException`	if `name` does not refer to a valid car service
`java.lang.IllegalStateException`	if the service referred by `name` can not be instantiated (e.g. missing library dependency)
`java.lang.NullPointerException`	if `name` is `null`

getCarService

Added in 1.0.0

fun <T> getCarService(serviceClass: Class<T!>): T

Returns a car service by class.

See getCarService for a list of the supported car services.

This method should not be called until the Lifecycle.State of the context's Session is at least CREATED.

Parameters
`serviceClass: Class<T!>`	the class of the requested service

Throws
`java.lang.IllegalArgumentException`	if `serviceClass` is not the class of a supported car service
`java.lang.IllegalStateException`	if `serviceClass` can not be instantiated (e.g. missing library dependency)
`java.lang.NullPointerException`	if `serviceClass` is `null`

getCarServiceName

Added in 1.0.0

fun getCarServiceName(serviceClass: Class<Any!>): String

Gets the name of the car service that is represented by the specified class.

This method should not be called until the Lifecycle.State of the context's Session is at least CREATED.

Parameters
`serviceClass: Class<Any!>`	the class of the requested service

Returns
`String`	the car service name to use with `getCarService`

Throws
`java.lang.IllegalArgumentException`	if `serviceClass` is not the class of a supported car service
`java.lang.NullPointerException`	if `serviceClass` is `null`

See also
`getCarService`

getHostInfo

Added in 1.1.0

fun getHostInfo(): HostInfo?

Returns information about the host attached to this service.

This method should not be called until the Lifecycle.State of the context's Session is at least CREATED.

Returns
`HostInfo?`	The `HostInfo` of the connected host, or `null` if it is not available.

See also
`HostInfo`

getOnBackPressedDispatcher

Added in 1.0.0

fun getOnBackPressedDispatcher(): OnBackPressedDispatcher

Returns the OnBackPressedDispatcher that will be triggered when the user clicks a back button.

The default back press behavior is to call pop.

To override the default behavior, register a androidx.activity.OnBackPressedCallback via calling addCallback. Using the LifecycleOwner ensures that your callback is only registered while its Lifecycle is at least STARTED.

If there is a androidx.activity.OnBackPressedCallback that is added and enabled, and you'd like to remove the top Screen as a part of the callback, you MUST call pop in the callback. The default behavior is overridden when you have a callback enabled.

isDarkMode

Added in 1.0.0

fun isDarkMode(): Boolean

Returns true if the car is set to dark mode.

Navigation applications must redraw their map with the proper dark colors when the host determines that conditions warrant it, as signaled by the value returned by this method.

Whenever the dark mode status changes, you will receive a call to onCarConfigurationChanged.

This method should not be called until the Lifecycle.State of the context's Session is at least CREATED.

requestPermissions

Added in 1.1.0

fun requestPermissions(
    permissions: (Mutable)List<String!>,
    listener: OnRequestPermissionsListener
): Unit

Requests the provided permissions from the user, calling the provided listener in the main thread.

The app can define a branded background to the permission request through the carPermissionActivityLayout theme attribute, by declaring it in a theme and referencing the theme from the androidx.car.app.theme metadata.

In AndroidManifest.xml, under the application element corresponding to the car app:

<meta-data
  android:name="androidx.car.app.theme"
  android:resource="@style/CarAppTheme"/>

The CarAppTheme style is defined as any other themes in a resource file:

<resources>
  <style name="CarAppTheme">
    <item name="carPermissionActivityLayout">@layout/app_branded_background</item>
  </style>
</resources>

The default behavior is to have no background behind the permission request.

See also
`requestPermissions`	=

requestPermissions

Added in 1.1.0

fun requestPermissions(
    permissions: (Mutable)List<String!>,
    executor: Executor,
    listener: OnRequestPermissionsListener
): Unit

Requests the provided permissions from the user.

When the result is available, the listener provided will be called using the Executor provided.

This method should be called using a androidx.car.app.model.ParkedOnlyOnClickListener.

If this method is called while the host deems it is unsafe (for example, when the user is driving), the permission(s) will not be requested from the user.

If the Session is destroyed before the user accepts or rejects the permissions, the callback will not be executed.

Platform Considerations Using this method allows the app to work across all platforms supported by the library with the same API (e.g. Android Auto on mobile devices and Android Automotive OS on native car heads unit). On a mobile platform, this method will start an activity that will display the platform's permissions UI over it. You can choose to not use this method and instead implement your own activity and code to request the permissions in that platform. On Automotive OS however, distraction-optimized activities other than CarAppActivity are not allowed and may be rejected during app submission. See CarAppActivity for more details.

Parameters
`permissions: (Mutable)List<String!>`	the runtime permissions to request from the user
`executor: Executor`	the executor that will be used for calling the `callback` provided
`listener: OnRequestPermissionsListener`	listener that will be notified when the user takes action on the permission request

Throws
`java.lang.NullPointerException`	if any of `executor`, `permissions` or `callback` are `null`

setCarAppResult

Added in 1.1.0

@RequiresCarApi(value = 2)
fun setCarAppResult(resultCode: Int, data: Intent?): Unit

Sets the result of this car app.

In Android Automotive OS, this is equivalent to setResult. Call this to set the result that your CarAppActivity will return to its caller.

This method is not implemented in Android Auto.

Parameters
`resultCode: Int`	the result code to propagate back to the originating app, often `RESULT_CANCELED` or `RESULT_OK`
`data: Intent?`	the data to propagate back to the originating app

Throws
`java.lang.IllegalStateException`	if the method is not supported in the current platform.

startCarApp

Added in 1.0.0

fun startCarApp(intent: Intent): Unit

Starts a car app on the car screen.

The target application will get the Intent via onCreateScreen or onNewIntent.

Supported Intents:

An Intent to navigate.: The action must be ACTION_NAVIGATE.; The data URI scheme must be either a latitude,longitude pair, or a + separated string query as follows:; 1) "geo:12.345,14.8767" for a latitude, longitude pair.; 2) "geo:0,0?q=123+Main+St,+Seattle,+WA+98101" for an address.; 3) "geo:0,0?q=a+place+name" for a place to search for.
An Intent to make a phone call.: The Intent must be created as defined here.
An Intent to start this app in the car.: The component name of the intent must be the one for the CarAppService that contains this CarContext. If the component name is for a different component, the method will throw a SecurityException.

This method should not be called until the Lifecycle.State of the context's Session is at least CREATED.

Parameters
`intent: Intent`	the `Intent` to send to the target application

Throws
`java.lang.SecurityException`	if the app attempts to start a different app explicitly or does not have permissions for the requested action
`androidx.car.app.HostException`	if the remote call fails. For example, if the intent cannot be handled by the car host.
`java.lang.NullPointerException`	if `intent` is `null`

startCarApp

Added in 1.0.0

Deprecated in 1.1.0

java-static fun startCarApp(notificationIntent: Intent, appIntent: Intent): Unit

Starts the car app on the car screen.

Use this method if the app has received a broadcast due to a notification action.

Parameters
`notificationIntent: Intent`	the `Intent` that the app received via broadcast due to a user taking an action on a notification in the car
`appIntent: Intent`	the `Intent` to use for starting the car app. See `startCarApp` for the documentation on valid `Intent`s

Throws
`java.security.InvalidParameterException`	if `notificationIntent` is not an `Intent` received from a broadcast, due to an action taken by the user in the car
`java.lang.NullPointerException`	if either `notificationIntent` or `appIntent` are `null`