include/hardware_legacy/gps.h

   1 /*
   2  * Copyright (C) 2008 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 _HARDWARE_GPS_H
  18 #define _HARDWARE_GPS_H
  19
  20 #include <stdint.h>
  21
  22 #if __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /** Milliseconds since January 1, 1970 */
  27 typedef int64_t GpsUtcTime;
  28
  29 /** Maximum number of SVs for gps_sv_status_callback(). */
  30 #define GPS_MAX_SVS 32
  31
  32 /** Requested mode for GPS operation. */
  33 typedef uint16_t GpsPositionMode;
  34 // IMPORTANT: Note that the following values must match
  35 // constants in GpsLocationProvider.java.
  36 /** Mode for running GPS standalone (no assistance). */
  37 #define GPS_POSITION_MODE_STANDALONE    0
  38 /** AGPS MS-Based mode. */
  39 #define GPS_POSITION_MODE_MS_BASED      1
  40 /** AGPS MS-Assisted mode. */
  41 #define GPS_POSITION_MODE_MS_ASSISTED   2
  42
  43 /** GPS status event values. */
  44 typedef uint16_t GpsStatusValue;
  45 // IMPORTANT: Note that the following values must match
  46 // constants in GpsLocationProvider.java.
  47 /** GPS status unknown. */
  48 #define GPS_STATUS_NONE             0
  49 /** GPS has begun navigating. */
  50 #define GPS_STATUS_SESSION_BEGIN    1
  51 /** GPS has stopped navigating. */
  52 #define GPS_STATUS_SESSION_END      2
  53 /** GPS has powered on but is not navigating. */
  54 #define GPS_STATUS_ENGINE_ON        3
  55 /** GPS is powered off. */
  56 #define GPS_STATUS_ENGINE_OFF       4
  57
  58 /** Flags to indicate which values are valid in a GpsLocation. */
  59 typedef uint16_t GpsLocationFlags;
  60 // IMPORTANT: Note that the following values must match
  61 // constants in GpsLocationProvider.java.
  62 /** GpsLocation has valid latitude and longitude. */
  63 #define GPS_LOCATION_HAS_LAT_LONG   0x0001
  64 /** GpsLocation has valid altitude. */
  65 #define GPS_LOCATION_HAS_ALTITUDE   0x0002
  66 /** GpsLocation has valid speed. */
  67 #define GPS_LOCATION_HAS_SPEED      0x0004
  68 /** GpsLocation has valid bearing. */
  69 #define GPS_LOCATION_HAS_BEARING    0x0008
  70 /** GpsLocation has valid accuracy. */
  71 #define GPS_LOCATION_HAS_ACCURACY   0x0010
  72
  73 /** Flags used to specify which aiding data to delete
  74     when calling delete_aiding_data(). */
  75 typedef uint16_t GpsAidingData;
  76 // IMPORTANT: Note that the following values must match
  77 // constants in GpsLocationProvider.java.
  78 #define GPS_DELETE_EPHEMERIS        0x0001
  79 #define GPS_DELETE_ALMANAC          0x0002
  80 #define GPS_DELETE_POSITION         0x0004
  81 #define GPS_DELETE_TIME             0x0008
  82 #define GPS_DELETE_IONO             0x0010
  83 #define GPS_DELETE_UTC              0x0020
  84 #define GPS_DELETE_HEALTH           0x0040
  85 #define GPS_DELETE_SVDIR            0x0080
  86 #define GPS_DELETE_SVSTEER          0x0100
  87 #define GPS_DELETE_SADATA           0x0200
  88 #define GPS_DELETE_RTI              0x0400
  89 #define GPS_DELETE_CELLDB_INFO      0x8000
  90 #define GPS_DELETE_ALL              0xFFFF
  91
  92 /** AGPS type */
  93 typedef uint16_t AGpsType;
  94 #define AGPS_TYPE_SUPL          1
  95 #define AGPS_TYPE_C2K           2
  96
  97
  98 /** AGPS status event values. */
  99 typedef uint16_t AGpsStatusValue;
 100 /** GPS requests data connection for AGPS. */
 101 #define GPS_REQUEST_AGPS_DATA_CONN  1
 102 /** GPS releases the AGPS data connection. */
 103 #define GPS_RELEASE_AGPS_DATA_CONN  2
 104 /** AGPS data connection initiated */
 105 #define GPS_AGPS_DATA_CONNECTED     3
 106 /** AGPS data connection completed */
 107 #define GPS_AGPS_DATA_CONN_DONE     4
 108 /** AGPS data connection failed */
 109 #define GPS_AGPS_DATA_CONN_FAILED   5
 110
 111 /**
 112  * Name for the GPS XTRA interface.
 113  */
 114 #define GPS_XTRA_INTERFACE      "gps-xtra"
 115
 116 /**
 117  * Name for the AGPS interface.
 118  */
 119 #define AGPS_INTERFACE      "agps"
 120
 121 /** Represents a location. */
 122 typedef struct {
 123     /** Contains GpsLocationFlags bits. */
 124     uint16_t        flags;
 125     /** Represents latitude in degrees. */
 126     double          latitude;
 127     /** Represents longitude in degrees. */
 128     double          longitude;
 129     /** Represents altitude in meters above the WGS 84 reference
 130      * ellipsoid. */
 131     double          altitude;
 132     /** Represents speed in meters per second. */
 133     float           speed;
 134     /** Represents heading in degrees. */
 135     float           bearing;
 136     /** Represents expected accuracy in meters. */
 137     float           accuracy;
 138     /** Timestamp for the location fix. */
 139     GpsUtcTime      timestamp;
 140 } GpsLocation;
 141
 142 /** Represents the status. */
 143 typedef struct {
 144     GpsStatusValue status;
 145 } GpsStatus;
 146
 147 /** Represents SV information. */
 148 typedef struct {
 149     /** Pseudo-random number for the SV. */
 150     int     prn;
 151     /** Signal to noise ratio. */
 152     float   snr;
 153     /** Elevation of SV in degrees. */
 154     float   elevation;
 155     /** Azimuth of SV in degrees. */
 156     float   azimuth;
 157 } GpsSvInfo;
 158
 159 /** Represents SV status. */
 160 typedef struct {
 161         /** Number of SVs currently visible. */
 162         int         num_svs;
 163
 164         /** Contains an array of SV information. */
 165         GpsSvInfo   sv_list[GPS_MAX_SVS];
 166
 167         /** Represents a bit mask indicating which SVs
 168          * have ephemeris data.
 169          */
 170         uint32_t    ephemeris_mask;
 171
 172         /** Represents a bit mask indicating which SVs
 173          * have almanac data.
 174          */
 175         uint32_t    almanac_mask;
 176
 177         /**
 178          * Represents a bit mask indicating which SVs
 179          * were used for computing the most recent position fix.
 180          */
 181         uint32_t    used_in_fix_mask;
 182 } GpsSvStatus;
 183
 184 /** Callback with location information. */
 185 typedef void (* gps_location_callback)(GpsLocation* location);
 186
 187 /** Callback with status information. */
 188 typedef void (* gps_status_callback)(GpsStatus* status);
 189
 190 /** Callback with SV status information. */
 191 typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info);
 192
 193 /** Callback for reporting NMEA sentences. */
 194 typedef void (* gps_nmea_callback)(GpsUtcTime timestamp, const char* nmea, int length);
 195
 196 /** GPS callback structure. */
 197 typedef struct {
 198         gps_location_callback location_cb;
 199         gps_status_callback status_cb;
 200         gps_sv_status_callback sv_status_cb;
 201         gps_nmea_callback nmea_cb;
 202 } GpsCallbacks;
 203
 204
 205 /** Represents the standard GPS interface. */
 206 typedef struct {
 207     /**
 208      * Opens the interface and provides the callback routines
 209      * to the implemenation of this interface.
 210      */
 211     int   (*init)( GpsCallbacks* callbacks );
 212
 213     /** Starts navigating. */
 214     int   (*start)( void );
 215
 216     /** Stops navigating. */
 217     int   (*stop)( void );
 218
 219     /** Closes the interface. */
 220     void  (*cleanup)( void );
 221
 222     /** Injects the current time. */
 223     int   (*inject_time)(GpsUtcTime time, int64_t timeReference,
 224                          int uncertainty);
 225
 226     /** Injects current location from another location provider
 227      *  (typically cell ID).
 228      *  latitude and longitude are measured in degrees
 229      *  expected accuracy is measured in meters
 230      */
 231     int  (*inject_location)(double latitude, double longitude, float accuracy);
 232
 233     /**
 234      * Specifies that the next call to start will not use the
 235      * information defined in the flags. GPS_DELETE_ALL is passed for
 236      * a cold start.
 237      */
 238     void  (*delete_aiding_data)(GpsAidingData flags);
 239
 240     /**
 241      * fix_frequency represents the time between fixes in seconds.
 242      * Set fix_frequency to zero for a single-shot fix.
 243      */
 244     int   (*set_position_mode)(GpsPositionMode mode, int fix_frequency);
 245
 246     /** Get a pointer to extension information. */
 247     const void* (*get_extension)(const char* name);
 248 } GpsInterface;
 249
 250 /** Callback to request the client to download XTRA data.
 251     The client should download XTRA data and inject it by calling
 252      inject_xtra_data(). */
 253 typedef void (* gps_xtra_download_request)();
 254
 255 /** Callback structure for the XTRA interface. */
 256 typedef struct {
 257         gps_xtra_download_request download_request_cb;
 258 } GpsXtraCallbacks;
 259
 260 /** Extended interface for XTRA support. */
 261 typedef struct {
 262     /**
 263      * Opens the XTRA interface and provides the callback routines
 264      * to the implemenation of this interface.
 265      */
 266     int  (*init)( GpsXtraCallbacks* callbacks );
 267     /** Injects XTRA data into the GPS. */
 268     int  (*inject_xtra_data)( char* data, int length );
 269 } GpsXtraInterface;
 270
 271 /** Represents the status of AGPS. */
 272 typedef struct {
 273     AGpsType        type;
 274     AGpsStatusValue status;
 275 } AGpsStatus;
 276
 277 /** Callback with AGPS status information. */
 278 typedef void (* agps_status_callback)(AGpsStatus* status);
 279
 280 /** Callback structure for the AGPS interface. */
 281 typedef struct {
 282         agps_status_callback status_cb;
 283 } AGpsCallbacks;
 284
 285
 286 /** Extended interface for AGPS support. */
 287 typedef struct {
 288     /**
 289      * Opens the AGPS interface and provides the callback routines
 290      * to the implemenation of this interface.
 291      */
 292     void  (*init)( AGpsCallbacks* callbacks );
 293     /**
 294      * Notifies that a data connection is available and sets
 295      * the name of the APN to be used for SUPL.
 296      */
 297     int  (*data_conn_open)( const char* apn );
 298     /**
 299      * Notifies that the AGPS data connection has been closed.
 300      */
 301     int  (*data_conn_closed)();
 302     /**
 303      * Notifies that a data connection is not available for AGPS.
 304      */
 305     int  (*data_conn_failed)();
 306     /**
 307      * Sets the hostname and port for the AGPS server.
 308      */
 309     int  (*set_server)( AGpsType type, const char* hostname, int port );
 310 } AGpsInterface;
 311
 312 /** Returns the hardware GPS interface. */
 313 const GpsInterface* gps_get_hardware_interface();
 314
 315 /**
 316  * Returns the qemu emulated GPS interface.
 317  */
 318 const GpsInterface* gps_get_qemu_interface();
 319
 320 /**
 321  * Returns the default GPS interface.
 322  */
 323 const GpsInterface* gps_get_interface();
 324
 325 #if __cplusplus
 326 }  // extern "C"
 327 #endif
 328
 329 #endif  // _HARDWARE_GPS_H