Home | History | Annotate | Download | only in hardware
      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 */
     36 typedef 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. */
     42 typedef 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. */
     53 typedef 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. */
     62 typedef 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. */
     77 typedef 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(). */
    111 typedef 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 */
    129 typedef uint16_t AGpsType;
    130 #define AGPS_TYPE_SUPL          1
    131 #define AGPS_TYPE_C2K           2
    132 
    133 typedef 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  */
    147 typedef 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  */
    155 typedef 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  */
    167 typedef 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  */
    175 typedef 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. */
    183 typedef 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. */
    240 typedef 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. */
    263 typedef struct {
    264     /** set to sizeof(GpsStatus) */
    265     size_t          size;
    266     GpsStatusValue status;
    267 } GpsStatus;
    268 
    269 /** Represents SV information. */
    270 typedef 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. */
    284 typedef 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 */
    313 typedef struct {
    314     uint16_t type;
    315     uint16_t mcc;
    316     uint16_t mnc;
    317     uint16_t lac;
    318     uint32_t cid;
    319 } AGpsRefLocationCellID;
    320 
    321 typedef struct {
    322     uint8_t mac[6];
    323 } AGpsRefLocationMac;
    324 
    325 /** Represents ref locations */
    326 typedef 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  */
    337 typedef 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  */
    342 typedef 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  */
    347 typedef 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  */
    352 typedef 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  */
    357 typedef 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  */
    362 typedef void (* gps_acquire_wakelock)();
    363 
    364 /** Callback utility for releasing the GPS wakelock. */
    365 typedef void (* gps_release_wakelock)();
    366 
    367 /** Callback for requesting NTP time */
    368 typedef 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  */
    373 typedef pthread_t (* gps_create_thread)(const char* name, void (*start)(void *), void* arg);
    374 
    375 /** GPS callback structure. */
    376 typedef 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. */
    392 typedef 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  */
    444 typedef void (* gps_xtra_download_request)();
    445 
    446 /** Callback structure for the XTRA interface. */
    447 typedef 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. */
    453 typedef 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. */
    466 typedef 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. */
    478 typedef 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  */
    490 typedef void (* agps_status_callback)(AGpsStatus* status);
    491 
    492 /** Callback structure for the AGPS interface. */
    493 typedef struct {
    494     agps_status_callback status_cb;
    495     gps_create_thread create_thread_cb;
    496 } AGpsCallbacks;
    497 
    498 
    499 /** Extended interface for AGPS support. */
    500 typedef 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 */
    530 typedef 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  */
    594 typedef void (*gps_ni_notify_callback)(GpsNiNotification *notification);
    595 
    596 /** GPS NI callback structure. */
    597 typedef 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  */
    609 typedef 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 
    621 struct 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 
    638 typedef void (*agps_ril_request_set_id)(uint32_t flags);
    639 typedef void (*agps_ril_request_ref_loc)(uint32_t flags);
    640 
    641 typedef 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. */
    648 typedef 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  */
    788 typedef 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  */
    801 typedef 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  */
    815 typedef 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  */
    826 typedef 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  */
    840 typedef 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  */
    851 typedef void (*gps_geofence_resume_callback) (int32_t geofence_id, int32_t status);
    852 
    853 typedef 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 */
    864 typedef 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