1 /* Copyright (c) 2017 The Linux Foundation. All rights reserved.
2  *
3  * Redistribution and use in source and binary forms, with or without
4  * modification, are permitted provided that the following conditions are
5  * met:
6  *     * Redistributions of source code must retain the above copyright
7  *       notice, this list of conditions and the following disclaimer.
8  *     * Redistributions in binary form must reproduce the above
9  *       copyright notice, this list of conditions and the following
10  *       disclaimer in the documentation and/or other materials provided
11  *       with the distribution.
12  *     * Neither the name of The Linux Foundation nor the names of its
13  *       contributors may be used to endorse or promote products derived
14  *       from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
17  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
19  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
20  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
23  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
24  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
25  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
26  * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 #ifndef LOCATION_H
30 #define LOCATION_H
31 
32 #include <vector>
33 #include <stdint.h>
34 #include <functional>
35 
36 #define GNSS_NI_REQUESTOR_MAX  256
37 #define GNSS_NI_MESSAGE_ID_MAX 2048
38 #define GNSS_SV_MAX 64
39 #define GNSS_MEASUREMENTS_MAX 64
40 #define GNSS_UTC_TIME_OFFSET   (3657)
41 
42 #define GNSS_BUGREPORT_GPS_MIN  (1)
43 #define GNSS_BUGREPORT_SBAS_MIN (120)
44 #define GNSS_BUGREPORT_GLO_MIN  (1)
45 #define GNSS_BUGREPORT_QZSS_MIN (193)
46 #define GNSS_BUGREPORT_BDS_MIN  (1)
47 #define GNSS_BUGREPORT_GAL_MIN  (1)
48 
49 typedef enum {
50     LOCATION_ERROR_SUCCESS = 0,
51     LOCATION_ERROR_GENERAL_FAILURE,
52     LOCATION_ERROR_CALLBACK_MISSING,
53     LOCATION_ERROR_INVALID_PARAMETER,
54     LOCATION_ERROR_ID_EXISTS,
55     LOCATION_ERROR_ID_UNKNOWN,
56     LOCATION_ERROR_ALREADY_STARTED,
57     LOCATION_ERROR_GEOFENCES_AT_MAX,
58     LOCATION_ERROR_NOT_SUPPORTED
59 } LocationError;
60 
61 // Flags to indicate which values are valid in a Location
62 typedef uint16_t LocationFlagsMask;
63 typedef enum {
64     LOCATION_HAS_LAT_LONG_BIT          = (1<<0), // location has valid latitude and longitude
65     LOCATION_HAS_ALTITUDE_BIT          = (1<<1), // location has valid altitude
66     LOCATION_HAS_SPEED_BIT             = (1<<2), // location has valid speed
67     LOCATION_HAS_BEARING_BIT           = (1<<3), // location has valid bearing
68     LOCATION_HAS_ACCURACY_BIT          = (1<<4), // location has valid accuracy
69     LOCATION_HAS_VERTICAL_ACCURACY_BIT = (1<<5), // location has valid vertical accuracy
70     LOCATION_HAS_SPEED_ACCURACY_BIT    = (1<<6), // location has valid speed accuracy
71     LOCATION_HAS_BEARING_ACCURACY_BIT  = (1<<7), // location has valid bearing accuracy
72 } LocationFlagsBits;
73 
74 typedef uint16_t LocationTechnologyMask;
75 typedef enum {
76     LOCATION_TECHNOLOGY_GNSS_BIT     = (1<<0), // location was calculated using GNSS
77     LOCATION_TECHNOLOGY_CELL_BIT     = (1<<1), // location was calculated using Cell
78     LOCATION_TECHNOLOGY_WIFI_BIT     = (1<<2), // location was calculated using WiFi
79     LOCATION_TECHNOLOGY_SENSORS_BIT  = (1<<3), // location was calculated using Sensors
80 } LocationTechnologyBits;
81 
82 typedef enum {
83     LOCATION_RELIABILITY_NOT_SET = 0,
84     LOCATION_RELIABILITY_VERY_LOW,
85     LOCATION_RELIABILITY_LOW,
86     LOCATION_RELIABILITY_MEDIUM,
87     LOCATION_RELIABILITY_HIGH,
88 } LocationReliability;
89 
90 typedef uint32_t GnssLocationInfoFlagMask;
91 typedef enum {
92     GNSS_LOCATION_INFO_ALTITUDE_MEAN_SEA_LEVEL_BIT      = (1<<0), // valid altitude mean sea level
93     GNSS_LOCATION_INFO_DOP_BIT                          = (1<<1), // valid pdop, hdop, and vdop
94     GNSS_LOCATION_INFO_MAGNETIC_DEVIATION_BIT           = (1<<2), // valid magnetic deviation
95     GNSS_LOCATION_INFO_HOR_RELIABILITY_BIT              = (1<<3), // valid horizontal reliability
96     GNSS_LOCATION_INFO_VER_RELIABILITY_BIT              = (1<<4), // valid vertical reliability
97     GNSS_LOCATION_INFO_HOR_ACCURACY_ELIP_SEMI_MAJOR_BIT = (1<<5), // valid elipsode semi major
98     GNSS_LOCATION_INFO_HOR_ACCURACY_ELIP_SEMI_MINOR_BIT = (1<<6), // valid elipsode semi minor
99     GNSS_LOCATION_INFO_HOR_ACCURACY_ELIP_AZIMUTH_BIT    = (1<<7),// valid accuracy elipsode azimuth
100 } GnssLocationInfoFlagBits;
101 
102 typedef enum {
103     GEOFENCE_BREACH_ENTER = 0,
104     GEOFENCE_BREACH_EXIT,
105     GEOFENCE_BREACH_DWELL_IN,
106     GEOFENCE_BREACH_DWELL_OUT,
107     GEOFENCE_BREACH_UNKNOWN,
108 } GeofenceBreachType;
109 
110 typedef uint16_t GeofenceBreachTypeMask;
111 typedef enum {
112     GEOFENCE_BREACH_ENTER_BIT     = (1<<0),
113     GEOFENCE_BREACH_EXIT_BIT      = (1<<1),
114     GEOFENCE_BREACH_DWELL_IN_BIT  = (1<<2),
115     GEOFENCE_BREACH_DWELL_OUT_BIT = (1<<3),
116 } GeofenceBreachTypeBits;
117 
118 typedef enum {
119     GEOFENCE_STATUS_AVAILABILE_NO = 0,
120     GEOFENCE_STATUS_AVAILABILE_YES,
121 } GeofenceStatusAvailable;
122 
123 typedef uint32_t LocationCapabilitiesMask;
124 typedef enum {
125     // supports startTracking API with minInterval param
126     LOCATION_CAPABILITIES_TIME_BASED_TRACKING_BIT           = (1<<0),
127     // supports startBatching API with minInterval param
128     LOCATION_CAPABILITIES_TIME_BASED_BATCHING_BIT           = (1<<1),
129     // supports startTracking API with minDistance param
130     LOCATION_CAPABILITIES_DISTANCE_BASED_TRACKING_BIT       = (1<<2),
131     // supports startBatching API with minDistance param
132     LOCATION_CAPABILITIES_DISTANCE_BASED_BATCHING_BIT       = (1<<3),
133     // supports addGeofences API
134     LOCATION_CAPABILITIES_GEOFENCE_BIT                      = (1<<4),
135     // supports GnssMeasurementsCallback
136     LOCATION_CAPABILITIES_GNSS_MEASUREMENTS_BIT             = (1<<5),
137     // supports startTracking/startBatching API with LocationOptions.mode of MSB (Ms Based)
138     LOCATION_CAPABILITIES_GNSS_MSB_BIT                      = (1<<6),
139     // supports startTracking/startBatching API with LocationOptions.mode of MSA (MS Assisted)
140     LOCATION_CAPABILITIES_GNSS_MSA_BIT                      = (1<<7),
141 } LocationCapabilitiesBits;
142 
143 typedef enum {
144     LOCATION_TECHNOLOGY_TYPE_GNSS = 0,
145 } LocationTechnologyType;
146 
147 // Configures how GPS is locked when GPS is disabled (through GnssDisable)
148 typedef enum {
149     GNSS_CONFIG_GPS_LOCK_NONE = 0, // gps is not locked when GPS is disabled (GnssDisable)
150     GNSS_CONFIG_GPS_LOCK_MO,       // gps mobile originated (MO) is locked when GPS is disabled
151     GNSS_CONFIG_GPS_LOCK_NI,       // gps network initiated (NI) is locked when GPS is disabled
152     GNSS_CONFIG_GPS_LOCK_MO_AND_NI,// gps MO and NI is locked when GPS is disabled
153 } GnssConfigGpsLock;
154 
155 // SUPL version
156 typedef enum {
157     GNSS_CONFIG_SUPL_VERSION_1_0_0 = 1,
158     GNSS_CONFIG_SUPL_VERSION_2_0_0,
159     GNSS_CONFIG_SUPL_VERSION_2_0_2,
160 } GnssConfigSuplVersion;
161 
162 // LTE Positioning Profile
163 typedef enum {
164     GNSS_CONFIG_LPP_PROFILE_RRLP_ON_LTE = 0,              // RRLP on LTE (Default)
165     GNSS_CONFIG_LPP_PROFILE_USER_PLANE,                   // LPP User Plane (UP) on LTE
166     GNSS_CONFIG_LPP_PROFILE_CONTROL_PLANE,                // LPP_Control_Plane (CP)
167     GNSS_CONFIG_LPP_PROFILE_USER_PLANE_AND_CONTROL_PLANE, // Both LPP UP and CP
168 } GnssConfigLppProfile;
169 
170 // Technology for LPPe Control Plane
171 typedef uint16_t GnssConfigLppeControlPlaneMask;
172 typedef enum {
173     GNSS_CONFIG_LPPE_CONTROL_PLANE_DBH_BIT                  = (1<<0), // DBH
174     GNSS_CONFIG_LPPE_CONTROL_PLANE_WLAN_AP_MEASUREMENTS_BIT = (1<<1), // WLAN_AP_MEASUREMENTS
175 } GnssConfigLppeControlPlaneBits;
176 
177 // Technology for LPPe User Plane
178 typedef uint16_t GnssConfigLppeUserPlaneMask;
179 typedef enum {
180     GNSS_CONFIG_LPPE_USER_PLANE_DBH_BIT                  = (1<<0), // DBH
181     GNSS_CONFIG_LPPE_USER_PLANE_WLAN_AP_MEASUREMENTS_BIT = (1<<1), // WLAN_AP_MEASUREMENTS
182 } GnssConfigLppeUserPlaneBits;
183 
184 // Positioning Protocol on A-GLONASS system
185 typedef uint16_t GnssConfigAGlonassPositionProtocolMask;
186 typedef enum {
187     GNSS_CONFIG_RRC_CONTROL_PLANE_BIT = (1<<0),  // RRC Control Plane
188     GNSS_CONFIG_RRLP_USER_PLANE_BIT   = (1<<1),  // RRLP User Plane
189     GNSS_CONFIG_LLP_USER_PLANE_BIT    = (1<<2),  // LPP User Plane
190     GNSS_CONFIG_LLP_CONTROL_PLANE_BIT = (1<<3),  // LPP Control Plane
191 } GnssConfigAGlonassPositionProtocolBits;
192 
193 typedef enum {
194     GNSS_CONFIG_EMERGENCY_PDN_FOR_EMERGENCY_SUPL_NO = 0,
195     GNSS_CONFIG_EMERGENCY_PDN_FOR_EMERGENCY_SUPL_YES,
196 } GnssConfigEmergencyPdnForEmergencySupl;
197 
198 typedef enum {
199     GNSS_CONFIG_SUPL_EMERGENCY_SERVICES_NO = 0,
200     GNSS_CONFIG_SUPL_EMERGENCY_SERVICES_YES,
201 } GnssConfigSuplEmergencyServices;
202 
203 typedef uint16_t GnssConfigSuplModeMask;
204 typedef enum {
205     GNSS_CONFIG_SUPL_MODE_MSB_BIT = (1<<0),
206     GNSS_CONFIG_SUPL_MODE_MSA_BIT = (1<<1),
207 } GnssConfigSuplModeBits;
208 
209 typedef uint32_t GnssConfigFlagsMask;
210 typedef enum {
211     GNSS_CONFIG_FLAGS_GPS_LOCK_VALID_BIT                   = (1<<0),
212     GNSS_CONFIG_FLAGS_SUPL_VERSION_VALID_BIT               = (1<<1),
213     GNSS_CONFIG_FLAGS_SET_ASSISTANCE_DATA_VALID_BIT        = (1<<2),
214     GNSS_CONFIG_FLAGS_LPP_PROFILE_VALID_BIT                = (1<<3),
215     GNSS_CONFIG_FLAGS_LPPE_CONTROL_PLANE_VALID_BIT         = (1<<4),
216     GNSS_CONFIG_FLAGS_LPPE_USER_PLANE_VALID_BIT            = (1<<5),
217     GNSS_CONFIG_FLAGS_AGLONASS_POSITION_PROTOCOL_VALID_BIT = (1<<6),
218     GNSS_CONFIG_FLAGS_EM_PDN_FOR_EM_SUPL_VALID_BIT         = (1<<7),
219     GNSS_CONFIG_FLAGS_SUPL_EM_SERVICES_BIT                 = (1<<8),
220     GNSS_CONFIG_FLAGS_SUPL_MODE_BIT                        = (1<<9),
221 } GnssConfigFlagsBits;
222 
223 typedef enum {
224     GNSS_NI_ENCODING_TYPE_NONE = 0,
225     GNSS_NI_ENCODING_TYPE_GSM_DEFAULT,
226     GNSS_NI_ENCODING_TYPE_UTF8,
227     GNSS_NI_ENCODING_TYPE_UCS2,
228 } GnssNiEncodingType;
229 
230 typedef enum {
231     GNSS_NI_TYPE_VOICE = 0,
232     GNSS_NI_TYPE_SUPL,
233     GNSS_NI_TYPE_CONTROL_PLANE,
234     GNSS_NI_TYPE_EMERGENCY_SUPL
235 } GnssNiType;
236 
237 typedef uint16_t GnssNiOptionsMask;
238 typedef enum {
239     GNSS_NI_OPTIONS_NOTIFICATION_BIT     = (1<<0),
240     GNSS_NI_OPTIONS_VERIFICATION_BIT     = (1<<1),
241     GNSS_NI_OPTIONS_PRIVACY_OVERRIDE_BIT = (1<<2),
242 } GnssNiOptionsBits;
243 
244 typedef enum {
245     GNSS_NI_RESPONSE_ACCEPT = 1,
246     GNSS_NI_RESPONSE_DENY,
247     GNSS_NI_RESPONSE_NO_RESPONSE,
248     GNSS_NI_RESPONSE_IGNORE,
249 } GnssNiResponse;
250 
251 typedef enum {
252     GNSS_SV_TYPE_UNKNOWN = 0,
253     GNSS_SV_TYPE_GPS,
254     GNSS_SV_TYPE_SBAS,
255     GNSS_SV_TYPE_GLONASS,
256     GNSS_SV_TYPE_QZSS,
257     GNSS_SV_TYPE_BEIDOU,
258     GNSS_SV_TYPE_GALILEO,
259 } GnssSvType;
260 
261 typedef enum {
262     GNSS_EPH_TYPE_UNKNOWN = 0,
263     GNSS_EPH_TYPE_EPHEMERIS,
264     GNSS_EPH_TYPE_ALMANAC,
265 } GnssEphemerisType;
266 
267 typedef enum {
268     GNSS_EPH_SOURCE_UNKNOWN = 0,
269     GNSS_EPH_SOURCE_DEMODULATED,
270     GNSS_EPH_SOURCE_SUPL_PROVIDED,
271     GNSS_EPH_SOURCE_OTHER_SERVER_PROVIDED,
272     GNSS_EPH_SOURCE_LOCAL,
273 } GnssEphemerisSource;
274 
275 typedef enum {
276     GNSS_EPH_HEALTH_UNKNOWN = 0,
277     GNSS_EPH_HEALTH_GOOD,
278     GNSS_EPH_HEALTH_BAD,
279 } GnssEphemerisHealth;
280 
281 typedef uint16_t GnssSvOptionsMask;
282 typedef enum {
283     GNSS_SV_OPTIONS_HAS_EPHEMER_BIT = (1<<0),
284     GNSS_SV_OPTIONS_HAS_ALMANAC_BIT = (1<<1),
285     GNSS_SV_OPTIONS_USED_IN_FIX_BIT = (1<<2),
286 } GnssSvOptionsBits;
287 
288 typedef enum {
289     GNSS_ASSISTANCE_TYPE_SUPL = 0,
290     GNSS_ASSISTANCE_TYPE_C2K,
291 } GnssAssistanceType;
292 
293 typedef enum {
294     GNSS_SUPL_MODE_STANDALONE = 0,
295     GNSS_SUPL_MODE_MSB,
296     GNSS_SUPL_MODE_MSA,
297 } GnssSuplMode;
298 
299 typedef uint16_t GnssMeasurementsAdrStateMask;
300 typedef enum {
301     GNSS_MEASUREMENTS_ACCUMULATED_DELTA_RANGE_STATE_UNKNOWN         = 0,
302     GNSS_MEASUREMENTS_ACCUMULATED_DELTA_RANGE_STATE_VALID_BIT       = (1<<0),
303     GNSS_MEASUREMENTS_ACCUMULATED_DELTA_RANGE_STATE_RESET_BIT       = (1<<1),
304     GNSS_MEASUREMENTS_ACCUMULATED_DELTA_RANGE_STATE_CYCLE_SLIP_BIT  = (1<<2),
305 } GnssMeasurementsAdrStateBits;
306 
307 typedef uint32_t GnssMeasurementsDataFlagsMask;
308 typedef enum {
309     GNSS_MEASUREMENTS_DATA_SV_ID_BIT                        = (1<<0),
310     GNSS_MEASUREMENTS_DATA_SV_TYPE_BIT                      = (1<<1),
311     GNSS_MEASUREMENTS_DATA_STATE_BIT                        = (1<<2),
312     GNSS_MEASUREMENTS_DATA_RECEIVED_SV_TIME_BIT             = (1<<3),
313     GNSS_MEASUREMENTS_DATA_RECEIVED_SV_TIME_UNCERTAINTY_BIT = (1<<4),
314     GNSS_MEASUREMENTS_DATA_CARRIER_TO_NOISE_BIT             = (1<<5),
315     GNSS_MEASUREMENTS_DATA_PSEUDORANGE_RATE_BIT             = (1<<6),
316     GNSS_MEASUREMENTS_DATA_PSEUDORANGE_RATE_UNCERTAINTY_BIT = (1<<7),
317     GNSS_MEASUREMENTS_DATA_ADR_STATE_BIT                    = (1<<8),
318     GNSS_MEASUREMENTS_DATA_ADR_BIT                          = (1<<9),
319     GNSS_MEASUREMENTS_DATA_ADR_UNCERTAINTY_BIT              = (1<<10),
320     GNSS_MEASUREMENTS_DATA_CARRIER_FREQUENCY_BIT            = (1<<11),
321     GNSS_MEASUREMENTS_DATA_CARRIER_CYCLES_BIT               = (1<<12),
322     GNSS_MEASUREMENTS_DATA_CARRIER_PHASE_BIT                = (1<<13),
323     GNSS_MEASUREMENTS_DATA_CARRIER_PHASE_UNCERTAINTY_BIT    = (1<<14),
324     GNSS_MEASUREMENTS_DATA_MULTIPATH_INDICATOR_BIT          = (1<<15),
325     GNSS_MEASUREMENTS_DATA_SIGNAL_TO_NOISE_RATIO_BIT        = (1<<16),
326     GNSS_MEASUREMENTS_DATA_AUTOMATIC_GAIN_CONTROL_BIT       = (1<<17),
327 } GnssMeasurementsDataFlagsBits;
328 
329 typedef uint32_t GnssMeasurementsStateMask;
330 typedef enum {
331     GNSS_MEASUREMENTS_STATE_UNKNOWN_BIT               = 0,
332     GNSS_MEASUREMENTS_STATE_CODE_LOCK_BIT             = (1<<0),
333     GNSS_MEASUREMENTS_STATE_BIT_SYNC_BIT              = (1<<1),
334     GNSS_MEASUREMENTS_STATE_SUBFRAME_SYNC_BIT         = (1<<2),
335     GNSS_MEASUREMENTS_STATE_TOW_DECODED_BIT           = (1<<3),
336     GNSS_MEASUREMENTS_STATE_MSEC_AMBIGUOUS_BIT        = (1<<4),
337     GNSS_MEASUREMENTS_STATE_SYMBOL_SYNC_BIT           = (1<<5),
338     GNSS_MEASUREMENTS_STATE_GLO_STRING_SYNC_BIT       = (1<<6),
339     GNSS_MEASUREMENTS_STATE_GLO_TOD_DECODED_BIT       = (1<<7),
340     GNSS_MEASUREMENTS_STATE_BDS_D2_BIT_SYNC_BIT       = (1<<8),
341     GNSS_MEASUREMENTS_STATE_BDS_D2_SUBFRAME_SYNC_BIT  = (1<<9),
342     GNSS_MEASUREMENTS_STATE_GAL_E1BC_CODE_LOCK_BIT    = (1<<10),
343     GNSS_MEASUREMENTS_STATE_GAL_E1C_2ND_CODE_LOCK_BIT = (1<<11),
344     GNSS_MEASUREMENTS_STATE_GAL_E1B_PAGE_SYNC_BIT     = (1<<12),
345     GNSS_MEASUREMENTS_STATE_SBAS_SYNC_BIT             = (1<<13),
346 } GnssMeasurementsStateBits;
347 
348 typedef enum {
349     GNSS_MEASUREMENTS_MULTIPATH_INDICATOR_UNKNOWN = 0,
350     GNSS_MEASUREMENTS_MULTIPATH_INDICATOR_PRESENT,
351     GNSS_MEASUREMENTS_MULTIPATH_INDICATOR_NOT_PRESENT,
352 } GnssMeasurementsMultipathIndicator;
353 
354 typedef uint32_t GnssMeasurementsClockFlagsMask;
355 typedef enum {
356     GNSS_MEASUREMENTS_CLOCK_FLAGS_LEAP_SECOND_BIT                  = (1<<0),
357     GNSS_MEASUREMENTS_CLOCK_FLAGS_TIME_BIT                         = (1<<1),
358     GNSS_MEASUREMENTS_CLOCK_FLAGS_TIME_UNCERTAINTY_BIT             = (1<<2),
359     GNSS_MEASUREMENTS_CLOCK_FLAGS_FULL_BIAS_BIT                    = (1<<3),
360     GNSS_MEASUREMENTS_CLOCK_FLAGS_BIAS_BIT                         = (1<<4),
361     GNSS_MEASUREMENTS_CLOCK_FLAGS_BIAS_UNCERTAINTY_BIT             = (1<<5),
362     GNSS_MEASUREMENTS_CLOCK_FLAGS_DRIFT_BIT                        = (1<<6),
363     GNSS_MEASUREMENTS_CLOCK_FLAGS_DRIFT_UNCERTAINTY_BIT            = (1<<7),
364     GNSS_MEASUREMENTS_CLOCK_FLAGS_HW_CLOCK_DISCONTINUITY_COUNT_BIT = (1<<8),
365 } GnssMeasurementsClockFlagsBits;
366 
367 typedef uint32_t GnssAidingDataSvMask;
368 typedef enum {
369     GNSS_AIDING_DATA_SV_EPHEMERIS_BIT    = (1<<0), // ephemeris
370     GNSS_AIDING_DATA_SV_ALMANAC_BIT      = (1<<1), // almanac
371     GNSS_AIDING_DATA_SV_HEALTH_BIT       = (1<<2), // health
372     GNSS_AIDING_DATA_SV_DIRECTION_BIT    = (1<<3), // direction
373     GNSS_AIDING_DATA_SV_STEER_BIT        = (1<<4), // steer
374     GNSS_AIDING_DATA_SV_ALMANAC_CORR_BIT = (1<<5), // almanac correction
375     GNSS_AIDING_DATA_SV_BLACKLIST_BIT    = (1<<6), // blacklist SVs
376     GNSS_AIDING_DATA_SV_SA_DATA_BIT      = (1<<7), // sensitivity assistance data
377     GNSS_AIDING_DATA_SV_NO_EXIST_BIT     = (1<<8), // SV does not exist
378     GNSS_AIDING_DATA_SV_IONOSPHERE_BIT   = (1<<9), // ionosphere correction
379     GNSS_AIDING_DATA_SV_TIME_BIT         = (1<<10),// reset satellite time
380 } GnssAidingDataSvBits;
381 
382 typedef uint32_t GnssAidingDataSvTypeMask;
383 typedef enum {
384     GNSS_AIDING_DATA_SV_TYPE_GPS_BIT      = (1<<0),
385     GNSS_AIDING_DATA_SV_TYPE_GLONASS_BIT  = (1<<1),
386     GNSS_AIDING_DATA_SV_TYPE_QZSS_BIT     = (1<<2),
387     GNSS_AIDING_DATA_SV_TYPE_BEIDOU_BIT   = (1<<3),
388     GNSS_AIDING_DATA_SV_TYPE_GALILEO_BIT  = (1<<4),
389 } GnssAidingDataSvTypeBits;
390 
391 typedef struct {
392     GnssAidingDataSvMask svMask;         // bitwise OR of GnssAidingDataSvBits
393     GnssAidingDataSvTypeMask svTypeMask; // bitwise OR of GnssAidingDataSvTypeBits
394 } GnssAidingDataSv;
395 
396 typedef uint32_t GnssAidingDataCommonMask;
397 typedef enum {
398     GNSS_AIDING_DATA_COMMON_POSITION_BIT      = (1<<0), // position estimate
399     GNSS_AIDING_DATA_COMMON_TIME_BIT          = (1<<1), // reset all clock values
400     GNSS_AIDING_DATA_COMMON_UTC_BIT           = (1<<2), // UTC estimate
401     GNSS_AIDING_DATA_COMMON_RTI_BIT           = (1<<3), // RTI
402     GNSS_AIDING_DATA_COMMON_FREQ_BIAS_EST_BIT = (1<<4), // frequency bias estimate
403     GNSS_AIDING_DATA_COMMON_CELLDB_BIT        = (1<<5), // all celldb info
404 } GnssAidingDataCommonBits;
405 
406 typedef struct {
407     GnssAidingDataCommonMask mask; // bitwise OR of GnssAidingDataCommonBits
408 } GnssAidingDataCommon;
409 
410 typedef struct {
411     bool deleteAll;              // if true, delete all aiding data and ignore other params
412     GnssAidingDataSv sv;         // SV specific aiding data
413     GnssAidingDataCommon common; // common aiding data
414 } GnssAidingData;
415 
416 typedef struct {
417     size_t size;             // set to sizeof(Location)
418     LocationFlagsMask flags; // bitwise OR of LocationFlagsBits to mark which params are valid
419     uint64_t timestamp;      // UTC timestamp for location fix, milliseconds since January 1, 1970
420     double latitude;         // in degrees
421     double longitude;        // in degrees
422     double altitude;         // in meters above the WGS 84 reference ellipsoid
423     float speed;             // in meters per second
424     float bearing;           // in degrees; range [0, 360)
425     float accuracy;          // in meters
426     float verticalAccuracy;  // in meters
427     float speedAccuracy;     // in meters/second
428     float bearingAccuracy;   // in degrees (0 to 359.999)
429     LocationTechnologyMask techMask;
430 } Location;
431 
432 typedef struct  {
433     size_t size;          // set to sizeof(LocationOptions)
434     uint32_t minInterval; // in milliseconds
435     uint32_t minDistance; // in meters. if minDistance > 0, gnssSvCallback/gnssNmeaCallback/
436                           // gnssMeasurementsCallback may not be called
437     GnssSuplMode mode;    // Standalone/MS-Based/MS-Assisted
438 } LocationOptions;
439 
440 typedef struct {
441     size_t size;                            // set to sizeof(GeofenceOption)
442     GeofenceBreachTypeMask breachTypeMask;  // bitwise OR of GeofenceBreachTypeBits
443     uint32_t responsiveness;                // in milliseconds
444     uint32_t dwellTime;                     // in seconds
445 } GeofenceOption;
446 
447 typedef struct  {
448     size_t size;      // set to sizeof(GeofenceInfo)
449     double latitude;  // in degrees
450     double longitude; // in degrees
451     double radius;    // in meters
452 } GeofenceInfo;
453 
454 typedef struct {
455     size_t size;             // set to sizeof(GeofenceBreachNotification)
456     size_t count;            // number of ids in array
457     uint32_t* ids;           // array of ids that have breached
458     Location location;       // location associated with breach
459     GeofenceBreachType type; // type of breach
460     uint64_t timestamp;      // timestamp of breach
461 } GeofenceBreachNotification;
462 
463 typedef struct {
464     size_t size;                       // set to sizeof(GeofenceBreachNotification)
465     GeofenceStatusAvailable available; // GEOFENCE_STATUS_AVAILABILE_NO/_YES
466     LocationTechnologyType techType;   // GNSS
467 } GeofenceStatusNotification;
468 
469 typedef struct {
470     size_t size;                        // set to sizeof(GnssLocationInfo)
471     GnssLocationInfoFlagMask flags;     // bitwise OR of GnssLocationInfoBits for param validity
472     float altitudeMeanSeaLevel;         // altitude wrt mean sea level
473     float pdop;                         // position dilusion of precision
474     float hdop;                         // horizontal dilusion of precision
475     float vdop;                         // vertical dilusion of precision
476     float magneticDeviation;            // magnetic deviation
477     LocationReliability horReliability; // horizontal reliability
478     LocationReliability verReliability; // vertical reliability
479     float horUncEllipseSemiMajor;       // horizontal elliptical accuracy semi-major axis
480     float horUncEllipseSemiMinor;       // horizontal elliptical accuracy semi-minor axis
481     float horUncEllipseOrientAzimuth;   // horizontal elliptical accuracy azimuth
482 } GnssLocationInfoNotification;
483 
484 typedef struct {
485     size_t size;                           // set to sizeof(GnssNiNotification)
486     GnssNiType type;                       // type of NI (Voice, SUPL, Control Plane)
487     GnssNiOptionsMask options;             // bitwise OR of GnssNiOptionsBits
488     uint32_t timeout;                      // time (seconds) to wait for user input
489     GnssNiResponse timeoutResponse;        // the response that should be sent when timeout expires
490     char requestor[GNSS_NI_REQUESTOR_MAX]; // the requestor that is making the request
491     GnssNiEncodingType requestorEncoding;  // the encoding type for requestor
492     char message[GNSS_NI_MESSAGE_ID_MAX];  // the message to show user
493     GnssNiEncodingType messageEncoding;    // the encoding type for message
494     char extras[GNSS_NI_MESSAGE_ID_MAX];
495 } GnssNiNotification;
496 
497 typedef struct {
498     size_t size;       // set to sizeof(GnssSv)
499     uint16_t svId;     // Unique Identifier
500     GnssSvType type;   // type of SV (GPS, SBAS, GLONASS, QZSS, BEIDOU, GALILEO)
501     float cN0Dbhz;     // signal strength
502     float elevation;   // elevation of SV (in degrees)
503     float azimuth;     // azimuth of SV (in degrees)
504     GnssSvOptionsMask gnssSvOptionsMask; // Bitwise OR of GnssSvOptionsBits
505 } GnssSv;
506 
507 typedef struct {
508     size_t size;             // set to sizeof(GnssConfigSetAssistanceServer)
509     GnssAssistanceType type; // SUPL or C2K
510     const char* hostName;    // null terminated string
511     uint32_t port;           // port of server
512 } GnssConfigSetAssistanceServer;
513 
514 typedef struct {
515     size_t size;                               // set to sizeof(GnssMeasurementsData)
516     GnssMeasurementsDataFlagsMask flags;       // bitwise OR of GnssMeasurementsDataFlagsBits
517     int16_t svId;
518     GnssSvType svType;
519     double timeOffsetNs;
520     GnssMeasurementsStateMask stateMask;       // bitwise OR of GnssMeasurementsStateBits
521     int64_t receivedSvTimeNs;
522     int64_t receivedSvTimeUncertaintyNs;
523     double carrierToNoiseDbHz;
524     double pseudorangeRateMps;
525     double pseudorangeRateUncertaintyMps;
526     GnssMeasurementsAdrStateMask adrStateMask; // bitwise OR of GnssMeasurementsAdrStateBits
527     double adrMeters;
528     double adrUncertaintyMeters;
529     float carrierFrequencyHz;
530     int64_t carrierCycles;
531     double carrierPhase;
532     double carrierPhaseUncertainty;
533     GnssMeasurementsMultipathIndicator multipathIndicator;
534     double signalToNoiseRatioDb;
535     double agcLevelDb;
536 } GnssMeasurementsData;
537 
538 typedef struct {
539     size_t size;                          // set to sizeof(GnssMeasurementsClock)
540     GnssMeasurementsClockFlagsMask flags; // bitwise OR of GnssMeasurementsClockFlagsBits
541     int16_t leapSecond;
542     int64_t timeNs;
543     double timeUncertaintyNs;
544     int64_t fullBiasNs;
545     double biasNs;
546     double biasUncertaintyNs;
547     double driftNsps;
548     double driftUncertaintyNsps;
549     uint32_t hwClockDiscontinuityCount;
550 } GnssMeasurementsClock;
551 
552 typedef struct {
553     size_t size;                 // set to sizeof(GnssSvNotification)
554     size_t count;                // number of SVs in the GnssSv array
555     GnssSv gnssSvs[GNSS_SV_MAX]; // information on a number of SVs
556 } GnssSvNotification;
557 
558 typedef struct {
559     size_t size;         // set to sizeof(GnssNmeaNotification)
560     uint64_t timestamp;  // timestamp
561     const char* nmea;    // nmea text
562     size_t length;       // length of the nmea text
563 } GnssNmeaNotification;
564 
565 typedef struct {
566     size_t size;         // set to sizeof(GnssMeasurementsNotification)
567     size_t count;        // number of items in GnssMeasurements array
568     GnssMeasurementsData measurements[GNSS_MEASUREMENTS_MAX];
569     GnssMeasurementsClock clock; // clock
570 } GnssMeasurementsNotification;
571 
572 typedef struct {
573     size_t size;  // set to sizeof(GnssConfig)
574     GnssConfigFlagsMask flags; // bitwise OR of GnssConfigFlagsBits to mark which params are valid
575     GnssConfigGpsLock gpsLock;
576     GnssConfigSuplVersion suplVersion;
577     GnssConfigSetAssistanceServer assistanceServer;
578     GnssConfigLppProfile lppProfile;
579     GnssConfigLppeControlPlaneMask lppeControlPlaneMask;
580     GnssConfigLppeUserPlaneMask lppeUserPlaneMask;
581     GnssConfigAGlonassPositionProtocolMask aGlonassPositionProtocolMask;
582     GnssConfigEmergencyPdnForEmergencySupl emergencyPdnForEmergencySupl;
583     GnssConfigSuplEmergencyServices suplEmergencyServices;
584     GnssConfigSuplModeMask suplModeMask; //bitwise OR of GnssConfigSuplModeBits
585 } GnssConfig;
586 
587 typedef struct {
588     size_t size;                        // set to sizeof
589     bool                                mValid;
590     Location                            mLocation;
591     double                              verticalAccuracyMeters;
592     double                              speedAccuracyMetersPerSecond;
593     double                              bearingAccuracyDegrees;
594     timespec                            mUtcReported;
595 } GnssDebugLocation;
596 
597 typedef struct {
598     size_t size;                        // set to sizeof
599     bool                                mValid;
600     int64_t                             timeEstimate;
601     float                               timeUncertaintyNs;
602     float                               frequencyUncertaintyNsPerSec;
603 } GnssDebugTime;
604 
605 typedef struct {
606     size_t size;                        // set to sizeof
607     uint32_t                            svid;
608     GnssSvType                          constellation;
609     GnssEphemerisType                   mEphemerisType;
610     GnssEphemerisSource                 mEphemerisSource;
611     GnssEphemerisHealth                 mEphemerisHealth;
612     float                               ephemerisAgeSeconds;
613     bool                                serverPredictionIsAvailable;
614     float                               serverPredictionAgeSeconds;
615 } GnssDebugSatelliteInfo;
616 
617 typedef struct {
618     size_t size;                        // set to sizeof
619     GnssDebugLocation                   mLocation;
620     GnssDebugTime                       mTime;
621     std::vector<GnssDebugSatelliteInfo> mSatelliteInfo;
622 } GnssDebugReport;
623 
624 /* Provides the capabilities of the system
625    capabilities callback is called once soon after createInstance is called */
626 typedef std::function<void(
627     LocationCapabilitiesMask capabilitiesMask // bitwise OR of LocationCapabilitiesBits
628 )> capabilitiesCallback;
629 
630 /* Used by tracking, batching, and miscellanous APIs
631    responseCallback is called for every Tracking, Batching API, and Miscellanous API */
632 typedef std::function<void(
633     LocationError err, // if not SUCCESS, then id is not valid
634     uint32_t id        // id to be associated to the request
635 )> responseCallback;
636 
637 /* Used by APIs that gets more than one LocationError in it's response
638    collectiveResponseCallback is called for every geofence API call.
639    ids array and LocationError array are only valid until collectiveResponseCallback returns. */
640 typedef std::function<void(
641     size_t count, // number of locations in arrays
642     LocationError* errs, // array of LocationError associated to the request
643     uint32_t* ids // array of ids to be associated to the request
644 )> collectiveResponseCallback;
645 
646 /* Used for startTracking API, optional can be NULL
647    trackingCallback is called when delivering a location in a tracking session
648    broadcasted to all clients, no matter if a session has started by client */
649 typedef std::function<void(
650     Location location
651 )> trackingCallback;
652 
653 /* Used for startBatching API, optional can be NULL
654    batchingCallback is called when delivering locations in a batching session.
655    broadcasted to all clients, no matter if a session has started by client */
656 typedef std::function<void(
657     size_t count,      // number of locations in array
658     Location* location  // array of locations
659 )> batchingCallback;
660 
661 /* Gives GNSS Location information, optional can be NULL
662     gnssLocationInfoCallback is called only during a tracking session
663     broadcasted to all clients, no matter if a session has started by client */
664 typedef std::function<void(
665     GnssLocationInfoNotification gnssLocationInfoNotification
666 )> gnssLocationInfoCallback;
667 
668 /* Used for addGeofences API, optional can be NULL
669    geofenceBreachCallback is called when any number of geofences have a state change */
670 typedef std::function<void(
671     GeofenceBreachNotification geofenceBreachNotification
672 )> geofenceBreachCallback;
673 
674 /* Used for addGeofences API, optional can be NULL
675        geofenceStatusCallback is called when any number of geofences have a status change */
676 typedef std::function<void(
677     GeofenceStatusNotification geofenceStatusNotification
678 )> geofenceStatusCallback;
679 
680 /* Network Initiated request, optional can be NULL
681    This callback should be responded to by calling gnssNiResponse */
682 typedef std::function<void(
683     uint32_t id, // id that should be used to respond by calling gnssNiResponse
684     GnssNiNotification gnssNiNotification
685 )> gnssNiCallback;
686 
687 /* Gives GNSS SV information, optional can be NULL
688     gnssSvCallback is called only during a tracking session
689     broadcasted to all clients, no matter if a session has started by client */
690 typedef std::function<void(
691     GnssSvNotification gnssSvNotification
692 )> gnssSvCallback;
693 
694 /* Gives GNSS NMEA data, optional can be NULL
695     gnssNmeaCallback is called only during a tracking session
696     broadcasted to all clients, no matter if a session has started by client */
697 typedef std::function<void(
698     GnssNmeaNotification gnssNmeaNotification
699 )> gnssNmeaCallback;
700 
701 /* Gives GNSS Measurements information, optional can be NULL
702     gnssMeasurementsCallback is called only during a tracking session
703     broadcasted to all clients, no matter if a session has started by client */
704 typedef std::function<void(
705     GnssMeasurementsNotification gnssMeasurementsNotification
706 )> gnssMeasurementsCallback;
707 
708 typedef struct {
709     size_t size; // set to sizeof(LocationCallbacks)
710     capabilitiesCallback capabilitiesCb;             // mandatory
711     responseCallback responseCb;                     // mandatory
712     collectiveResponseCallback collectiveResponseCb; // mandatory
713     trackingCallback trackingCb;                     // optional
714     batchingCallback batchingCb;                     // optional
715     geofenceBreachCallback geofenceBreachCb;         // optional
716     geofenceStatusCallback geofenceStatusCb;         // optional
717     gnssLocationInfoCallback gnssLocationInfoCb;     // optional
718     gnssNiCallback gnssNiCb;                         // optional
719     gnssSvCallback gnssSvCb;                         // optional
720     gnssNmeaCallback gnssNmeaCb;                     // optional
721     gnssMeasurementsCallback gnssMeasurementsCb;     // optional
722 } LocationCallbacks;
723 
724 class LocationAPI
725 {
726 private:
727     LocationAPI();
728     ~LocationAPI();
729 
730 public:
731     /* creates an instance to LocationAPI object.
732        Will return NULL if mandatory parameters are invalid or if the maximum number
733        of instances have been reached */
734     static LocationAPI* createInstance(LocationCallbacks&);
735 
736     /* destroy/cleans up the instance, which should be called when LocationAPI object is
737        no longer needed. LocationAPI* returned from createInstance will no longer valid
738        after destroy is called */
739     void destroy();
740 
741     /* updates/changes the callbacks that will be called.
742         mandatory callbacks must be present for callbacks to be successfully updated
743         no return value */
744     void updateCallbacks(LocationCallbacks&);
745 
746     /* ================================== TRACKING ================================== */
747 
748     /* startTracking starts a tracking session, which returns a session id that will be
749        used by the other tracking APIs and also in the responseCallback to match command
750        with response. locations are reported on the trackingCallback passed in createInstance
751        periodically according to LocationOptions.
752         responseCallback returns:
753                 LOCATION_ERROR_SUCCESS if session was successfully started
754                 LOCATION_ERROR_ALREADY_STARTED if a startTracking session is already in progress
755                 LOCATION_ERROR_CALLBACK_MISSING if no trackingCallback was passed in createInstance
756                 LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameter is invalid */
757     uint32_t startTracking(LocationOptions&); // returns session id
758 
759     /* stopTracking stops a tracking session associated with id parameter.
760         responseCallback returns:
761                 LOCATION_ERROR_SUCCESS if successful
762                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */
763     void stopTracking(uint32_t id);
764 
765     /* updateTrackingOptions changes the LocationOptions of a tracking session associated with id
766         responseCallback returns:
767                 LOCATION_ERROR_SUCCESS if successful
768                 LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameters are invalid
769                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */
770     void updateTrackingOptions(uint32_t id, LocationOptions&);
771 
772     /* ================================== BATCHING ================================== */
773 
774     /* startBatching starts a batching session, which returns a session id that will be
775        used by the other batching APIs and also in the responseCallback to match command
776        with response. locations are reported on the batchingCallback passed in createInstance
777        periodically according to LocationOptions. A batching session starts tracking on
778        the low power processor and delivers them in batches by the batchingCallback when
779        the batch is full or when getBatchedLocations is called. This allows for the processor
780        that calls this API to sleep when the low power processor can batch locations in the
781        backgroup and wake up the processor calling the API only when the batch is full, thus
782        saving power
783         responseCallback returns:
784                 LOCATION_ERROR_SUCCESS if session was successful
785                 LOCATION_ERROR_ALREADY_STARTED if a startBatching session is already in progress
786                 LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback was passed in createInstance
787                 LOCATION_ERROR_INVALID_PARAMETER if a parameter is invalid
788                 LOCATION_ERROR_NOT_SUPPORTED if batching is not supported */
789     uint32_t startBatching(LocationOptions&); // returns session id
790 
791     /* stopBatching stops a batching session associated with id parameter.
792         responseCallback returns:
793                 LOCATION_ERROR_SUCCESS if successful
794                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with batching session */
795     void stopBatching(uint32_t id);
796 
797     /* updateBatchingOptions changes the LocationOptions of a batching session associated with id
798         responseCallback returns:
799                 LOCATION_ERROR_SUCCESS if successful
800                 LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameters are invalid
801                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */
802     void updateBatchingOptions(uint32_t id, LocationOptions&);
803 
804     /* getBatchedLocations gets a number of locations that are currently stored/batched
805        on the low power processor, delivered by the batchingCallback passed in createInstance.
806        Location are then deleted from the batch stored on the low power processor.
807         responseCallback returns:
808                 LOCATION_ERROR_SUCCESS if successful, will be followed by batchingCallback call
809                 LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback was passed in createInstance
810                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */
811     void getBatchedLocations(uint32_t id, size_t count);
812 
813     /* ================================== GEOFENCE ================================== */
814 
815     /* addGeofences adds any number of geofences and returns an array of geofence ids that
816        will be used by the other geofence APIs and also in the collectiveResponseCallback to
817        match command with response. The geofenceBreachCallback will deliver the status of each
818        geofence according to the GeofenceOption for each. The geofence id array returned will
819        be valid until the collectiveResponseCallback is called and has returned.
820         collectiveResponseCallback returns:
821                 LOCATION_ERROR_SUCCESS if session was successful
822                 LOCATION_ERROR_CALLBACK_MISSING if no geofenceBreachCallback
823                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
824                 LOCATION_ERROR_NOT_SUPPORTED if geofence is not supported */
825     uint32_t* addGeofences(size_t count, GeofenceOption*, GeofenceInfo*); // returns id array
826 
827     /* removeGeofences removes any number of geofences. Caller should delete ids array after
828        removeGeofences returneds.
829         collectiveResponseCallback returns:
830                 LOCATION_ERROR_SUCCESS if successful
831                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */
832     void removeGeofences(size_t count, uint32_t* ids);
833 
834     /* modifyGeofences modifies any number of geofences. Caller should delete ids array after
835        modifyGeofences returns.
836         collectiveResponseCallback returns:
837                 LOCATION_ERROR_SUCCESS if successful
838                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session
839                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid */
840     void modifyGeofences(size_t count, uint32_t* ids, GeofenceOption* options);
841 
842     /* pauseGeofences pauses any number of geofences, which is similar to removeGeofences,
843        only that they can be resumed at any time. Caller should delete ids array after
844        pauseGeofences returns.
845         collectiveResponseCallback returns:
846                 LOCATION_ERROR_SUCCESS if successful
847                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */
848     void pauseGeofences(size_t count, uint32_t* ids);
849 
850     /* resumeGeofences resumes any number of geofences that are currently paused. Caller should
851        delete ids array after resumeGeofences returns.
852         collectiveResponseCallback returns:
853                 LOCATION_ERROR_SUCCESS if successful
854                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */
855     void resumeGeofences(size_t count, uint32_t* ids);
856 
857     /* ================================== GNSS ====================================== */
858 
859      /* gnssNiResponse is called in response to a gnssNiCallback.
860         responseCallback returns:
861                 LOCATION_ERROR_SUCCESS if session was successful
862                 LOCATION_ERROR_INVALID_PARAMETER if any parameters in GnssNiResponse are invalid
863                 LOCATION_ERROR_ID_UNKNOWN if id does not match a gnssNiCallback */
864     void gnssNiResponse(uint32_t id, GnssNiResponse response);
865 };
866 
867 typedef struct {
868     size_t size; // set to sizeof(LocationControlCallbacks)
869     responseCallback responseCb;                     // mandatory
870     collectiveResponseCallback collectiveResponseCb; // mandatory
871 } LocationControlCallbacks;
872 
873 class LocationControlAPI
874 {
875 private:
876     LocationControlAPI();
877     ~LocationControlAPI();
878 
879 public:
880     /* creates an instance to LocationControlAPI object.
881        Will return NULL if mandatory parameters are invalid or if the maximum number
882        of instances have been reached. Only once instance allowed */
883     static LocationControlAPI* createInstance(LocationControlCallbacks&);
884 
885     /* destroy/cleans up the instance, which should be called when LocationControlAPI object is
886        no longer needed. LocationControlAPI* returned from createInstance will no longer valid
887        after destroy is called */
888     void destroy();
889 
890     /* enable will enable specific location technology to be used for calculation locations and
891        will effectively start a control session if call is successful, which returns a session id
892        that will be returned in responseCallback to match command with response. The session id is
893        also needed to call the disable command.
894        This effect is global for all clients of LocationAPI
895         responseCallback returns:
896                 LOCATION_ERROR_SUCCESS if successful
897                 LOCATION_ERROR_ALREADY_STARTED if an enable was already called for this techType
898                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
899                 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */
900     uint32_t enable(LocationTechnologyType techType);
901 
902     /* disable will disable specific location technology to be used for calculation locations and
903        effectively ends the control session if call is successful.
904        id parameter is the session id that was returned in enable responseCallback for techType.
905        The session id is no longer valid after disable's responseCallback returns success.
906        This effect is global for all clients of LocationAPI
907         responseCallback returns:
908                 LOCATION_ERROR_SUCCESS if successful
909                 LOCATION_ERROR_ID_UNKNOWN if id was not returned from responseCallback from enable
910                 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */
911     void disable(uint32_t id);
912 
913     /* gnssUpdateConfig updates the gnss specific configuration, which returns a session id array
914        with an id for each of the bits set in GnssConfig.flags, order from low bits to high bits.
915        The response for each config that is set will be returned in collectiveResponseCallback.
916        The session id array returned will be valid until the collectiveResponseCallback is called
917        and has returned. This effect is global for all clients of LocationAPI
918         collectiveResponseCallback returns:
919                 LOCATION_ERROR_SUCCESS if session was successful
920                 LOCATION_ERROR_INVALID_PARAMETER if any other parameters are invalid
921                 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */
922     uint32_t* gnssUpdateConfig(GnssConfig config);
923 
924     /* delete specific gnss aiding data for testing, which returns a session id
925        that will be returned in responseCallback to match command with response.
926        Only allowed in userdebug builds. This effect is global for all clients of LocationAPI
927         responseCallback returns:
928                 LOCATION_ERROR_SUCCESS if successful
929                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
930                 LOCATION_ERROR_NOT_SUPPORTED if build is not userdebug */
931     uint32_t gnssDeleteAidingData(GnssAidingData& data);
932 };
933 
934 #endif /* LOCATION_H */
935