CarAppService

public abstract class CarAppService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ androidx.car.app.CarAppService


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>
 

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. Also note that accessing location may become unreliable when the phone is in the battery saver mode.

Summary

Constants

String CATEGORY_CHARGING_APP

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

String CATEGORY_NAVIGATION_APP

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

String CATEGORY_PARKING_APP

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

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Inherited constants

Public constructors

CarAppService()

Public methods

abstract HostValidator createHostValidator()

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

final void dump(FileDescriptor fd, PrintWriter writer, String[] args)
final Session getCurrentSession()

Returns the current Session for this service.

final HostInfo getHostInfo()

Returns information about the host attached to this service.

final IBinder onBind(Intent intent)

Handles the host binding to this car app.

abstract Session onCreateSession()

Creates a new Session for the application.

final boolean onUnbind(Intent intent)

Handles the host unbinding from this car app.

Inherited methods

Constants

CATEGORY_CHARGING_APP

public static final String CATEGORY_CHARGING_APP

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

Constant Value: "androidx.car.app.category.CHARGING"

CATEGORY_NAVIGATION_APP

public static final String CATEGORY_NAVIGATION_APP

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

Constant Value: "androidx.car.app.category.NAVIGATION"

CATEGORY_PARKING_APP

public static final String CATEGORY_PARKING_APP

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

Constant Value: "androidx.car.app.category.PARKING"

SERVICE_INTERFACE

public static final String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Constant Value: "androidx.car.app.CarAppService"

Public constructors

CarAppService

public CarAppService ()

Public methods

createHostValidator

public abstract 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 HostValidator.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.

Please refer to 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()
             .addAllowedHosts(androidx.car.app.R.array.hosts_allowlist_sample)
             .build();
     }
 }
 

Returns
HostValidator

dump

public final void dump (FileDescriptor fd, 
                PrintWriter writer, 
                String[] args)

Parameters
fd FileDescriptor

writer PrintWriter

args String

getCurrentSession

public final Session getCurrentSession ()

Returns the current Session for this service.

Returns
Session

getHostInfo

public final HostInfo getHostInfo ()

Returns information about the host attached to this service.

Returns
HostInfo

See also:

onBind

public final IBinder onBind (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 Session.onNewIntent(Intent) instead to handle incoming Intents.

Parameters
intent Intent

Returns
IBinder

onCreateSession

public abstract 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, Session.onCreateScreen(Intent) will be called on the Session returned.

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

Returns
Session

onUnbind

public final boolean onUnbind (Intent intent)

Handles the host unbinding from this car app.

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

Parameters
intent Intent

Returns
boolean