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 GPS DEBUG interface.
 118  */
 119 #define GPS_DEBUG_INTERFACE      "gps-debug"
 120
 121 /**
 122  * Name for the AGPS interface.
 123  */
 124 #define AGPS_INTERFACE      "agps"
 125
 126 /** Represents a location. */
 127 typedef struct {
 128     /** Contains GpsLocationFlags bits. */
 129     uint16_t        flags;
 130     /** Represents latitude in degrees. */
 131     double          latitude;
 132     /** Represents longitude in degrees. */
 133     double          longitude;
 134     /** Represents altitude in meters above the WGS 84 reference
 135      * ellipsoid. */
 136     double          altitude;
 137     /** Represents speed in meters per second. */
 138     float           speed;
 139     /** Represents heading in degrees. */
 140     float           bearing;
 141     /** Represents expected accuracy in meters. */
 142     float           accuracy;
 143     /** Timestamp for the location fix. */
 144     GpsUtcTime      timestamp;
 145 } GpsLocation;
 146
 147 /** Represents the status. */
 148 typedef struct {
 149     GpsStatusValue status;
 150 } GpsStatus;
 151
 152 /** Represents SV information. */
 153 typedef struct {
 154     /** Pseudo-random number for the SV. */
 155     int     prn;
 156     /** Signal to noise ratio. */
 157     float   snr;
 158     /** Elevation of SV in degrees. */
 159     float   elevation;
 160     /** Azimuth of SV in degrees. */
 161     float   azimuth;
 162 } GpsSvInfo;
 163
 164 /** Represents SV status. */
 165 typedef struct {
 166         /** Number of SVs currently visible. */
 167         int         num_svs;
 168
 169         /** Contains an array of SV information. */
 170         GpsSvInfo   sv_list[GPS_MAX_SVS];
 171
 172         /** Represents a bit mask indicating which SVs
 173          * have ephemeris data.
 174          */
 175         uint32_t    ephemeris_mask;
 176
 177         /** Represents a bit mask indicating which SVs
 178          * have almanac data.
 179          */
 180         uint32_t    almanac_mask;
 181
 182         /**
 183          * Represents a bit mask indicating which SVs
 184          * were used for computing the most recent position fix.
 185          */
 186         uint32_t    used_in_fix_mask;
 187 } GpsSvStatus;
 188
 189 /** Callback with location information. */
 190 typedef void (* gps_location_callback)(GpsLocation* location);
 191
 192 /** Callback with status information. */
 193 typedef void (* gps_status_callback)(GpsStatus* status);
 194
 195 /** Callback with SV status information. */
 196 typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info);
 197
 198 /** Callback for reporting NMEA sentences. */
 199 typedef void (* gps_nmea_callback)(GpsUtcTime timestamp, const char* nmea, int length);
 200
 201 /** GPS callback structure. */
 202 typedef struct {
 203         gps_location_callback location_cb;
 204         gps_status_callback status_cb;
 205         gps_sv_status_callback sv_status_cb;
 206         gps_nmea_callback nmea_cb;
 207 } GpsCallbacks;
 208
 209
 210 /** Represents the standard GPS interface. */
 211 typedef struct {
 212     /**
 213      * Opens the interface and provides the callback routines
 214      * to the implemenation of this interface.
 215      */
 216     int   (*init)( GpsCallbacks* callbacks );
 217
 218     /** Starts navigating. */
 219     int   (*start)( void );
 220
 221     /** Stops navigating. */
 222     int   (*stop)( void );
 223
 224     /** Closes the interface. */
 225     void  (*cleanup)( void );
 226
 227     /** Injects the current time. */
 228     int   (*inject_time)(GpsUtcTime time, int64_t timeReference,
 229                          int uncertainty);
 230
 231     /** Injects current location from another location provider
 232      *  (typically cell ID).
 233      *  latitude and longitude are measured in degrees
 234      *  expected accuracy is measured in meters
 235      */
 236     int  (*inject_location)(double latitude, double longitude, float accuracy);
 237
 238     /**
 239      * Specifies that the next call to start will not use the
 240      * information defined in the flags. GPS_DELETE_ALL is passed for
 241      * a cold start.
 242      */
 243     void  (*delete_aiding_data)(GpsAidingData flags);
 244
 245     /**
 246      * fix_frequency represents the time between fixes in seconds.
 247      * Set fix_frequency to zero for a single-shot fix.
 248      */
 249     int   (*set_position_mode)(GpsPositionMode mode, int fix_frequency);
 250
 251     /** Get a pointer to extension information. */
 252     const void* (*get_extension)(const char* name);
 253 } GpsInterface;
 254
 255 /** Callback to request the client to download XTRA data.
 256     The client should download XTRA data and inject it by calling
 257      inject_xtra_data(). */
 258 typedef void (* gps_xtra_download_request)();
 259
 260 /** Callback structure for the XTRA interface. */
 261 typedef struct {
 262         gps_xtra_download_request download_request_cb;
 263 } GpsXtraCallbacks;
 264
 265 /** Extended interface for XTRA support. */
 266 typedef struct {
 267     /**
 268      * Opens the XTRA interface and provides the callback routines
 269      * to the implemenation of this interface.
 270      */
 271     int  (*init)( GpsXtraCallbacks* callbacks );
 272     /** Injects XTRA data into the GPS. */
 273     int  (*inject_xtra_data)( char* data, int length );
 274 } GpsXtraInterface;
 275
 276 /** Extended interface for DEBUG support. */
 277 typedef struct {
 278     /**
 279      * This function should return any information that the native
 280      * implementation wishes to include in a bugreport.
 281      */
 282     size_t (*get_internal_state)(char* buffer, size_t bufferSize);
 283 } GpsDebugInterface;
 284
 285 /** Represents the status of AGPS. */
 286 typedef struct {
 287     AGpsType        type;
 288     AGpsStatusValue status;
 289 } AGpsStatus;
 290
 291 /** Callback with AGPS status information. */
 292 typedef void (* agps_status_callback)(AGpsStatus* status);
 293
 294 /** Callback structure for the AGPS interface. */
 295 typedef struct {
 296         agps_status_callback status_cb;
 297 } AGpsCallbacks;
 298
 299
 300 /** Extended interface for AGPS support. */
 301 typedef struct {
 302     /**
 303      * Opens the AGPS interface and provides the callback routines
 304      * to the implemenation of this interface.
 305      */
 306     void  (*init)( AGpsCallbacks* callbacks );
 307     /**
 308      * Notifies that a data connection is available and sets
 309      * the name of the APN to be used for SUPL.
 310      */
 311     int  (*data_conn_open)( const char* apn );
 312     /**
 313      * Notifies that the AGPS data connection has been closed.
 314      */
 315     int  (*data_conn_closed)();
 316     /**
 317      * Notifies that a data connection is not available for AGPS.
 318      */
 319     int  (*data_conn_failed)();
 320     /**
 321      * Sets the hostname and port for the AGPS server.
 322      */
 323     int  (*set_server)( AGpsType type, const char* hostname, int port );
 324 } AGpsInterface;
 325
 326 /** Returns the hardware GPS interface. */
 327 const GpsInterface* gps_get_hardware_interface();
 328
 329 /**
 330  * Returns the qemu emulated GPS interface.
 331  */
 332 const GpsInterface* gps_get_qemu_interface();
 333
 334 /**
 335  * Returns the default GPS interface.
 336  */
 337 const GpsInterface* gps_get_interface();
 338
 339 #if __cplusplus
 340 }  // extern "C"
 341 #endif
 342
 343 #endif  // _HARDWARE_GPS_H