| /* |
| * 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 transitions. 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 { |
| @export(name="", value_prefix="GPS_GEOFENCE_") |
| enum GeofenceTransition : int32_t { |
| ENTERED = (1 << 0L), |
| EXITED = (1 << 1L), |
| UNCERTAIN = (1 << 2L), |
| }; |
| |
| @export(name="", value_prefix="GPS_GEOFENCE_") |
| enum GeofenceAvailability : int32_t { |
| UNAVAILABLE = (1 << 0L), |
| AVAILABLE = (1 << 1L), |
| }; |
| |
| @export(name="", value_prefix="GPS_GEOFENCE_") |
| 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); |
| }; |