CarAppService

public abstract class CarAppService extends 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

static final String
@ExperimentalCarApi
CATEGORY_CALLING_APP = "androidx.car.app.category.CALLING"

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

static final String
CATEGORY_CHARGING_APP = "androidx.car.app.category.CHARGING"

This field is deprecated.

use CATEGORY_POI_APP instead

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

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

static final String
@ExperimentalCarApi
CATEGORY_IOT_APP = "androidx.car.app.category.IOT"

Used in the app manifest.

static final String
@ExperimentalCarApi
CATEGORY_MESSAGING_APP = "androidx.car.app.category.MESSAGING"

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

static final String
CATEGORY_NAVIGATION_APP = "androidx.car.app.category.NAVIGATION"

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

static final String
CATEGORY_PARKING_APP = "androidx.car.app.category.PARKING"

This field is deprecated.

use CATEGORY_POI_APP instead

static final String
CATEGORY_POI_APP = "androidx.car.app.category.POI"

Used in the app manifest.

static final String
@ExperimentalCarApi
CATEGORY_SETTINGS_APP = "androidx.car.app.category.SETTINGS"

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

static final String
@ExperimentalCarApi
CATEGORY_WEATHER_APP = "androidx.car.app.category.WEATHER"

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

static final String
SERVICE_INTERFACE = "androidx.car.app.CarAppService"

The full qualified name of the CarAppService class.

Public constructors

Public methods

abstract @NonNull HostValidator

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

final void
@CallSuper
dump(
    @NonNull FileDescriptor fd,
    @NonNull PrintWriter writer,
    @Nullable String[] args
)
final @Nullable Session

This method is deprecated.

use getSession

final @Nullable HostInfo

Returns information about the host attached to this service.

final @Nullable Session

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

final @NonNull IBinder

Handles the host binding to this car app.

@NonNull Session

Creates a new Session for the application.

@NonNull Session

Creates a new Session.

void
final boolean

Handles the host unbinding from this car app.

Inherited Constants

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

This field is deprecated.

static final int
static final int
static final int

This field is deprecated.

static final int

This field is deprecated.

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

This field is deprecated.

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

This field is deprecated.

static final int

Inherited methods

From android.content.Context
final int
getColor(int id)
final ColorStateList
final Drawable
getDrawable(int id)
final String
getString(int resId)
final T
<T> getSystemService(Class<T> serviceClass)
final CharSequence
getText(int resId)
final TypedArray
void
void
sendBroadcastWithMultiplePermissions(
    Intent intent,
    String[] receiverPermissions
)
From android.content.ContextWrapper
boolean
bindIsolatedService(
    Intent service,
    int flags,
    String instanceName,
    Executor executor,
    ServiceConnection conn
)
boolean
bindService(Intent service, ServiceConnection conn, int flags)
boolean
bindServiceAsUser(
    Intent service,
    ServiceConnection conn,
    int flags,
    UserHandle user
)
int
int
checkCallingOrSelfUriPermission(Uri uri, int modeFlags)
int[]
checkCallingOrSelfUriPermissions(List<Uri> uris, int modeFlags)
int
int
checkCallingUriPermission(Uri uri, int modeFlags)
int[]
checkCallingUriPermissions(List<Uri> uris, int modeFlags)
int
checkPermission(String permission, int pid, int uid)
int
int
checkUriPermission(Uri uri, int pid, int uid, int modeFlags)
int[]
checkUriPermissions(List<Uri> uris, int pid, int uid, int modeFlags)
void

This method is deprecated.

Context
Context
Context
Context
Context
createDeviceContext(int deviceId)
Context
Context
Context
createPackageContext(String packageName, int flags)
Context
createWindowContext(int type, Bundle options)
String[]
boolean
boolean
boolean
void
void
enforceCallingOrSelfUriPermission(
    Uri uri,
    int modeFlags,
    String message
)
void
enforceCallingPermission(String permission, String message)
void
enforceCallingUriPermission(Uri uri, int modeFlags, String message)
void
enforcePermission(String permission, int pid, int uid, String message)
void
enforceUriPermission(
    Uri uri,
    int pid,
    int uid,
    int modeFlags,
    String message
)
String[]
Context
ApplicationInfo
AssetManager
AttributionSource
String
Context
File
ClassLoader
File
ContentResolver
File
File
int
File
getDir(String name, int mode)
Display
File
File[]
File
File[]
File[]

This method is deprecated.

File
File
Executor
Looper
File
File
File[]
String
String
PackageManager
String
String
ContextParams
Resources
SharedPreferences
getSharedPreferences(String name, int mode)
Object
String
Resources.Theme
Drawable

This method is deprecated.

int

This method is deprecated.

int

This method is deprecated.

void
grantUriPermission(String toPackage, Uri uri, int modeFlags)
boolean
boolean
boolean
boolean
moveDatabaseFrom(Context sourceContext, String name)
boolean
moveSharedPreferencesFrom(Context sourceContext, String name)
FileInputStream
FileOutputStream
openFileOutput(String name, int mode)
SQLiteDatabase
openOrCreateDatabase(
    String name,
    int mode,
    SQLiteDatabase.CursorFactory factory
)
Drawable

This method is deprecated.

void
void
Intent
void

This method is deprecated.

void

This method is deprecated.

void
void
revokeUriPermission(Uri uri, int modeFlags)
void
void
void
sendOrderedBroadcast(Intent intent, String receiverPermission)
void
sendOrderedBroadcastAsUser(
    Intent intent,
    UserHandle user,
    String receiverPermission,
    BroadcastReceiver resultReceiver,
    Handler scheduler,
    int initialCode,
    String initialData,
    Bundle initialExtras
)
void

This method is deprecated.

void

This method is deprecated.

void
sendStickyOrderedBroadcast(
    Intent intent,
    BroadcastReceiver resultReceiver,
    Handler scheduler,
    int initialCode,
    String initialData,
    Bundle initialExtras
)

This method is deprecated.

void
sendStickyOrderedBroadcastAsUser(
    Intent intent,
    UserHandle user,
    BroadcastReceiver resultReceiver,
    Handler scheduler,
    int initialCode,
    String initialData,
    Bundle initialExtras
)

This method is deprecated.

void
setTheme(int resid)
void

This method is deprecated.

void
startActivities(Intent[] intents)
void
ComponentName
boolean
startInstrumentation(
    ComponentName className,
    String profileFile,
    Bundle arguments
)
void
startIntentSender(
    IntentSender intent,
    Intent fillInIntent,
    int flagsMask,
    int flagsValues,
    int extraFlags
)
ComponentName
boolean
void
void
void
void
void
updateServiceGroup(ServiceConnection conn, int group, int importance)
From android.app.Service
void
final Application
final int
void
void
void
void
onRebind(Intent intent)
void
onStart(Intent intent, int startId)

This method is deprecated.

int
onStartCommand(Intent intent, int flags, int startId)
void
onTaskRemoved(Intent rootIntent)
void
onTimeout(int startId)
void
onTrimMemory(int level)
final void
startForeground(int id, Notification notification)
final void
stopForeground(boolean removeNotification)

This method is deprecated.

final void
final boolean
stopSelfResult(int startId)

Constants

CATEGORY_CALLING_APP

Added in 1.4.0-rc02
@ExperimentalCarApi
public static final String CATEGORY_CALLING_APP = "androidx.car.app.category.CALLING"

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
public static final String CATEGORY_CHARGING_APP = "androidx.car.app.category.CHARGING"

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

CATEGORY_FEATURE_CLUSTER

Added in 1.3.0
@RequiresCarApi(value = 6)
public static final String CATEGORY_FEATURE_CLUSTER = "androidx.car.app.category.FEATURE_CLUSTER"

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

CATEGORY_IOT_APP

Added in 1.3.0
@ExperimentalCarApi
public static final String CATEGORY_IOT_APP = "androidx.car.app.category.IOT"

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
public static final String CATEGORY_MESSAGING_APP = "androidx.car.app.category.MESSAGING"

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
public static final String CATEGORY_NAVIGATION_APP = "androidx.car.app.category.NAVIGATION"

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
public static final String CATEGORY_PARKING_APP = "androidx.car.app.category.PARKING"

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

CATEGORY_POI_APP

Added in 1.3.0
public static final String CATEGORY_POI_APP = "androidx.car.app.category.POI"

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

CATEGORY_SETTINGS_APP

Added in 1.2.0
@ExperimentalCarApi
public static final String CATEGORY_SETTINGS_APP = "androidx.car.app.category.SETTINGS"

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-rc02
@ExperimentalCarApi
public static final String CATEGORY_WEATHER_APP = "androidx.car.app.category.WEATHER"

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

SERVICE_INTERFACE

Added in 1.0.0
public static final String SERVICE_INTERFACE = "androidx.car.app.CarAppService"

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
public CarAppService()

Public methods

createHostValidator

Added in 1.0.0
public abstract @NonNull HostValidator createHostValidator()

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
public final void dump(
    @NonNull FileDescriptor fd,
    @NonNull PrintWriter writer,
    @Nullable String[] args
)

getCurrentSession

Added in 1.0.0
Deprecated in 1.3.0
public final @Nullable Session getCurrentSession()

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

getHostInfo

Added in 1.0.0
public final @Nullable HostInfo getHostInfo()

Returns information about the host attached to this service.

See also
HostInfo

getSession

Added in 1.3.0
public final @Nullable Session getSession(@NonNull SessionInfo sessionInfo)

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

onBind

Added in 1.0.0
@CallSuper
public final @NonNull IBinder onBind(@NonNull Intent intent)

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
public @NonNull Session onCreateSession()

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)
public @NonNull Session onCreateSession(@NonNull SessionInfo sessionInfo)

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

Added in 1.4.0-rc02
@CallSuper
public void onDestroy()

onUnbind

Added in 1.0.0
public final boolean onUnbind(@NonNull Intent intent)

Handles the host unbinding from this car app.

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