1 /* Copyright (c) 2017-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 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 183 typedef struct { 184 size_t size; // set to sizeof(LocationControlCallbacks) 185 responseCallback responseCb; // mandatory 186 collectiveResponseCallback collectiveResponseCb; // mandatory 187 gnssConfigCallback gnssConfigCb; // optional 188 } LocationControlCallbacks; 189 190 class LocationControlAPI : public ILocationControlAPI 191 { 192 private: 193 LocationControlAPI(); 194 ~LocationControlAPI(); 195 196 public: 197 /* creates an instance to LocationControlAPI object. 198 Will return NULL if mandatory parameters are invalid or if the maximum number 199 of instances have been reached. Only once instance allowed */ 200 static LocationControlAPI* createInstance(LocationControlCallbacks&); 201 202 /* destroy/cleans up the instance, which should be called when LocationControlAPI object is 203 no longer needed. LocationControlAPI* returned from createInstance will no longer valid 204 after destroy is called */ 205 void destroy(); 206 207 /* enable will enable specific location technology to be used for calculation locations and 208 will effectively start a control session if call is successful, which returns a session id 209 that will be returned in responseCallback to match command with response. The session id is 210 also needed to call the disable command. 211 This effect is global for all clients of LocationAPI 212 responseCallback returns: 213 LOCATION_ERROR_SUCCESS if successful 214 LOCATION_ERROR_ALREADY_STARTED if an enable was already called for this techType 215 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 216 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */ 217 uint32_t enable(LocationTechnologyType techType); 218 219 /* disable will disable specific location technology to be used for calculation locations and 220 effectively ends the control session if call is successful. 221 id parameter is the session id that was returned in enable responseCallback for techType. 222 The session id is no longer valid after disable's responseCallback returns success. 223 This effect is global for all clients of LocationAPI 224 responseCallback returns: 225 LOCATION_ERROR_SUCCESS if successful 226 LOCATION_ERROR_ID_UNKNOWN if id was not returned from responseCallback from enable 227 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */ 228 void disable(uint32_t id); 229 230 /* gnssUpdateConfig updates the gnss specific configuration, which returns a session id array 231 with an id for each of the bits set in GnssConfig.flags, order from low bits to high bits. 232 The response for each config that is set will be returned in collectiveResponseCallback. 233 The session id array returned will be valid until the collectiveResponseCallback is called 234 and has returned. This effect is global for all clients of LocationAPI 235 collectiveResponseCallback returns: 236 LOCATION_ERROR_SUCCESS if session was successful 237 LOCATION_ERROR_INVALID_PARAMETER if any other parameters are invalid 238 LOCATION_ERROR_GENERAL_FAILURE if failure for any other reason */ 239 virtual uint32_t* gnssUpdateConfig(GnssConfig config) override; 240 241 /* gnssGetConfig fetches the current constellation and SV configuration 242 on the GNSS engine. 243 Returns a session id array with an id for each of the bits set in 244 the mask parameter, order from low bits to high bits. 245 Response is sent via the registered gnssConfigCallback. 246 This effect is global for all clients of LocationAPI 247 collectiveResponseCallback returns: 248 LOCATION_ERROR_SUCCESS if session was successful 249 LOCATION_ERROR_INVALID_PARAMETER if any parameter is invalid 250 LOCATION_ERROR_CALLBACK_MISSING If no gnssConfigCallback 251 was passed in createInstance 252 LOCATION_ERROR_NOT_SUPPORTED If read of requested configuration 253 is not supported */ 254 uint32_t* gnssGetConfig(GnssConfigFlagsMask mask); 255 256 /* delete specific gnss aiding data for testing, which returns a session id 257 that will be returned in responseCallback to match command with response. 258 Only allowed in userdebug builds. This effect is global for all clients of LocationAPI 259 responseCallback returns: 260 LOCATION_ERROR_SUCCESS if successful 261 LOCATION_ERROR_INVALID_PARAMETER if any parameters are invalid 262 LOCATION_ERROR_NOT_SUPPORTED if build is not userdebug */ 263 virtual uint32_t gnssDeleteAidingData(GnssAidingData& data) override; 264 }; 265 266 #endif /* LOCATIONAPI_H */ 267