1/*
2 * Copyright (C) 2010 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef ANDROID_INCLUDE_HARDWARE_GPS_H
18#define ANDROID_INCLUDE_HARDWARE_GPS_H
19
20#include <stdint.h>
21#include <sys/cdefs.h>
22#include <sys/types.h>
23#include <pthread.h>
24
25#include <hardware/hardware.h>
26
27__BEGIN_DECLS
28
29/**
30 * The id of this module
31 */
32#define GPS_HARDWARE_MODULE_ID "gps"
33
34
35/** Milliseconds since January 1, 1970 */
36typedef int64_t GpsUtcTime;
37
38/** Maximum number of SVs for gps_sv_status_callback(). */
39#define GPS_MAX_SVS 32
40
41/** Requested operational mode for GPS operation. */
42typedef uint32_t GpsPositionMode;
43// IMPORTANT: Note that the following values must match
44// constants in GpsLocationProvider.java.
45/** Mode for running GPS standalone (no assistance). */
46#define GPS_POSITION_MODE_STANDALONE    0
47/** AGPS MS-Based mode. */
48#define GPS_POSITION_MODE_MS_BASED      1
49/** AGPS MS-Assisted mode. */
50#define GPS_POSITION_MODE_MS_ASSISTED   2
51
52/** Requested recurrence mode for GPS operation. */
53typedef uint32_t GpsPositionRecurrence;
54// IMPORTANT: Note that the following values must match
55// constants in GpsLocationProvider.java.
56/** Receive GPS fixes on a recurring basis at a specified period. */
57#define GPS_POSITION_RECURRENCE_PERIODIC    0
58/** Request a single shot GPS fix. */
59#define GPS_POSITION_RECURRENCE_SINGLE      1
60
61/** GPS status event values. */
62typedef uint16_t GpsStatusValue;
63// IMPORTANT: Note that the following values must match
64// constants in GpsLocationProvider.java.
65/** GPS status unknown. */
66#define GPS_STATUS_NONE             0
67/** GPS has begun navigating. */
68#define GPS_STATUS_SESSION_BEGIN    1
69/** GPS has stopped navigating. */
70#define GPS_STATUS_SESSION_END      2
71/** GPS has powered on but is not navigating. */
72#define GPS_STATUS_ENGINE_ON        3
73/** GPS is powered off. */
74#define GPS_STATUS_ENGINE_OFF       4
75
76/** Flags to indicate which values are valid in a GpsLocation. */
77typedef uint16_t GpsLocationFlags;
78// IMPORTANT: Note that the following values must match
79// constants in GpsLocationProvider.java.
80/** GpsLocation has valid latitude and longitude. */
81#define GPS_LOCATION_HAS_LAT_LONG   0x0001
82/** GpsLocation has valid altitude. */
83#define GPS_LOCATION_HAS_ALTITUDE   0x0002
84/** GpsLocation has valid speed. */
85#define GPS_LOCATION_HAS_SPEED      0x0004
86/** GpsLocation has valid bearing. */
87#define GPS_LOCATION_HAS_BEARING    0x0008
88/** GpsLocation has valid accuracy. */
89#define GPS_LOCATION_HAS_ACCURACY   0x0010
90
91/** Flags for the gps_set_capabilities callback. */
92
93/** GPS HAL schedules fixes for GPS_POSITION_RECURRENCE_PERIODIC mode.
94    If this is not set, then the framework will use 1000ms for min_interval
95    and will start and call start() and stop() to schedule the GPS.
96 */
97#define GPS_CAPABILITY_SCHEDULING       0x0000001
98/** GPS supports MS-Based AGPS mode */
99#define GPS_CAPABILITY_MSB              0x0000002
100/** GPS supports MS-Assisted AGPS mode */
101#define GPS_CAPABILITY_MSA              0x0000004
102/** GPS supports single-shot fixes */
103#define GPS_CAPABILITY_SINGLE_SHOT      0x0000008
104/** GPS supports on demand time injection */
105#define GPS_CAPABILITY_ON_DEMAND_TIME   0x0000010
106/** GPS supports Geofencing  */
107#define GPS_CAPABILITY_GEOFENCING       0x0000020
108
109/** Flags used to specify which aiding data to delete
110    when calling delete_aiding_data(). */
111typedef uint16_t GpsAidingData;
112// IMPORTANT: Note that the following values must match
113// constants in GpsLocationProvider.java.
114#define GPS_DELETE_EPHEMERIS        0x0001
115#define GPS_DELETE_ALMANAC          0x0002
116#define GPS_DELETE_POSITION         0x0004
117#define GPS_DELETE_TIME             0x0008
118#define GPS_DELETE_IONO             0x0010
119#define GPS_DELETE_UTC              0x0020
120#define GPS_DELETE_HEALTH           0x0040
121#define GPS_DELETE_SVDIR            0x0080
122#define GPS_DELETE_SVSTEER          0x0100
123#define GPS_DELETE_SADATA           0x0200
124#define GPS_DELETE_RTI              0x0400
125#define GPS_DELETE_CELLDB_INFO      0x8000
126#define GPS_DELETE_ALL              0xFFFF
127
128/** AGPS type */
129typedef uint16_t AGpsType;
130#define AGPS_TYPE_SUPL          1
131#define AGPS_TYPE_C2K           2
132
133typedef uint16_t AGpsSetIDType;
134#define AGPS_SETID_TYPE_NONE    0
135#define AGPS_SETID_TYPE_IMSI    1
136#define AGPS_SETID_TYPE_MSISDN  2
137
138/**
139 * String length constants
140 */
141#define GPS_NI_SHORT_STRING_MAXLEN      256
142#define GPS_NI_LONG_STRING_MAXLEN       2048
143
144/**
145 * GpsNiType constants
146 */
147typedef uint32_t GpsNiType;
148#define GPS_NI_TYPE_VOICE              1
149#define GPS_NI_TYPE_UMTS_SUPL          2
150#define GPS_NI_TYPE_UMTS_CTRL_PLANE    3
151
152/**
153 * GpsNiNotifyFlags constants
154 */
155typedef uint32_t GpsNiNotifyFlags;
156/** NI requires notification */
157#define GPS_NI_NEED_NOTIFY          0x0001
158/** NI requires verification */
159#define GPS_NI_NEED_VERIFY          0x0002
160/** NI requires privacy override, no notification/minimal trace */
161#define GPS_NI_PRIVACY_OVERRIDE     0x0004
162
163/**
164 * GPS NI responses, used to define the response in
165 * NI structures
166 */
167typedef int GpsUserResponseType;
168#define GPS_NI_RESPONSE_ACCEPT         1
169#define GPS_NI_RESPONSE_DENY           2
170#define GPS_NI_RESPONSE_NORESP         3
171
172/**
173 * NI data encoding scheme
174 */
175typedef int GpsNiEncodingType;
176#define GPS_ENC_NONE                   0
177#define GPS_ENC_SUPL_GSM_DEFAULT       1
178#define GPS_ENC_SUPL_UTF8              2
179#define GPS_ENC_SUPL_UCS2              3
180#define GPS_ENC_UNKNOWN                -1
181
182/** AGPS status event values. */
183typedef uint16_t AGpsStatusValue;
184/** GPS requests data connection for AGPS. */
185#define GPS_REQUEST_AGPS_DATA_CONN  1
186/** GPS releases the AGPS data connection. */
187#define GPS_RELEASE_AGPS_DATA_CONN  2
188/** AGPS data connection initiated */
189#define GPS_AGPS_DATA_CONNECTED     3
190/** AGPS data connection completed */
191#define GPS_AGPS_DATA_CONN_DONE     4
192/** AGPS data connection failed */
193#define GPS_AGPS_DATA_CONN_FAILED   5
194
195#define AGPS_REF_LOCATION_TYPE_GSM_CELLID   1
196#define AGPS_REF_LOCATION_TYPE_UMTS_CELLID  2
197#define AGPS_REG_LOCATION_TYPE_MAC          3
198
199/** Network types for update_network_state "type" parameter */
200#define AGPS_RIL_NETWORK_TYPE_MOBILE        0
201#define AGPS_RIL_NETWORK_TYPE_WIFI          1
202#define AGPS_RIL_NETWORK_TYPE_MOBILE_MMS    2
203#define AGPS_RIL_NETWORK_TYPE_MOBILE_SUPL   3
204#define AGPS_RIL_NETWORK_TTYPE_MOBILE_DUN   4
205#define AGPS_RIL_NETWORK_TTYPE_MOBILE_HIPRI 5
206#define AGPS_RIL_NETWORK_TTYPE_WIMAX        6
207
208/**
209 * Name for the GPS XTRA interface.
210 */
211#define GPS_XTRA_INTERFACE      "gps-xtra"
212
213/**
214 * Name for the GPS DEBUG interface.
215 */
216#define GPS_DEBUG_INTERFACE      "gps-debug"
217
218/**
219 * Name for the AGPS interface.
220 */
221#define AGPS_INTERFACE      "agps"
222
223/**
224 * Name for NI interface
225 */
226#define GPS_NI_INTERFACE "gps-ni"
227
228/**
229 * Name for the AGPS-RIL interface.
230 */
231#define AGPS_RIL_INTERFACE      "agps_ril"
232
233/**
234 * Name for the GPS_Geofencing interface.
235 */
236#define GPS_GEOFENCING_INTERFACE   "gps_geofencing"
237
238
239/** Represents a location. */
240typedef struct {
241    /** set to sizeof(GpsLocation) */
242    size_t          size;
243    /** Contains GpsLocationFlags bits. */
244    uint16_t        flags;
245    /** Represents latitude in degrees. */
246    double          latitude;
247    /** Represents longitude in degrees. */
248    double          longitude;
249    /** Represents altitude in meters above the WGS 84 reference
250     * ellipsoid. */
251    double          altitude;
252    /** Represents speed in meters per second. */
253    float           speed;
254    /** Represents heading in degrees. */
255    float           bearing;
256    /** Represents expected accuracy in meters. */
257    float           accuracy;
258    /** Timestamp for the location fix. */
259    GpsUtcTime      timestamp;
260} GpsLocation;
261
262/** Represents the status. */
263typedef struct {
264    /** set to sizeof(GpsStatus) */
265    size_t          size;
266    GpsStatusValue status;
267} GpsStatus;
268
269/** Represents SV information. */
270typedef struct {
271    /** set to sizeof(GpsSvInfo) */
272    size_t          size;
273    /** Pseudo-random number for the SV. */
274    int     prn;
275    /** Signal to noise ratio. */
276    float   snr;
277    /** Elevation of SV in degrees. */
278    float   elevation;
279    /** Azimuth of SV in degrees. */
280    float   azimuth;
281} GpsSvInfo;
282
283/** Represents SV status. */
284typedef struct {
285    /** set to sizeof(GpsSvStatus) */
286    size_t          size;
287
288    /** Number of SVs currently visible. */
289    int         num_svs;
290
291    /** Contains an array of SV information. */
292    GpsSvInfo   sv_list[GPS_MAX_SVS];
293
294    /** Represents a bit mask indicating which SVs
295     * have ephemeris data.
296     */
297    uint32_t    ephemeris_mask;
298
299    /** Represents a bit mask indicating which SVs
300     * have almanac data.
301     */
302    uint32_t    almanac_mask;
303
304    /**
305     * Represents a bit mask indicating which SVs
306     * were used for computing the most recent position fix.
307     */
308    uint32_t    used_in_fix_mask;
309} GpsSvStatus;
310
311/* 2G and 3G */
312/* In 3G lac is discarded */
313typedef struct {
314    uint16_t type;
315    uint16_t mcc;
316    uint16_t mnc;
317    uint16_t lac;
318    uint32_t cid;
319} AGpsRefLocationCellID;
320
321typedef struct {
322    uint8_t mac[6];
323} AGpsRefLocationMac;
324
325/** Represents ref locations */
326typedef struct {
327    uint16_t type;
328    union {
329        AGpsRefLocationCellID   cellID;
330        AGpsRefLocationMac      mac;
331    } u;
332} AGpsRefLocation;
333
334/** Callback with location information.
335 *  Can only be called from a thread created by create_thread_cb.
336 */
337typedef void (* gps_location_callback)(GpsLocation* location);
338
339/** Callback with status information.
340 *  Can only be called from a thread created by create_thread_cb.
341 */
342typedef void (* gps_status_callback)(GpsStatus* status);
343
344/** Callback with SV status information.
345 *  Can only be called from a thread created by create_thread_cb.
346 */
347typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info);
348
349/** Callback for reporting NMEA sentences.
350 *  Can only be called from a thread created by create_thread_cb.
351 */
352typedef void (* gps_nmea_callback)(GpsUtcTime timestamp, const char* nmea, int length);
353
354/** Callback to inform framework of the GPS engine's capabilities.
355 *  Capability parameter is a bit field of GPS_CAPABILITY_* flags.
356 */
357typedef void (* gps_set_capabilities)(uint32_t capabilities);
358
359/** Callback utility for acquiring the GPS wakelock.
360 *  This can be used to prevent the CPU from suspending while handling GPS events.
361 */
362typedef void (* gps_acquire_wakelock)();
363
364/** Callback utility for releasing the GPS wakelock. */
365typedef void (* gps_release_wakelock)();
366
367/** Callback for requesting NTP time */
368typedef void (* gps_request_utc_time)();
369
370/** Callback for creating a thread that can call into the Java framework code.
371 *  This must be used to create any threads that report events up to the framework.
372 */
373typedef pthread_t (* gps_create_thread)(const char* name, void (*start)(void *), void* arg);
374
375/** GPS callback structure. */
376typedef struct {
377    /** set to sizeof(GpsCallbacks) */
378    size_t      size;
379    gps_location_callback location_cb;
380    gps_status_callback status_cb;
381    gps_sv_status_callback sv_status_cb;
382    gps_nmea_callback nmea_cb;
383    gps_set_capabilities set_capabilities_cb;
384    gps_acquire_wakelock acquire_wakelock_cb;
385    gps_release_wakelock release_wakelock_cb;
386    gps_create_thread create_thread_cb;
387    gps_request_utc_time request_utc_time_cb;
388} GpsCallbacks;
389
390
391/** Represents the standard GPS interface. */
392typedef struct {
393    /** set to sizeof(GpsInterface) */
394    size_t          size;
395    /**
396     * Opens the interface and provides the callback routines
397     * to the implemenation of this interface.
398     */
399    int   (*init)( GpsCallbacks* callbacks );
400
401    /** Starts navigating. */
402    int   (*start)( void );
403
404    /** Stops navigating. */
405    int   (*stop)( void );
406
407    /** Closes the interface. */
408    void  (*cleanup)( void );
409
410    /** Injects the current time. */
411    int   (*inject_time)(GpsUtcTime time, int64_t timeReference,
412                         int uncertainty);
413
414    /** Injects current location from another location provider
415     *  (typically cell ID).
416     *  latitude and longitude are measured in degrees
417     *  expected accuracy is measured in meters
418     */
419    int  (*inject_location)(double latitude, double longitude, float accuracy);
420
421    /**
422     * Specifies that the next call to start will not use the
423     * information defined in the flags. GPS_DELETE_ALL is passed for
424     * a cold start.
425     */
426    void  (*delete_aiding_data)(GpsAidingData flags);
427
428    /**
429     * min_interval represents the time between fixes in milliseconds.
430     * preferred_accuracy represents the requested fix accuracy in meters.
431     * preferred_time represents the requested time to first fix in milliseconds.
432     */
433    int   (*set_position_mode)(GpsPositionMode mode, GpsPositionRecurrence recurrence,
434            uint32_t min_interval, uint32_t preferred_accuracy, uint32_t preferred_time);
435
436    /** Get a pointer to extension information. */
437    const void* (*get_extension)(const char* name);
438} GpsInterface;
439
440/** Callback to request the client to download XTRA data.
441 *  The client should download XTRA data and inject it by calling inject_xtra_data().
442 *  Can only be called from a thread created by create_thread_cb.
443 */
444typedef void (* gps_xtra_download_request)();
445
446/** Callback structure for the XTRA interface. */
447typedef struct {
448    gps_xtra_download_request download_request_cb;
449    gps_create_thread create_thread_cb;
450} GpsXtraCallbacks;
451
452/** Extended interface for XTRA support. */
453typedef struct {
454    /** set to sizeof(GpsXtraInterface) */
455    size_t          size;
456    /**
457     * Opens the XTRA interface and provides the callback routines
458     * to the implemenation of this interface.
459     */
460    int  (*init)( GpsXtraCallbacks* callbacks );
461    /** Injects XTRA data into the GPS. */
462    int  (*inject_xtra_data)( char* data, int length );
463} GpsXtraInterface;
464
465/** Extended interface for DEBUG support. */
466typedef struct {
467    /** set to sizeof(GpsDebugInterface) */
468    size_t          size;
469
470    /**
471     * This function should return any information that the native
472     * implementation wishes to include in a bugreport.
473     */
474    size_t (*get_internal_state)(char* buffer, size_t bufferSize);
475} GpsDebugInterface;
476
477/** Represents the status of AGPS. */
478typedef struct {
479    /** set to sizeof(AGpsStatus) */
480    size_t          size;
481
482    AGpsType        type;
483    AGpsStatusValue status;
484    uint32_t        ipaddr;
485} AGpsStatus;
486
487/** Callback with AGPS status information.
488 *  Can only be called from a thread created by create_thread_cb.
489 */
490typedef void (* agps_status_callback)(AGpsStatus* status);
491
492/** Callback structure for the AGPS interface. */
493typedef struct {
494    agps_status_callback status_cb;
495    gps_create_thread create_thread_cb;
496} AGpsCallbacks;
497
498
499/** Extended interface for AGPS support. */
500typedef struct {
501    /** set to sizeof(AGpsInterface) */
502    size_t          size;
503
504    /**
505     * Opens the AGPS interface and provides the callback routines
506     * to the implemenation of this interface.
507     */
508    void  (*init)( AGpsCallbacks* callbacks );
509    /**
510     * Notifies that a data connection is available and sets
511     * the name of the APN to be used for SUPL.
512     */
513    int  (*data_conn_open)( const char* apn );
514    /**
515     * Notifies that the AGPS data connection has been closed.
516     */
517    int  (*data_conn_closed)();
518    /**
519     * Notifies that a data connection is not available for AGPS.
520     */
521    int  (*data_conn_failed)();
522    /**
523     * Sets the hostname and port for the AGPS server.
524     */
525    int  (*set_server)( AGpsType type, const char* hostname, int port );
526} AGpsInterface;
527
528
529/** Represents an NI request */
530typedef struct {
531    /** set to sizeof(GpsNiNotification) */
532    size_t          size;
533
534    /**
535     * An ID generated by HAL to associate NI notifications and UI
536     * responses
537     */
538    int             notification_id;
539
540    /**
541     * An NI type used to distinguish different categories of NI
542     * events, such as GPS_NI_TYPE_VOICE, GPS_NI_TYPE_UMTS_SUPL, ...
543     */
544    GpsNiType       ni_type;
545
546    /**
547     * Notification/verification options, combinations of GpsNiNotifyFlags constants
548     */
549    GpsNiNotifyFlags notify_flags;
550
551    /**
552     * Timeout period to wait for user response.
553     * Set to 0 for no time out limit.
554     */
555    int             timeout;
556
557    /**
558     * Default response when time out.
559     */
560    GpsUserResponseType default_response;
561
562    /**
563     * Requestor ID
564     */
565    char            requestor_id[GPS_NI_SHORT_STRING_MAXLEN];
566
567    /**
568     * Notification message. It can also be used to store client_id in some cases
569     */
570    char            text[GPS_NI_LONG_STRING_MAXLEN];
571
572    /**
573     * Client name decoding scheme
574     */
575    GpsNiEncodingType requestor_id_encoding;
576
577    /**
578     * Client name decoding scheme
579     */
580    GpsNiEncodingType text_encoding;
581
582    /**
583     * A pointer to extra data. Format:
584     * key_1 = value_1
585     * key_2 = value_2
586     */
587    char           extras[GPS_NI_LONG_STRING_MAXLEN];
588
589} GpsNiNotification;
590
591/** Callback with NI notification.
592 *  Can only be called from a thread created by create_thread_cb.
593 */
594typedef void (*gps_ni_notify_callback)(GpsNiNotification *notification);
595
596/** GPS NI callback structure. */
597typedef struct
598{
599    /**
600     * Sends the notification request from HAL to GPSLocationProvider.
601     */
602    gps_ni_notify_callback notify_cb;
603    gps_create_thread create_thread_cb;
604} GpsNiCallbacks;
605
606/**
607 * Extended interface for Network-initiated (NI) support.
608 */
609typedef struct
610{
611    /** set to sizeof(GpsNiInterface) */
612    size_t          size;
613
614   /** Registers the callbacks for HAL to use. */
615   void (*init) (GpsNiCallbacks *callbacks);
616
617   /** Sends a response to HAL. */
618   void (*respond) (int notif_id, GpsUserResponseType user_response);
619} GpsNiInterface;
620
621struct gps_device_t {
622    struct hw_device_t common;
623
624    /**
625     * Set the provided lights to the provided values.
626     *
627     * Returns: 0 on succes, error code on failure.
628     */
629    const GpsInterface* (*get_gps_interface)(struct gps_device_t* dev);
630};
631
632#define AGPS_RIL_REQUEST_SETID_IMSI     (1<<0L)
633#define AGPS_RIL_REQUEST_SETID_MSISDN   (1<<1L)
634
635#define AGPS_RIL_REQUEST_REFLOC_CELLID  (1<<0L)
636#define AGPS_RIL_REQUEST_REFLOC_MAC     (1<<1L)
637
638typedef void (*agps_ril_request_set_id)(uint32_t flags);
639typedef void (*agps_ril_request_ref_loc)(uint32_t flags);
640
641typedef struct {
642    agps_ril_request_set_id request_setid;
643    agps_ril_request_ref_loc request_refloc;
644    gps_create_thread create_thread_cb;
645} AGpsRilCallbacks;
646
647/** Extended interface for AGPS_RIL support. */
648typedef struct {
649    /** set to sizeof(AGpsRilInterface) */
650    size_t          size;
651    /**
652     * Opens the AGPS interface and provides the callback routines
653     * to the implemenation of this interface.
654     */
655    void  (*init)( AGpsRilCallbacks* callbacks );
656
657    /**
658     * Sets the reference location.
659     */
660    void (*set_ref_location) (const AGpsRefLocation *agps_reflocation, size_t sz_struct);
661    /**
662     * Sets the set ID.
663     */
664    void (*set_set_id) (AGpsSetIDType type, const char* setid);
665
666    /**
667     * Send network initiated message.
668     */
669    void (*ni_message) (uint8_t *msg, size_t len);
670
671    /**
672     * Notify GPS of network status changes.
673     * These parameters match values in the android.net.NetworkInfo class.
674     */
675    void (*update_network_state) (int connected, int type, int roaming, const char* extra_info);
676
677    /**
678     * Notify GPS of network status changes.
679     * These parameters match values in the android.net.NetworkInfo class.
680     */
681    void (*update_network_availability) (int avaiable, const char* apn);
682} AGpsRilInterface;
683
684/**
685 * GPS Geofence.
686 *      There are 3 states associated with a Geofence: Inside, Outside, Unknown.
687 * There are 3 transitions: ENTERED, EXITED, UNCERTAIN.
688 *
689 * An example state diagram with confidence level: 95% and Unknown time limit
690 * set as 30 secs is shown below. (confidence level and Unknown time limit are
691 * explained latter)
692 *                         ____________________________
693 *                        |       Unknown (30 secs)   |
694 *                         """"""""""""""""""""""""""""
695 *                            ^ |                  |  ^
696 *                   UNCERTAIN| |ENTERED     EXITED|  |UNCERTAIN
697 *                            | v                  v  |
698 *                        ________    EXITED     _________
699 *                       | Inside | -----------> | Outside |
700 *                       |        | <----------- |         |
701 *                        """"""""    ENTERED    """""""""
702 *
703 * Inside state: We are 95% confident that the user is inside the geofence.
704 * Outside state: We are 95% confident that the user is outside the geofence
705 * Unknown state: Rest of the time.
706 *
707 * The Unknown state is better explained with an example:
708 *
709 *                            __________
710 *                           |         c|
711 *                           |  ___     |    _______
712 *                           |  |a|     |   |   b   |
713 *                           |  """     |    """""""
714 *                           |          |
715 *                            """"""""""
716 * In the diagram above, "a" and "b" are 2 geofences and "c" is the accuracy
717 * circle reported by the GPS subsystem. Now with regard to "b", the system is
718 * confident that the user is outside. But with regard to "a" is not confident
719 * whether it is inside or outside the geofence. If the accuracy remains the
720 * same for a sufficient period of time, the UNCERTAIN transition would be
721 * triggered with the state set to Unknown. If the accuracy improves later, an
722 * appropriate transition should be triggered.  This "sufficient period of time"
723 * is defined by the parameter in the add_geofence_area API.
724 *     In other words, Unknown state can be interpreted as a state in which the
725 * GPS subsystem isn't confident enough that the user is either inside or
726 * outside the Geofence. It moves to Unknown state only after the expiry of the
727 * timeout.
728 *
729 * The geofence callback needs to be triggered for the ENTERED and EXITED
730 * transitions, when the GPS system is confident that the user has entered
731 * (Inside state) or exited (Outside state) the Geofence. An implementation
732 * which uses a value of 95% as the confidence is recommended. The callback
733 * should be triggered only for the transitions requested by the
734 * add_geofence_area call.
735 *
736 * Even though the diagram and explanation talks about states and transitions,
737 * the callee is only interested in the transistions. The states are mentioned
738 * here for illustrative purposes.
739 *
740 * Startup Scenario: When the device boots up, if an application adds geofences,
741 * and then we get an accurate GPS location fix, it needs to trigger the
742 * appropriate (ENTERED or EXITED) transition for every Geofence it knows about.
743 * By default, all the Geofences will be in the Unknown state.
744 *
745 * When the GPS system is unavailable, gps_geofence_status_callback should be
746 * called to inform the upper layers of the same. Similarly, when it becomes
747 * available the callback should be called. This is a global state while the
748 * UNKNOWN transition described above is per geofence.
749 *
750 * An important aspect to note is that users of this API (framework), will use
751 * other subsystems like wifi, sensors, cell to handle Unknown case and
752 * hopefully provide a definitive state transition to the third party
753 * application. GPS Geofence will just be a signal indicating what the GPS
754 * subsystem knows about the Geofence.
755 *
756 */
757#define GPS_GEOFENCE_ENTERED     (1<<0L)
758#define GPS_GEOFENCE_EXITED      (1<<1L)
759#define GPS_GEOFENCE_UNCERTAIN   (1<<2L)
760
761#define GPS_GEOFENCE_UNAVAILABLE (1<<0L)
762#define GPS_GEOFENCE_AVAILABLE   (1<<1L)
763
764#define GPS_GEOFENCE_OPERATION_SUCCESS           0
765#define GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES -100
766#define GPS_GEOFENCE_ERROR_ID_EXISTS          -101
767#define GPS_GEOFENCE_ERROR_ID_UNKNOWN         -102
768#define GPS_GEOFENCE_ERROR_INVALID_TRANSITION -103
769#define GPS_GEOFENCE_ERROR_GENERIC            -149
770
771/**
772 * The callback associated with the geofence.
773 * Parameters:
774 *      geofence_id - The id associated with the add_geofence_area.
775 *      location    - The current GPS location.
776 *      transition  - Can be one of GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED,
777 *                    GPS_GEOFENCE_UNCERTAIN.
778 *      timestamp   - Timestamp when the transition was detected.
779 *
780 * The callback should only be called when the caller is interested in that
781 * particular transition. For instance, if the caller is interested only in
782 * ENTERED transition, then the callback should NOT be called with the EXITED
783 * transition.
784 *
785 * IMPORTANT: If a transition is triggered resulting in this callback, the GPS
786 * subsystem will wake up the application processor, if its in suspend state.
787 */
788typedef void (*gps_geofence_transition_callback) (int32_t geofence_id,  GpsLocation* location,
789        int32_t transition, GpsUtcTime timestamp);
790
791/**
792 * The callback associated with the availablity of the GPS system for geofencing
793 * monitoring. If the GPS system determines that it cannot monitor geofences
794 * because of lack of reliability or unavailability of the GPS signals, it will
795 * call this callback with GPS_GEOFENCE_UNAVAILABLE parameter.
796 *
797 * Parameters:
798 *  status - GPS_GEOFENCE_UNAVAILABLE or GPS_GEOFENCE_AVAILABLE.
799 *  last_location - Last known location.
800 */
801typedef void (*gps_geofence_status_callback) (int32_t status, GpsLocation* last_location);
802
803/**
804 * The callback associated with the add_geofence call.
805 *
806 * Parameter:
807 * geofence_id - Id of the geofence.
808 * status - GPS_GEOFENCE_OPERATION_SUCCESS
809 *          GPS_GEOFENCE_ERROR_TOO_MANY_GEOFENCES  - geofence limit has been reached.
810 *          GPS_GEOFENCE_ERROR_ID_EXISTS  - geofence with id already exists
811 *          GPS_GEOFENCE_ERROR_INVALID_TRANSITION - the monitorTransition contains an
812 *              invalid transition
813 *          GPS_GEOFENCE_ERROR_GENERIC - for other errors.
814 */
815typedef void (*gps_geofence_add_callback) (int32_t geofence_id, int32_t status);
816
817/**
818 * The callback associated with the remove_geofence call.
819 *
820 * Parameter:
821 * geofence_id - Id of the geofence.
822 * status - GPS_GEOFENCE_OPERATION_SUCCESS
823 *          GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id
824 *          GPS_GEOFENCE_ERROR_GENERIC for others.
825 */
826typedef void (*gps_geofence_remove_callback) (int32_t geofence_id, int32_t status);
827
828
829/**
830 * The callback associated with the pause_geofence call.
831 *
832 * Parameter:
833 * geofence_id - Id of the geofence.
834 * status - GPS_GEOFENCE_OPERATION_SUCCESS
835 *          GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id
836 *          GPS_GEOFENCE_ERROR_INVALID_TRANSITION -
837 *                    when monitor_transitions is invalid
838 *          GPS_GEOFENCE_ERROR_GENERIC for others.
839 */
840typedef void (*gps_geofence_pause_callback) (int32_t geofence_id, int32_t status);
841
842/**
843 * The callback associated with the resume_geofence call.
844 *
845 * Parameter:
846 * geofence_id - Id of the geofence.
847 * status - GPS_GEOFENCE_OPERATION_SUCCESS
848 *          GPS_GEOFENCE_ERROR_ID_UNKNOWN - for invalid id
849 *          GPS_GEOFENCE_ERROR_GENERIC for others.
850 */
851typedef void (*gps_geofence_resume_callback) (int32_t geofence_id, int32_t status);
852
853typedef struct {
854    gps_geofence_transition_callback geofence_transition_callback;
855    gps_geofence_status_callback geofence_status_callback;
856    gps_geofence_add_callback geofence_add_callback;
857    gps_geofence_remove_callback geofence_remove_callback;
858    gps_geofence_pause_callback geofence_pause_callback;
859    gps_geofence_resume_callback geofence_resume_callback;
860    gps_create_thread create_thread_cb;
861} GpsGeofenceCallbacks;
862
863/** Extended interface for GPS_Geofencing support */
864typedef struct {
865   /** set to sizeof(GpsGeofencingInterface) */
866   size_t          size;
867
868   /**
869    * Opens the geofence interface and provides the callback routines
870    * to the implemenation of this interface.
871    */
872   void  (*init)( GpsGeofenceCallbacks* callbacks );
873
874   /**
875    * Add a geofence area. This api currently supports circular geofences.
876    * Parameters:
877    *    geofence_id - The id for the geofence. If a geofence with this id
878    *       already exists, an error value (GPS_GEOFENCE_ERROR_ID_EXISTS)
879    *       should be returned.
880    *    latitude, longtitude, radius_meters - The lat, long and radius
881    *       (in meters) for the geofence
882    *    last_transition - The current state of the geofence. For example, if
883    *       the system already knows that the user is inside the geofence,
884    *       this will be set to GPS_GEOFENCE_ENTERED. In most cases, it
885    *       will be GPS_GEOFENCE_UNCERTAIN.
886    *    monitor_transition - Which transitions to monitor. Bitwise OR of
887    *       GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and
888    *       GPS_GEOFENCE_UNCERTAIN.
889    *    notification_responsiveness_ms - Defines the best-effort description
890    *       of how soon should the callback be called when the transition
891    *       associated with the Geofence is triggered. For instance, if set
892    *       to 1000 millseconds with GPS_GEOFENCE_ENTERED, the callback
893    *       should be called 1000 milliseconds within entering the geofence.
894    *       This parameter is defined in milliseconds.
895    *       NOTE: This is not to be confused with the rate that the GPS is
896    *       polled at. It is acceptable to dynamically vary the rate of
897    *       sampling the GPS for power-saving reasons; thus the rate of
898    *       sampling may be faster or slower than this.
899    *    unknown_timer_ms - The time limit after which the UNCERTAIN transition
900    *       should be triggered. This paramter is defined in milliseconds.
901    *       See above for a detailed explanation.
902    */
903   void (*add_geofence_area) (int32_t geofence_id, double latitude,
904                                double longitude, double radius_meters,
905                                int last_transition, int monitor_transitions,
906                                int notification_responsiveness_ms,
907                                int unknown_timer_ms);
908
909   /**
910    * Pause monitoring a particular geofence.
911    * Parameters:
912    *   geofence_id - The id for the geofence.
913    */
914   void (*pause_geofence) (int32_t geofence_id);
915
916   /**
917    * Resume monitoring a particular geofence.
918    * Parameters:
919    *   geofence_id - The id for the geofence.
920    *   monitor_transitions - Which transitions to monitor. Bitwise OR of
921    *       GPS_GEOFENCE_ENTERED, GPS_GEOFENCE_EXITED and
922    *       GPS_GEOFENCE_UNCERTAIN.
923    *       This supersedes the value associated provided in the
924    *       add_geofence_area call.
925    */
926   void (*resume_geofence) (int32_t geofence_id, int monitor_transitions);
927
928   /**
929    * Remove a geofence area. After the function returns, no notifications
930    * should be sent.
931    * Parameter:
932    *   geofence_id - The id for the geofence.
933    */
934   void (*remove_geofence_area) (int32_t geofence_id);
935} GpsGeofencingInterface;
936__END_DECLS
937
938#endif /* ANDROID_INCLUDE_HARDWARE_GPS_H */
939
940