1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Location 18 * @{ 19 * 20 * @brief Provide functions for querying the status of location switch, starting and stopping locating. 21 * 22 * @since 13 23 */ 24 25 /** 26 * @file oh_location_type.h 27 * @kit LocationKit 28 * @brief Declares the common location attributes. 29 * @library libohlocation.so 30 * @syscap SystemCapability.Location.Location.Core 31 * @since 13 32 */ 33 34 #ifndef OH_LOCATION_TYPE_H 35 #define OH_LOCATION_TYPE_H 36 37 #include <cstdint> 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /** 44 * @brief Enumerates the location result codes. 45 * 46 * @since 13 47 */ 48 typedef enum Location_ResultCode { 49 /** 50 * @error The operation is successful. 51 */ 52 LOCATION_SUCCESS = 0, 53 /** 54 * @error Permission verification failed. The application does not have the 55 * permission required to call the API. 56 */ 57 LOCATION_PERMISSION_DENIED = 201, 58 /** 59 * @error Parameter error. Possible reasons: 1. The input parameter is a null pointer;\n 60 * 2. Parameter values exceed the defined range.\n 61 */ 62 LOCATION_INVALID_PARAM = 401, 63 /** 64 * @error Capability not supported. Failed to call function due to limited device capabilities. 65 */ 66 LOCATION_NOT_SUPPORTED = 801, 67 /** 68 * @error The location service is unavailable. 69 * Possible reasons: Abnormal startup of location services.\n 70 */ 71 LOCATION_SERVICE_UNAVAILABLE = 3301000, 72 /** 73 * @error The location switch is off. 74 */ 75 LOCATION_SWITCH_OFF = 3301100 76 } Location_ResultCode; 77 78 /** 79 * @brief Enumeration values of use scenarios. 80 * 81 * @since 13 82 */ 83 typedef enum Location_UseScene { 84 /** 85 * Indicates the navigation scenario. 86 * This feature applies to outdoor scenarios where real-time device locations need 87 * to be obtained, such as vehicle-mounted and pedestrian navigation. 88 * The GNSS positioning technology is used to provide positioning services, and the 89 * power consumption is high. 90 */ 91 LOCATION_USE_SCENE_NAVIGATION = 0x0401, 92 /** 93 * Indicates the sport scenario. 94 * This feature applies to scenarios where user location tracks are recorded, 95 * for example, sports apps. The GNSS positioning technology is used to provide 96 * positioning services, and the power consumption is high. 97 */ 98 LOCATION_USE_SCENE_SPORT = 0x0402, 99 /** 100 * Indicates a travel scenario. 101 * This mode applies to travel scenarios, such as taxi and public transportation. 102 * The GNSS positioning technology is used to provide positioning services, and 103 * the power consumption is high. 104 */ 105 LOCATION_USE_SCENE_TRANSPORT = 0x0403, 106 /** 107 * Indicates the daily service usage scenario. 108 * This mode applies to scenarios where precise user location is not required, 109 * such as news, online shopping, and ordering applications. 110 * In this scenario, only a network positioning technology is used to provide a 111 * positioning service, and power consumption is relatively low. 112 */ 113 LOCATION_USE_SCENE_DAILY_LIFE_SERVICE = 0x0404 114 } Location_UseScene; 115 116 /** 117 * @brief Enumerates the power consumption scenario. 118 * 119 * @since 13 120 */ 121 typedef enum Location_PowerConsumptionScene { 122 /** 123 * High power consumption. 124 * GNSS positioning technology is mainly used. We will use network positioning 125 * technology to provide services before GNSS provides stable location results; 126 * During continuous positioning, if the GNSS positioning result cannot be obtained 127 * for more than 30 seconds, the network positioning technology is used to obtain 128 * the location. Consumes a large number of hardware resources and power. 129 */ 130 LOCATION_HIGH_POWER_CONSUMPTION = 0x0601, 131 /** 132 * Low power consumption. 133 * This mode applies to scenarios that do not require high user location precision, 134 * such as news, online shopping, and meal ordering. 135 * In this scenario, only a network positioning technology is used to provide a 136 * positioning service, and power consumption is relatively low. 137 */ 138 LOCATION_LOW_POWER_CONSUMPTION = 0x0602, 139 /** 140 * No power consumption. 141 * In this scenario, the location is not proactively triggered. The location is 142 * returned to the current app only when other apps are located. 143 */ 144 LOCATION_NO_POWER_CONSUMPTION = 0x0603 145 } Location_PowerConsumptionScene; 146 147 /** 148 * @brief Enumerates the source type of location. 149 * 150 * @since 13 151 */ 152 typedef enum Location_SourceType { 153 /** 154 * The positioning result is based on the GNSS positioning technology. 155 */ 156 LOCATION_SOURCE_TYPE_GNSS = 1, 157 /** 158 * The positioning result comes from the network positioning technology. 159 */ 160 LOCATION_SOURCE_TYPE_NETWORK = 2, 161 /** 162 * The positioning result comes from the high-precision indoor positioning technology. 163 */ 164 LOCATION_SOURCE_TYPE_INDOOR = 3, 165 /** 166 * The positioning result comes from the high-precision positioning technology. 167 */ 168 LOCATION_SOURCE_TYPE_RTK = 4 169 } Location_SourceType; 170 171 /** 172 * @brief Defines the location information. 173 * 174 * @since 13 175 */ 176 typedef struct Location_BasicInfo { 177 /** 178 * Indicates latitude information, with positive values indicating north latitude\n 179 * and negative values indicating south latitude. The value range is -90 to 90.\n 180 * Only supports WGS84 coordinate system.\n 181 */ 182 double latitude; 183 /** 184 * Indicates longitude information, positive values indicate east longitude,\n 185 * and negative values indicate west longitude. The value range is -180 to 180.\n 186 * Only supports WGS84 coordinate system.\n 187 */ 188 double longitude; 189 /** 190 * Altitude in meters. 191 */ 192 double altitude; 193 /** 194 * Horizontal location accuracy in meters. 195 */ 196 double accuracy; 197 /** 198 * Speed in meters per second. 199 */ 200 double speed; 201 /** 202 * Heading in degrees. The value range is 0 to 360. 203 */ 204 double direction; 205 /** 206 * Timestamp for the location fix. Number of milliseconds since January 1, 1970. 207 */ 208 int64_t timeForFix; 209 /** 210 * Time since the system was booted, and include deep sleep. The unit is nanosecond. 211 */ 212 int64_t timeSinceBoot; 213 /** 214 * Vertical position accuracy in meters. 215 */ 216 double altitudeAccuracy; 217 /** 218 * Speed accuracy in meter per seconds. 219 */ 220 double speedAccuracy; 221 /** 222 * Direction accuracy in degrees. The value range is 0 to 360. 223 */ 224 double directionAccuracy; 225 /** 226 * Time uncertainty in nanosecond. 227 */ 228 int64_t uncertaintyOfTimeSinceBoot; 229 /** 230 * Indicates the source of the location result. 231 */ 232 Location_SourceType locationSourceType; 233 } Location_BasicInfo; 234 235 /** 236 * @brief Define the structure of location information. 237 * @since 13 238 */ 239 typedef struct Location_Info Location_Info; 240 241 /** 242 * @brief Obtain basic location information. 243 * 244 * @param location - Pointer to the location information structure.\n 245 * A non-null pointer is required. The pointer can be obtained from {@link Location_InfoCallback}.\n 246 * @return Return the basic information structure of the location.\n 247 * For a detailed definition, please refer to {@link Location_BasicInfo}.\n 248 * @since 13 249 */ 250 Location_BasicInfo OH_LocationInfo_GetBasicInfo(Location_Info* location); 251 252 /** 253 * @brief Obtain additional information from the location information. 254 * 255 * @param location - Pointer to the location information structure.\n 256 * A non-null pointer is required. The pointer can be obtained from {@link Location_InfoCallback}.\n 257 * @param additionalInfo - Non null pointers of char type; This variable is used to store additional\n 258 * information strings. The string is in JSON format.\n 259 * The pointer and the corresponding memory are created by the caller.\n 260 * You are advised to apply for a memory of 256 bytes or more.\n 261 * If a null pointer is passed, an error code is returned.\n 262 * @param length - Memory size of additionalInfo. 263 * @return Location functions result code.\n 264 * For a detailed definition, please refer to {@link Location_ResultCode}.\n 265 * {@link LOCAION_SUCCESS} Successfully obtained additional information.\n 266 * {@link LOCATION_INVALID_PARAM} 1.The input parameter location or additionalInfo is a null pointer.\n 267 * 2.The input parameter length is too small to store additional information.\n 268 * @since 13 269 */ 270 Location_ResultCode OH_LocationInfo_GetAdditionalInfo(Location_Info* location, 271 char* additionalInfo, uint32_t length); 272 273 /** 274 * @brief Defines the callback function used to report location data. 275 * 276 * @param location - Pointer to the {@link Location_Info} instance. Carry the latest location information.\n 277 * The memory of the location instance is recycled at the end of {@link Location_InfoCallback}.\n 278 * Before that, call {@link OH_LocationInfo_GetBasicInfo} and other interfaces to obtain location information.\n 279 * @param userData - Pointer to an application data structure, this parameter is passed in\n 280 * through {@link OH_LocationRequestConfig_SetCallback}.\n 281 * @since 13 282 */ 283 typedef void (*Location_InfoCallback)(Location_Info* location, void* userData); 284 285 /** 286 * @brief Define the structure of location request parameters. 287 * @since 13 288 */ 289 typedef struct Location_RequestConfig Location_RequestConfig; 290 291 /** 292 * @brief Create a location request parameter structure instance. 293 * 294 * @return Return a pointer to the {@ link Location_RequestConfig} instance. \n 295 * If NULL is returned, it indicates that the creation failed. \n 296 * The possible reason is that the application address space is full,\n 297 * resulting in the inability to allocate space. \n 298 * @since 13 299 */ 300 Location_RequestConfig* OH_Location_CreateRequestConfig(void); 301 302 /** 303 * @brief Destroy the location request parameter instance and reclaim memory. 304 * 305 * @param requestConfig - Pointer to {@link Location_RequestConfig} instance.\n 306 * The instance was created by {@link OH_Location_CreateRequestConfig}.\n 307 * @since 13 308 */ 309 void OH_Location_DestroyRequestConfig(Location_RequestConfig* requestConfig); 310 311 /** 312 * @brief Set the use scenario in the location request parameter.\n 313 * Prioritize useScene in the location request parameter {@link Location_RequestConfig}.\n 314 * If useScene is set, powerConsumptionScene becomes invalid.\n 315 * If useScene is not set and powerConsumptionScene is set, this parameter takes effect.\n 316 * If both parameters are not set, the default useScene is\n 317 * {@link LOCATION_USE_SCENE_DAILY_LIFE_SERVICE},\n 318 * and the powerConsumptionCenario parameter is invalid.\n 319 * 320 * @param requestConfig - Pointer to the {@link Location_RequestConfig} instance.\n 321 * The instance was created by {@link OH_Location_CreateRequestConfig}.\n 322 * @param useScene - Representing the use scenario during location requests.\n 323 * The default value is {@link LOCATION_USE_SCENE_DAILY_LIFE_SERVICE}\n. 324 * For a detailed definition, please refer to {@link Location_UseScene}.\n 325 * @since 13 326 */ 327 void OH_LocationRequestConfig_SetUseScene(Location_RequestConfig* requestConfig, 328 Location_UseScene useScene); 329 330 /** 331 * @brief Set the power consumption scenario in the location request parameters. 332 * 333 * @param requestConfig - Pointer to the {@link Location_RequestConfig} instance.\n 334 * The instance was created by {@link OH_Location_CreateRequestConfig}.\n 335 * @param powerConsumptionScene - Represents the power consumption scenario for location requests.\n 336 * The recognition value is {@link LOCATION_LOW_POWER_CONSUMPTION}.\n 337 * For a detailed definition, please refer to {@link Location_PowerConsumptionScene}.\n 338 * @since 13 339 */ 340 void OH_LocationRequestConfig_SetPowerConsumptionScene(Location_RequestConfig* requestConfig, 341 Location_PowerConsumptionScene powerConsumptionScene); 342 343 /** 344 * @brief Set the location reporting interval in the location request parameter. 345 * 346 * @param requestConfig - Pointer to the {@link Location_RequestConfig} instance.\n 347 * The instance was created by {@link OH_Location_CreateRequestConfig}.\n 348 * @param interval - Indicates the time interval for location reporting, in seconds.\n 349 * The value is greater than or equal to 1. The default value is 1.\n 350 * @since 13 351 */ 352 void OH_LocationRequestConfig_SetInterval(Location_RequestConfig* requestConfig, 353 int interval); 354 355 /** 356 * @brief Set up a callback function for receiving location information. 357 * 358 * @param requestConfig - Pointer to the {@link Location_RequestConfig} instance.\n 359 * The instance was created by {@link OH_Location_CreateRequestConfig}.\n 360 * @param callback - Pointer to the callback function for receiving the location.\n 361 * For details, see {@link Location_InfoCallback}.\n 362 * @param userData - Pointer to the application data structure, which will be\n 363 * carried in the callback function.\n 364 * @since 13 365 */ 366 void OH_LocationRequestConfig_SetCallback(Location_RequestConfig* requestConfig, 367 Location_InfoCallback callback, void* userData); 368 #ifdef __cplusplus 369 } 370 #endif 371 /** @} */ 372 #endif // OH_LOCATION_TYPE_H