1 /* Copyright (c) 2018-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 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(const 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         Configure the constellation and SVs to be used by the GNSS engine on
195         modem.
196 
197         @param
198         constellationEnablementConfig: configuration to enable/disable SV
199         constellation to be used by SPE engine. When size in
200         constellationEnablementConfig is set to 0, this indicates to reset SV
201         constellation configuration to modem NV default.
202 
203         blacklistSvConfig: configuration to blacklist or unblacklist SVs
204         used by SPE engine
205 
206         @return
207         A session id that will be returned in responseCallback to
208         match command with response. This effect is global for all
209         clients of LocationAPI responseCallback returns:
210                 LOCATION_ERROR_SUCCESS if successful
211                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
212     */
213     virtual uint32_t configConstellations(
214             const GnssSvTypeConfig& constellationEnablementConfig,
215             const GnssSvIdConfig&   blacklistSvConfig) = 0;
216 
217     /** @brief
218         Configure the secondary band of constellations to be used by
219         the GNSS engine on modem.
220 
221         @param
222         secondaryBandConfig: configuration the secondary band usage
223         for SPE engine
224 
225         @return
226         A session id that will be returned in responseCallback to
227         match command with response. This effect is global for all
228         clients of LocationAPI responseCallback returns:
229                 LOCATION_ERROR_SUCCESS if successful
230                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
231     */
232     virtual uint32_t configConstellationSecondaryBand(
233             const GnssSvTypeConfig& secondaryBandConfig) = 0;
234 
235     /** @brief
236         Enable or disable the constrained time uncertainty feature.
237 
238         @param
239         enable: true to enable the constrained time uncertainty
240         feature and false to disable the constrainted time
241         uncertainty feature.
242 
243         @param
244         tuncThreshold: this specifies the time uncertainty threshold
245         that gps engine need to maintain, in units of milli-seconds.
246         Default is 0.0 meaning that modem default value of time
247         uncertainty threshold will be used. This parameter is
248         ignored when requesting to disable this feature.
249 
250         @param
251         energyBudget: this specifies the power budget that gps
252         engine is allowed to spend to maintain the time uncertainty.
253         Default is 0 meaning that GPS engine is not constained by
254         power budget and can spend as much power as needed. The
255         parameter need to be specified in units of 0.1 milli watt
256         second. This parameter is ignored requesting to disable this
257         feature.
258 
259         @return
260         A session id that will be returned in responseCallback to
261         match command with response. This effect is global for all
262         clients of LocationAPI responseCallback returns:
263                 LOCATION_ERROR_SUCCESS if successful
264                 LOCATION_ERROR_INVALID_PARAMETER if any parameters
265                 are invalid
266     */
267     virtual uint32_t configConstrainedTimeUncertainty(
268             bool enable, float tuncThreshold = 0.0,
269             uint32_t energyBudget = 0) = 0;
270 
271     /** @brief
272         Enable or disable position assisted clock estimator feature.
273 
274         @param
275         enable: true to enable position assisted clock estimator and
276         false to disable the position assisted clock estimator
277         feature.
278 
279         @return
280         A session id that will be returned in responseCallback to
281         match command with response. This effect is global for all
282         clients of LocationAPI responseCallback returns:
283                 LOCATION_ERROR_SUCCESS if successful
284                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
285     */
286     virtual uint32_t configPositionAssistedClockEstimator(bool enable) = 0;
287 
288     /** @brief
289         Sets the lever arm parameters for the vehicle.
290 
291         @param
292         configInfo: lever arm configuration info regarding below two
293         types of lever arm info:
294         a: GNSS Antenna w.r.t the origin at the IMU e.g.: inertial
295         measurement unit.
296         b: lever arm parameters regarding the OPF (output frame)
297         w.r.t the origin (at the GPS Antenna). Vehicle manufacturers
298         prefer the position output to be tied to a specific point in
299         the vehicle rather than where the antenna is placed
300         (midpoint of the rear axle is typical).
301 
302         Caller can choose types of lever arm info to configure via the
303         leverMarkTypeMask.
304 
305         @return
306         A session id that will be returned in responseCallback to
307         match command with response. This effect is global for all
308         clients of LocationAPI responseCallback returns:
309                 LOCATION_ERROR_SUCCESS if successful
310                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
311     */
312     virtual uint32_t configLeverArm(const LeverArmConfigInfo& configInfo) = 0;
313 
314     /** @brief
315         Configure the robust location setting.
316 
317         @param
318         enable: true to enable robust location and false to disable
319         robust location.
320 
321         @param
322         enableForE911: true to enable robust location when device is on
323         E911 session and false to disable on E911 session.
324         This parameter is only valid if robust location is enabled.
325 
326         @return
327         A session id that will be returned in responseCallback to
328         match command with response. This effect is global for all
329         clients of LocationAPI responseCallback returns:
330                 LOCATION_ERROR_SUCCESS if successful
331                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
332     */
333     virtual uint32_t configRobustLocation(bool enable, bool enableForE911) = 0;
334 
335     /** @brief
336         Config the minimum GPS week used by modem GNSS engine.
337 
338         @param
339         minGpsWeek: minimum GPS week to be used by modem GNSS engine.
340 
341         @return
342         A session id that will be returned in responseCallback to
343         match command with response. This effect is global for all
344         clients of LocationAPI responseCallback returns:
345                 LOCATION_ERROR_SUCCESS if successful
346                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
347     */
348     virtual uint32_t configMinGpsWeek(uint16_t minGpsWeek) = 0;
349 
350     /** @brief
351         Configure the vehicle body-to-Sensor mount parameters and
352         other parameters for dead reckoning position engine.
353 
354         @param
355         dreConfig: vehicle body-to-Sensor mount angles and other
356         parameters.
357 
358         @return
359         A session id that will be returned in responseCallback to
360         match command with response. This effect is global for all
361         clients of LocationAPI responseCallback returns:
362                 LOCATION_ERROR_SUCCESS if successful
363                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
364     */
365     virtual uint32_t configDeadReckoningEngineParams(const DeadReckoningEngineConfig& dreConfig)=0;
366 
367     /** @brief
368         This API is used to instruct the specified engine to be in
369         the pause/resume state. <br/>
370 
371         When the engine is placed in paused state, the engine will
372         stop. If there is an on-going session, engine will no longer
373         produce fixes. In the paused state, calling API to delete
374         aiding data from the paused engine may not have effect.
375         Request to delete Aiding data shall be issued after
376         engine resume. <br/>
377 
378         Currently, only DRE engine will support pause/resume
379         request. responseCb() will return not supported when request
380         is made to pause/resume none-DRE engine. <br/>
381 
382         Request to pause/resume DRE engine can be made with or
383         without an on-going session. With QDR engine, on resume,
384         GNSS position & heading re-acquisition is needed for DR
385         engine to engage. If DR engine is already in the requested
386         state, the request will be no-op.  <br/>
387 
388         @param
389         engType: the engine that is instructed to change its run
390         state. <br/>
391 
392         engState: the new engine run state that the engine is
393         instructed to be in. <br/>
394 
395         @return
396         A session id that will be returned in responseCallback to
397         match command with response. This effect is global for all
398         clients of LocationAPI responseCallback returns:
399                 LOCATION_ERROR_SUCCESS if successful
400                 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid
401     */
402     virtual uint32_t configEngineRunState(PositioningEngineMask engType,
403                                           LocEngineRunState engState) = 0;
404 };
405 
406 #endif /* ILOCATIONAPI_H */
407