oh_location_type.h

Overview

Defines common attributes of the location service.

Reference file: <LocationKit/oh_location_type.h>

Library: liblocation_ndk.so

System capability: SystemCapability.Location.Location.Core

Since: 13

Related module: [Location] (capi-location.md)

Summary

Structs

Name	typedef Keyword	Description
Location_BasicInfo	Location_BasicInfo	Defines the struct for the basic location information.
Location_Info	Location_Info	Defines the struct for the location information.
Location_RequestConfig	Location_RequestConfig	Defines the struct for the location request configuration.

Enums

Name	typedef Keyword	Description
Location_ResultCode	Location_ResultCode	Enumerates error codes of the location service.
Location_UseScene	Location_UseScene	Enumerates use scenes in a location request.
Location_PowerConsumptionScene	Location_PowerConsumptionScene	Enumerates power consumption scenarios in a location request.
Location_SourceType	Location_SourceType	Defines the source of location information.

Functions

Name	typedef Keyword	Description
Location_BasicInfo OH_LocationInfo_GetBasicInfo(Location_Info* location)	-	Obtains basic location information.
Location_ResultCode OH_LocationInfo_GetAdditionalInfo(Location_Info* location, char* additionalInfo, uint32_t length)	-	Obtains the additional information in the location information.
typedef void (Location_InfoCallback)(Location_Info location, void* userData)	Location_InfoCallback	Defines the callback for receiving reported location information.
Location_RequestConfig* OH_Location_CreateRequestConfig(void)	-	Creates a Location_RequestConfig instance.
void OH_Location_DestroyRequestConfig(Location_RequestConfig* requestConfig)	-	Destroys the Location_RequestConfig instance and reclaims the memory.
void OH_LocationRequestConfig_SetUseScene(Location_RequestConfig* requestConfig, Location_UseScene useScene)	-	Sets the use scene in the location request configuration. useScene takes precedence over powerConsumptionScene in Location_RequestConfig. If useScene is set, powerConsumptionScene is invalid. Otherwise, powerConsumptionScene takes effect. If neither of the two parameters is set, the default value of useScene is LOCATION_USE_SCENE_DAILY_LIFE_SERVICE and powerConsumptionScene is invalid.
void OH_LocationRequestConfig_SetPowerConsumptionScene(Location_RequestConfig* requestConfig, Location_PowerConsumptionScene powerConsumptionScene)	-	Sets the power consumption scene in the location request configuration.
void OH_LocationRequestConfig_SetInterval(Location_RequestConfig* requestConfig, int interval)	-	Sets the location reporting interval in the location request configuration.
void OH_LocationRequestConfig_SetCallback(Location_RequestConfig* requestConfig, Location_InfoCallback callback, void* userData)	-	Sets the callback function.

Enum Description

Location_ResultCode

enum Location_ResultCode

Description

Enumerates error codes of the location service.

Since: 13

Enum Item	Description
LOCATION_SUCCESS = 0	Operation success.
LOCATION_PERMISSION_DENIED = 201	Permission denied.
LOCATION_INVALID_PARAM = 401	The parameter is invalid. Possible causes: 1. The input parameter is a null pointer. 2. The parameter value is out of the value range.
LOCATION_NOT_SUPPORTED = 801	Function not supported. due to limited device capabilities.
LOCATION_SERVICE_UNAVAILABLE = 3301000	Location service unavailable.
LOCATION_SWITCH_OFF = 3301100	Location switch disabled.

Location_UseScene

enum Location_UseScene

Description

Enumerates use scenes in a location request.

Since: 13

Enum Item	Description
LOCATION_USE_SCENE_NAVIGATION = 0x0401	Navigation scenario. 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. This option mainly uses the GNSS positioning technology and therefore the power consumption is relatively high.
LOCATION_USE_SCENE_SPORT = 0x0402	Sport scenario. Applicable when your application needs to record user trajectories, for example, the track recording function of sports applications. This option mainly uses the GNSS positioning technology and therefore the power consumption is relatively high.
LOCATION_USE_SCENE_TRANSPORT = 0x0403	Travel scenario. This option is applicable to user travel scenarios, such as taxi hailing and public transportation. This option mainly uses the GNSS positioning technology and therefore the power consumption is relatively high.
LOCATION_USE_SCENE_DAILY_LIFE_SERVICE = 0x0404	Daily life services. 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. It mainly uses the network positioning technology and therefore the power consumption is relatively low.

Location_PowerConsumptionScene

enum Location_PowerConsumptionScene

Description

Enumerates power consumption scenarios in a location request.

Since: 13

Enum Item	Description
LOCATION_HIGH_POWER_CONSUMPTION = 0x0601	High power consumption. 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. During the continuous location process, the network positioning technology is used if the GNSS location result cannot be obtained within 30 seconds. This policy can lead to significant hardware resource consumption and power consumption.
LOCATION_LOW_POWER_CONSUMPTION = 0x0602	Low power consumption. 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. It mainly uses the network positioning technology and therefore the power consumption is relatively low.
LOCATION_NO_POWER_CONSUMPTION = 0x0603	No power consumption. 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.

Location_SourceType

enum Location_SourceType

Description

Defines the source of location information.

Since: 13

Enum Item	Description
LOCATION_SOURCE_TYPE_GNSS = 1	GNSS positioning technology.
LOCATION_SOURCE_TYPE_NETWORK = 2	Network positioning technology.
LOCATION_SOURCE_TYPE_INDOOR = 3	Indoor high-precision positioning technology.
LOCATION_SOURCE_TYPE_RTK = 4	Outdoor high-precision positioning technology.

Function Description

OH_LocationInfo_GetBasicInfo()

Location_BasicInfo OH_LocationInfo_GetBasicInfo(Location_Info* location)

Description

Obtains basic location information.

Since: 13

Parameters

Name	Description
Location_Info* location	Pointer to the Location_Info instance. A non-null pointer must be passed. The pointer can be obtained from Location_InfoCallback.

Returns

Type	Description
Location_BasicInfo	Struct for the basic location information. For details, see Location_BasicInfo.

OH_LocationInfo_GetAdditionalInfo()

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

Description

Obtains the additional information in the location information.

Since: 13

Parameters

Name	Description
Location_Info* location	Pointer to the Location_Info instance. A non-null pointer needs to be passed in. This pointer can be obtained from Location_InfoCallback.
char* additionalInfo	Non-null pointer of the char type. This variable is used to store the additional location information in JSON format. 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. If a null pointer is passed in, an error code is returned.
uint32_t length	Memory size of additionalInfo.

Returns

Type	Description
Location_ResultCode	Operation result. For details, see Location_ResultCode. LOCATION_SUCCESS if additional information obtained successfully; LOCATION_INVALID_PARAM if the input location or additionalInfo is a null pointer, 2. or the value of the input length is too small, that is, the memory size of additionalInfo is too small, which is unable to save the complete additional information.

Location_InfoCallback()

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

Description

Defines the callback for receiving reported location information.

Since: 13

Parameters

Name	Description
Location_Info* location	Pointer to the Location_Info instance, which carries the latest location information. The memory occupied by the instance will be reclaimed when Location_InfoCallback is complete. Before that, call APIs such as OH_LocationInfo_GetBasicInfo to obtain the location information.
void* userData	Pointer to the userData struct or object. This parameter is passed in through OH_LocationRequestConfig_SetCallback.

OH_Location_CreateRequestConfig()

Location_RequestConfig* OH_Location_CreateRequestConfig(void)

Description

Creates a Location_RequestConfig instance.

Since: 13

Returns

Type	Description
Location_RequestConfig*	Pointer to the Location_RequestConfig instance. If NULL is returned, the operation has failed. The probable cause is that the application address space is full.

OH_Location_DestroyRequestConfig()

void OH_Location_DestroyRequestConfig(Location_RequestConfig* requestConfig)

Description

Destroys the Location_RequestConfig instance and reclaims the memory.

Since: 13

Parameters

Name	Description
Location_RequestConfig* requestConfig	Pointer to the Location_RequestConfig instance, which is created using OH_Location_CreateRequestConfig.

OH_LocationRequestConfig_SetUseScene()

void OH_LocationRequestConfig_SetUseScene(Location_RequestConfig* requestConfig, Location_UseScene useScene)

Description

Sets the use scene in the location request configuration.
useScene takes precedence over powerConsumptionScene in Location_RequestConfig.
If useScene is set, powerConsumptionScene is invalid.
Otherwise, powerConsumptionScene takes effect.
If neither of the two parameters is set, the default value of useScene is LOCATION_USE_SCENE_DAILY_LIFE_SERVICE and powerConsumptionScene is invalid.

Since: 13

Parameters

Name	Description
Location_RequestConfig* requestConfig	Pointer to the Location_RequestConfig instance, which is created using OH_Location_CreateRequestConfig.
Location_UseScene useScene	Use scene in the location request. The default value is LOCATION_USE_SCENE_DAILY_LIFE_SERVICE. For details, see Location_UseScene.

OH_LocationRequestConfig_SetPowerConsumptionScene()

void OH_LocationRequestConfig_SetPowerConsumptionScene(Location_RequestConfig* requestConfig, Location_PowerConsumptionScene powerConsumptionScene)

Description

Sets the power consumption scene in the location request configuration.

Since: 13

Parameters

Name	Description
Location_RequestConfig* requestConfig	Pointer to the Location_RequestConfig instance, which is created using OH_Location_CreateRequestConfig.
Location_PowerConsumptionScene powerConsumptionScene	Power consumption scene in the location request. The default value is LOCATION_LOW_POWER_CONSUMPTION. For details, see Location_PowerConsumptionScene.

OH_LocationRequestConfig_SetInterval()

void OH_LocationRequestConfig_SetInterval(Location_RequestConfig* requestConfig, int interval)

Description

Sets the location reporting interval in the location request configuration.

Since: 13

Parameters

Name	Description
Location_RequestConfig* requestConfig	Pointer to the Location_RequestConfig instance, which is created using OH_Location_CreateRequestConfig.
int interval	Location reporting interval, in seconds. The value must be greater than or equal to 1. The default value is 1.

OH_LocationRequestConfig_SetCallback()

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

Description

Sets a callback for sign generation.

Since: 13

Parameters

Name	Description
Location_RequestConfig* requestConfig	Pointer to the Location_RequestConfig instance, which is created using OH_Location_CreateRequestConfig.
Location_InfoCallback callback	Pointer to the callback function, which is used to receive location information changes. For details, see Location_InfoCallback.
void* userData	Pointer to the userData struct or object. This pointer is returned to the caller as an input parameter when the callback function is executed.