gnss/1.0/IGnssGeofenceCallback.hal

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