/*
* 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);
};