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 194 #endif /* ILOCATIONAPI_H */ 195