openharmony 鸿蒙 capi-oh-location-type-h

2026-08-25 浏览 (1)

oh_location_type.h

概述

定义位置服务常用的属性。

引用文件： <LocationKit/oh_location_type.h>

库： liblocation_ndk.so

系统能力： SystemCapability.Location.Location.Core

起始版本： 13

相关模块： Location

汇总

结构体

名称typedef关键字描述
Location_BasicInfoLocation_BasicInfo定义位置基本信息的结构体。
Location_InfoLocation_Info定义位置信息的结构体。
Location_RequestConfigLocation_RequestConfig定义位置请求参数的结构体。

枚举

名称typedef关键字描述
Location_ResultCodeLocation_ResultCode定义位置服务的错误码。
Location_UseSceneLocation_UseScene定义位置请求中的用户活动场景类型。
Location_PowerConsumptionSceneLocation_PowerConsumptionScene定义位置请求中的功耗场景类型。
Location_SourceTypeLocation_SourceType定义位置信息的来源。

函数

名称typedef关键字描述
Location_BasicInfo OH_LocationInfo_GetBasicInfo(Location_Info* location)-获取位置基本信息。
Location_ResultCode OH_LocationInfo_GetAdditionalInfo(Location_Info* location, char* additionalInfo, uint32_t length)-获取位置信息中的附加信息。
typedef void (*Location_InfoCallback)(Location_Info* location, void* userData)Location_InfoCallback用于接收位置上报的回调函数。
Location_RequestConfig* OH_Location_CreateRequestConfig(void)-创建一个位置请求参数结构体实例。
void OH_Location_DestroyRequestConfig(Location_RequestConfig* requestConfig)-销毁位置请求参数实例并回收内存。
void OH_LocationRequestConfig_SetUseScene(Location_RequestConfig* requestConfig, Location_UseScene useScene)-设置位置请求参数中的用户活动场景。
位置请求参数Location_RequestConfig中以useScene优先。
如果设置了useScene，则powerConsumptionScene参数无效。
如果未设置useScene，设置了powerConsumptionScene则该参数生效。
如果两个参数都未设置，则默认useScene为LOCATION_USE_SCENE_DAILY_LIFE_SERVICE，powerConsumptionScene参数无效。
void OH_LocationRequestConfig_SetPowerConsumptionScene(Location_RequestConfig* requestConfig, Location_PowerConsumptionScene powerConsumptionScene)-设置位置请求参数中的功耗场景。
void OH_LocationRequestConfig_SetInterval(Location_RequestConfig* requestConfig, int interval)-设置位置请求参数中的位置上报间隔。
void OH_LocationRequestConfig_SetCallback(Location_RequestConfig* requestConfig, Location_InfoCallback callback, void* userData)-设置回调函数。

枚举类型说明

Location_ResultCode

enum Location_ResultCode

描述

定义位置服务的错误码。

起始版本： 13

枚举项描述
LOCATION_SUCCESS = 0操作成功。
LOCATION_PERMISSION_DENIED = 201权限校验失败。
LOCATION_INVALID_PARAM = 401参数错误。
可能原因：1.输入参数为空指针；2.参数数值超出定义范围。
LOCATION_NOT_SUPPORTED = 801该功能不支持。由于设备能力有限，无法调用该函数。
LOCATION_SERVICE_UNAVAILABLE = 3301000位置服务不可用。
LOCATION_SWITCH_OFF = 3301100位置开关处于关闭状态。

Location_UseScene

enum Location_UseScene

描述

定义位置请求中的用户活动场景类型。

起始版本： 13

枚举项描述
LOCATION_USE_SCENE_NAVIGATION = 0x0401导航场景。
适用于在户外获取设备实时位置的场景，如车载、步行导航。
主要使用GNSS定位技术提供定位服务，功耗较高。
LOCATION_USE_SCENE_SPORT = 0x0402表示运动场景。
适用于记录用户位置轨迹的场景，如运动类应用记录轨迹功能。
主要使用GNSS定位技术提供定位服务，功耗较高。
LOCATION_USE_SCENE_TRANSPORT = 0x0403表示出行场景。
适用于用户出行场景，如打车、乘坐公共交通等场景。
主要使用GNSS定位技术提供定位服务，功耗较高。
LOCATION_USE_SCENE_DAILY_LIFE_SERVICE = 0x0404表示日常服务使用场景。
适用于不需要定位用户精确位置的使用场景，如新闻资讯、网购、点餐类应用。
该场景仅使用网络定位技术提供定位服务，功耗较低。

Location_PowerConsumptionScene

enum Location_PowerConsumptionScene

描述

定义位置请求中的功耗场景类型。

起始版本： 13

枚举项描述
LOCATION_HIGH_POWER_CONSUMPTION = 0x0601高功耗。
以GNSS定位技术为主。在GNSS提供稳定位置结果之前会使用网络定位技术提供服务。
在持续定位时，如果超过30秒无法获取GNSS定位结果则会使用网络定位技术获取位置。
对设备的硬件资源消耗较大，功耗较大。
LOCATION_LOW_POWER_CONSUMPTION = 0x0602低功耗。
适用于对用户位置精度要求不高的使用场景，如新闻资讯、网购、点餐类应用。
该场景仅使用网络定位技术提供定位服务，功耗较低。
LOCATION_NO_POWER_CONSUMPTION = 0x0603无功耗。
这种场景下不会主动触发定位，会在其他应用定位时，才给当前应用返回位置。

Location_SourceType

enum Location_SourceType

描述

定义位置信息的来源。

起始版本： 13

枚举项描述
LOCATION_SOURCE_TYPE_GNSS = 1表示定位结果来自于GNSS定位技术。
LOCATION_SOURCE_TYPE_NETWORK = 2表示定位结果来自于网络定位技术。
LOCATION_SOURCE_TYPE_INDOOR = 3表示定位结果来自于室内高精度定位技术。
LOCATION_SOURCE_TYPE_RTK = 4表示定位结果来自于室外高精度定位技术。

函数说明

OH_LocationInfo_GetBasicInfo()

Location_BasicInfo OH_LocationInfo_GetBasicInfo(Location_Info* location)

描述

获取位置基本信息。

起始版本： 13

参数：

参数项描述
Location_Info* location指向位置信息结构体的指针。
需要传入非空指针，该指针可以在Location_InfoCallback中获取。

返回：

类型说明
Location_BasicInfo返回位置基本信息结构体。详细定义请参考Location_BasicInfo。

OH_LocationInfo_GetAdditionalInfo()

Location_ResultCode OH_LocationInfo_GetAdditionalInfo(Location_Info* location, char* additionalInfo, uint32_t length)

描述

获取位置信息中的附加信息。

起始版本： 13

参数：

参数项描述
Location_Info* location指向位置信息结构体的指针。
需要传入非空指针，该指针可以在Location_InfoCallback中获取。
char* additionalInfochar类型的非空指针；该变量用于保存附加信息字符串，该字符串是JSON格式。
该指针和对应的内存由调用者创建，建议申请大于等于256字节的内存。
如果传入空指针，会返回错误码。
uint32_t length表示additionalInfo的内存大小。

返回：

类型说明
Location_ResultCode返回操作结果，详细定义参见Location_ResultCode。
LOCATION_SUCCESS 获取附加信息成功。
LOCATION_INVALID_PARAM 1. 入参location或additionalInfo是空指针。
2. 入参length太小，也就是additionalInfo指向的内存太小导致无法保存完整的附加信息字符串。

Location_InfoCallback()

typedef void (*Location_InfoCallback)(Location_Info* location, void* userData)

描述

用于接收位置上报的回调函数。

起始版本： 13

参数：

参数项描述
Location_Info* location指向Location_Info实例的指针，携带最新的位置信息。
location实例的内存会在Location_InfoCallback结束时回收，请在此之前调用OH_LocationInfo_GetBasicInfo等接口获取位置信息。
void* userData指向调用者数据结构或对象的指针，该参数是通过OH_LocationRequestConfig_SetCallback传入的。

OH_Location_CreateRequestConfig()

Location_RequestConfig* OH_Location_CreateRequestConfig(void)

描述

创建一个位置请求参数结构体实例。

起始版本： 13

返回：

类型说明
Location_RequestConfig*返回指向Location_RequestConfig实例的指针。
如果返回NULL表示创建失败，可能的原因是应用地址空间满，导致空间分配不出来。

OH_Location_DestroyRequestConfig()

void OH_Location_DestroyRequestConfig(Location_RequestConfig* requestConfig)

描述

销毁位置请求参数实例并回收内存。

起始版本： 13

参数：

参数项描述
Location_RequestConfig* requestConfig指向Location_RequestConfig实例的指针。
该实例是由OH_Location_CreateRequestConfig创建的。

OH_LocationRequestConfig_SetUseScene()

void OH_LocationRequestConfig_SetUseScene(Location_RequestConfig* requestConfig, Location_UseScene useScene)

描述

设置位置请求参数中的用户活动场景。
位置请求参数Location_RequestConfig中以useScene优先。
如果设置了useScene，则powerConsumptionScene参数无效。
如果未设置useScene，设置了powerConsumptionScene则该参数生效。
如果两个参数都未设置，则默认useScene为LOCATION_USE_SCENE_DAILY_LIFE_SERVICE，powerConsumptionScene参数无效。

起始版本： 13

参数：

参数项描述
Location_RequestConfig* requestConfig指向Location_RequestConfig实例的指针。
该实例是由OH_Location_CreateRequestConfig创建的。
Location_UseScene useScene表示位置请求时的用户活动场景。
默认值是LOCATION_USE_SCENE_DAILY_LIFE_SERVICE。
详细定义见Location_UseScene。

OH_LocationRequestConfig_SetPowerConsumptionScene()

void OH_LocationRequestConfig_SetPowerConsumptionScene(Location_RequestConfig* requestConfig, Location_PowerConsumptionScene powerConsumptionScene)

描述

设置位置请求参数中的功耗场景。

起始版本： 13

参数：

参数项描述
Location_RequestConfig* requestConfig指向Location_RequestConfig实例的指针。
该实例是由OH_Location_CreateRequestConfig创建的。
Location_PowerConsumptionScene powerConsumptionScene表示位置请求的功耗场景。
默认值是LOCATION_LOW_POWER_CONSUMPTION。
详细定义见Location_PowerConsumptionScene。

OH_LocationRequestConfig_SetInterval()

void OH_LocationRequestConfig_SetInterval(Location_RequestConfig* requestConfig, int interval)

描述

设置位置请求参数中的位置上报间隔。

起始版本： 13

参数：

参数项描述
Location_RequestConfig* requestConfig指向Location_RequestConfig实例的指针。
该实例是由OH_Location_CreateRequestConfig创建的。
int interval表示位置上报时间间隔，单位是“秒”。取值范围为大于等于1，默认值为1。

OH_LocationRequestConfig_SetCallback()

void OH_LocationRequestConfig_SetCallback(Location_RequestConfig* requestConfig, Location_InfoCallback callback, void* userData)

描述

设置回调函数。

起始版本： 13

参数：

参数项描述
Location_RequestConfig* requestConfig指向Location_RequestConfig实例的指针。
该实例是由OH_Location_CreateRequestConfig创建的。
Location_InfoCallback callback指向回调函数的指针，该回调函数用于接收位置信息变化。
详细定义请参考Location_InfoCallback。
void* userData指向调用者数据结构或对象的指针。这个指针会在回调函数执行时作为入参回传给调用者。

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 errorcode-geoLocationManager

openharmony 鸿蒙 js-apis-system-location

openharmony 鸿蒙 capi-location-location-basicinfo

openharmony 鸿蒙 Readme-CN

openharmony 鸿蒙 js-apis-geoLocationManager

openharmony 鸿蒙 js-apis-app-ability-FenceExtensionAbility

openharmony 鸿蒙 capi-location-location-requestconfig

openharmony 鸿蒙 capi-location-location-info

openharmony 鸿蒙 js-apis-app-ability-FenceExtensionContext

openharmony 鸿蒙 capi-location

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/Ek2Lbh8i