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