CarPropertyManager

ASYNC_GET_DEFAULT_TIMEOUT_MS

public static final long ASYNC_GET_DEFAULT_TIMEOUT_MS

The default timeout in MS for CarPropertyManager#getPropertiesAsync.

Constant Value: 10000 (0x0000000000002710)

CAR_SET_PROPERTY_ERROR_CODE_ACCESS_DENIED

public static final int CAR_SET_PROPERTY_ERROR_CODE_ACCESS_DENIED

Status to indicate that set operation failed because car denied access to the property.

Constant Value: 4 (0x00000004)

CAR_SET_PROPERTY_ERROR_CODE_INVALID_ARG

public static final int CAR_SET_PROPERTY_ERROR_CODE_INVALID_ARG

Status to indicate that set operation failed because of an invalid argument.

Constant Value: 2 (0x00000002)

CAR_SET_PROPERTY_ERROR_CODE_PROPERTY_NOT_AVAILABLE

public static final int CAR_SET_PROPERTY_ERROR_CODE_PROPERTY_NOT_AVAILABLE

Status to indicate that set operation failed because the property is not available.

Constant Value: 3 (0x00000003)

CAR_SET_PROPERTY_ERROR_CODE_TRY_AGAIN

public static final int CAR_SET_PROPERTY_ERROR_CODE_TRY_AGAIN

Status to indicate that set operation failed. Try it again.

Constant Value: 1 (0x00000001)

CAR_SET_PROPERTY_ERROR_CODE_UNKNOWN

public static final int CAR_SET_PROPERTY_ERROR_CODE_UNKNOWN

Status to indicate that set operation failed because of a general error in cars.

Constant Value: 5 (0x00000005)

SENSOR_RATE_FAST

public static final float SENSOR_RATE_FAST

Read sensors at the rate of 10 hertz

Constant Value: 10.0

SENSOR_RATE_FASTEST

public static final float SENSOR_RATE_FASTEST

Read sensors at the rate of 100 hertz

Constant Value: 100.0

SENSOR_RATE_NORMAL

public static final float SENSOR_RATE_NORMAL

Read sensors at the rate of 1 hertz

Constant Value: 1.0

SENSOR_RATE_ONCHANGE

public static final float SENSOR_RATE_ONCHANGE

Read ONCHANGE sensors.

Constant Value: 0.0

SENSOR_RATE_UI

public static final float SENSOR_RATE_UI

Read sensors at the rate of 5 hertz

Constant Value: 5.0

STATUS_ERROR_INTERNAL_ERROR

public static final int STATUS_ERROR_INTERNAL_ERROR

Error indicating that there is an error detected in cars.

Constant Value: 1 (0x00000001)

STATUS_ERROR_NOT_AVAILABLE

public static final int STATUS_ERROR_NOT_AVAILABLE

Error indicating that the property is temporarily not available.

Constant Value: 2 (0x00000002)

STATUS_ERROR_TIMEOUT

public static final int STATUS_ERROR_TIMEOUT

Error indicating the operation has timed-out.

Constant Value: 3 (0x00000003)

generateGetPropertyRequest

public CarPropertyManager.GetPropertyRequest generateGetPropertyRequest (int propertyId, 
                int areaId)

Generate unique get request ID and return to the client.

generateSetPropertyRequest

public SetPropertyRequest<T> generateSetPropertyRequest (int propertyId, 
                int areaId, 
                T value)

Generate unique set request ID and return to the client.

getAreaId

public int getAreaId (int propertyId, 
                int area)

Returns areaId contains the selected area for the property.

getBooleanProperty

public boolean getBooleanProperty (int propertyId, 
                int areaId)

Returns value of a bool property

This method may take couple seconds to complete, so it needs to be called from a non-main thread.

Note: Client MUST NOT use one of the following as propertyId, otherwise the behavior is undefined:

• INITIAL_USER_INFO
• SWITCH_USER
• CREATE_USER
• REMOVE_USER
• USER_IDENTIFICATION_ASSOCIATION

Clients that declare a ApplicationInfo.targetSdkVersion equal or later than Build.VERSION_CODES#UPSIDE_DOWN_CAKE will receive the following exceptions when request failed.

• CarInternalErrorException when there is an unexpected error detected in cars
• PropertyAccessDeniedSecurityException when cars denied the access of the property
• PropertyNotAvailableAndRetryException when the property is temporarily not available and likely that retrying will be successful
• PropertyNotAvailableException when the property is not available and might be unavailable for a while.
• IllegalArgumentException when the [propertyId, areaId] is not supported or when the property is of wrong type.

Clients that declare a ApplicationInfo.targetSdkVersion equal or later than Build.VERSION_CODES#R, before Build.VERSION_CODES#UPSIDE_DOWN_CAKE will receive the following exceptions or false when request failed.

• CarInternalErrorException when there is an unexpected error detected in cars
• PropertyAccessDeniedSecurityException when cars denied the access of the property
• PropertyNotAvailableAndRetryException when the property is temporarily not available and likely that retrying will be successful
• PropertyNotAvailableException when the property is not available and might be unavailable for a while.
• IllegalArgumentException when the property is of wrong type.
• false when the [propertyId, areaId] is not supported

Clients that declare a ApplicationInfo.targetSdkVersion earlier than Build.VERSION_CODES#R will receive the following exceptions or false when request failed.

• IllegalStateException when there is an error detected in cars, or when cars denied the access of the property, or when the property is not available and might be unavailable for a while, or when unexpected error happens.
• IllegalArgumentException when the property is of wrong type.
• false when the [propertyId, areaId] is not supported or when the property is temporarily not available.

For pre-R client, the returned value might be false if the property is temporarily not available. The client should try again in this case.

For pre-U client, when the [propertyId, areaId] is not supported, this will return false.

For U and later client, when the [propertyId, areaId] is not supported, this is guaranteed to throw IllegalArgumentException.

getCarPropertyConfig

public CarPropertyConfig<?> getCarPropertyConfig (int propertyId)

Get CarPropertyConfig by property ID.

getFloatProperty

public float getFloatProperty (int propertyId, 
                int areaId)

Returns value of a float property

This method may take couple seconds to complete, so it needs to be called from a non-main thread.

This method has the same exception behavior as getBooleanProperty(int, int).

getIntArrayProperty

public int[] getIntArrayProperty (int propertyId, 
                int areaId)

Returns value of an integer array property

This method may take couple seconds to complete, so it needs to be called from a non-main thread.

This method has the same exception behavior as getBooleanProperty(int, int).

getIntProperty

public int getIntProperty (int propertyId, 
                int areaId)

Returns value of an integer property

This method may take couple seconds to complete, so it needs to be called form a non-main thread.

This method has the same exception behavior as getBooleanProperty(int, int).

getPropertiesAsync

public void getPropertiesAsync (List<CarPropertyManager.GetPropertyRequest> getPropertyRequests, 
                CancellationSignal cancellationSignal, 
                Executor callbackExecutor, 
                CarPropertyManager.GetPropertyCallback getPropertyCallback)

Query a list of CarPropertyValue with property Id and area Id asynchronously. Same as CarPropertyManager#getPropertiesAsync(List, long, CancellationSignal, Executor, GetPropertyCallback) with default timeout 10s.

getPropertiesAsync

public void getPropertiesAsync (List<CarPropertyManager.GetPropertyRequest> getPropertyRequests, 
                long timeoutInMs, 
                CancellationSignal cancellationSignal, 
                Executor callbackExecutor, 
                CarPropertyManager.GetPropertyCallback getPropertyCallback)

Query a list of CarPropertyValue with property ID and area ID asynchronously.

This function would return immediately before the results are ready. For each request, the corresponding result would either be delivered through one resultCallback.onSuccess call if the request succeeded or through one errorCallback.onFailure call if failed. It is guaranteed that the total times the callback functions are called is equal to the number of requests if this function does not throw an exception. It is guaranteed that none of the callback functions are called if an exception is thrown. If the callbackExecutor is null, the callback will be executed on the default event handler thread. If the callback is doing heavy work, it is recommended that the callbackExecutor is provided.

If the operation is cancelled, it is guaranteed that no more callbacks will be called.

For one request, if the property's status is not available, errorCallback.onFailure will be called once with STATUS_ERROR_NOT_AVAILABLE.

For one request, if the property's status is error, errorCallback.onFailure will be called once with STATUS_ERROR_INTERNAL_ERROR.

getProperty

public CarPropertyValue<E> getProperty (Class<E> clazz, 
                int propertyId, 
                int areaId)

Return CarPropertyValue

This method may take couple seconds to complete, so it needs to be called from a non-main thread.

Note: Client MUST NOT use one of the following as propertyId, otherwise the behavior is undefined (might throw exception or might return null):

• INITIAL_USER_INFO
• SWITCH_USER
• CREATE_USER
• REMOVE_USER
• USER_IDENTIFICATION_ASSOCIATION

Clients that declare a ApplicationInfo.targetSdkVersion equal or later than Build.VERSION_CODES#UPSIDE_DOWN_CAKE will receive the following exceptions when request failed.

• CarInternalErrorException when there is an unexpected error detected in cars
• PropertyAccessDeniedSecurityException when cars denied the access of the property
• PropertyNotAvailableAndRetryException when the property is temporarily not available and likely that retrying will be successful
• PropertyNotAvailableException when the property is not available and might be unavailable for a while.
• IllegalArgumentException when the [propertyId, areaId] is not supported or when the specified class does not match the property type.

Clients that declare a ApplicationInfo.targetSdkVersion equal or later than Build.VERSION_CODES#R, before Build.VERSION_CODES#UPSIDE_DOWN_CAKE will receive the following exceptions or null when request failed.

• CarInternalErrorException when there is an unexpected error detected in cars
• PropertyAccessDeniedSecurityException when cars denied the access of the property
• PropertyNotAvailableAndRetryException when the property is temporarily not available and likely that retrying will be successful
• PropertyNotAvailableException when the property is not available and might be unavailable for a while.
• IllegalArgumentException when the specified class does not match the property type.
• null when the [propertyId, areaId] is not supported

Clients that declare a ApplicationInfo.targetSdkVersion earlier than Build.VERSION_CODES#R will receive the following exceptions or null when request failed.

• IllegalStateException when there is an error detected in cars, or when cars denied the access of the property, or when the property is not available and might be unavailable for a while, or when unexpected error happens.
• IllegalArgumentException when the specified class does not match the property type.
• null when the [propertyId, areaId] is not supported or when the property is temporarily not available.

For pre-R client, the returned value might be null if the property is temporarily not available. The client should try again in this case.

For pre-U client, when the [propertyId, areaId] is not supported, this will return null.

For pre-U client, the returned CarPropertyValue might contain unavailable or error status. Client must use CarPropertyValue#getStatus to check. If the returned status is not ERROR(/CarPropertyValue.STATUS_AVAILABLE), then the value returned via CarPropertyValue#getValue is undefined.

For U and later client, when the [propertyId, areaId] is not supported, this is guaranteed to throw IllegalArgumentException. This method will never return null.

For U and later client, if the property's status is ERROR(/CarPropertyValue.STATUS_UNAVAILABLE), then PropertyNotAvailableException will be thrown. If the property's status is ERROR(/CarPropertyValue.STATUS_ERROR), then CarInternalErrorException will be thrown. If no exception is thrown, the returned CarPropertyValue#getStatus is guaranteed to be ERROR(/CarPropertyValue.STATUS_AVAILABLE) so client do not need to check.

getProperty

public CarPropertyValue<E> getProperty (int propertyId, 
                int areaId)

Query CarPropertyValue with property id and areaId.

This method may take couple seconds to complete, so it needs to be called from a non-main thread.

Note: Client MUST NOT use one of the following as propertyId, otherwise the behavior is undefined (might throw exception or might return null):

• INITIAL_USER_INFO
• SWITCH_USER
• CREATE_USER
• REMOVE_USER
• USER_IDENTIFICATION_ASSOCIATION

Clients that declare a ApplicationInfo.targetSdkVersion equal or later than Build.VERSION_CODES#UPSIDE_DOWN_CAKE will receive the following exceptions when request failed.

• CarInternalErrorException when there is an unexpected error detected in cars
• PropertyAccessDeniedSecurityException when cars denied the access of the property
• PropertyNotAvailableAndRetryException when the property is temporarily not available and likely that retrying will be successful
• PropertyNotAvailableException when the property is not available and might be unavailable for a while.
• IllegalArgumentException when the [propertyId, areaId] is not supported.

Clients that declare a ApplicationInfo.targetSdkVersion equal or later than Build.VERSION_CODES#R, before Build.VERSION_CODES#UPSIDE_DOWN_CAKE will receive the following exceptions or null when request failed.

• CarInternalErrorException when there is an unexpected error detected in cars
• PropertyAccessDeniedSecurityException when cars denied the access of the property
• PropertyNotAvailableAndRetryException when the property is temporarily not available and likely that retrying will be successful
• PropertyNotAvailableException when the property is not available and might be unavailable for a while.
• null when the [propertyId, areaId] is not supported

Clients that declare a ApplicationInfo.targetSdkVersion earlier than Build.VERSION_CODES#R will receive the following exceptions or null when request failed.

• IllegalStateException when there is an error detected in cars, or when cars denied the access of the property, or when the property is not available and might be unavailable for a while, or when unexpected error happens.
• null when the [propertyId, areaId] is not supported or when the property is temporarily not available.

For pre-R client, the returned value might be null if the property is temporarily not available. The client should try again in this case.

For pre-U client, when the [propertyId, areaId] is not supported, this will return null.

For pre-U client, the returned CarPropertyValue might contain unavailable or error status. Client must use CarPropertyValue#getStatus to check. If the returned status is not ERROR(/CarPropertyValue.STATUS_AVAILABLE), then the value returned via CarPropertyValue#getValue is undefined.

For U and later client, when the [propertyId, areaId] is not supported, this is guaranteed to throw IllegalArgumentException. This method will never return null.

For U and later client, if the property's status is ERROR(/CarPropertyValue.STATUS_UNAVAILABLE), then PropertyNotAvailableException will be thrown. If the property's status is ERROR(/CarPropertyValue.STATUS_ERROR), then CarInternalErrorException will be thrown. If no exception is thrown, the returned CarPropertyValue#getStatus is guaranteed to be ERROR(/CarPropertyValue.STATUS_AVAILABLE) so client do not need to check.

getPropertyList

public List<CarPropertyConfig<T>> getPropertyList (ArraySet<Integer> propertyIds)

Checks the given property IDs and returns a list of property configs supported by the car. If some of the properties in the given ID list are not supported, they will not be returned.

getPropertyList

public List<CarPropertyConfig<T>> getPropertyList ()

isPropertyAvailable

public boolean isPropertyAvailable (int propertyId, 
                int areaId)

Check whether a given property is available or disabled based on the car's current state.

registerCallback

public boolean registerCallback (CarPropertyManager.CarPropertyEventCallback carPropertyEventCallback, 
                int propertyId, 
                float updateRateHz)

Register CarPropertyEventCallback to get property updates. Multiple callbacks can be registered for a single property or the same callback can be used for different properties. If the same callback is registered again for the same property, it will be updated to new updateRateHz.

Rate could be one of the following:

• CarPropertyManager#SENSOR_RATE_ONCHANGE
• CarPropertyManager#SENSOR_RATE_NORMAL
• CarPropertyManager#SENSOR_RATE_UI
• CarPropertyManager#SENSOR_RATE_FAST
• CarPropertyManager#SENSOR_RATE_FASTEST

Note:Rate has no effect if the property has one of the following change modes:

• CarPropertyConfig#VEHICLE_PROPERTY_CHANGE_MODE_STATIC
• CarPropertyConfig#VEHICLE_PROPERTY_CHANGE_MODE_ONCHANGE

Note: If listener registers a callback for updates for a property for the first time, it will receive the property's current value via a change event upon registration if the property's value is currently available for reading. If the property is currently not available for reading or in error state, a property change event with a unavailable or error status will be generated.

For properties that might be unavailable for reading because their power state is off, property change events containing the property's initial value will be generated once their power state is on.

If updateRateHz is higher than CarPropertyConfig#getMaxSampleRate(), it will be registered with max sample updateRateHz.

If updateRateHz is lower than CarPropertyConfig#getMinSampleRate(), it will be registered with min sample updateRateHz.

Note:Caller must check the value of CarPropertyValue#getStatus() for property change events and only use CarPropertyValue#getValue() when CarPropertyValue#getStatus() is CarPropertyValue#STATUS_AVAILABLE. If not, the CarPropertyValue#getValue() is meaningless.

Note:A property change event may/may not happen when the property's status changes. Caller should not depend on the change event to check property's status. For properties that might be unavailable because they depend on certain power state, caller should subscribe to the power state property (e.g. VehiclePropertyIds#HVAC_POWER_ON for hvac power dependent properties) to decide this property's availability.

setBooleanProperty

public void setBooleanProperty (int propertyId, 
                int areaId, 
                boolean val)

Modifies a property. If the property modification doesn't occur, an error event shall be generated and propagated back to the application.

This method may take couple seconds to complete, so it needs to be called from a non-main thread.

setFloatProperty

public void setFloatProperty (int propertyId, 
                int areaId, 
                float val)

Set float value of property

This method may take couple seconds to complete, so it needs to be called from a non-main thread.

setIntProperty

public void setIntProperty (int propertyId, 
                int areaId, 
                int val)

Set int value of property

This method may take couple seconds to complete, so it needs to be called from a non-main thread.

setPropertiesAsync

public void setPropertiesAsync (List<SetPropertyRequest<?>> setPropertyRequests, 
                long timeoutInMs, 
                CancellationSignal cancellationSignal, 
                Executor callbackExecutor, 
                CarPropertyManager.SetPropertyCallback setPropertyCallback)

Sets a list of car property values asynchronously.

This function would return immediately before the results are ready. For each request, the corresponding result would either be delivered through one resultCallback.onSuccess call if the request succeeded or through one errorCallback.onFailure call if failed. It is guaranteed that the total times the callback functions are called is equal to the number of requests if this function does not throw an exception. It is guaranteed that none of the callback functions are called if an exception is thrown. If the callbackExecutor is null, the callback will be executed on the default event handler thread. If the callback is doing heavy work, it is recommended that the callbackExecutor is provided.

If the operation is cancelled, it is guaranteed that no more callbacks will be called.

If multiple clients set a property for the same area ID simultaneously, which one takes precedence is undefined. Typically, the last set operation (in the order that they are issued to the car's ECU) overrides the previous set operations.

When the success callback will be called depends on whether waitForPropertyUpdate for each request is set. If this is set to true (by default), the success callback will be called when the set operation is successfully delivered to vehicle bus AND either target value is the same as the current or when the property is updated to the target value.

When waitForPropertyUpdate is set to false, the success callback will be called as long as the set operation is successfully delivered to vehicle bus.

Under most cases, client should wait for the property update to verify that the set operation actually succeeded.

For cases when the property is write-only (no way to get property update event) or when the property represents some action, instead of an actual state, e.g. key stroke where the property's current value is not meaningful, caller must set waitForPropertyUpdate to false.

For HVAC_TEMPERATURE_VALUE_SUGGESTION, this must be set to false because the updated property value will not be the same as the value to be set.

setPropertiesAsync

public void setPropertiesAsync (List<SetPropertyRequest<?>> setPropertyRequests, 
                CancellationSignal cancellationSignal, 
                Executor callbackExecutor, 
                CarPropertyManager.SetPropertyCallback setPropertyCallback)

Sets a list of car property values asynchronously. Same as CarPropertyManager#setPropertiesAsync(List, long, CancellationSignal, Executor, SetPropertyCallback) with default timeout 10s.

setProperty

public void setProperty (Class<E> clazz, 
                int propertyId, 
                int areaId, 
                E val)

Set value of car property by areaId.

If multiple clients set a property for the same area ID simultaneously, which one takes precedence is undefined. Typically, the last set operation (in the order that they are issued to the car's ECU) overrides the previous set operations.

This method may take couple seconds to complete, so it needs to be called form a non-main thread.

Clients that declare a ApplicationInfo.targetSdkVersion equal or later than Build.VERSION_CODES#R will receive the following exceptions when request failed.

• CarInternalErrorException
• PropertyAccessDeniedSecurityException
• PropertyNotAvailableAndRetryException
• PropertyNotAvailableException
• IllegalArgumentException

Clients that declare a ApplicationInfo.targetSdkVersion earlier than Build.VERSION_CODES#R will receive the following exceptions when request failed.

• RuntimeException when the property is temporarily not available.
• IllegalStateException when there is an error detected in cars, or when cars denied the access of the property, or when the property is not available and might be unavailable for a while, or when unexpected error happens.
• IllegalArgumentException when the [propertyId, areaId] is not supported.

unregisterCallback

public void unregisterCallback (CarPropertyManager.CarPropertyEventCallback carPropertyEventCallback)

Stop getting property updates for the given CarPropertyEventCallback. If there are multiple registrations for this CarPropertyEventCallback, all listening will be stopped.

unregisterCallback

public void unregisterCallback (CarPropertyManager.CarPropertyEventCallback carPropertyEventCallback, 
                int propertyId)

Stop getting update for propertyId to the given CarPropertyEventCallback. If the same CarPropertyEventCallback is used for other properties, those subscriptions will not be affected.