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 /** SUPL MS-Based mode. */
  39 #define GPS_POSITION_MODE_MS_BASED      1
  40 /** SUPL 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 /**
  93  * Name for the GPS XTRA interface.
  94  */
  95 #define GPS_XTRA_INTERFACE      "gps-xtra"
  96
  97 /**
  98  * Name for the GPS SUPL interface.
  99  */
 100 #define GPS_SUPL_INTERFACE      "gps-supl"
 101
 102 /** Represents a location. */
 103 typedef struct {
 104     /** Contains GpsLocationFlags bits. */
 105     uint16_t        flags;
 106     /** Represents latitude in degrees. */
 107     double          latitude;
 108     /** Represents longitude in degrees. */
 109     double          longitude;
 110     /** Represents altitude in meters above the WGS 84 reference
 111      * ellipsoid. */
 112     double          altitude;
 113     /** Represents speed in meters per second. */
 114     float           speed;
 115     /** Represents heading in degrees. */
 116     float           bearing;
 117     /** Represents expected accuracy in meters. */
 118     float           accuracy;
 119     /** Timestamp for the location fix. */
 120     GpsUtcTime      timestamp;
 121 } GpsLocation;
 122
 123 /** Represents the status. */
 124 typedef struct {
 125     GpsStatusValue status;
 126 } GpsStatus;
 127
 128 /** Represents SV information. */
 129 typedef struct {
 130     /** Pseudo-random number for the SV. */
 131     int     prn;
 132     /** Signal to noise ratio. */
 133     float   snr;
 134     /** Elevation of SV in degrees. */
 135     float   elevation;
 136     /** Azimuth of SV in degrees. */
 137     float   azimuth;
 138 } GpsSvInfo;
 139
 140 /** Represents SV status. */
 141 typedef struct {
 142         /** Number of SVs currently visible. */
 143         int         num_svs;
 144
 145         /** Contains an array of SV information. */
 146         GpsSvInfo   sv_list[GPS_MAX_SVS];
 147
 148         /** Represents a bit mask indicating which SVs
 149          * have ephemeris data.
 150          */
 151         uint32_t    ephemeris_mask;
 152
 153         /** Represents a bit mask indicating which SVs
 154          * have almanac data.
 155          */
 156         uint32_t    almanac_mask;
 157
 158         /**
 159          * Represents a bit mask indicating which SVs
 160          * were used for computing the most recent position fix.
 161          */
 162         uint32_t    used_in_fix_mask;
 163 } GpsSvStatus;
 164
 165 /** Callback with location information. */
 166 typedef void (* gps_location_callback)(GpsLocation* location);
 167
 168 /** Callback with status information. */
 169 typedef void (* gps_status_callback)(GpsStatus* status);
 170
 171 /** Callback with SV status information. */
 172 typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info);
 173
 174 /** GPS callback structure. */
 175 typedef struct {
 176         gps_location_callback location_cb;
 177         gps_status_callback status_cb;
 178         gps_sv_status_callback sv_status_cb;
 179 } GpsCallbacks;
 180
 181
 182 /** Represents the standard GPS interface. */
 183 typedef struct {
 184     /**
 185      * Opens the interface and provides the callback routines
 186      * to the implemenation of this interface.
 187      */
 188     int   (*init)( GpsCallbacks* callbacks );
 189
 190     /** Starts navigating. */
 191     int   (*start)( void );
 192
 193     /** Stops navigating. */
 194     int   (*stop)( void );
 195
 196     /** Sets requested frequency of fixes in seconds. */
 197     void  (*set_fix_frequency)( int frequency );
 198
 199     /** Closes the interface. */
 200     void  (*cleanup)( void );
 201
 202     /** Injects the current time. */
 203     int   (*inject_time)(GpsUtcTime time, int64_t timeReference,
 204                          int uncertainty);
 205
 206     /**
 207      * Specifies that the next call to start will not use the
 208      * information defined in the flags. GPS_DELETE_ALL is passed for
 209      * a cold start.
 210      */
 211     void  (*delete_aiding_data)(GpsAidingData flags);
 212
 213     /**
 214      * fix_frequency represents the time between fixes in seconds.
 215      * Set fix_frequency to zero for a single-shot fix.
 216      */
 217     int   (*set_position_mode)(GpsPositionMode mode, int fix_frequency);
 218
 219     /** Get a pointer to extension information. */
 220     const void* (*get_extension)(const char* name);
 221 } GpsInterface;
 222
 223 /** Callback to request the client to download XTRA data.
 224     The client should download XTRA data and inject it by calling
 225      inject_xtra_data(). */
 226 typedef void (* gps_xtra_download_request)();
 227
 228 /** Callback structure for the XTRA interface. */
 229 typedef struct {
 230         gps_xtra_download_request download_request_cb;
 231 } GpsXtraCallbacks;
 232
 233 /** Extended interface for XTRA support. */
 234 typedef struct {
 235     /**
 236      * Opens the XTRA interface and provides the callback routines
 237      * to the implemenation of this interface.
 238      */
 239     int  (*init)( GpsXtraCallbacks* callbacks );
 240     /** Injects XTRA data into the GPS. */
 241     int  (*inject_xtra_data)( char* data, int length );
 242 } GpsXtraInterface;
 243
 244 /** Returns the hardware GPS interface. */
 245 const GpsInterface* gps_get_hardware_interface();
 246
 247 /**
 248  * Returns the qemu emulated GPS interface.
 249  */
 250 const GpsInterface* gps_get_qemu_interface();
 251
 252 /**
 253  * Returns the default GPS interface.
 254  */
 255 const GpsInterface* gps_get_interface();
 256
 257 #if __cplusplus
 258 }  // extern "C"
 259 #endif
 260
 261 #endif  // _HARDWARE_GPS_H