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