1# Location 2 3 4## Overview 5 6Provides APIs for querying the location switch status, and starting and stopping location. 7 8**Since**: 13 9 10 11## Summary 12 13 14### File 15 16| Name| Description| 17| -------- | -------- | 18| [oh_location.h](oh__location_8h.md) | Defines APIs for querying the location switch status, and starting and stopping location. | 19| [oh_location_type.h](oh__location__type_8h.md) | Defines common attributes of the location service. | 20 21 22### Structs 23 24| Name| Description| 25| -------- | -------- | 26| struct [Location_BasicInfo](_location___basic_info.md) | Struct for the basic location information. | 27 28 29### Types 30 31| Name| Description| 32| -------- | -------- | 33| typedef enum [Location_ResultCode](#location_resultcode-1) [Location_ResultCode](#location_resultcode) | Enumerates error codes of the location service. | 34| typedef enum [Location_UseScene](#location_usescene-1) [Location_UseScene](#location_usescene) | Enumerates use scenes in a location request. | 35| typedef enum [Location_PowerConsumptionScene](#location_powerconsumptionscene-1) [Location_PowerConsumptionScene](#location_powerconsumptionscene) | Enumerates power consumption scenarios in a location request. | 36| typedef enum [Location_SourceType](#location_sourcetype-1) [Location_SourceType](#location_sourcetype) | Defines the source of location information. | 37| typedef struct [Location_BasicInfo](_location___basic_info.md) [Location_BasicInfo](#location_basicinfo) | Defines the struct for the basic location information. | 38| typedef struct [Location_Info](#location_info) [Location_Info](#location_info) | Defines the struct for the location information. | 39| typedef void(\* [Location_InfoCallback](#location_infocallback)) ([Location_Info](#location_info) \*location, void \*userData) | Defines the callback for receiving reported location information. | 40| typedef struct [Location_RequestConfig](#location_requestconfig) [Location_RequestConfig](#location_requestconfig) | Defines the struct for the location request configuration. | 41 42 43### Enums 44 45| Name| Description| 46| -------- | -------- | 47| [Location_ResultCode](#location_resultcode-1) {<br>LOCATION_SUCCESS = 0, LOCATION_PERMISSION_DENIED = 201, LOCATION_INVALID_PARAM = 401, LOCATION_NOT_SUPPORTED = 801,<br>LOCATION_SERVICE_UNAVAILABLE = 3301000, LOCATION_SWITCH_OFF = 3301100<br>} | Enumerates error codes of the location service. | 48| [Location_UseScene](#location_usescene-1) { LOCATION_USE_SCENE_NAVIGATION = 0x0401, LOCATION_USE_SCENE_SPORT = 0x0402, LOCATION_USE_SCENE_TRANSPORT = 0x0403, LOCATION_USE_SCENE_DAILY_LIFE_SERVICE = 0x0404 } | Enumerates use scenes in a location request. | 49| [Location_PowerConsumptionScene](#location_powerconsumptionscene-1) { LOCATION_HIGH_POWER_CONSUMPTION = 0x0601, LOCATION_LOW_POWER_CONSUMPTION = 0x0602, LOCATION_NO_POWER_CONSUMPTION = 0x0603 } | Enumerates power consumption scenarios in a location request. | 50| [Location_SourceType](#location_sourcetype-1) { LOCATION_SOURCE_TYPE_GNSS = 1, LOCATION_SOURCE_TYPE_NETWORK = 2, LOCATION_SOURCE_TYPE_INDOOR = 3, LOCATION_SOURCE_TYPE_RTK = 4 } | Defines the source of location information. | 51 52 53### Functions 54 55| Name| Description| 56| -------- | -------- | 57| [Location_ResultCode](#location_resultcode-1) [OH_Location_IsLocatingEnabled](#oh_location_islocatingenabled) (bool \*enabled) | Checks whether the location switch is enabled. | 58| [Location_ResultCode](#location_resultcode-1) [OH_Location_StartLocating](#oh_location_startlocating) (const [Location_RequestConfig](#location_requestconfig) \*requestConfig) | Starts locating and subscribes to location changes. | 59| [Location_ResultCode](#location_resultcode-1) [OH_Location_StopLocating](#oh_location_stoplocating) (const [Location_RequestConfig](#location_requestconfig) \*requestConfig) | Stops locating and unsubscribes from location changes. | 60| [Location_BasicInfo](_location___basic_info.md) [OH_LocationInfo_GetBasicInfo](#oh_locationinfo_getbasicinfo) ([Location_Info](#location_info) \*location) | Obtains basic location information. | 61| [Location_ResultCode](#location_resultcode-1) [OH_LocationInfo_GetAdditionalInfo](#oh_locationinfo_getadditionalinfo) ([Location_Info](#location_info) \*location, char \*additionalInfo, uint32_t length) | Obtains the additional information in the location information. | 62| [Location_RequestConfig](#location_requestconfig) \* [OH_Location_CreateRequestConfig](#oh_location_createrequestconfig) (void) | Creates a **Location_RequestConfig** instance. | 63| void [OH_Location_DestroyRequestConfig](#oh_location_destroyrequestconfig) ([Location_RequestConfig](#location_requestconfig) \*requestConfig) | Destroys the **Location_RequestConfig** instance and reclaims the memory. | 64| void [OH_LocationRequestConfig_SetUseScene](#oh_locationrequestconfig_setusescene) ([Location_RequestConfig](#location_requestconfig) \*requestConfig, [Location_UseScene](#location_usescene) useScene) | Sets the use scene in the location request configuration.<br>**useScene** takes precedence over **powerConsumptionScene** in [Location_RequestConfig](#location_requestconfig).<br>If **useScene** is set, **powerConsumptionScene** is invalid.<br>Otherwise, **powerConsumptionScene** takes effect.<br>If neither of the two parameters is set, **useScene** is set to **LOCATION_USE_SCENE_DAILY_LIFE_SERVICE** by default,<br>and **powerConsumptionScene** is invalid.| 65| void [OH_LocationRequestConfig_SetPowerConsumptionScene](#oh_locationrequestconfig_setpowerconsumptionscene) ([Location_RequestConfig](#location_requestconfig) \*requestConfig, [Location_PowerConsumptionScene](#location_powerconsumptionscene) powerConsumptionScene) | Sets the power consumption scene in the location request configuration. | 66| void [OH_LocationRequestConfig_SetInterval](#oh_locationrequestconfig_setinterval) ([Location_RequestConfig](#location_requestconfig) \*requestConfig, int interval) | Sets the location reporting interval in the location request configuration. | 67| void [OH_LocationRequestConfig_SetCallback](#oh_locationrequestconfig_setcallback) ([Location_RequestConfig](#location_requestconfig) \*requestConfig, [Location_InfoCallback](#location_infocallback) callback, void \*userData) | Sets the callback function. | 68 69 70## Type Description 71 72 73### Location_BasicInfo 74 75``` 76typedef struct Location_BasicInfo Location_BasicInfo 77``` 78**Description** 79Defines the struct for the basic location information. 80 81**Since**: 13 82 83 84### Location_Info 85 86``` 87typedef struct Location_Info Location_Info 88``` 89**Description** 90Defines the struct for the location information. 91 92**Since**: 13 93 94 95### Location_InfoCallback 96 97``` 98typedef void(* Location_InfoCallback) (Location_Info *location, void *userData) 99``` 100**Description** 101Defines the callback for receiving reported location information. 102 103**Since**: 13 104 105**Parameters** 106 107| Name| Description| 108| -------- | -------- | 109| location | Pointer to the [Location_Info](#location_info) instance, which carries the latest location information.<br>The memory occupied by the instance will be reclaimed when [Location_InfoCallback](#location_infocallback) is complete.<br>Before calling this API, call APIs such as [OH_LocationInfo_GetBasicInfo](#oh_locationinfo_getbasicinfo) to obtain the location information.| 110| userData | Pointer to the **userData** struct or object. This parameter is passed in through [OH_LocationRequestConfig_SetCallback](#oh_locationrequestconfig_setcallback).| 111 112 113### Location_PowerConsumptionScene 114 115``` 116typedef enum Location_PowerConsumptionScene Location_PowerConsumptionScene 117``` 118**Description** 119Enumerates power consumption scenarios in a location request. 120 121**Since**: 13 122 123 124### Location_RequestConfig 125 126``` 127typedef struct Location_RequestConfig Location_RequestConfig 128``` 129**Description** 130Defines the struct for the location request configuration. 131 132**Since**: 13 133 134 135### Location_ResultCode 136 137``` 138typedef enum Location_ResultCode Location_ResultCode 139``` 140**Description** 141Enumerates error codes of the location service. 142 143**Since**: 13 144 145 146### Location_SourceType 147 148``` 149typedef enum Location_SourceType Location_SourceType 150``` 151**Description** 152Defines the source of location information. 153 154**Since**: 13 155 156 157### Location_UseScene 158 159``` 160typedef enum Location_UseScene Location_UseScene 161``` 162**Description** 163Enumerates use scenes in a location request. 164 165**Since**: 13 166 167 168## Enum Description 169 170 171### Location_PowerConsumptionScene 172 173``` 174enum Location_PowerConsumptionScene 175``` 176**Description** 177Enumerates power consumption scenarios in a location request. 178 179**Since**: 13 180 181| Value| Description| 182| -------- | -------- | 183| LOCATION_HIGH_POWER_CONSUMPTION | High power consumption.<br>The mode mainly uses the GNSS positioning technology. The system uses the network positioning technology as an alternative to provide the location service for your application until the GNSS can provide stable location results.<br>During the continuous location process, the network positioning technology is used if the GNSS location result cannot be obtained within 30 seconds.<br>This policy can lead to significant hardware resource consumption and power consumption.| 184| LOCATION_LOW_POWER_CONSUMPTION | Low power consumption.<br>This mode is applicable when your application only needs the approximate location in scenarios such as when the user is browsing news, shopping online, and ordering food.<br>It mainly uses the network positioning technology and therefore the power consumption is relatively low.| 185| LOCATION_NO_POWER_CONSUMPTION | No power consumption.<br>Your application does not proactively start the location service. When responding to another application requesting the same location service, the system marks a copy of the location result to your application. | 186 187 188### Location_ResultCode 189 190``` 191enum Location_ResultCode 192``` 193**Description** 194Enumerates error codes of the location service. 195 196**Since**: 13 197 198| Value| Description| 199| -------- | -------- | 200| LOCATION_SUCCESS | Operation succeeded. | 201| LOCATION_PERMISSION_DENIED | Permission verification has failed. | 202| LOCATION_INVALID_PARAM | Parameter error.<br>Possible causes: 1. The input parameter is a null pointer. 2. The parameter value is out of the value range.| 203| LOCATION_NOT_SUPPORTED | Function not supported due to limited device capabilities. | 204| LOCATION_SERVICE_UNAVAILABLE | Location service unavailable. | 205| LOCATION_SWITCH_OFF | Location switch disabled. | 206 207 208### Location_SourceType 209 210``` 211enum Location_SourceType 212``` 213**Description** 214Defines the source of location information. 215 216**Since**: 13 217 218| Value| Description| 219| -------- | -------- | 220| LOCATION_SOURCE_TYPE_GNSS | GNSS positioning technology. | 221| LOCATION_SOURCE_TYPE_NETWORK | Network positioning technology. | 222| LOCATION_SOURCE_TYPE_INDOOR | Indoor high-precision positioning technology. | 223| LOCATION_SOURCE_TYPE_RTK | Outdoor high-precision positioning technology. | 224 225 226### Location_UseScene 227 228``` 229enum Location_UseScene 230``` 231**Description** 232Enumerates use scenes in a location request. 233 234**Since**: 13 235 236| Value| Description| 237| -------- | -------- | 238| LOCATION_USE_SCENE_NAVIGATION | Navigation scenario.<br>This option is applicable when your application needs to obtain the real-time location of a mobile device outdoors, such as navigation for driving or walking.<br>This option mainly uses the GNSS positioning technology and therefore the power consumption is relatively high.| 239| LOCATION_USE_SCENE_SPORT | Sport scenario.<br>This option is applicable when your application needs to record user trajectories, for example, the track recording function of sports applications.<br>This option mainly uses the GNSS positioning technology and therefore the power consumption is relatively high.| 240| LOCATION_USE_SCENE_TRANSPORT | Travel scenario.<br>This option is applicable to user travel scenarios, such as taxi hailing and public transportation.<br>This option mainly uses the GNSS positioning technology and therefore the power consumption is relatively high.| 241| LOCATION_USE_SCENE_DAILY_LIFE_SERVICE | Daily life services.<br>This option is applicable when your application only needs the approximate location in scenarios such as when the user is browsing news, shopping online, and ordering food.<br>It mainly uses the network positioning technology and therefore the power consumption is relatively low.| 242 243 244## Function Description 245 246 247### OH_Location_CreateRequestConfig() 248 249``` 250Location_RequestConfig* OH_Location_CreateRequestConfig (void ) 251``` 252**Description** 253Creates a **Location_RequestConfig** instance. 254 255**Since**: 13 256 257**Returns** 258 259Pointer to the [Location_RequestConfig](#location_requestconfig) instance. 260 261If **NULL** is returned, the operation has failed. The probable cause is that the application address space is full. 262 263 264### OH_Location_DestroyRequestConfig() 265 266``` 267void OH_Location_DestroyRequestConfig (Location_RequestConfig * requestConfig) 268``` 269**Description** 270Destroys the **Location_RequestConfig** instance and reclaims the memory. 271 272**Since**: 13 273 274**Parameters** 275 276| Name| Description| 277| -------- | -------- | 278| requestConfig | Pointer to the [Location_RequestConfig](#location_requestconfig) instance.<br>The instance is created by [OH_Location_CreateRequestConfig](#oh_location_createrequestconfig).| 279 280 281### OH_Location_IsLocatingEnabled() 282 283``` 284Location_ResultCode OH_Location_IsLocatingEnabled (bool * enabled) 285``` 286**Description** 287Checks whether the location switch is enabled. 288 289**Since**: 13 290 291**Parameters** 292 293| Name| Description| 294| -------- | -------- | 295| enabled | Pointer of the bool type, which is used to receive the location switch status.<br>If the value is **true**, the location switch is enabled. If the value is **false**, the location switch is disabled.<br>A non-null pointer must be passed in. Otherwise, an error is returned.| 296 297**Returns** 298 299Operation result. For details, see [Location_ResultCode](#location_resultcode). 300 301**LOCAION_SUCCESS**: The location switch status is successfully queried. 302 303**LOCATION_INVALID_PARAM**: The input parameter is a null pointer. 304 305**LOCATION_SERVICE_UNAVAILABLE**: The location switch status fails to be queried because the location service is abnormal. 306 307 308### OH_Location_StartLocating() 309 310``` 311Location_ResultCode OH_Location_StartLocating (const Location_RequestConfig * requestConfig) 312``` 313**Description** 314Starts locating and subscribes to location changes. 315 316**Since**: 13 317 318**Parameters** 319 320| Name| Description| 321| -------- | -------- | 322| requestConfig | Pointer to the **Location_RequestConfig** instance. This parameter is used to specify the location scene and location reporting interval.<br>For details, see [Location_RequestConfig](#location_requestconfig). You can use [OH_Location_CreateRequ·estConfig](#oh_location_createrequestconfig) to create a **Location_RequestConfig** instance.| 323 324**Returns** 325 326Operation result. For details, see [Location_ResultCode](#location_resultcode). 327 328**LOCAION_SUCCESS**: The location function is started successfully. 329 330**LOCATION_INVALID_PARAM**: The input parameter **requestConfig** is a null pointer. 331 332**LOCATION_PERMISSION_DENIED**: Permission verification has failed. 333 334**LOCATION_NOT_SUPPORTED**: The device does not support the location function. 335 336**LOCATION_SERVICE_UNAVAILABLE**: The location service is abnormal. 337 338**LOCATION_SWITCH_OFF**: The location function fails to be started because the location switch is disabled. 339 340**Required Permissions** 341 342ohos.permission.APPROXIMATELY_LOCATION 343 344 345### OH_Location_StopLocating() 346 347``` 348Location_ResultCode OH_Location_StopLocating (const Location_RequestConfig * requestConfig) 349``` 350**Description** 351Stops locating and unsubscribes from location changes. 352 353**Since**: 13 354 355**Parameters** 356 357| Name| Description| 358| -------- | -------- | 359| requestConfig | Pointer to the **Location_RequestConfig** instance.<br>This parameter must be the same as the pointer to **requestConfig** in [OH_Location_StartLocating](#oh_location_startlocating).<br>For details, see [Location_RequestConfig](#location_requestconfig).<br>A non-null pointer must be passed in. Otherwise, an error is returned.| 360 361**Returns** 362 363Operation result. For details, see [Location_ResultCode](#location_resultcode). 364 365**LOCAION_SUCCESS**: The location function is stopped successfully. 366 367**LOCATION_INVALID_PARAM**: The input parameter is a null pointer or is different from the **requestConfig** pointer of [OH_Location_StartLocating](#oh_location_startlocating). 368 369**LOCATION_PERMISSION_DENIED**: Permission verification has failed. 370 371**LOCATION_NOT_SUPPORTED**: The device does not support the location function. 372 373**LOCATION_SERVICE_UNAVAILABLE**: The location service is abnormal. 374 375**LOCATION_SWITCH_OFF**: The location switch is disabled. 376 377**Required Permissions** 378 379ohos.permission.APPROXIMATELY_LOCATION 380 381 382### OH_LocationInfo_GetAdditionalInfo() 383 384``` 385Location_ResultCode OH_LocationInfo_GetAdditionalInfo (Location_Info * location, char * additionalInfo, uint32_t length ) 386``` 387**Description** 388Obtains the additional information in the location information. 389 390**Since**: 13 391 392**Parameters** 393 394| Name| Description| 395| -------- | -------- | 396| location | Pointer to the [Location_Info](#location_info) instance.<br>A non-null pointer needs to be passed in. This pointer can be obtained from [Location_InfoCallback](#location_infocallback).| 397| additionalInfo | Non-null pointer of the char type. This variable is used to store the additional location information in JSON format.<br>The pointer and the corresponding memory are created by the caller. It is recommended that the memory be greater than or equal to 256 bytes.<br>If a null pointer is passed in, an error code is returned.| 398| length | Memory size of **additionalInfo**. | 399 400**Returns** 401 402Operation result. For details, see [Location_ResultCode](#location_resultcode). 403 404**LOCAION_SUCCESS**: The additional location information is successfully obtained. 405 406LOCATION_INVALID_PARAM 1. The input parameter **location** or **additionalInfo** is a null pointer. 407 4081. The value of the input parameter **length** is too small, that is, the memory size of **additionalInfo** is too small, which is unable to save the complete additional information. 409 410 411### OH_LocationInfo_GetBasicInfo() 412 413``` 414Location_BasicInfo OH_LocationInfo_GetBasicInfo (Location_Info * location) 415``` 416**Description** 417Obtains basic location information. 418 419**Since**: 13 420 421**Parameters** 422 423| Name| Description| 424| -------- | -------- | 425| location | Pointer to the [Location_Info](#location_info) instance.<br>A non-null pointer needs to be passed in. This pointer can be obtained from [Location_InfoCallback](#location_infocallback).| 426 427**Returns** 428 429Struct for the basic location information. For details, see [Location_BasicInfo](_location___basic_info.md). 430 431 432### OH_LocationRequestConfig_SetCallback() 433 434``` 435void OH_LocationRequestConfig_SetCallback (Location_RequestConfig * requestConfig, Location_InfoCallback callback, void * userData ) 436``` 437**Description** 438Sets the callback function. 439 440**Since**: 13 441 442**Parameters** 443 444| Name| Description| 445| -------- | -------- | 446| requestConfig | Pointer to the [Location_RequestConfig](#location_requestconfig) instance.<br>The instance is created by [OH_Location_CreateRequestConfig](#oh_location_createrequestconfig).| 447| callback | Pointer to the callback function, which is used to receive location information changes.<br>For details, see [Location_InfoCallback](#location_infocallback).| 448| userData | Pointer to the **userData** instance. This pointer is returned to the caller as an input parameter when the callback function is executed.| 449 450 451### OH_LocationRequestConfig_SetInterval() 452 453``` 454void OH_LocationRequestConfig_SetInterval (Location_RequestConfig * requestConfig, int interval ) 455``` 456**Description** 457Sets the location reporting interval in the location request configuration. 458 459**Since**: 13 460 461**Parameters** 462 463| Name| Description| 464| -------- | -------- | 465| requestConfig | Pointer to the [Location_RequestConfig](#location_requestconfig) instance.<br>The instance is created by [OH_Location_CreateRequestConfig](#oh_location_createrequestconfig).| 466| interval | Location reporting interval, in seconds. The value must be greater than or equal to **1**. The default value is **1**. | 467 468 469### OH_LocationRequestConfig_SetPowerConsumptionScene() 470 471``` 472void OH_LocationRequestConfig_SetPowerConsumptionScene (Location_RequestConfig * requestConfig, Location_PowerConsumptionScene powerConsumptionScene ) 473``` 474**Description** 475Sets the power consumption scene in the location request configuration. 476 477**Since**: 13 478 479**Parameters** 480 481| Name| Description| 482| -------- | -------- | 483| requestConfig | Pointer to the [Location_RequestConfig](#location_requestconfig) instance.<br>The instance is created by [OH_Location_CreateRequestConfig](#oh_location_createrequestconfig).| 484| powerConsumptionScene | Power consumption scene in the location request.<br>The default value is **LOCATION_LOW_POWER_CONSUMPTION**.<br>For details, see [Location_PowerConsumptionScene](#location_powerconsumptionscene).| 485 486 487### OH_LocationRequestConfig_SetUseScene() 488 489``` 490void OH_LocationRequestConfig_SetUseScene (Location_RequestConfig * requestConfig, Location_UseScene useScene ) 491``` 492**Description** 493Sets the use scene in the location request configuration. 494 495**useScene** takes precedence over **powerConsumptionScene** in [Location_RequestConfig](#location_requestconfig). 496 497If **useScene** is set, **powerConsumptionScene** is invalid. 498 499Otherwise, **powerConsumptionScene** takes effect. 500 501If neither of the two parameters is set, **useScene** is set to **LOCATION_USE_SCENE_DAILY_LIFE_SERVICE** by default, 502 503and **powerConsumptionScene** is invalid. 504 505**Since**: 13 506 507**Parameters** 508 509| Name| Description| 510| -------- | -------- | 511| requestConfig | Pointer to the [Location_RequestConfig](#location_requestconfig) instance.<br>The instance is created by [OH_Location_CreateRequestConfig](#oh_location_createrequestconfig).| 512| useScene | Use scene in the location request.<br>The default value is **LOCATION_USE_SCENE_DAILY_LIFE_SERVICE**.<br>For details, see [Location_UseScene](#location_usescene).| 513