1# Location 2 3 4## 概述 5 6提供用于查询位置开关状态、启动和停止定位的功能。 7 8**起始版本：** 13 9 10 11## 汇总 12 13 14### 文件 15 16| 名称 | 描述 | 17| -------- | -------- | 18| [oh_location.h](oh__location_8h.md) | 定义查询位置开关状态、启动定位、停止定位的接口。 | 19| [oh_location_type.h](oh__location__type_8h.md) | 定义位置服务常用的属性。 | 20 21 22### 结构体 23 24| 名称 | 描述 | 25| -------- | -------- | 26| struct [Location_BasicInfo](_location___basic_info.md) | 定义位置基本信息的结构体。 | 27 28 29### 类型定义 30 31| 名称 | 描述 | 32| -------- | -------- | 33| typedef enum [Location_ResultCode](#location_resultcode-1) [Location_ResultCode](#location_resultcode) | 定义位置服务的错误码。 | 34| typedef enum [Location_UseScene](#location_usescene-1) [Location_UseScene](#location_usescene) | 定义位置请求中的用户活动场景类型。 | 35| typedef enum [Location_PowerConsumptionScene](#location_powerconsumptionscene-1) [Location_PowerConsumptionScene](#location_powerconsumptionscene) | 定义位置请求中的功耗场景类型。 | 36| typedef enum [Location_SourceType](#location_sourcetype-1) [Location_SourceType](#location_sourcetype) | 定义位置信息的来源。 | 37| typedef struct [Location_BasicInfo](_location___basic_info.md) [Location_BasicInfo](#location_basicinfo) | 定义位置基本信息的结构体。 | 38| typedef struct [Location_Info](#location_info) [Location_Info](#location_info) | 定义位置信息的结构体。 | 39| typedef void(\* [Location_InfoCallback](#location_infocallback)) ([Location_Info](#location_info) \*location, void \*userData) | 用于接收位置上报的回调函数。 | 40| typedef struct [Location_RequestConfig](#location_requestconfig) [Location_RequestConfig](#location_requestconfig) | 定义位置请求参数的结构体。 | 41 42 43### 枚举 44 45| 名称 | 描述 | 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/>} | 定义位置服务的错误码。 | 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 } | 定义位置请求中的用户活动场景类型。 | 49| [Location_PowerConsumptionScene](#location_powerconsumptionscene-1) { LOCATION_HIGH_POWER_CONSUMPTION = 0x0601, LOCATION_LOW_POWER_CONSUMPTION = 0x0602, LOCATION_NO_POWER_CONSUMPTION = 0x0603 } | 定义位置请求中的功耗场景类型。 | 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 } | 定义位置信息的来源。 | 51 52 53### 函数 54 55| 名称 | 描述 | 56| -------- | -------- | 57| [Location_ResultCode](#location_resultcode-1) [OH_Location_IsLocatingEnabled](#oh_location_islocatingenabled) (bool \*enabled) | 查询位置开关是否开启。 | 58| [Location_ResultCode](#location_resultcode-1) [OH_Location_StartLocating](#oh_location_startlocating) (const [Location_RequestConfig](#location_requestconfig) \*requestConfig) | 启动定位并订阅位置变化。 | 59| [Location_ResultCode](#location_resultcode-1) [OH_Location_StopLocating](#oh_location_stoplocating) (const [Location_RequestConfig](#location_requestconfig) \*requestConfig) | 停止定位并取消订阅位置变化。 | 60| [Location_BasicInfo](_location___basic_info.md) [OH_LocationInfo_GetBasicInfo](#oh_locationinfo_getbasicinfo) ([Location_Info](#location_info) \*location) | 获取位置基本信息。 | 61| [Location_ResultCode](#location_resultcode-1) [OH_LocationInfo_GetAdditionalInfo](#oh_locationinfo_getadditionalinfo) ([Location_Info](#location_info) \*location, char \*additionalInfo, uint32_t length) | 获取位置信息中的附加信息。 | 62| [Location_RequestConfig](#location_requestconfig) \* [OH_Location_CreateRequestConfig](#oh_location_createrequestconfig) (void) | 创建一个位置请求参数结构体实例。 | 63| void [OH_Location_DestroyRequestConfig](#oh_location_destroyrequestconfig) ([Location_RequestConfig](#location_requestconfig) \*requestConfig) | 销毁位置请求参数实例并回收内存。 | 64| void [OH_LocationRequestConfig_SetUseScene](#oh_locationrequestconfig_setusescene) ([Location_RequestConfig](#location_requestconfig) \*requestConfig, [Location_UseScene](#location_usescene) useScene) | 设置位置请求参数中的用户活动场景。<br/>位置请求参数[Location_RequestConfig](#location_requestconfig)中以useScene优先。<br/>如果设置了useScene，则powerConsumptionScene参数无效。<br/>如果未设置useScene，设置了powerConsumptionScene则该参数生效。<br/>如果两个参数都未设置，则默认useScene为LOCATION_USE_SCENE_DAILY_LIFE_SERVICE，<br/>powerConsumptionScene参数无效。 | 65| void [OH_LocationRequestConfig_SetPowerConsumptionScene](#oh_locationrequestconfig_setpowerconsumptionscene) ([Location_RequestConfig](#location_requestconfig) \*requestConfig, [Location_PowerConsumptionScene](#location_powerconsumptionscene) powerConsumptionScene) | 设置位置请求参数中的功耗场景。 | 66| void [OH_LocationRequestConfig_SetInterval](#oh_locationrequestconfig_setinterval) ([Location_RequestConfig](#location_requestconfig) \*requestConfig, int interval) | 设置位置请求参数中的位置上报间隔。 | 67| void [OH_LocationRequestConfig_SetCallback](#oh_locationrequestconfig_setcallback) ([Location_RequestConfig](#location_requestconfig) \*requestConfig, [Location_InfoCallback](#location_infocallback) callback, void \*userData) | 设置回调函数。 | 68 69 70## 类型定义说明 71 72 73### Location_BasicInfo 74 75``` 76typedef struct Location_BasicInfo Location_BasicInfo 77``` 78**描述** 79定义位置基本信息的结构体。 80 81**起始版本：** 13 82 83 84### Location_Info 85 86``` 87typedef struct Location_Info Location_Info 88``` 89**描述** 90定义位置信息的结构体。 91 92**起始版本：** 13 93 94 95### Location_InfoCallback 96 97``` 98typedef void(* Location_InfoCallback) (Location_Info *location, void *userData) 99``` 100**描述** 101用于接收位置上报的回调函数。 102 103**起始版本：** 13 104 105**参数:** 106 107| 名称 | 描述 | 108| -------- | -------- | 109| location | - 指向[Location_Info](#location_info)实例的指针，携带最新的位置信息。<br/>location实例的内存会在[Location_InfoCallback](#location_infocallback)结束时回收，<br/>请在此之前调用[OH_LocationInfo_GetBasicInfo](#oh_locationinfo_getbasicinfo)等接口获取位置信息。 | 110| userData | - 指向调用者数据结构或对象的指针，该参数是通过[OH_LocationRequestConfig_SetCallback](#oh_locationrequestconfig_setcallback)传入的。 | 111 112 113### Location_PowerConsumptionScene 114 115``` 116typedef enum Location_PowerConsumptionScene Location_PowerConsumptionScene 117``` 118**描述** 119定义位置请求中的功耗场景类型。 120 121**起始版本：** 13 122 123 124### Location_RequestConfig 125 126``` 127typedef struct Location_RequestConfig Location_RequestConfig 128``` 129**描述** 130定义位置请求参数的结构体。 131 132**起始版本：** 13 133 134 135### Location_ResultCode 136 137``` 138typedef enum Location_ResultCode Location_ResultCode 139``` 140**描述** 141定义位置服务的错误码。 142 143**起始版本：** 13 144 145 146### Location_SourceType 147 148``` 149typedef enum Location_SourceType Location_SourceType 150``` 151**描述** 152定义位置信息的来源。 153 154**起始版本：** 13 155 156 157### Location_UseScene 158 159``` 160typedef enum Location_UseScene Location_UseScene 161``` 162**描述** 163定义位置请求中的用户活动场景类型。 164 165**起始版本：** 13 166 167 168## 枚举类型说明 169 170 171### Location_PowerConsumptionScene 172 173``` 174enum Location_PowerConsumptionScene 175``` 176**描述** 177定义位置请求中的功耗场景类型。 178 179**起始版本：** 13 180 181| 枚举值 | 描述 | 182| -------- | -------- | 183| LOCATION_HIGH_POWER_CONSUMPTION | 高功耗。<br/>以GNSS定位技术为主。在GNSS提供稳定位置结果之前会使用网络定位技术提供服务；<br/>在持续定位时，如果超过30秒无法获取GNSS定位结果则会使用网络定位技术获取位置。<br/>对设备的硬件资源消耗较大，功耗较大。 | 184| LOCATION_LOW_POWER_CONSUMPTION | 低功耗。<br/>适用于对用户位置精度要求不高的使用场景，如新闻资讯、网购、点餐类应用。<br/>该场景仅使用网络定位技术提供定位服务，功耗较低。 | 185| LOCATION_NO_POWER_CONSUMPTION | 无功耗。<br/>这种场景下不会主动触发定位，会在其他应用定位时，才给当前应用返回位置。 | 186 187 188### Location_ResultCode 189 190``` 191enum Location_ResultCode 192``` 193**描述** 194定义位置服务的错误码。 195 196**起始版本：** 13 197 198| 枚举值 | 描述 | 199| -------- | -------- | 200| LOCATION_SUCCESS | 操作成功。 | 201| LOCATION_PERMISSION_DENIED | 权限校验失败。 | 202| LOCATION_INVALID_PARAM | 参数错误。<br/>可能原因：1.输入参数为空指针；2.参数数值超出定义范围。 | 203| LOCATION_NOT_SUPPORTED | 该功能不支持。由于设备能力有限，无法调用该函数。 | 204| LOCATION_SERVICE_UNAVAILABLE | 位置服务不可用。 | 205| LOCATION_SWITCH_OFF | 位置开关处于关闭状态。 | 206 207 208### Location_SourceType 209 210``` 211enum Location_SourceType 212``` 213**描述** 214定义位置信息的来源。 215 216**起始版本：** 13 217 218| 枚举值 | 描述 | 219| -------- | -------- | 220| LOCATION_SOURCE_TYPE_GNSS | 表示定位结果来自于GNSS定位技术。 | 221| LOCATION_SOURCE_TYPE_NETWORK | 表示定位结果来自于网络定位技术。 | 222| LOCATION_SOURCE_TYPE_INDOOR | 表示定位结果来自于室内高精度定位技术。 | 223| LOCATION_SOURCE_TYPE_RTK | 表示定位结果来自于室外高精度定位技术。 | 224 225 226### Location_UseScene 227 228``` 229enum Location_UseScene 230``` 231**描述** 232定义位置请求中的用户活动场景类型。 233 234**起始版本：** 13 235 236| 枚举值 | 描述 | 237| -------- | -------- | 238| LOCATION_USE_SCENE_NAVIGATION | 导航场景。<br/>适用于在户外获取设备实时位置的场景，如车载、步行导航。<br/>主要使用GNSS定位技术提供定位服务，功耗较高。 | 239| LOCATION_USE_SCENE_SPORT | 表示运动场景。<br/>适用于记录用户位置轨迹的场景，如运动类应用记录轨迹功能。<br/>主要使用GNSS定位技术提供定位服务，功耗较高。 | 240| LOCATION_USE_SCENE_TRANSPORT | 表示出行场景。<br/>适用于用户出行场景，如打车、乘坐公共交通等场景。<br/>主要使用GNSS定位技术提供定位服务，功耗较高。 | 241| LOCATION_USE_SCENE_DAILY_LIFE_SERVICE | 表示日常服务使用场景。<br/>适用于不需要定位用户精确位置的使用场景，如新闻资讯、网购、点餐类应用。<br/>该场景仅使用网络定位技术提供定位服务，功耗较低。 | 242 243 244## 函数说明 245 246 247### OH_Location_CreateRequestConfig() 248 249``` 250Location_RequestConfig* OH_Location_CreateRequestConfig (void ) 251``` 252**描述** 253创建一个位置请求参数结构体实例。 254 255**起始版本：** 13 256 257**返回：** 258 259返回指向[Location_RequestConfig](#location_requestconfig)实例的指针。 260 261如果返回NULL表示创建失败，可能的原因是应用地址空间满，导致空间分配不出来。 262 263 264### OH_Location_DestroyRequestConfig() 265 266``` 267void OH_Location_DestroyRequestConfig (Location_RequestConfig * requestConfig) 268``` 269**描述** 270销毁位置请求参数实例并回收内存。 271 272**起始版本：** 13 273 274**参数:** 275 276| 名称 | 描述 | 277| -------- | -------- | 278| requestConfig | - 指向[Location_RequestConfig](#location_requestconfig)实例的指针。<br/>该实例是由[OH_Location_CreateRequestConfig](#oh_location_createrequestconfig)创建的。 | 279 280 281### OH_Location_IsLocatingEnabled() 282 283``` 284Location_ResultCode OH_Location_IsLocatingEnabled (bool * enabled) 285``` 286**描述** 287查询位置开关是否开启。 288 289**起始版本：** 13 290 291**参数:** 292 293| 名称 | 描述 | 294| -------- | -------- | 295| enabled | - bool类型的指针，用于接收位置开关状态值。<br/>等于true表示位置开关开启，false表示位置开关关闭。<br/>需要传入非空指针，否则会返回错误。 | 296 297**返回：** 298 299返回操作结果，详细定义参见[Location_ResultCode](#location_resultcode)。 300 301**LOCAION_SUCCESS** 查询位置开关状态成功。 302 303LOCATION_INVALID_PARAM 入参是空指针。 304 305LOCATION_SERVICE_UNAVAILABLE 位置服务运行异常导致查询位置开关状态失败。 306 307 308### OH_Location_StartLocating() 309 310``` 311Location_ResultCode OH_Location_StartLocating (const Location_RequestConfig * requestConfig) 312``` 313**描述** 314启动定位并订阅位置变化。 315 316**起始版本：** 13 317 318**参数:** 319 320| 名称 | 描述 | 321| -------- | -------- | 322| requestConfig | - 指向定位请求参数的指针，该参数用于指定发起定位的场景信息和位置上报间隔。<br/>详细定义请参考[Location_RequestConfig](#location_requestconfig)，可以使用[OH_Location_CreateRequestConfig](#oh_location_createrequestconfig)创建。 | 323 324**返回：** 325 326返回操作结果，详细定义参见[Location_ResultCode](#location_resultcode)。 327 328**LOCAION_SUCCESS** 启动定位成功。 329 330LOCATION_INVALID_PARAM 入参requestConfig为空指针。 331 332LOCATION_PERMISSION_DENIED 权限校验失败。 333 334LOCATION_NOT_SUPPORTED 当前设备不支持该功能。 335 336LOCATION_SERVICE_UNAVAILABLE 位置服务运行异常。 337 338LOCATION_SWITCH_OFF 位置开关未打开导致无法启动定位。 339 340**Permission：** 341 342ohos.permission.APPROXIMATELY_LOCATION 343 344 345### OH_Location_StopLocating() 346 347``` 348Location_ResultCode OH_Location_StopLocating (const Location_RequestConfig * requestConfig) 349``` 350**描述** 351停止定位并取消订阅位置变化。 352 353**起始版本：** 13 354 355**参数:** 356 357| 名称 | 描述 | 358| -------- | -------- | 359| requestConfig | - 指向定位请求参数的指针。<br/>该参数需要与[OH_Location_StartLocating](#oh_location_startlocating)中的requestConfig是同一个指针。<br/>详细定义请参考[Location_RequestConfig](#location_requestconfig)。<br/>需要传入非空指针，否则会返回错误。 | 360 361**返回：** 362 363返回操作结果，详细定义参见[Location_ResultCode](#location_resultcode)。 364 365**LOCAION_SUCCESS** 停止定位成功。 366 367LOCATION_INVALID_PARAM 1. 入参为空指针。 368 3691. 入参与[OH_Location_StartLocating](#oh_location_startlocating)的requestConfig指针不同。 370 371 LOCATION_PERMISSION_DENIED 权限校验失败。 372 373 LOCATION_NOT_SUPPORTED 当前设备不支持该功能。 374 375 LOCATION_SERVICE_UNAVAILABLE 位置服务运行异常。 376 377 LOCATION_SWITCH_OFF 位置开关未打开。 378 379**Permission：** 380 381ohos.permission.APPROXIMATELY_LOCATION 382 383 384### OH_LocationInfo_GetAdditionalInfo() 385 386``` 387Location_ResultCode OH_LocationInfo_GetAdditionalInfo (Location_Info * location, char * additionalInfo, uint32_t length ) 388``` 389**描述** 390获取位置信息中的附加信息。 391 392**起始版本：** 13 393 394**参数:** 395 396| 名称 | 描述 | 397| -------- | -------- | 398| location | - 指向位置信息结构体的指针。<br/>需要传入非空指针，该指针可以在[Location_InfoCallback](#location_infocallback)中获取。 | 399| additionalInfo | - char类型的非空指针；该变量用于保存附加信息字符串，该字符串是JSON格式。<br/>该指针和对应的内存由调用者创建，建议申请大于等于256字节的内存。<br/>如果传入空指针，会返回错误码。 | 400| length | - 表示additionalInfo的内存大小。 | 401 402**返回：** 403 404返回操作结果，详细定义参见[Location_ResultCode](#location_resultcode)。 405 406**LOCAION_SUCCESS** 获取附加信息成功。 407 408LOCATION_INVALID_PARAM 1. 入参location或additionalInfo是空指针。 409 4101. 入参length太小，也就是additionalInfo指向的内存太小导致无法保存完整的附加信息字符串。 411 412 413### OH_LocationInfo_GetBasicInfo() 414 415``` 416Location_BasicInfo OH_LocationInfo_GetBasicInfo (Location_Info * location) 417``` 418**描述** 419获取位置基本信息。 420 421**起始版本：** 13 422 423**参数:** 424 425| 名称 | 描述 | 426| -------- | -------- | 427| location | - 指向位置信息结构体的指针。<br/>需要传入非空指针，该指针可以在[Location_InfoCallback](#location_infocallback)中获取。 | 428 429**返回：** 430 431返回位置基本信息结构体。详细定义请参考[Location_BasicInfo](_location___basic_info.md)。 432 433 434### OH_LocationRequestConfig_SetCallback() 435 436``` 437void OH_LocationRequestConfig_SetCallback (Location_RequestConfig * requestConfig, Location_InfoCallback callback, void * userData ) 438``` 439**描述** 440设置回调函数。 441 442**起始版本：** 13 443 444**参数:** 445 446| 名称 | 描述 | 447| -------- | -------- | 448| requestConfig | - 指向[Location_RequestConfig](#location_requestconfig)实例的指针。<br/>该实例是由[OH_Location_CreateRequestConfig](#oh_location_createrequestconfig)创建的。 | 449| callback | - 指向回调函数的指针，该回调函数用于接收位置信息变化。<br/>详细定义请参考[Location_InfoCallback](#location_infocallback)。 | 450| userData | - 指向调用者数据结构或对象的指针。这个指针会在回调函数执行时作为入参回传给调用者。 | 451 452 453### OH_LocationRequestConfig_SetInterval() 454 455``` 456void OH_LocationRequestConfig_SetInterval (Location_RequestConfig * requestConfig, int interval ) 457``` 458**描述** 459设置位置请求参数中的位置上报间隔。 460 461**起始版本：** 13 462 463**参数:** 464 465| 名称 | 描述 | 466| -------- | -------- | 467| requestConfig | - 指向[Location_RequestConfig](#location_requestconfig)实例的指针。<br/>该实例是由[OH_Location_CreateRequestConfig](#oh_location_createrequestconfig)创建的。 | 468| interval | - 表示位置上报时间间隔，单位是“秒”。取值范围为大于等于1，默认值为1。 | 469 470 471### OH_LocationRequestConfig_SetPowerConsumptionScene() 472 473``` 474void OH_LocationRequestConfig_SetPowerConsumptionScene (Location_RequestConfig * requestConfig, Location_PowerConsumptionScene powerConsumptionScene ) 475``` 476**描述** 477设置位置请求参数中的功耗场景。 478 479**起始版本：** 13 480 481**参数:** 482 483| 名称 | 描述 | 484| -------- | -------- | 485| requestConfig | - 指向[Location_RequestConfig](#location_requestconfig)实例的指针。<br/>该实例是由[OH_Location_CreateRequestConfig](#oh_location_createrequestconfig)创建的。 | 486| powerConsumptionScene | - 表示位置请求的功耗场景。<br/>默认值是LOCATION_LOW_POWER_CONSUMPTION。<br/>详细定义见[Location_PowerConsumptionScene](#location_powerconsumptionscene)。 | 487 488 489### OH_LocationRequestConfig_SetUseScene() 490 491``` 492void OH_LocationRequestConfig_SetUseScene (Location_RequestConfig * requestConfig, Location_UseScene useScene ) 493``` 494**描述** 495设置位置请求参数中的用户活动场景。 496 497位置请求参数[Location_RequestConfig](#location_requestconfig)中以useScene优先。 498 499如果设置了useScene，则powerConsumptionScene参数无效。 500 501如果未设置useScene，设置了powerConsumptionScene则该参数生效。 502 503如果两个参数都未设置，则默认useScene为LOCATION_USE_SCENE_DAILY_LIFE_SERVICE， 504 505powerConsumptionScene参数无效。 506 507**起始版本：** 13 508 509**参数:** 510 511| 名称 | 描述 | 512| -------- | -------- | 513| requestConfig | - 指向[Location_RequestConfig](#location_requestconfig)实例的指针。<br/>该实例是由[OH_Location_CreateRequestConfig](#oh_location_createrequestconfig)创建的。 | 514| useScene | - 表示位置请求时的用户活动场景。<br/>默认值是LOCATION_USE_SCENE_DAILY_LIFE_SERVICE。<br/>详细定义见[Location_UseScene](#location_usescene)。 | 515