diff options
Diffstat (limited to 'gps/location/ILocationAPI.h')
| -rw-r--r-- | gps/location/ILocationAPI.h | 406 |
1 files changed, 406 insertions, 0 deletions
diff --git a/gps/location/ILocationAPI.h b/gps/location/ILocationAPI.h new file mode 100644 index 0000000..29846ac --- /dev/null +++ b/gps/location/ILocationAPI.h @@ -0,0 +1,406 @@ +/* Copyright (c) 2018-2020 The Linux Foundation. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * * Neither the name of The Linux Foundation nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS + * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN + * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef ILOCATIONAPI_H +#define ILOCATIONAPI_H + +#include "LocationDataTypes.h" + +class ILocationAPI +{ +public: + virtual ~ILocationAPI(){}; + + /** @brief Updates/changes the callbacks that will be called. + mandatory callbacks must be present for callbacks to be successfully updated + no return value */ + virtual void updateCallbacks(LocationCallbacks&) = 0; + + /* ================================== TRACKING ================================== */ + + /** @brief Starts a tracking session, which returns a session id that will be + used by the other tracking APIs and also in the responseCallback to match command + with response. locations are reported on the registered trackingCallback + periodically according to LocationOptions. + @return session id + responseCallback returns: + LOCATION_ERROR_SUCCESS if session was successfully started + LOCATION_ERROR_ALREADY_STARTED if a startTracking session is already in progress + LOCATION_ERROR_CALLBACK_MISSING if no trackingCallback was passed + LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameter is invalid */ + virtual uint32_t startTracking(TrackingOptions&) = 0; + + /** @brief Stops a tracking session associated with id parameter. + responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */ + virtual void stopTracking(uint32_t id) = 0; + + /** @brief Changes the LocationOptions of a tracking session associated with id. + responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameters are invalid + LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */ + virtual void updateTrackingOptions(uint32_t id, TrackingOptions&) = 0; + + /* ================================== BATCHING ================================== */ + + /** @brief starts a batching session, which returns a session id that will be + used by the other batching APIs and also in the responseCallback to match command + with response. locations are reported on the batchingCallback passed in createInstance + periodically according to LocationOptions. A batching session starts tracking on + the low power processor and delivers them in batches by the batchingCallback when + the batch is full or when getBatchedLocations is called. This allows for the processor + that calls this API to sleep when the low power processor can batch locations in the + backgroup and wake up the processor calling the API only when the batch is full, thus + saving power. + @return session id + responseCallback returns: + LOCATION_ERROR_SUCCESS if session was successful + LOCATION_ERROR_ALREADY_STARTED if a startBatching session is already in progress + LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback + LOCATION_ERROR_INVALID_PARAMETER if a parameter is invalid + LOCATION_ERROR_NOT_SUPPORTED if batching is not supported */ + virtual uint32_t startBatching(BatchingOptions&) = 0; + + /** @brief Stops a batching session associated with id parameter. + responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_ID_UNKNOWN if id is not associated with batching session */ + virtual void stopBatching(uint32_t id) = 0; + + /** @brief Changes the LocationOptions of a batching session associated with id. + responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameters are invalid + LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */ + virtual void updateBatchingOptions(uint32_t id, BatchingOptions&) = 0; + + /** @brief Gets a number of locations that are currently stored/batched + on the low power processor, delivered by the batchingCallback passed in createInstance. + Location are then deleted from the batch stored on the low power processor. + responseCallback returns: + LOCATION_ERROR_SUCCESS if successful, will be followed by batchingCallback call + LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback + LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */ + virtual void getBatchedLocations(uint32_t id, size_t count) = 0; + + /* ================================== GEOFENCE ================================== */ + + /** @brief Adds any number of geofences and returns an array of geofence ids that + will be used by the other geofence APIs and also in the collectiveResponseCallback to + match command with response. The geofenceBreachCallback will deliver the status of each + geofence according to the GeofenceOption for each. The geofence id array returned will + be valid until the collectiveResponseCallback is called and has returned. + @return id array + collectiveResponseCallback returns: + LOCATION_ERROR_SUCCESS if session was successful + LOCATION_ERROR_CALLBACK_MISSING if no geofenceBreachCallback + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + LOCATION_ERROR_NOT_SUPPORTED if geofence is not supported */ + virtual uint32_t* addGeofences(size_t count, GeofenceOption*, GeofenceInfo*) = 0; + + /** @brief Removes any number of geofences. Caller should delete ids array after + removeGeofences returneds. + collectiveResponseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */ + virtual void removeGeofences(size_t count, uint32_t* ids) = 0; + + /** @brief Modifies any number of geofences. Caller should delete ids array after + modifyGeofences returns. + collectiveResponseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid */ + virtual void modifyGeofences(size_t count, uint32_t* ids, GeofenceOption* options) = 0; + + /** @brief Pauses any number of geofences, which is similar to removeGeofences, + only that they can be resumed at any time. Caller should delete ids array after + pauseGeofences returns. + collectiveResponseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */ + virtual void pauseGeofences(size_t count, uint32_t* ids) = 0; + + /** @brief Resumes any number of geofences that are currently paused. Caller should + delete ids array after resumeGeofences returns. + collectiveResponseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */ + virtual void resumeGeofences(size_t count, uint32_t* ids) = 0; + + /* ================================== GNSS ====================================== */ + + /** @brief gnssNiResponse is called in response to a gnssNiCallback. + responseCallback returns: + LOCATION_ERROR_SUCCESS if session was successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters in GnssNiResponse are invalid + LOCATION_ERROR_ID_UNKNOWN if id does not match a gnssNiCallback */ + virtual void gnssNiResponse(uint32_t id, GnssNiResponse response) = 0; +}; + +class ILocationControlAPI +{ +public: + virtual ~ILocationControlAPI(){}; + + /** @brief Updates the gnss specific configuration, which returns a session id array + with an id for each of the bits set in GnssConfig.flags, order from low bits to high bits. + The response for each config that is set will be returned in collectiveResponseCallback. + The session id array returned will be valid until the collectiveResponseCallback is called + and has returned. This effect is global for all clients of ILocationAPI. + collectiveResponseCallback returns: + LOCATION_ERROR_SUCCESS if session was successful + LOCATION_ERROR_INVALID_PARAMETER if any other parameters are invalid + LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */ + virtual uint32_t* gnssUpdateConfig(const GnssConfig& config) = 0; + + /** @brief Delete specific gnss aiding data for testing, which returns a session id + that will be returned in responseCallback to match command with response. + Only allowed in userdebug builds. This effect is global for all clients of ILocationAPI. + responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + LOCATION_ERROR_NOT_SUPPORTED if build is not userdebug */ + virtual uint32_t gnssDeleteAidingData(GnssAidingData& data) = 0; + + /** @brief + Configure the constellation and SVs to be used by the GNSS engine on + modem. + + @param + constellationEnablementConfig: configuration to enable/disable SV + constellation to be used by SPE engine. When size in + constellationEnablementConfig is set to 0, this indicates to reset SV + constellation configuration to modem NV default. + + blacklistSvConfig: configuration to blacklist or unblacklist SVs + used by SPE engine + + @return + A session id that will be returned in responseCallback to + match command with response. This effect is global for all + clients of LocationAPI responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + */ + virtual uint32_t configConstellations( + const GnssSvTypeConfig& constellationEnablementConfig, + const GnssSvIdConfig& blacklistSvConfig) = 0; + + /** @brief + Configure the secondary band of constellations to be used by + the GNSS engine on modem. + + @param + secondaryBandConfig: configuration the secondary band usage + for SPE engine + + @return + A session id that will be returned in responseCallback to + match command with response. This effect is global for all + clients of LocationAPI responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + */ + virtual uint32_t configConstellationSecondaryBand( + const GnssSvTypeConfig& secondaryBandConfig) = 0; + + /** @brief + Enable or disable the constrained time uncertainty feature. + + @param + enable: true to enable the constrained time uncertainty + feature and false to disable the constrainted time + uncertainty feature. + + @param + tuncThreshold: this specifies the time uncertainty threshold + that gps engine need to maintain, in units of milli-seconds. + Default is 0.0 meaning that modem default value of time + uncertainty threshold will be used. This parameter is + ignored when requesting to disable this feature. + + @param + energyBudget: this specifies the power budget that gps + engine is allowed to spend to maintain the time uncertainty. + Default is 0 meaning that GPS engine is not constained by + power budget and can spend as much power as needed. The + parameter need to be specified in units of 0.1 milli watt + second. This parameter is ignored requesting to disable this + feature. + + @return + A session id that will be returned in responseCallback to + match command with response. This effect is global for all + clients of LocationAPI responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters + are invalid + */ + virtual uint32_t configConstrainedTimeUncertainty( + bool enable, float tuncThreshold = 0.0, + uint32_t energyBudget = 0) = 0; + + /** @brief + Enable or disable position assisted clock estimator feature. + + @param + enable: true to enable position assisted clock estimator and + false to disable the position assisted clock estimator + feature. + + @return + A session id that will be returned in responseCallback to + match command with response. This effect is global for all + clients of LocationAPI responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + */ + virtual uint32_t configPositionAssistedClockEstimator(bool enable) = 0; + + /** @brief + Sets the lever arm parameters for the vehicle. + + @param + configInfo: lever arm configuration info regarding below two + types of lever arm info: + a: GNSS Antenna w.r.t the origin at the IMU e.g.: inertial + measurement unit. + b: lever arm parameters regarding the OPF (output frame) + w.r.t the origin (at the GPS Antenna). Vehicle manufacturers + prefer the position output to be tied to a specific point in + the vehicle rather than where the antenna is placed + (midpoint of the rear axle is typical). + + Caller can choose types of lever arm info to configure via the + leverMarkTypeMask. + + @return + A session id that will be returned in responseCallback to + match command with response. This effect is global for all + clients of LocationAPI responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + */ + virtual uint32_t configLeverArm(const LeverArmConfigInfo& configInfo) = 0; + + /** @brief + Configure the robust location setting. + + @param + enable: true to enable robust location and false to disable + robust location. + + @param + enableForE911: true to enable robust location when device is on + E911 session and false to disable on E911 session. + This parameter is only valid if robust location is enabled. + + @return + A session id that will be returned in responseCallback to + match command with response. This effect is global for all + clients of LocationAPI responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + */ + virtual uint32_t configRobustLocation(bool enable, bool enableForE911) = 0; + + /** @brief + Config the minimum GPS week used by modem GNSS engine. + + @param + minGpsWeek: minimum GPS week to be used by modem GNSS engine. + + @return + A session id that will be returned in responseCallback to + match command with response. This effect is global for all + clients of LocationAPI responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + */ + virtual uint32_t configMinGpsWeek(uint16_t minGpsWeek) = 0; + + /** @brief + Configure the vehicle body-to-Sensor mount parameters and + other parameters for dead reckoning position engine. + + @param + dreConfig: vehicle body-to-Sensor mount angles and other + parameters. + + @return + A session id that will be returned in responseCallback to + match command with response. This effect is global for all + clients of LocationAPI responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + */ + virtual uint32_t configDeadReckoningEngineParams(const DeadReckoningEngineConfig& dreConfig)=0; + + /** @brief + This API is used to instruct the specified engine to be in + the pause/resume state. <br/> + + When the engine is placed in paused state, the engine will + stop. If there is an on-going session, engine will no longer + produce fixes. In the paused state, calling API to delete + aiding data from the paused engine may not have effect. + Request to delete Aiding data shall be issued after + engine resume. <br/> + + Currently, only DRE engine will support pause/resume + request. responseCb() will return not supported when request + is made to pause/resume none-DRE engine. <br/> + + Request to pause/resume DRE engine can be made with or + without an on-going session. With QDR engine, on resume, + GNSS position & heading re-acquisition is needed for DR + engine to engage. If DR engine is already in the requested + state, the request will be no-op. <br/> + + @param + engType: the engine that is instructed to change its run + state. <br/> + + engState: the new engine run state that the engine is + instructed to be in. <br/> + + @return + A session id that will be returned in responseCallback to + match command with response. This effect is global for all + clients of LocationAPI responseCallback returns: + LOCATION_ERROR_SUCCESS if successful + LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid + */ + virtual uint32_t configEngineRunState(PositioningEngineMask engType, + LocEngineRunState engState) = 0; +}; + +#endif /* ILOCATIONAPI_H */ |