1 /* Copyright (c) 2017-2020 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 LOCATIONAPI_H 30 #define LOCATIONAPI_H 31 32 #include "ILocationAPI.h" 33 34 class LocationAPI : public ILocationAPI 35 { 36 private: 37 LocationAPI(); 38 ~LocationAPI(); 39 40 public: 41 /* creates an instance to LocationAPI object. 42 Will return NULL if mandatory parameters are invalid or if the maximum number 43 of instances have been reached */ 44 static LocationAPI* createInstance(LocationCallbacks&); 45 46 /* destroy/cleans up the instance, which should be called when LocationControlAPI object is 47 no longer needed. LocationControlAPI* returned from createInstance will no longer valid 48 after destroy is called. 49 If the caller allocates the memory for LocationControlCallbacks used in 50 LocationControlAPI::createInstance, then the caller must ensure that the memory still remains 51 valid until destroyCompleteCb is invoked. 52 */ 53 void destroy(locationApiDestroyCompleteCallback destroyCompleteCb=nullptr); 54 55 void onRemoveClientCompleteCb (LocationAdapterTypeMask adapterType); 56 57 /* updates/changes the callbacks that will be called. 58 mandatory callbacks must be present for callbacks to be successfully updated 59 no return value */ 60 virtual void updateCallbacks(LocationCallbacks&) override; 61 62 /* ================================== TRACKING ================================== */ 63 64 /* startTracking starts a tracking session, which returns a session id that will be 65 used by the other tracking APIs and also in the responseCallback to match command 66 with response. locations are reported on the trackingCallback passed in createInstance 67 periodically according to LocationOptions. 68 responseCallback returns: 69 LOCATION_ERROR_SUCCESS if session was successfully started 70 LOCATION_ERROR_ALREADY_STARTED if a startTracking session is already in progress 71 LOCATION_ERROR_CALLBACK_MISSING if no trackingCallback was passed in createInstance 72 LOCATION_ERROR_INVALID_PARAMETER if TrackingOptions parameter is invalid */ 73 virtual uint32_t startTracking(TrackingOptions&) override; 74 75 /* stopTracking stops a tracking session associated with id parameter. 76 responseCallback returns: 77 LOCATION_ERROR_SUCCESS if successful 78 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */ 79 virtual void stopTracking(uint32_t id) override; 80 81 /* updateTrackingOptions changes the TrackingOptions of a tracking session associated with id 82 responseCallback returns: 83 LOCATION_ERROR_SUCCESS if successful 84 LOCATION_ERROR_INVALID_PARAMETER if TrackingOptions parameters are invalid 85 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */ 86 virtual void updateTrackingOptions(uint32_t id, TrackingOptions&) override; 87 88 /* ================================== BATCHING ================================== */ 89 90 /* startBatching starts a batching session, which returns a session id that will be 91 used by the other batching APIs and also in the responseCallback to match command 92 with response. locations are reported on the batchingCallback passed in createInstance 93 periodically according to LocationOptions. A batching session starts tracking on 94 the low power processor and delivers them in batches by the batchingCallback when 95 the batch is full or when getBatchedLocations is called. This allows for the processor 96 that calls this API to sleep when the low power processor can batch locations in the 97 backgroup and wake up the processor calling the API only when the batch is full, thus 98 saving power 99 responseCallback returns: 100 LOCATION_ERROR_SUCCESS if session was successful 101 LOCATION_ERROR_ALREADY_STARTED if a startBatching session is already in progress 102 LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback was passed in createInstance 103 LOCATION_ERROR_INVALID_PARAMETER if a parameter is invalid 104 LOCATION_ERROR_NOT_SUPPORTED if batching is not supported */ 105 virtual uint32_t startBatching(BatchingOptions&) override; 106 107 /* stopBatching stops a batching session associated with id parameter. 108 responseCallback returns: 109 LOCATION_ERROR_SUCCESS if successful 110 LOCATION_ERROR_ID_UNKNOWN if id is not associated with batching session */ 111 virtual void stopBatching(uint32_t id) override; 112 113 /* updateBatchingOptions changes the BatchingOptions of a batching session associated with id 114 responseCallback returns: 115 LOCATION_ERROR_SUCCESS if successful 116 LOCATION_ERROR_INVALID_PARAMETER if BatchingOptions parameters are invalid 117 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */ 118 virtual void updateBatchingOptions(uint32_t id, BatchingOptions&) override; 119 120 /* getBatchedLocations gets a number of locations that are currently stored/batched 121 on the low power processor, delivered by the batchingCallback passed in createInstance. 122 Location are then deleted from the batch stored on the low power processor. 123 responseCallback returns: 124 LOCATION_ERROR_SUCCESS if successful, will be followed by batchingCallback call 125 LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback was passed in createInstance 126 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */ 127 virtual void getBatchedLocations(uint32_t id, size_t count) override; 128 129 /* ================================== GEOFENCE ================================== */ 130 131 /* addGeofences adds any number of geofences and returns an array of geofence ids that 132 will be used by the other geofence APIs and also in the collectiveResponseCallback to 133 match command with response. The geofenceBreachCallback will deliver the status of each 134 geofence according to the GeofenceOption for each. The geofence id array returned will 135 be valid until the collectiveResponseCallback is called and has returned. 136 collectiveResponseCallback returns: 137 LOCATION_ERROR_SUCCESS if session was successful 138 LOCATION_ERROR_CALLBACK_MISSING if no geofenceBreachCallback 139 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 140 LOCATION_ERROR_NOT_SUPPORTED if geofence is not supported */ 141 virtual uint32_t* addGeofences(size_t count, GeofenceOption*, GeofenceInfo*) override; 142 143 /* removeGeofences removes any number of geofences. Caller should delete ids array after 144 removeGeofences returneds. 145 collectiveResponseCallback returns: 146 LOCATION_ERROR_SUCCESS if successful 147 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */ 148 virtual void removeGeofences(size_t count, uint32_t* ids) override; 149 150 /* modifyGeofences modifies any number of geofences. Caller should delete ids array after 151 modifyGeofences returns. 152 collectiveResponseCallback returns: 153 LOCATION_ERROR_SUCCESS if successful 154 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session 155 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid */ 156 virtual void modifyGeofences(size_t count, uint32_t* ids, GeofenceOption* options) override; 157 158 /* pauseGeofences pauses any number of geofences, which is similar to removeGeofences, 159 only that they can be resumed at any time. Caller should delete ids array after 160 pauseGeofences returns. 161 collectiveResponseCallback returns: 162 LOCATION_ERROR_SUCCESS if successful 163 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */ 164 virtual void pauseGeofences(size_t count, uint32_t* ids) override; 165 166 /* resumeGeofences resumes any number of geofences that are currently paused. Caller should 167 delete ids array after resumeGeofences returns. 168 collectiveResponseCallback returns: 169 LOCATION_ERROR_SUCCESS if successful 170 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */ 171 virtual void resumeGeofences(size_t count, uint32_t* ids) override; 172 173 /* ================================== GNSS ====================================== */ 174 175 /* gnssNiResponse is called in response to a gnssNiCallback. 176 responseCallback returns: 177 LOCATION_ERROR_SUCCESS if session was successful 178 LOCATION_ERROR_INVALID_PARAMETER if any parameters in GnssNiResponse are invalid 179 LOCATION_ERROR_ID_UNKNOWN if id does not match a gnssNiCallback */ 180 virtual void gnssNiResponse(uint32_t id, GnssNiResponse response) override; 181 182 /* ================================== NETWORK PROVIDER =========================== */ 183 184 /* enableNetworkProvider enables Network Provider */ 185 virtual void enableNetworkProvider(); 186 187 /* disableNetworkProvider disables Network Provider */ 188 virtual void disableNetworkProvider(); 189 190 /* startNetworkLocation start a single shot network location request */ 191 virtual void startNetworkLocation(trackingCallback* callback); 192 193 /* stopNetworkLocation stop any ongoing network location request */ 194 virtual void stopNetworkLocation(trackingCallback* callback); 195 }; 196 197 typedef struct { 198 size_t size; // set to sizeof(LocationControlCallbacks) 199 responseCallback responseCb; // mandatory 200 collectiveResponseCallback collectiveResponseCb; // mandatory 201 gnssConfigCallback gnssConfigCb; // optional 202 } LocationControlCallbacks; 203 204 class LocationControlAPI : public ILocationControlAPI 205 { 206 private: 207 LocationControlAPI(); 208 ~LocationControlAPI(); 209 210 public: 211 /* creates an instance to LocationControlAPI object. 212 Will return NULL if mandatory parameters are invalid or if the maximum number 213 of instances have been reached. Only once instance allowed */ 214 static LocationControlAPI* createInstance(LocationControlCallbacks&); 215 216 /* destroy/cleans up the instance, which should be called when LocationControlAPI object is 217 no longer needed. LocationControlAPI* returned from createInstance will no longer valid 218 after destroy is called */ 219 void destroy(); 220 221 /* enable will enable specific location technology to be used for calculation locations and 222 will effectively start a control session if call is successful, which returns a session id 223 that will be returned in responseCallback to match command with response. The session id is 224 also needed to call the disable command. 225 This effect is global for all clients of LocationAPI 226 responseCallback returns: 227 LOCATION_ERROR_SUCCESS if successful 228 LOCATION_ERROR_ALREADY_STARTED if an enable was already called for this techType 229 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 230 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */ 231 uint32_t enable(LocationTechnologyType techType); 232 233 /* disable will disable specific location technology to be used for calculation locations and 234 effectively ends the control session if call is successful. 235 id parameter is the session id that was returned in enable responseCallback for techType. 236 The session id is no longer valid after disable's responseCallback returns success. 237 This effect is global for all clients of LocationAPI 238 responseCallback returns: 239 LOCATION_ERROR_SUCCESS if successful 240 LOCATION_ERROR_ID_UNKNOWN if id was not returned from responseCallback from enable 241 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */ 242 void disable(uint32_t id); 243 244 /* gnssUpdateConfig updates the gnss specific configuration, which returns a session id array 245 with an id for each of the bits set in GnssConfig.flags, order from low bits to high bits. 246 The response for each config that is set will be returned in collectiveResponseCallback. 247 The session id array returned will be valid until the collectiveResponseCallback is called 248 and has returned. This effect is global for all clients of LocationAPI 249 collectiveResponseCallback returns: 250 LOCATION_ERROR_SUCCESS if session was successful 251 LOCATION_ERROR_INVALID_PARAMETER if any other parameters are invalid 252 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason 253 254 PLEASE NOTE: It is caller's resposibility to FREE the memory of the return value. 255 The memory must be freed by delete [].*/ 256 virtual uint32_t* gnssUpdateConfig(const GnssConfig& config) override; 257 258 /* gnssGetConfig fetches the current constellation and SV configuration 259 on the GNSS engine. 260 Returns a session id array with an id for each of the bits set in 261 the mask parameter, order from low bits to high bits. 262 Response is sent via the registered gnssConfigCallback. 263 This effect is global for all clients of LocationAPI 264 collectiveResponseCallback returns: 265 LOCATION_ERROR_SUCCESS if session was successful 266 LOCATION_ERROR_INVALID_PARAMETER if any parameter is invalid 267 LOCATION_ERROR_CALLBACK_MISSING If no gnssConfigCallback 268 was passed in createInstance 269 LOCATION_ERROR_NOT_SUPPORTED If read of requested configuration 270 is not supported 271 272 PLEASE NOTE: It is caller's resposibility to FREE the memory of the return value. 273 The memory must be freed by delete [].*/ 274 uint32_t* gnssGetConfig(GnssConfigFlagsMask mask); 275 276 /* delete specific gnss aiding data for testing, which returns a session id 277 that will be returned in responseCallback to match command with response. 278 Only allowed in userdebug builds. This effect is global for all clients of LocationAPI 279 responseCallback returns: 280 LOCATION_ERROR_SUCCESS if successful 281 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 282 LOCATION_ERROR_NOT_SUPPORTED if build is not userdebug */ 283 virtual uint32_t gnssDeleteAidingData(GnssAidingData& data) override; 284 285 /** @brief 286 Configure the constellation and SVs to be used by the GNSS engine on 287 modem. 288 289 @param 290 constellationEnablementConfig: configuration to enable/disable SV 291 constellation to be used by SPE engine. When size in 292 constellationEnablementConfig is set to 0, this indicates to reset SV 293 constellation configuration to modem NV default. 294 295 blacklistSvConfig: configuration to blacklist or unblacklist SVs 296 used by SPE engine 297 298 @return 299 A session id that will be returned in responseCallback to 300 match command with response. This effect is global for all 301 clients of LocationAPI responseCallback returns: 302 LOCATION_ERROR_SUCCESS if successful 303 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 304 */ 305 virtual uint32_t configConstellations( 306 const GnssSvTypeConfig& constellationEnablementConfig, 307 const GnssSvIdConfig& blacklistSvConfig) override; 308 309 /** @brief 310 Configure the secondary band of constellations to be used by 311 the GNSS engine on modem. 312 313 @param 314 secondaryBandConfig: configuration the secondary band usage 315 for SPE engine 316 317 @return 318 A session id that will be returned in responseCallback to 319 match command with response. This effect is global for all 320 clients of LocationAPI responseCallback returns: 321 LOCATION_ERROR_SUCCESS if successful 322 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 323 */ 324 virtual uint32_t configConstellationSecondaryBand( 325 const GnssSvTypeConfig& secondaryBandConfig) override; 326 327 /** @brief 328 Enable or disable the constrained time uncertainty feature. 329 330 @param 331 enable: true to enable the constrained time uncertainty 332 feature and false to disable the constrainted time 333 uncertainty feature. 334 335 @param 336 tuncThreshold: this specifies the time uncertainty threshold 337 that gps engine need to maintain, in units of milli-seconds. 338 Default is 0.0 meaning that modem default value of time 339 uncertainty threshold will be used. This parameter is 340 ignored when requesting to disable this feature. 341 342 @param 343 energyBudget: this specifies the power budget that gps 344 engine is allowed to spend to maintain the time uncertainty. 345 Default is 0 meaning that GPS engine is not constained by 346 power budget and can spend as much power as needed. The 347 parameter need to be specified in units of 0.1 milli watt 348 second. This parameter is ignored requesting to disable this 349 feature. 350 351 @return 352 A session id that will be returned in responseCallback to 353 match command with response. This effect is global for all 354 clients of LocationAPI responseCallback returns: 355 LOCATION_ERROR_SUCCESS if successful 356 LOCATION_ERROR_INVALID_PARAMETER if any parameters 357 are invalid 358 */ 359 virtual uint32_t configConstrainedTimeUncertainty( 360 bool enable, float tuncThreshold = 0.0, 361 uint32_t energyBudget = 0) override; 362 363 /** @brief 364 Enable or disable position assisted clock estimator feature. 365 366 @param 367 enable: true to enable position assisted clock estimator and 368 false to disable the position assisted clock estimator 369 feature. 370 371 @return 372 A session id that will be returned in responseCallback to 373 match command with response. This effect is global for all 374 clients of LocationAPI responseCallback returns: 375 LOCATION_ERROR_SUCCESS if successful 376 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 377 */ 378 virtual uint32_t configPositionAssistedClockEstimator(bool enable) override; 379 380 /** @brief 381 Sets the lever arm parameters for the vehicle. 382 383 @param 384 configInfo: lever arm configuration info regarding below two 385 types of lever arm info: 386 a: GNSS Antenna w.r.t the origin at the IMU e.g.: inertial 387 measurement unit. 388 b: lever arm parameters regarding the OPF (output frame) 389 w.r.t the origin (at the GPS Antenna). Vehicle manufacturers 390 prefer the position output to be tied to a specific point in 391 the vehicle rather than where the antenna is placed 392 (midpoint of the rear axle is typical). 393 394 Caller can choose types of lever arm info to configure via the 395 leverMarkTypeMask. 396 397 @return 398 A session id that will be returned in responseCallback to 399 match command with response. This effect is global for all 400 clients of LocationAPI responseCallback returns: 401 LOCATION_ERROR_SUCCESS if successful 402 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 403 */ 404 virtual uint32_t configLeverArm(const LeverArmConfigInfo& configInfo) override; 405 406 /** @brief 407 Configure the robust location setting. 408 409 @param 410 enable: true to enable robust location and false to disable 411 robust location. 412 413 @param 414 enableForE911: true to enable robust location when device is 415 on E911 session and false to disable on E911 session. 416 This parameter is only valid if robust location is enabled. 417 418 @return 419 A session id that will be returned in responseCallback to 420 match command with response. This effect is global for all 421 clients of LocationAPI responseCallback returns: 422 LOCATION_ERROR_SUCCESS if successful 423 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 424 */ 425 virtual uint32_t configRobustLocation(bool enable, bool enableForE911) override; 426 427 /** @brief 428 Config the minimal GPS week used by modem GNSS engine. 429 430 @param 431 minGpsWeek: minimal GPS week to be used by modem GNSS engine. 432 433 @return 434 A session id that will be returned in responseCallback to 435 match command with response. This effect is global for all 436 clients of LocationAPI responseCallback returns: 437 LOCATION_ERROR_SUCCESS if successful 438 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 439 */ 440 virtual uint32_t configMinGpsWeek(uint16_t minGpsWeek) override; 441 442 /** @brief 443 Configure the vehicle body-to-Sensor mount parameters and 444 other parameters for dead reckoning position engine. 445 446 @param 447 dreConfig: vehicle body-to-Sensor mount angles and other 448 parameters. 449 450 @return 451 A session id that will be returned in responseCallback to 452 match command with response. This effect is global for all 453 clients of LocationAPI responseCallback returns: 454 LOCATION_ERROR_SUCCESS if successful 455 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 456 */ 457 virtual uint32_t configDeadReckoningEngineParams( 458 const DeadReckoningEngineConfig& dreConfig) override; 459 460 /** @brief 461 This API is used to instruct the specified engine to be in 462 the pause/resume state. <br/> 463 464 When the engine is placed in paused state, the engine will 465 stop. If there is an on-going session, engine will no longer 466 produce fixes. In the paused state, calling API to delete 467 aiding data from the paused engine may not have effect. 468 Request to delete Aiding data shall be issued after 469 engine resume. <br/> 470 471 Currently, only DRE engine will support pause/resume 472 request. responseCb() will return not supported when request 473 is made to pause/resume none-DRE engine. <br/> 474 475 Request to pause/resume DRE engine can be made with or 476 without an on-going session. With QDR engine, on resume, GNSS 477 position & heading re-acquisition is needed for DR engine to 478 engage. If DR engine is already in the requested state, the 479 request will be no-op. <br/> 480 481 @param 482 engType: the engine that is instructed to change its run 483 state. <br/> 484 485 engState: the new engine run state that the engine is 486 instructed to be in. <br/> 487 488 @return 489 A session id that will be returned in responseCallback to 490 match command with response. This effect is global for all 491 clients of LocationAPI responseCallback returns: 492 LOCATION_ERROR_SUCCESS if successful 493 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 494 */ 495 virtual uint32_t configEngineRunState(PositioningEngineMask engType, 496 LocEngineRunState engState) override; 497 498 /** @brief 499 Set the EULA opt-in status from system user. This is used as consent to 500 use network-based positioning. 501 502 @param 503 userConsnt: user agrees to use GTP service or not. 504 505 @return 506 A session id that will be returned in responseCallback to 507 match command with response. 508 */ 509 virtual uint32_t setOptInStatus(bool userConsent); 510 }; 511 512 #endif /* LOCATIONAPI_H */ 513