GPS HAL Binderization
A Debug interface as well as a configuration interface will be added in
another CL.
Bug: 31974439
Test: mma
Change-Id: I977d95fc815172bd2aae7c78f81e1fc7c9bce72a
diff --git a/gnss/1.0/IGnssGeofenceCallback.hal b/gnss/1.0/IGnssGeofenceCallback.hal
new file mode 100644
index 0000000..06eb62a
--- /dev/null
+++ b/gnss/1.0/IGnssGeofenceCallback.hal
@@ -0,0 +1,188 @@
+/*
+ * Copyright (C) 2016 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.gnss@1.0;
+
+/*
+ * GNSS Geofence.
+ * There are 3 states associated with a Geofence: Inside, Outside, Unknown.
+ * There are 3 transitions: ENTERED, EXITED, UNCERTAIN.
+ *
+ * An example state diagram with confidence level: 95% and Unknown time limit
+ * set as 30 secs is shown below. (confidence level and Unknown time limit are
+ * explained latter).
+ * ____________________________
+ * | Unknown (30 secs) |
+ * """"""""""""""""""""""""""""
+ * ^ | | ^
+ * UNCERTAIN| |ENTERED EXITED| |UNCERTAIN
+ * | v v |
+ * ________ EXITED _________
+ * | Inside | -----------> | Outside |
+ * | | <----------- | |
+ * """""""" ENTERED """""""""
+ *
+ * Inside state: We are 95% confident that the user is inside the geofence.
+ * Outside state: We are 95% confident that the user is outside the geofence
+ * Unknown state: Rest of the time.
+ *
+ * The Unknown state is better explained with an example:
+ *
+ * __________
+ * | c|
+ * | ___ | _______
+ * | |a| | | b |
+ * | """ | """""""
+ * | |
+ * """"""""""
+ * In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy
+ * circle reported by the GNSS subsystem. Now with regard to "b", the system is
+ * confident that the user is outside. But with regard to "a" is not confident
+ * whether it is inside or outside the geofence. If the accuracy remains the
+ * same for a sufficient period of time, the UNCERTAIN transition must be
+ * triggered with the state set to Unknown. If the accuracy improves later, an
+ * appropriate transition must be triggered. This "sufficient period of time"
+ * is defined by the parameter in the addGeofenceArea API.
+ * In other words, Unknown state can be interpreted as a state in which the
+ * GNSS subsystem isn't confident enough that the user is either inside or
+ * outside the Geofence. It moves to Unknown state only after the expiry of the
+ * timeout.
+ *
+ * The geofence callback needs to be triggered for the ENTERED and EXITED
+ * transitions, when the GNSS system is confident that the user has entered
+ * (Inside state) or exited (Outside state) the Geofence. An implementation
+ * which uses a value of 95% as the confidence is recommended. The callback
+ * must be triggered only for the transitions requested by the
+ * addGeofenceArea method.
+ *
+ * Even though the diagram and explanation talks about states and transitions,
+ * the callee is only interested in the transistions. The states are mentioned
+ * here for illustrative purposes.
+ *
+ * Startup Scenario: When the device boots up, if an application adds geofences,
+ * and then we get an accurate GNSS location fix, it needs to trigger the
+ * appropriate (ENTERED or EXITED) transition for every Geofence it knows about.
+ * By default, all the Geofences will be in the Unknown state.
+ *
+ * When the GNSS system is unavailable, gnssGeofenceStatusCb must be
+ * called to inform the upper layers of the same. Similarly, when it becomes
+ * available the callback must be called. This is a global state while the
+ * UNKNOWN transition described above is per geofence.
+ *
+ * An important aspect to note is that users of this API (framework), will use
+ * other subsystems like wifi, sensors, cell to handle Unknown case and
+ * hopefully provide a definitive state transition to the third party
+ * application. GNSS Geofence will just be a signal indicating what the GNSS
+ * subsystem knows about the Geofence.
+ *
+ */
+
+interface IGnssGeofenceCallback {
+ enum GeofenceTransition : int32_t {
+ ENTERED = (1 << 0L),
+ EXITED = (1 << 1L),
+ UNCERTAIN = (1 << 2L),
+ };
+
+ enum GeofenceAvailability : int32_t {
+ UNAVAILABLE = (1 << 0L),
+ AVAILABLE = (1 << 1L),
+ };
+
+ enum GeofenceStatus : int32_t {
+ OPERATION_SUCCESS = 0,
+ ERROR_TOO_MANY_GEOFENCES = -100,
+ ERROR_ID_EXISTS = -101,
+ ERROR_ID_UNKNOWN = -102,
+ ERROR_INVALID_TRANSITION = -103,
+ ERROR_GENERIC = -149
+ };
+
+ /*
+ * The callback associated with the geofence transition.
+ * The callback must only be called when the caller is interested in that
+ * particular transition. For instance, if the caller is interested only in
+ * ENTERED transition, then the callback must not be called with the EXITED
+ * transition.
+ *
+ * IMPORTANT: If a transition is triggered resulting in this callback, the
+ * GNSS subsystem will wake up the application processor, if its in suspend
+ * state.
+ *
+ * @param geofenceId The id associated with the addGeofenceArea.
+ * @param location The current GNSS location.
+ * @param transition Can be one of ENTERED, EXITED or UNCERTAIN.
+ * @param timestamp Timestamp when the transition was detected.
+ *
+ */
+ gnssGeofenceTransitionCb(int32_t geofenceId, GnssLocation location,
+ GeofenceTransition transition, GnssUtcTime timestamp);
+
+ /*
+ * The callback associated with the availability of the GNSS system for
+ * geofencing monitoring. If the GNSS system determines that it cannot monitor
+ * geofences because of lack of reliability or unavailability of the GNSS
+ * signals, it will call this callback with UNAVAILABLE parameter.
+ *
+ * @param status - UNAVAILABLE or AVAILABLE.
+ * @param lastLocation - Last known location.
+ */
+ gnssGeofenceStatusCb(GeofenceAvailability status, GnssLocation lastLocation);
+
+ /*
+ * The callback associated with the addGeofence call.
+ *
+ * @param geofenceId Id of the geofence.
+ * @param status Will be OPERATION_SUCCESS if the geofence
+ * add was successful. Will be ERROR_TOO_MANY_GEOFENCES if the
+ * geofence limit has been reached.
+ * Will be ERROR_ID_EXISTS if geofence with id already exists.
+ * Will be ERROR_INVALID_TRANSITION if the monitorTransition contains an
+ * invalid transition.
+ * Will be ERROR_GENERIC for other errors.
+ */
+ gnssGeofenceAddCb(int32_t geofenceId, GeofenceStatus status);
+
+ /*
+ * The callback associated with the removeGeofence call.
+ *
+ * @param geofenceId Id of the geofence.
+ * @param status Will return OPERATION_SUCCESS if successful.
+ * Will be ERROR_ID_UNKNOWN for invalid id and
+ * ERROR_GENERIC for others.
+ */
+ gnssGeofenceRemoveCb(int32_t geofenceId, GeofenceStatus status);
+
+ /*
+ * The callback associated with the pauseGeofence call.
+ *
+ * @param geofenceId Id of the geofence.
+ * @param status Will be OPERATION_SUCCESS if success.
+ * Will be ERROR_ID_UNKNOWN for invalid id. Will be
+ * ERROR_INVALID_TRANSITION when monitorTransitions is invalid.
+ * Will be ERROR_GENERIC for other err errors.
+ */
+ gnssGeofencePauseCb(int32_t geofenceId, GeofenceStatus status);
+
+ /*
+ * The callback associated with the resumeGeofence call.
+ *
+ * @param geofenceId - Id of the geofence.
+ * @param status Will be OPERATION_SUCCESS if successful.
+ * Will be ERROR_ID_UNKNOWN for invalid id and ERROR_GENERIC for others.
+ */
+ gnssGeofenceResumeCb(int32_t geofenceId, GeofenceStatus status);
+};