1 /* Copyright (c) 2018 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 ILOCATIONAPI_H
30 #define ILOCATIONAPI_H
31 
32 #include "LocationDataTypes.h"
33 
34 class ILocationAPI
35 {
36 public:
~ILocationAPI()37     virtual ~ILocationAPI(){};
38 
39     /** @brief Updates/changes the callbacks that will be called.
40         mandatory callbacks must be present for callbacks to be successfully updated
41         no return value */
42     virtual void updateCallbacks(LocationCallbacks&) = 0;
43 
44     /* ================================== TRACKING ================================== */
45 
46     /** @brief Starts a tracking session, which returns a session id that will be
47        used by the other tracking APIs and also in the responseCallback to match command
48        with response. locations are reported on the registered trackingCallback
49        periodically according to LocationOptions.
50        @return session id
51         responseCallback returns:
52                 LOCATION_ERROR_SUCCESS if session was successfully started
53                 LOCATION_ERROR_ALREADY_STARTED if a startTracking session is already in progress
54                 LOCATION_ERROR_CALLBACK_MISSING if no trackingCallback was passed
55                 LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameter is invalid */
56     virtual uint32_t startTracking(TrackingOptions&) = 0;
57 
58     /** @brief Stops a tracking session associated with id parameter.
59         responseCallback returns:
60                 LOCATION_ERROR_SUCCESS if successful
61                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */
62     virtual void stopTracking(uint32_t id) = 0;
63 
64     /** @brief Changes the LocationOptions of a tracking session associated with id.
65         responseCallback returns:
66                 LOCATION_ERROR_SUCCESS if successful
67                 LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameters are invalid
68                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a tracking session */
69     virtual void updateTrackingOptions(uint32_t id, TrackingOptions&) = 0;
70 
71     /* ================================== BATCHING ================================== */
72 
73     /** @brief starts a batching session, which returns a session id that will be
74        used by the other batching APIs and also in the responseCallback to match command
75        with response. locations are reported on the batchingCallback passed in createInstance
76        periodically according to LocationOptions. A batching session starts tracking on
77        the low power processor and delivers them in batches by the batchingCallback when
78        the batch is full or when getBatchedLocations is called. This allows for the processor
79        that calls this API to sleep when the low power processor can batch locations in the
80        backgroup and wake up the processor calling the API only when the batch is full, thus
81        saving power.
82        @return session id
83         responseCallback returns:
84                 LOCATION_ERROR_SUCCESS if session was successful
85                 LOCATION_ERROR_ALREADY_STARTED if a startBatching session is already in progress
86                 LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback
87                 LOCATION_ERROR_INVALID_PARAMETER if a parameter is invalid
88                 LOCATION_ERROR_NOT_SUPPORTED if batching is not supported */
89     virtual uint32_t startBatching(BatchingOptions&) = 0;
90 
91     /** @brief Stops a batching session associated with id parameter.
92         responseCallback returns:
93                 LOCATION_ERROR_SUCCESS if successful
94                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with batching session */
95     virtual void stopBatching(uint32_t id) = 0;
96 
97     /** @brief Changes the LocationOptions of a batching session associated with id.
98         responseCallback returns:
99                 LOCATION_ERROR_SUCCESS if successful
100                 LOCATION_ERROR_INVALID_PARAMETER if LocationOptions parameters are invalid
101                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */
102     virtual void updateBatchingOptions(uint32_t id, BatchingOptions&) = 0;
103 
104     /** @brief Gets a number of locations that are currently stored/batched
105        on the low power processor, delivered by the batchingCallback passed in createInstance.
106        Location are then deleted from the batch stored on the low power processor.
107         responseCallback returns:
108                 LOCATION_ERROR_SUCCESS if successful, will be followed by batchingCallback call
109                 LOCATION_ERROR_CALLBACK_MISSING if no batchingCallback
110                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a batching session */
111     virtual void getBatchedLocations(uint32_t id, size_t count) = 0;
112 
113     /* ================================== GEOFENCE ================================== */
114 
115     /** @brief Adds any number of geofences and returns an array of geofence ids that
116        will be used by the other geofence APIs and also in the collectiveResponseCallback to
117        match command with response. The geofenceBreachCallback will deliver the status of each
118        geofence according to the GeofenceOption for each. The geofence id array returned will
119        be valid until the collectiveResponseCallback is called and has returned.
120        @return id array
121         collectiveResponseCallback returns:
122                 LOCATION_ERROR_SUCCESS if session was successful
123                 LOCATION_ERROR_CALLBACK_MISSING if no geofenceBreachCallback
124                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
125                 LOCATION_ERROR_NOT_SUPPORTED if geofence is not supported */
126     virtual uint32_t* addGeofences(size_t count, GeofenceOption*, GeofenceInfo*) = 0;
127 
128     /** @brief Removes any number of geofences. Caller should delete ids array after
129        removeGeofences returneds.
130         collectiveResponseCallback returns:
131                 LOCATION_ERROR_SUCCESS if successful
132                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */
133     virtual void removeGeofences(size_t count, uint32_t* ids) = 0;
134 
135     /** @brief Modifies any number of geofences. Caller should delete ids array after
136        modifyGeofences returns.
137         collectiveResponseCallback returns:
138                 LOCATION_ERROR_SUCCESS if successful
139                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session
140                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid */
141     virtual void modifyGeofences(size_t count, uint32_t* ids, GeofenceOption* options) = 0;
142 
143     /** @brief Pauses any number of geofences, which is similar to removeGeofences,
144        only that they can be resumed at any time. Caller should delete ids array after
145        pauseGeofences returns.
146         collectiveResponseCallback returns:
147                 LOCATION_ERROR_SUCCESS if successful
148                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */
149     virtual void pauseGeofences(size_t count, uint32_t* ids) = 0;
150 
151     /** @brief Resumes any number of geofences that are currently paused. Caller should
152        delete ids array after resumeGeofences returns.
153         collectiveResponseCallback returns:
154                 LOCATION_ERROR_SUCCESS if successful
155                 LOCATION_ERROR_ID_UNKNOWN if id is not associated with a geofence session */
156     virtual void resumeGeofences(size_t count, uint32_t* ids) = 0;
157 
158     /* ================================== GNSS ====================================== */
159 
160      /** @brief gnssNiResponse is called in response to a gnssNiCallback.
161         responseCallback returns:
162                 LOCATION_ERROR_SUCCESS if session was successful
163                 LOCATION_ERROR_INVALID_PARAMETER if any parameters in GnssNiResponse are invalid
164                 LOCATION_ERROR_ID_UNKNOWN if id does not match a gnssNiCallback */
165     virtual void gnssNiResponse(uint32_t id, GnssNiResponse response) = 0;
166 };
167 
168 class ILocationControlAPI
169 {
170 public:
~ILocationControlAPI()171     virtual ~ILocationControlAPI(){};
172 
173     /** @brief Updates the gnss specific configuration, which returns a session id array
174        with an id for each of the bits set in GnssConfig.flags, order from low bits to high bits.
175        The response for each config that is set will be returned in collectiveResponseCallback.
176        The session id array returned will be valid until the collectiveResponseCallback is called
177        and has returned. This effect is global for all clients of ILocationAPI.
178         collectiveResponseCallback returns:
179                 LOCATION_ERROR_SUCCESS if session was successful
180                 LOCATION_ERROR_INVALID_PARAMETER if any other parameters are invalid
181                 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */
182     virtual uint32_t* gnssUpdateConfig(GnssConfig config) = 0;
183 
184     /** @brief Delete specific gnss aiding data for testing, which returns a session id
185        that will be returned in responseCallback to match command with response.
186        Only allowed in userdebug builds. This effect is global for all clients of ILocationAPI.
187         responseCallback returns:
188                 LOCATION_ERROR_SUCCESS if successful
189                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
190                 LOCATION_ERROR_NOT_SUPPORTED if build is not userdebug */
191     virtual uint32_t gnssDeleteAidingData(GnssAidingData& data) = 0;
192 
193     /** @brief
194         Reset the constellation settings to modem default.
195 
196         @param
197         None
198 
199         @return
200         A session id that will be returned in responseCallback to
201         match command with response. This effect is global for all
202         clients of LocationAPI responseCallback returns:
203                 LOCATION_ERROR_SUCCESS if successful
204                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
205     */
206     virtual uint32_t resetConstellationConfig() = 0;
207 
208     /** @brief
209         Configure the constellation to be used by the GNSS engine on
210         modem.
211 
212         @param
213         constellationConfig: specify the constellation configuration
214         used by GNSS engine.
215 
216         @return
217         A session id that will be returned in responseCallback to
218         match command with response. This effect is global for all
219         clients of LocationAPI responseCallback returns:
220                 LOCATION_ERROR_SUCCESS if successful
221                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
222     */
223     virtual uint32_t configConstellations(
224             const GnssSvTypeConfig& svTypeConfig,
225             const GnssSvIdConfig&   svIdConfig) = 0;
226 
227     /** @brief
228         Enable or disable the constrained time uncertainty feature.
229 
230         @param
231         enable: true to enable the constrained time uncertainty
232         feature and false to disable the constrainted time
233         uncertainty feature.
234 
235         @param
236         tuncThreshold: this specifies the time uncertainty threshold
237         that gps engine need to maintain, in units of milli-seconds.
238         Default is 0.0 meaning that modem default value of time
239         uncertainty threshold will be used. This parameter is
240         ignored when requesting to disable this feature.
241 
242         @param
243         energyBudget: this specifies the power budget that gps
244         engine is allowed to spend to maintain the time uncertainty.
245         Default is 0 meaning that GPS engine is not constained by
246         power budget and can spend as much power as needed. The
247         parameter need to be specified in units of 0.1 milli watt
248         second. This parameter is ignored requesting to disable this
249         feature.
250 
251         @return
252         A session id that will be returned in responseCallback to
253         match command with response. This effect is global for all
254         clients of LocationAPI responseCallback returns:
255                 LOCATION_ERROR_SUCCESS if successful
256                 LOCATION_ERROR_INVALID_PARAMETER if any parameters
257                 are invalid
258     */
259     virtual uint32_t configConstrainedTimeUncertainty(
260             bool enable, float tuncThreshold = 0.0,
261             uint32_t energyBudget = 0) = 0;
262 
263     /** @brief
264         Enable or disable position assisted clock estimator feature.
265 
266         @param
267         enable: true to enable position assisted clock estimator and
268         false to disable the position assisted clock estimator
269         feature.
270 
271         @return
272         A session id that will be returned in responseCallback to
273         match command with response. This effect is global for all
274         clients of LocationAPI responseCallback returns:
275                 LOCATION_ERROR_SUCCESS if successful
276                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
277     */
278     virtual uint32_t configPositionAssistedClockEstimator(bool enable) = 0;
279 
280     /** @brief
281         Sets the lever arm parameters for the vehicle.
282 
283         @param
284         configInfo: lever arm configuration info regarding below two
285         types of lever arm info:
286         a: GNSS Antenna w.r.t the origin at the IMU e.g.: inertial
287         measurement unit.
288         b: lever arm parameters regarding the OPF (output frame)
289         w.r.t the origin (at the GPS Antenna). Vehicle manufacturers
290         prefer the position output to be tied to a specific point in
291         the vehicle rather than where the antenna is placed
292         (midpoint of the rear axle is typical).
293 
294         Caller can choose types of lever arm info to configure via the
295         leverMarkTypeMask.
296 
297         @return
298         A session id that will be returned in responseCallback to
299         match command with response. This effect is global for all
300         clients of LocationAPI responseCallback returns:
301                 LOCATION_ERROR_SUCCESS if successful
302                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
303     */
304     virtual uint32_t configLeverArm(const LeverArmConfigInfo& configInfo) = 0;
305 };
306 
307 #endif /* ILOCATIONAPI_H */
308