Clarify when IGnss.hal cleanup() and setCallback() methods are called
Update IGnss.hal cleanup() and setCallback() method documentation to
clarify when the framework calls these methods so that the GNSS engine
knows when to shut down for power savings.
This CL updates @1.1::IGnss.hal and @1.0::IGnss.hal interfaces only.
@2.0::IGnss.hal is updated in another CL.
Bug: 124104175
Test: Existing tests pass
Change-Id: I8181251677dab78ce0619fa1e2a667b36e115f25
diff --git a/gnss/1.0/IGnss.hal b/gnss/1.0/IGnss.hal
index 602c615..d32bc63 100644
--- a/gnss/1.0/IGnss.hal
+++ b/gnss/1.0/IGnss.hal
@@ -75,8 +75,13 @@
};
/**
- * Opens the interface and provides the callback routines
- * to the implementation of this interface.
+ * Opens the interface and provides the callback routines to the implementation of this
+ * interface.
+ *
+ * The framework calls this method to instruct the GPS engine to prepare for serving requests
+ * from the framework. The GNSS HAL implementation must respond to all GNSS requests from the
+ * framework upon successful return from this method until cleanup() method is called to
+ * close this interface.
*
* @param callback Callback interface for IGnss.
*
@@ -105,6 +110,18 @@
/**
* Closes the interface.
+ *
+ * The cleanup() method is called by the framework to tell the GNSS HAL implementation to
+ * not expect any GNSS requests in the immediate future - e.g. this may be called when
+ * location is disabled by a user setting or low battery conditions. The GNSS HAL
+ * implementation must immediately stop responding to any existing requests until the
+ * setCallback() method is called again and the requests are re-initiated by the framework.
+ *
+ * After this method is called, the GNSS HAL implementation may choose to modify GNSS hardware
+ * states to save power. It is expected that when setCallback() method is called again to
+ * reopen this interface, to serve requests, there may be some minor delays in GNSS response
+ * requests as hardware readiness states are restored, not to exceed those that occur on normal
+ * device boot up.
*/
cleanup();
@@ -153,7 +170,7 @@
* @param mode Parameter must be one of MS_BASED or STANDALONE.
* It is allowed by the platform (and it is recommended) to fallback to
* MS_BASED if MS_ASSISTED is passed in, and MS_BASED is supported.
- * @recurrence GNSS postion recurrence value, either periodic or single.
+ * @recurrence GNSS position recurrence value, either periodic or single.
* @param minIntervalMs Represents the time between fixes in milliseconds.
* @param preferredAccuracyMeters Represents the requested fix accuracy in meters.
* @param preferredTimeMs Represents the requested time to first fix in milliseconds.
diff --git a/gnss/1.1/IGnss.hal b/gnss/1.1/IGnss.hal
index 672f742..3400807 100644
--- a/gnss/1.1/IGnss.hal
+++ b/gnss/1.1/IGnss.hal
@@ -29,6 +29,11 @@
* Opens the interface and provides the callback routines to the implementation of this
* interface.
*
+ * The framework calls this method to instruct the GPS engine to prepare for serving requests
+ * from the framework. The GNSS HAL implementation must respond to all GNSS requests from the
+ * framework upon successful return from this method until cleanup() method is called to
+ * close this interface.
+ *
* @param callback Callback interface for IGnss.
*
* @return success Returns true on success.
@@ -42,7 +47,7 @@
* @param mode Parameter must be one of MS_BASED or STANDALONE. It is allowed by the platform
* (and it is recommended) to fallback to MS_BASED if MS_ASSISTED is passed in, and MS_BASED
* is supported.
- * @param recurrence GNSS postion recurrence value, either periodic or single.
+ * @param recurrence GNSS position recurrence value, either periodic or single.
* @param minIntervalMs Represents the time between fixes in milliseconds.
* @param preferredAccuracyMeters Represents the requested fix accuracy in meters.
* @param preferredTimeMs Represents the requested time to first fix in milliseconds.