Update doc for subscribing unavailable props.
Test: None
Bug: 258513729
Change-Id: I31f0a9490d3462bcc1266d14b4b3b893ce1d03a0
diff --git a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/IVehicle.aidl b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/IVehicle.aidl
index 47fc54b..c896d14 100644
--- a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/IVehicle.aidl
+++ b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/IVehicle.aidl
@@ -190,6 +190,14 @@
* what the sampleRate specified in {@code options}, the timestamp for
* the timestamp is updated 10 times/s.
*
+ * If a property is unavailable for reading because it depends on some power
+ * state which is off, property change event may not be generated until the
+ * property becomes available. For ON_CHANGE property, if the property
+ * changes from NOT_AVAILABLE to OKAY for reading some or all area(s), for
+ * each area that becomes available for reading, one property change event
+ * must be generated. The event must contain the current value for the area
+ * and must have {@code AVAILABLE} status.
+ *
* @param callback The subscription callbacks.
* {@link IVehicleCallback#onPropertyEvent} would be called when a new
* property event arrives.
diff --git a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/StatusCode.aidl b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/StatusCode.aidl
index 23019ca..35080db 100644
--- a/automotive/vehicle/aidl/android/hardware/automotive/vehicle/StatusCode.aidl
+++ b/automotive/vehicle/aidl/android/hardware/automotive/vehicle/StatusCode.aidl
@@ -24,7 +24,11 @@
enum StatusCode {
OK = 0,
/**
- * Try again.
+ * Caller should try again.
+ *
+ * This code must be returned when an ephemeral error happens and a retry
+ * will likely succeed. E.g., when the device is currently booting up
+ * and the property is not ready yet.
*/
TRY_AGAIN = 1,
/**
@@ -32,9 +36,22 @@
*/
INVALID_ARG = 2,
/**
+ * The property is currently unavailable and will be unavailable unless
+ * some other state changes.
+ *
* This code must be returned when device that associated with the vehicle
* property is not available. For example, when client tries to set HVAC
* temperature when the whole HVAC unit is turned OFF.
+ *
+ * The difference between this and TRY_AGAIN is that if NOT_AVAILABLE is
+ * returned for a property, it will remain NOT_AVAILABLE unless some other
+ * state changes. This means a retry will likely still return NOT_AVAILABLE.
+ * However, for TRY_AGAIN error, a retry will likely return OK.
+ *
+ * When subscribing to a property that is currently unavailable for getting.
+ * VHAL must return OK even if getting/setting must return NOT_AVAILABLE.
+ * VHAL must not generate property change event when the property is not
+ * available for getting.
*/
NOT_AVAILABLE = 3,
/**