gnss/1.0/IGnssGeofencing.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;

import IGnssGeofenceCallback;

/** Extended interface for GNSS Geofencing support */
interface IGnssGeofencing {
    /**
     * Opens the geofence interface and provides the callback routines
     * to the HAL.
     *
     * @param callback Handle to the IGnssGeofenceCallback interface.
     */
    setCallback(IGnssGeofenceCallback callback);

    /**
     * Add a geofence area. This api currently supports circular geofences.
     *
     * @param geofenceId The id for the geofence. If a geofence with this id
     * already exists, an error value (ERROR_ID_EXISTS) must be returned.
     * @param latitudeDegrees The latitude(in degrees) for the geofence lastTransition.
     * @param longtitudeDegrees The longitude(in degrees) for the geofence lastTransition.
     * @param radiusMeters The radius(in meters) for the geofence lastTransition.
     * @param lastTransition The current state of the geofence. For example, if
     * the system already knows that the user is inside the geofence, this will
     * be set to ENTERED. In most cases, it will be UNCERTAIN.
     * @param monitorTransitions - Which transitions to monitor. Bitwise OR of
     * ENTERED, EXITED and UNCERTAIN.
     * @param notificationResponsivenessMs - Defines the best-effort description
     * of how soon must the callback be called when the transition associated
     * with the Geofence is triggered. For instance, if set to 1000 millseconds
     * with ENTERED, the callback must be called 1000 milliseconds within entering
     * the geofence. This parameter is defined in milliseconds.
     * NOTE: This is not to be confused with the rate that the GNSS is polled at.
     * It is acceptable to dynamically vary the rate of sampling the GNSS for
     * power-saving reasons; thus the rate of sampling may be faster or slower
     * than this.
     * @param unknownTimerMs - The time limit after which the UNCERTAIN transition
     * must be triggered. This parameter is defined in milliseconds.
     */
    addGeofence(int32_t geofenceId, double latitudeDegrees, double longitudeDegrees,
            double radiusMeters, GeofenceTransition lastTransition,
            bitfield<IGnssGeofenceCallback.GeofenceTransition> monitorTransitions,
            uint32_t notificationResponsivenessMs,
            uint32_t unknownTimerMs);

    /**
     * Pause monitoring a particular geofence.
     *
     * @param geofenceId The id for the geofence.
     */
    pauseGeofence(int32_t geofenceId);

    /**
     * Resume monitoring a particular geofence.
     *
     * @param geofenceId - The id for the geofence.
     * @param monitorTransitions Specifies which transitions to monitor.
     * It can be a bitwise OR of ENTERED, EXITED and
     * UNCERTAIN. This supersedes the value associated
     * provided in the addGeofenceArea call.
     */
    resumeGeofence(int32_t geofenceId,
            bitfield<IGnssGeofenceCallback.GeofenceTransition> monitorTransitions);

    /**
     * Remove a geofence area. After the function returns, no notifications
     * must be sent.
     *
     * @param geofenceId The id of the geofence.
     */
    removeGeofence(int32_t geofenceId);
};