Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
提交 d7b16f6e 编写于 作者: S shawn_he
浏览文件
操作

update doc 

Signed-off-by: Nshawn_he <shawn.he@huawei.com>
上级 6d8e2990
显示空白变更内容
内联 并排
Showing with 1156 addition and 832 deletion
en/application-dev/device/Readme-EN.md
浏览文件 @ d7b16f6e
......@@ -4,9 +4,7 @@
- [USB Service Overview](usb-overview.md)
- [USB Service Development](usb-guidelines.md)
- Location
- [Location Overview](device-location-overview.md)
- [Obtaining Device Location Information](device-location-info.md)
- [Geocoding and Reverse Geocoding Capabilities](device-location-geocoding.md)
- [Location Service Development](location-guidelines.md)
- Sensor
- [Sensor Overview](sensor-overview.md)
- [Sensor Development](sensor-guidelines.md)
......
en/application-dev/device/location-guidelines.md 0 → 100644
浏览文件 @ d7b16f6e
# Location Service Development
## Overview
People take their mobile devices wherever they go. Mobile devices have become a necessity in people's daily routines, whether it be for looking at the weather forecast, browsing news, hailing a taxi, navigating, or recording data from a workout. All these activities are so much associated with the location services on mobile devices.
With the location awareness capability offered by OpenHarmony, mobile devices will be able to obtain real-time, accurate location data. Building location awareness into your application can also lead to a better contextual experience for application users.
Your application can call location-specific APIs to obtain the location information of a mobile device for offering location-based services such as drive navigation and motion track recording.
### Service Introduction
Location awareness helps determine where a mobile device locates. The location subsystem identifies the location of a mobile device with its coordinates, and uses location technologies such as Global Navigation Satellite System (GNSS) and network positioning (for example, base station positioning or WLAN/Bluetooth positioning) to provide diverse location-based services.
These advanced location technologies make it possible to obtain the accurate location of the mobile device, regardless of whether it is indoors or outdoors.
- **Coordinate**
A coordinate describes a location on the earth using the longitude and latitude in reference to the World Geodetic Coordinate System 1984.
- **GNSS positioning**
GNSS positioning locates a mobile device by using the location algorithm offered by the device chip to compute the location information provided by the Global Navigation Satellite System, for example, GPS, GLONASS, BeiDou, and Galileo. Whichever positioning system will be used during the location process depends on a hardware capability of the device.
- **Base station positioning**
Base station positioning estimates the current location of a mobile device based on the location of the resident base station in reference to the neighboring base stations. This technology provides only a low accuracy and requires access to the cellular network.
- **WLAN or Bluetooth positioning**
WLAN or Bluetooth positioning estimates the current location of a mobile device based on the locations of WLANs and Bluetooth devices that can be discovered by the device. The location accuracy of this technology depends on the distribution of fixed WLAN access points (APs) and Bluetooth devices around the device. A high density of WLAN APs and Bluetooth devices can produce a more accurate location result than base station positioning. This technology also requires access to the network.
### Working Principles
Location awareness is offered by the system as a basic service for applications. Depending on the service scenario, an application needs to initiate a location request to the system and stop the location request when the service scenario ends. In this process, the system reports the location information to the application on a real-time basis.
### Constraints
Your application can use the location function only after the user has granted the required permission and turned on the location function. If the location function is off, the system will not provide the location service for any application.
Since the location information is considered sensitive, your application still needs to obtain the location access permission from the user even if the user has turned on the location function. The system will provide the location service for your application only after it has been granted the permission to access the device location information.
### Samples
The following sample is provided to help you better understand how to develop location services:
- [`Location`: Location (ArkTS) (API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/device/Location)
## Applying for Location Permissions
### When to Use
Before using system basic location capabilities, check whether your application has been granted the permission to access the device location information. If not, your application needs to obtain the permission from the user.
The system provides the following location permissions:
- ohos.permission.LOCATION: used to obtain location accurate to meters.
- ohos.permission.APPROXIMATELY\_LOCATION: used to obtain location accurate to 5 kilometers.
- ohos.permission.LOCATION\_IN\_BACKGROUND: used to obtain location while the application is running at the background.
If your application needs to access the device location information, it must first apply for required permissions.
**Table 1** Ways to apply for location permissions
| Target API Level| Location Permission| Permission Application Result| Location Accuracy|
| -------- | -------- | -------- | -------- |
| Earlier than 9| ohos.permission.LOCATION | Successful| Location accurate to meters.|
| 9 and later| ohos.permission.LOCATION | Failed| No location obtained.|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION | Successful| Location accurate to 5 kilometers.|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Successful| Location accurate to meters.|
If your application needs to access the device location information when running in the background, it must be configured to be able to run in the background and be granted the **ohos.permission.LOCATION_IN_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background.
You can declare the required permission in your application's configuration file. For details, see [Access Control (Permission) Development](../security/accesstoken-guidelines.md).
For details about the permissions required for each API of the location service, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md).
### How to Develop
You can declare the required permission in your application's configuration file. For details, see [Access Control (Permission) Development](../security/accesstoken-guidelines.md).
## Obtaining Device Location Information
### When to Use
You can call location-related APIs in OpenHarmony to obtain the real-time location or last known location of a mobile device.
Real-time location of the device is recommended for location-sensitive services. If you want to lower power consumption when the real-time location of the device is not needed, you may consider obtaining the last known location of the device.
### Available APIs
The following table lists the APIs used to obtain the device location information. For details, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md).
**Table 2** APIs for obtaining device location information
| API| Description|
| -------- | -------- |
| on(type: 'locationChange', request: LocationRequest, callback: Callback&lt;Location&gt;): void | Registers a listener for location changes with a location request initiated.|
| off(type: 'locationChange', callback?: Callback&lt;Location&gt;): void | Unregisters the listener for location changes with the corresponding location request deleted.|
| getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback&lt;Location&gt;): void | Obtains the current location. This API uses an asynchronous callback to return the result. |
| getCurrentLocation(request?: CurrentLocationRequest): Promise&lt;Location&gt; | Obtains the current location. This API uses a promise to return the result. |
| getLastLocation(): Location | Obtains the last known device location.|
### How to Develop
1. Before using basic location capabilities, check whether your application has been granted the permission to access device location information. If not, your application first needs to apply for the required permission. For details, see [Applying for Location Permissions](#applying-for-location-permissions).
2. Import the **geoLocationManager** module by which you can implement all APIs related to the basic location capabilities.
```ts
import geoLocationManager from '@ohos.geoLocationManager';
```
3. Instantiate the **LocationRequest** object. This object provides APIs to notify the system of the location service type and the interval of reporting location information.<br>
**Method 1:**
To better serve your needs for using APIs, the system has categorized APIs into different packages to match your common use cases of the location function. In this way, you can directly use the APIs specific to a certain use case, making application development much easier. The location service scenarios currently supported are described as follows.
**Location service scenarios**
- NAVIGATION<br>
Applicable when your application needs to obtain the real-time location of a mobile device outdoors, such as navigation for driving or walking. <br>In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy. However, due to its limitations, the technology may be unable to provide the location service when navigation is just started or when the user moves into a shielded environment such as indoors or a garage. <br>To resolve this issue, 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. This helps achieve a smooth navigation experience for users. <br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.
- TRAJECTORY\_TRACKING<br>
Applicable when your application needs to record user trajectories, for example, the track recording function of sports applications. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy. <br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.
- CAR\_HAILING<br>
Applicable when your application needs to obtain the current location of a user who is hailing a taxi. <br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.
- DAILY\_LIFE\_SERVICE<br>
Applicable when your application only needs the approximate user location for recommendations and push notifications in scenarios such as when the user is browsing news, shopping online, and ordering food. <br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.
- NO\_POWER<br>
Applicable when your application does not proactively start the location service for a higher battery efficiency. When responding to another application requesting the same location service, the system marks a copy of the location result to your application. In this way, your application will not consume extra power for obtaining the user location. <br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.
```ts
export enum LocationRequestScenario {
UNSET = 0x300,
NAVIGATION,
TRAJECTORY_TRACKING,
CAR_HAILING,
DAILY_LIFE_SERVICE,
NO_POWER,
}
```
Sample code for initializing **requestInfo** for navigation:
```ts
let requestInfo = {'scenario': geoLocationManager.LocationRequestScenario.NAVIGATION, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
```
**Method 2:**
If the predefined use cases do not meet your needs, you can also use the basic location priority policies provided by the system.
**Location priority policies**
- ACCURACY<br>
This policy mainly uses the GNSS positioning technology. In an open area, the technology can achieve the meter-level location accuracy, depending on the hardware performance of the device. However, in a shielded environment, the location accuracy may significantly decrease.
- FIRST\_FIX<br>
This policy uses the GNSS positioning, base station positioning, WLAN positioning, and Bluetooth positioning technologies simultaneously to obtain the device location in both the indoor and outdoor scenarios. When all positioning technologies provide a location result, the system provides the most accurate location result for your application. This policy can lead to significant hardware resource consumption and power consumption.
- LOW\_POWER<br>
This policy mainly uses the base station positioning, WLAN positioning, and Bluetooth positioning technologies to obtain device location in both indoor and outdoor scenarios. The location accuracy depends on the distribution of surrounding base stations, visible WLANs, and Bluetooth devices and therefore may fluctuate greatly. This policy is recommended and can reduce power consumption when your application does not require high location accuracy or when base stations, visible WLANs, and Bluetooth devices are densely distributed.
```ts
export enum LocationRequestPriority {
UNSET = 0x200,
ACCURACY,
LOW_POWER,
FIRST_FIX,
}
```
Sample code for initializing **requestInfo** for the location accuracy priority policy:
```ts
let requestInfo = {'priority': geoLocationManager.LocationRequestPriority.ACCURACY, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
```
4. Instantiate the **Callback** object for the system to report location results.
Your application needs to implement the callback defined by the system. When the system successfully obtains the real-time location of a device, it will report the location result to your application through the callback interface. Your application can implement the callback interface in such a way to complete your own service logic.
```ts
let locationChange = (location) => {
console.log('locationChanger: data: ' + JSON.stringify(location));
};
```
5. Start obtaining the device location.
```ts
geoLocationManager.on('locationChange', requestInfo, locationChange);
```
6. (Optional) Stop obtaining the device location.
If your application no longer needs the device location, stop obtaining the device location to avoid high power consumption.
```ts
geoLocationManager.off('locationChange', locationChange);
```
If your application does not need the real-time device location, it can use the last known device location cached in the system instead.
```ts
import geoLocationManager from '@ohos.geoLocationManager';
try {
let location = geoLocationManager.getLastLocation();
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
```
## Geocoding and Reverse Geocoding
### When to Use
Describing a location using coordinates is accurate, but neither intuitive nor user-friendly. To address this issue, the system provides your application the geocoding and reverse geocoding capabilities:
- Geocoding: converts geographic descriptions into specific coordinates.
- Reverse geocoding: converts coordinates into geographic descriptions.
The geocoding information describes a location using several attributes, including the country, administrative region, street, house number, and address, etc.
### Available APIs
The following table lists the APIs used for mutual conversion between coordinates and geographic descriptions. For details, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md).
**Table 3** APIs for geocoding and reverse geocoding conversion
| API| Description|
| -------- | -------- |
| isGeocoderAvailable(): boolean; | Obtains the (reverse) geocoding service status.|
| getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback&lt;Array&lt;GeoAddress&gt;&gt;): void | Converts coordinates into geographic descriptions through reverse geocoding. This API uses an asynchronous callback to return the result. |
| getAddressesFromLocation(request: ReverseGeoCodeRequest): Promise&lt;Array&lt;GeoAddress&gt;&gt; | Converts coordinates into geographic descriptions through reverse geocoding. This API uses a promise to return the result. |
| getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback&lt;Array&lt;GeoAddress&gt;&gt;): void | Converts geographic descriptions into coordinates through geocoding. This API uses an asynchronous callback to return the result. |
| getAddressesFromLocationName(request: GeoCodeRequest): Promise&lt;Array&lt;GeoAddress&gt;&gt; | Converts geographic descriptions into coordinates through geocoding. This API uses a promise to return the result. |
### How to Develop
> **NOTE**
> The **GeoConvert** instance needs to access backend services to obtain information. Therefore, before performing the following steps, ensure that your device is connected to the network.
1. Import the **geoLocationManager** module by which you can implement all APIs related to the geocoding and reverse geocoding conversion capabilities.
```ts
import geoLocationManager from '@ohos.geoLocationManager';
```
2. Check whether the **geoCoder** service is available.
- Call **isGeoServiceAvailable** to check whether the **geoCoder** service is available. If the service is available, go to step 3.
```ts
import geoLocationManager from '@ohos.geoLocationManager';
try {
let isAvailable = geoLocationManager.isGeocoderAvailable();
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
```
3. Obtain the geocoding conversion result.
- Call **getAddressesFromLocation** to convert coordinates into geographical location information.
```ts
let reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
try {
geoLocationManager.getAddressesFromLocation(reverseGeocodeRequest, (err, data) => {
if (err) {
console.log('getAddressesFromLocation err: ' + JSON.stringify(err));
} else {
console.log('getAddressesFromLocation data: ' + JSON.stringify(data));
}
});
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
```
The application can access the **GeoAddress** list that matches the specified coordinates for the corresponding geographic descriptions. For details, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md).
- Call **getAddressesFromLocationName** to convert geographic descriptions into coordinates.
```ts
let geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
try {
geoLocationManager.getAddressesFromLocationName(geocodeRequest, (err, data) => {
if (err) {
console.log('getAddressesFromLocationName err: ' + JSON.stringify(err));
} else {
console.log('getAddressesFromLocationName data: ' + JSON.stringify(data));
}
});
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
```
The application can access the **GeoAddress** list that matches the specified geographic descriptions for the corresponding coordinates. For details, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md).
To improve the accuracy of location results, you can set the longitude and latitude ranges in **GeoCodeRequest**.
## Geofencing
### When to Use
A geofence is a group of virtual bounds defining an area on the map. When a user device enters or leaves a geofence, or stays in a geofence, your app on the user device can automatically receive notifications and alarms.
Currently, only circular geofences are supported, and the geofencing function of the GNSS chip is required.
A typical application of geofencing is to create a geofence around an enterprise for targeted advertising. In different areas, you can provide differentiated promotions for mobile devices.
### Available APIs
The following table lists the APIs used for geofencing. For details, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md).
**Table 4** Geofencing APIs
| API| Description|
| -------- | -------- |
| on(type: 'gnssFenceStatusChange', request: GeofenceRequest, want: WantAgent): void; | Registers a listener for status change events of the specified geofence.|
| off(type: 'gnssFenceStatusChange', request: GeofenceRequest, want: WantAgent): void; | Unregisters the listener for status change events of the specified geofence.|
### How to Develop
1. Declare the **ohos.permission.APPROXIMATELY_LOCATION** permission. For details, see [Applying for Location Permissions](#applying-for-location-permissions).
2. Import the [geoLocationManager](../reference/apis/js-apis-geoLocationManager.md) and [wantAgent](../reference/apis/js-apis-app-ability-wantAgent.md) modules.
```ts
import geoLocationManager from '@ohos.geoLocationManager';
import wantAgent from '@ohos.app.ability.wantAgent';
```
3. Create a [WantAgentInfo](../reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md) object.
Scenario 1: Create a **WantAgentInfo** object for starting an ability.
```ts
let wantAgentObj = null; // Save the created WantAgent object for completing the trigger operations at a later time.
// Set the operation type through operationType of the WantAgentInfo object.
let wantAgentInfo = {
wants: [
{
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility',
action: '',
entities: [],
uri: '',
parameters: {}
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
};
```
Scenario 2: Create a **WantAgentInfo** object for publishing [common events](../application-models/common-event-overview.md).
```ts
let wantAgentObj = null; // Save the created WantAgent object for completing the trigger operations at a later time.
// Set the operation type through operationType of the WantAgentInfo object.
let wantAgentInfo = {
wants: [
{
action: "event_name", // Set the event name.
parameters: {},
}
],
operationType: wantAgent.OperationType.SEND_COMMON_EVENT,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.CONSTANT_FLAG],
}
```
4. Call [getWantAgent()](../reference/apis/js-apis-app-ability-wantAgent.md#wantagentgetwantagent) to create a **WantAgent** object.
After obtaining the **WantAgent** object, call the geofencing API to add a geofence.
```ts
// Create a WantAgent object.
wantAgent.getWantAgent(wantAgentInfo, (err, data) => {
if (err) {
console.error('getWantAgent err=' + JSON.stringify(err));
return;
}
console.info('getWantAgent success');
wantAgentObj = data;
let requestInfo = {'priority': 0x201, 'scenario': 0x301, "geofence": {"latitude": 121, "longitude": 26, "radius": 100, "expiration": 10000}};
try {
geoLocationManager.on('gnssFenceStatusChange', requestInfo, wantAgentObj);
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
});
```
5. Have the system automatically trigger the action defined for the **WantAgent** object when a device enters or exits the geofence.
en/application-dev/reference/apis/js-apis-batteryStatistics.md
浏览文件 @ d7b16f6e
......@@ -46,7 +46,7 @@ batteryStats.getBatteryStats()
console.info('battery statistics info: ' + data);
})
.catch(err => {
console.error('get battery statisitics failed, err: ' + err);
console.error('get battery statistics failed, err: ' + err);
});
```
......@@ -81,7 +81,7 @@ batteryStats.getBatteryStats((err, data) => {
if (typeof err === 'undefined') {
console.info('battery statistics info: ' + data);
} else {
console.error('get battery statisitics failed, err: ' + err);
console.error('get battery statistics failed, err: ' + err);
}
});
```
......@@ -123,7 +123,7 @@ try {
var value = batteryStats.getAppPowerValue(10021);
console.info('battery statistics value of app is: ' + value);
} catch(err) {
console.error('get battery statisitics value of app failed, err: ' + err);
console.error('get battery statistics value of app failed, err: ' + err);
}
```
......@@ -164,7 +164,7 @@ try {
var percent = batteryStats.getAppPowerPercent(10021);
console.info('battery statistics percent of app is: ' + percent);
} catch(err) {
console.error('get battery statisitics percent of app failed, err: ' + err);
console.error('get battery statistics percent of app failed, err: ' + err);
}
```
......@@ -205,7 +205,7 @@ try {
var value = batteryStats.getHardwareUnitPowerValue(ConsumptionType.CONSUMPTION_TYPE_SCREEN);
console.info('battery statistics percent of hardware is: ' + percent);
} catch(err) {
console.error('get battery statisitics percent of hardware failed, err: ' + err);
console.error('get battery statistics percent of hardware failed, err: ' + err);
}
```
......@@ -246,7 +246,7 @@ try {
var value = batteryStats.getHardwareUnitPowerPercent(ConsumptionType.CONSUMPTION_TYPE_SCREEN);
console.info('battery statistics percent of hardware is: ' + percent);
} catch(err) {
console.error('get battery statisitics percent of hardware failed, err: ' + err);
console.error('get battery statistics percent of hardware failed, err: ' + err);
}
```
......
en/application-dev/reference/apis/js-apis-geoLocationManager.md
浏览文件 @ d7b16f6e
# @ohos.geoLocationManager (Geolocation Manager)
The **geoLocationManager** module provides location service management functions.
The **geoLocationManager** module provides a wide array of location services, including GNSS positioning, network positioning, geocoding, reverse geocoding, and geofencing.
> **NOTE**<br>
> **NOTE**
>
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Applying for Permissions
......@@ -18,18 +19,18 @@ The system provides the following location permissions:
If your application needs to access the device location information, it must first apply for required permissions. Specifically speaking:
- API versions earlier than 9: Apply for **ohos.permission.LOCATION**.
API versions earlier than 9: Apply for **ohos.permission.LOCATION**.
- API version 9 and later: Apply for **ohos.permission.APPROXIMATELY\_LOCATION**, or apply for **ohos.permission.APPROXIMATELY\_LOCATION** and **ohos.permission.LOCATION**. Note that **ohos.permission.LOCATION** cannot be applied for separately.
API version 9 and later: Apply for **ohos.permission.APPROXIMATELY_LOCATION**, or apply for **ohos.permission.APPROXIMATELY_LOCATION** and **ohos.permission.LOCATION**. Note that **ohos.permission.LOCATION** cannot be applied for separately.
| API Version| Location Permission| Permission Application Result| Location Accuracy|
| -------- | -------- | -------- | -------- |
| Earlier than 9| ohos.permission.LOCATION | Success| Location accurate to meters|
| 9 and later| ohos.permission.LOCATION | Failure| No location obtained|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION | Success| Location accurate to 5 kilometers|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Success| Location accurate to meters|
| Earlier than 9| ohos.permission.LOCATION | Successful| Location accurate to meters.|
| 9 and later| ohos.permission.LOCATION | Failed| No location obtained.|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION | Successful| Location accurate to 5 kilometers.|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Successful| Location accurate to meters.|
If your application needs to access the device location information when running in the background, it must be configured to be able to run in the background and be granted the **ohos.permission.LOCATION\_IN\_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background.
If your application needs to access the device location information when running in the background, it must be configured to be able to run in the background and be granted the **ohos.permission.LOCATION_IN_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background.
You can declare the required permission in your application's configuration file. For details, see [Access Control (Permission) Development](../../security/accesstoken-guidelines.md).
......@@ -41,13 +42,288 @@ import geoLocationManager from '@ohos.geoLocationManager';
```
## ReverseGeoCodeRequest
Defines a reverse geocoding request.
**System capability**: SystemCapability.Location.Location.Geocoder
| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| latitude | number | Yes| Yes| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude. The value ranges from **-90** to **90**.|
| longitude | number | Yes| Yes| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude . The value ranges from **-180** to **180**.|
| maxItems | number | Yes| Yes| Maximum number of location records to be returned. The value must be greater than or equal to **0**. A value smaller than **10** is recommended.|
## GeoCodeRequest
Defines a geocoding request.
**System capability**: SystemCapability.Location.Location.Geocoder
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| description | string | Yes| Yes| Location description, for example, **No. xx, xx Road, Pudong New District, Shanghai**.|
| maxItems | number | Yes| Yes| Maximum number of location records to be returned. The value must be greater than or equal to **0**. A value smaller than **10** is recommended.|
| minLatitude | number | Yes| Yes| Minimum latitude. This parameter is used with **minLongitude**, **maxLatitude**, and **maxLongitude** to specify the latitude and longitude ranges. The value ranges from **-90** to **90**.|
| minLongitude | number | Yes| Yes| Minimum longitude. The value ranges from **-180** to **180**.|
| maxLatitude | number | Yes| Yes| Maximum latitude. The value ranges from **-90** to **90**.|
| maxLongitude | number | Yes| Yes| Maximum longitude. The value ranges from **-180** to **180**.|
## GeoAddress
Defines a geographic location.
**System capability**: SystemCapability.Location.Location.Geocoder
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| latitude | number | Yes| No | Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude. The value ranges from **-90** to **90**.|
| longitude | number | Yes| No | Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude . The value ranges from **-180** to **180**.|
| locale | string | Yes| No | Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| placeName | string | Yes| No | Landmark of the location.|
| countryCode | string | Yes| No | Country code.|
| countryName | string| Yes| No| Country name.|
| administrativeArea | string | Yes| No| Administrative region name.|
| subAdministrativeArea | string | Yes| No| Sub-administrative region name.|
| locality | string | Yes| No| Locality information.|
| subLocality | string | Yes| No| Sub-locality information.|
| roadName | string | Yes| No|Road name.|
| subRoadName | string | Yes| No| Auxiliary road information.|
| premises | string| Yes| No|House information.|
| postalCode | string | Yes| No| Postal code.|
| phoneNumber | string | Yes| No| Phone number.|
| addressUrl | string | Yes| No| Website URL.|
| descriptions | Array&lt;string&gt; | Yes| No| Additional descriptions.|
| descriptionsSize | number | Yes| No| Total number of additional descriptions. The value must be greater than or equal to **0**. A value smaller than **10** is recommended.|
| isFromMock | Boolean | Yes| No| Whether the geographic address is obtained from the mock reverse geocoding function.<br>**System API**: This is a system API.|
## LocationRequest
Defines a location request.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request. For details about the value range, see [LocationRequestPriority](#locationrequestpriority).|
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes| Scenario of the location request. For details about the value range, see [LocationRequestScenario](#locationrequestscenario).|
| timeInterval | number | Yes| Yes| Time interval at which location information is reported, in seconds. The value must be greater than **0**.|
| distanceInterval | number | Yes| Yes| Distance interval at which location information is reported. The value must be greater than **0**, in meters.|
| maxAccuracy | number | Yes| Yes| Location accuracy. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled. The value must be greater than **0**.|
## CurrentLocationRequest
Defines the current location request.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request. For details about the value range, see [LocationRequestPriority](#locationrequestpriority).|
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes| Scenario of the location request. For details about the value range, see [LocationRequestScenario](#locationrequestscenario).|
| maxAccuracy | number | Yes| Yes| Location accuracy, in meters. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled. The value must be greater than **0**.|
| timeoutMs | number | Yes| Yes| Timeout duration, in milliseconds. The minimum value is **1000**. The value must be greater than or equal to **1000**.|
## SatelliteStatusInfo
Defines the satellite status information.
**System capability**: SystemCapability.Location.Location.Gnss
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| satellitesNumber | number | Yes| No| Number of satellites. The value must be greater than or equal to **0**.|
| satelliteIds | Array&lt;number&gt; | Yes| No| Array of satellite IDs. The value must be greater than or equal to **0**.|
| carrierToNoiseDensitys | Array&lt;number&gt; | Yes| No| Carrier-to-noise density ratio, that is, **cn0**. The value must be greater than **0**.|
| altitudes | Array&lt;number&gt; | Yes| No| Satellite altitude angle information. The value ranges from **-90** to **90**, in degrees.|
| azimuths | Array&lt;number&gt; | Yes| No| Azimuth information. The value ranges from **0** to **360**, in degrees.|
| carrierFrequencies | Array&lt;number&gt; | Yes| No| Carrier frequency. The value must be greater than or equal to **0**, in Hz.|
## CachedGnssLocationsRequest
Represents a request for reporting cached GNSS locations.
**System capability**: SystemCapability.Location.Location.Gnss
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| reportingPeriodSec | number | Yes| Yes| Interval for reporting the cached GNSS locations, in milliseconds. The value must be greater than **0**.|
| wakeUpCacheQueueFull | boolean | Yes| Yes | **true**: reports the cached GNSS locations to the application when the cache queue is full.<br>**false**: discards the cached GNSS locations when the cache queue is full.|
## Geofence
Defines a GNSS geofence. Currently, only circular geofences are supported.
**System capability**: SystemCapability.Location.Location.Geofence
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| latitude | number | Yes| Yes|Latitude information. The value ranges from **-90** to **90**.|
| longitude | number | Yes|Yes| Longitude information. The value ranges from **-180** to **180**.|
| radius | number | Yes|Yes| Radius of a circular geofence. The value must be greater than **0**, in meters.|
| expiration | number | Yes|Yes| Expiration period of a geofence, in milliseconds. The value must be greater than **0**.|
## GeofenceRequest
Represents a GNSS geofencing request.
**System capability**: SystemCapability.Location.Location.Geofence
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes | Location scenario.|
| geofence | [Geofence](#geofence)| Yes| Yes | Geofence information.|
## LocationCommand
Defines an extended command.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes | Location scenario.|
| command | string | Yes| Yes | Extended command, in the string format.|
## Location
Defines a location.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| latitude | number| Yes| No| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude. The value ranges from **-90** to **90**.|
| longitude | number| Yes| No| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude . The value ranges from **-180** to **180**.|
| altitude | number | Yes| No| Location altitude, in meters.|
| accuracy | number | Yes| No| Location accuracy, in meters.|
| speed | number | Yes| No|Speed, in m/s.|
| timeStamp | number | Yes| No| Location timestamp in the UTC format.|
| direction | number | Yes| No| Direction information. The value ranges from **0** to **360**, in degrees.|
| timeSinceBoot | number | Yes| No| Location timestamp since boot.|
| additions | Array&lt;string&gt; | Yes| No| Additional description.|
| additionSize | number | Yes| No| Number of additional descriptions. The value must be greater than or equal to **0**. |
| isFromMock | Boolean | Yes| No| Whether the location information is from the mock location function.<br>**System API**: This is a system API.|
## ReverseGeocodingMockInfo
Represents information of the mock reverse geocoding function.
**System capability**: SystemCapability.Location.Location.Core
**System API**: This is a system API and cannot be called by third-party applications.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| location | [ReverseGeoCodeRequest](#reversegeocoderequest) | Yes| Yes| Latitude and longitude information.|
| geoAddress | [GeoAddress](#geoaddress) | Yes| Yes|Geographic address.|
## LocationMockConfig
Represents the mock location configuration.
**System capability**: SystemCapability.Location.Location.Core
**System API**: This is a system API and cannot be called by third-party applications.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| timeInterval | number | Yes| Yes| Interval at which mock locations are reported, in seconds.|
| locations | Array&lt;[Location](#location)&gt; | Yes| Yes| Array of mocked locations.|
## CountryCode
Represents country code information.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| country | string | Yes| No| Country code.|
| type | [CountryCodeType](#countrycodetype) | Yes| No| Country code source.|
## LocationRequestPriority
Sets the priority of the location request.
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| UNSET | 0x200 | Priority unspecified.<br>If this option is used, [LocationRequestPriority](#locationrequestpriority) is invalid.|
| ACCURACY | 0x201 | Location accuracy preferred.<br>This policy mainly uses the GNSS positioning technology. In an open area, the technology can achieve the meter-level location accuracy, depending on the hardware performance of the device. However, in a shielded environment, the location accuracy may significantly decrease.|
| LOW_POWER | 0x202 | Power efficiency preferred.<br>This policy mainly uses the base station positioning, WLAN positioning, and Bluetooth positioning technologies to obtain device location in both indoor and outdoor scenarios. The location accuracy depends on the distribution of surrounding base stations, visible WLANs, and Bluetooth devices and therefore may fluctuate greatly. This policy is recommended and can reduce power consumption when your application does not require high location accuracy or when base stations, visible WLANs, and Bluetooth devices are densely distributed.|
| FIRST_FIX | 0x203 | Fast location preferred. Use this option if you want to obtain a location as fast as possible.<br>This policy uses the GNSS positioning, base station positioning, WLAN positioning, and Bluetooth positioning technologies simultaneously to obtain the device location in both the indoor and outdoor scenarios. When all positioning technologies provide a location result, the system provides the most accurate location result for your application. It can lead to significant hardware resource consumption and power consumption.|
## LocationRequestScenario
Sets the scenario of the location request.
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| UNSET | 0x300 | Scenario unspecified.<br>If this option is used, [LocationRequestScenario](#locationrequest scenario) is invalid.|
| NAVIGATION | 0x301 | 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>In this scenario, GNSS positioning is used to provide location services to ensure the optimal location accuracy of the system.<br>The location result is reported at a minimum interval of 1 second by default.|
| TRAJECTORY_TRACKING | 0x302 | Trajectory tracking scenario.<br>This option is applicable when your application needs to record user trajectories, for example, the track recording function of sports applications. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy.<br>The location result is reported at a minimum interval of 1 second by default.|
| CAR_HAILING | 0x303 | Ride hailing scenario.<br>This option is applicable when your application needs to obtain the current location of a user who is hailing a taxi.<br>The location result is reported at a minimum interval of 1 second by default.|
| DAILY_LIFE_SERVICE | 0x304 | Daily life service scenario.<br>This option is applicable when your application only needs the approximate user location for recommendations and push notifications in scenarios such as when the user is browsing news, shopping online, and ordering food.<br>The location result is reported at a minimum interval of 1 second by default.|
| NO_POWER | 0x305 | Power efficiency scenario.<br>This option is applicable when 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. In this way, your application will not consume extra power for obtaining the user location.|
## LocationPrivacyType
Defines the privacy statement type.
**System capability**: SystemCapability.Location.Location.Core
**System API**: This is a system API and cannot be called by third-party applications.
| Name| Value| Description|
| -------- | -------- | -------- |
| OTHERS | 0 | Other scenarios. Reserved field.|
| STARTUP | 1 | Privacy statement displayed in the startup wizard. |
| CORE_LOCATION | 2 | Privacy statement displayed when enabling the location service.|
## CountryCodeType
Represents the country code source type.
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| COUNTRY_CODE_FROM_LOCALE | 1 | Country code obtained from the language configuration of the globalization module.|
| COUNTRY_CODE_FROM_SIM | 2 | Country code obtained from the SIM card.|
| COUNTRY_CODE_FROM_LOCATION | 3 | Country code obtained using the reverse geocoding function based on the user's location information.|
| COUNTRY_CODE_FROM_NETWORK | 4 | Country code obtained from the cellular network registration information.|
## geoLocationManager.on('locationChange')
on(type: 'locationChange', request: LocationRequest, callback: Callback&lt;Location&gt;): void
Registers a listener for location changes with a location request initiated. The location result is reported through [LocationRequest](#locationrequest).
Registers a listener for location changes with a location request initiated.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Core
......@@ -73,8 +349,8 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
var locationChange = (location) => {
let requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
let locationChange = (location) => {
console.log('locationChanger: data: ' + JSON.stringify(location));
};
try {
......@@ -92,7 +368,7 @@ off(type: 'locationChange', callback?: Callback&lt;Location&gt;): void
Unregisters the listener for location changes with the corresponding location request deleted.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Core
......@@ -117,8 +393,8 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
var locationChange = (location) => {
let requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
let locationChange = (location) => {
console.log('locationChanger: data: ' + JSON.stringify(location));
};
try {
......@@ -157,7 +433,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var locationEnabledChange = (state) => {
let locationEnabledChange = (state) => {
console.log('locationEnabledChange: ' + JSON.stringify(state));
}
try {
......@@ -195,7 +471,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var locationEnabledChange = (state) => {
let locationEnabledChange = (state) => {
console.log('locationEnabledChange: state: ' + JSON.stringify(state));
}
try {
......@@ -213,7 +489,7 @@ on(type: 'cachedGnssLocationsChange', request: CachedGnssLocationsRequest, callb
Registers a listener for cached GNSS location reports.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Gnss
......@@ -239,10 +515,10 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var cachedLocationsCb = (locations) => {
let cachedLocationsCb = (locations) => {
console.log('cachedGnssLocationsChange: locations: ' + JSON.stringify(locations));
}
var requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true};
let requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true};
try {
geoLocationManager.on('cachedGnssLocationsChange', requestInfo, cachedLocationsCb);
} catch (err) {
......@@ -257,7 +533,7 @@ off(type: 'cachedGnssLocationsChange', callback?: Callback&lt;Array&lt;Location&
Unregisters the listener for cached GNSS location reports.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Gnss
......@@ -282,10 +558,10 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var cachedLocationsCb = (locations) => {
let cachedLocationsCb = (locations) => {
console.log('cachedGnssLocationsChange: locations: ' + JSON.stringify(locations));
}
var requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true};
let requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true};
try {
geoLocationManager.on('cachedGnssLocationsChange', requestInfo, cachedLocationsCb);
geoLocationManager.off('cachedGnssLocationsChange');
......@@ -301,7 +577,7 @@ on(type: 'satelliteStatusChange', callback: Callback&lt;SatelliteStatusInfo&gt;)
Registers a listener for GNSS satellite status change events.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Gnss
......@@ -325,7 +601,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var gnssStatusCb = (satelliteStatusInfo) => {
let gnssStatusCb = (satelliteStatusInfo) => {
console.log('satelliteStatusChange: ' + JSON.stringify(satelliteStatusInfo));
}
......@@ -343,7 +619,7 @@ off(type: 'satelliteStatusChange', callback?: Callback&lt;SatelliteStatusInfo&gt
Unregisters the listener for GNSS satellite status change events.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Gnss
......@@ -368,7 +644,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var gnssStatusCb = (satelliteStatusInfo) => {
let gnssStatusCb = (satelliteStatusInfo) => {
console.log('satelliteStatusChange: ' + JSON.stringify(satelliteStatusInfo));
}
try {
......@@ -411,7 +687,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var nmeaCb = (str) => {
let nmeaCb = (str) => {
console.log('nmeaMessage: ' + JSON.stringify(str));
}
......@@ -454,7 +730,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var nmeaCb = (str) => {
let nmeaCb = (str) => {
console.log('nmeaMessage: ' + JSON.stringify(str));
}
......@@ -473,7 +749,7 @@ on(type: 'gnssFenceStatusChange', request: GeofenceRequest, want: WantAgent): vo
Registers a listener for status change events of the specified geofence.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Geofence
......@@ -483,7 +759,7 @@ Registers a listener for status change events of the specified geofence.
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **gnssFenceStatusChange** indicates a geofence status change event.|
| request | [GeofenceRequest](#geofencerequest) | Yes| Geofencing request.|
| want | WantAgent | Yes| **WantAgent** used to return geofence (entrance or exit) events.|
| want | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes| **WantAgent** used to return geofence (entrance or exit) events.|
**Error codes**
......@@ -499,13 +775,13 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
import wantAgent from '@ohos.wantAgent';
import wantAgent from '@ohos.app.ability.wantAgent';
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility",
abilityName: "EntryAbility",
action: "action1",
}
],
......@@ -515,7 +791,7 @@ For details about the following error codes, see [Location Error Codes](../error
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
var requestInfo = {'priority': 0x201, 'scenario': 0x301, "geofence": {"latitude": 121, "longitude": 26, "radius": 100, "expiration": 10000}};
let requestInfo = {'priority': 0x201, 'scenario': 0x301, "geofence": {"latitude": 121, "longitude": 26, "radius": 100, "expiration": 10000}};
try {
geoLocationManager.on('gnssFenceStatusChange', requestInfo, wantAgentObj);
} catch (err) {
......@@ -531,7 +807,7 @@ off(type: 'gnssFenceStatusChange', request: GeofenceRequest, want: WantAgent): v
Unregisters the listener for status change events of the specified geofence.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Geofence
......@@ -541,7 +817,7 @@ Unregisters the listener for status change events of the specified geofence.
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **gnssFenceStatusChange** indicates a geofence status change event.|
| request | [GeofenceRequest](#geofencerequest) | Yes| Geofencing request.|
| want | WantAgent | Yes| **WantAgent** used to return geofence (entrance or exit) events.|
| want | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes| **WantAgent** used to return geofence (entrance or exit) events.|
**Error codes**
......@@ -557,13 +833,13 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
import wantAgent from '@ohos.wantAgent';
import wantAgent from '@ohos.app.ability.wantAgent';
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility",
abilityName: "EntryAbility",
action: "action1",
}
],
......@@ -573,7 +849,7 @@ For details about the following error codes, see [Location Error Codes](../error
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
var requestInfo = {'priority': 0x201, 'scenario': 0x301, "geofence": {"latitude": 121, "longitude": 26, "radius": 100, "expiration": 10000}};
let requestInfo = {'priority': 0x201, 'scenario': 0x301, "geofence": {"latitude": 121, "longitude": 26, "radius": 100, "expiration": 10000}};
try {
geoLocationManager.on('gnssFenceStatusChange', requestInfo, wantAgentObj);
geoLocationManager.off('gnssFenceStatusChange', requestInfo, wantAgentObj);
......@@ -614,7 +890,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var callback = (code) => {
let callback = (code) => {
console.log('countryCodeChange: ' + JSON.stringify(code));
}
......@@ -655,7 +931,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var callback = (code) => {
let callback = (code) => {
console.log('countryCodeChange: ' + JSON.stringify(code));
}
......@@ -675,7 +951,7 @@ getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback&lt;L
Obtains the current location. This API uses an asynchronous callback to return the result.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Core
......@@ -700,8 +976,8 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0};
var locationChange = (err, location) => {
let requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0};
let locationChange = (err, location) => {
if (err) {
console.log('locationChanger: err=' + JSON.stringify(err));
}
......@@ -723,7 +999,7 @@ getCurrentLocation(callback: AsyncCallback&lt;Location&gt;): void;
Obtains the current location. This API uses an asynchronous callback to return the result.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Core
......@@ -747,7 +1023,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var locationChange = (err, location) => {
let locationChange = (err, location) => {
if (err) {
console.log('locationChanger: err=' + JSON.stringify(err));
}
......@@ -769,7 +1045,7 @@ getCurrentLocation(request?: CurrentLocationRequest): Promise&lt;Location&gt;
Obtains the current location. This API uses a promise to return the result.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Core
......@@ -783,87 +1059,7 @@ Obtains the current location. This API uses a promise to return the result.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Promise&lt;[Location](#location)&gt; | [Location](#location) | NA | Promise used to return the current location.|
**Error codes**
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
|3301000 | Location service is unavailable. |
|3301100 | The location switch is off. |
|3301200 | Failed to obtain the geographical location. |
**Example**
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0};
try {
geoLocationManager.getCurrentLocation(requestInfo).then((result) => {
console.log('current location: ' + JSON.stringify(result));
})
.catch((error) => {
console.log('promise, getCurrentLocation: error=' + JSON.stringify(error));
});
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
```
## geoLocationManager.getLastLocation
getLastLocation(): Location
Obtains the last location.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Core
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Location | [Location](#location) | NA | Location information.|
**Error codes**
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
|3301000 | Location service is unavailable. |
|3301100 | The location switch is off. |
|3301200 |Failed to obtain the geographical location. |
**Example**
```ts
import geoLocationManager from '@ohos.geoLocationManager';
try {
var location = geoLocationManager.getLastLocation();
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
```
## geoLocationManager.isLocationEnabled
isLocationEnabled(): boolean
Checks whether the location service is enabled.
**System capability**: SystemCapability.Location.Location.Core
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| boolean | boolean | NA | Result indicating whether the location service is enabled.|
| Promise&lt;[Location](#location)&gt; | [Location](#location) | NA | Promise used to return the current location.|
**Error codes**
......@@ -872,34 +1068,42 @@ For details about the following error codes, see [Location Error Codes](../error
| ID| Error Message|
| -------- | ---------------------------------------- |
|3301000 | Location service is unavailable. |
|3301100 | The location switch is off. |
|3301200 | Failed to obtain the geographical location. |
**Example**
```ts
import geoLocationManager from '@ohos.geoLocationManager';
let requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0};
try {
var locationEnabled = geoLocationManager.isLocationEnabled();
geoLocationManager.getCurrentLocation(requestInfo).then((result) => {
console.log('current location: ' + JSON.stringify(result));
})
.catch((error) => {
console.log('promise, getCurrentLocation: error=' + JSON.stringify(error));
});
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
```
## geoLocationManager.requestEnableLocation
## geoLocationManager.getLastLocation
requestEnableLocation(callback: AsyncCallback&lt;boolean&gt;): void
getLastLocation(): Location
Requests to enable the location service. This API uses an asynchronous callback to return the result.
Obtains the last location.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Core
**Parameters**
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return the result. The value **true** indicates that the user agrees to enable the location service, and the value **false** indicates the opposite.|
| Location | [Location](#location) | NA | Location information.|
**Error codes**
......@@ -908,34 +1112,26 @@ For details about the following error codes, see [Location Error Codes](../error
| ID| Error Message|
| -------- | ---------------------------------------- |
|3301000 | Location service is unavailable. |
|3301700 | No response to the request. |
|3301100 | The location switch is off. |
|3301200 |Failed to obtain the geographical location. |
**Example**
```ts
import geoLocationManager from '@ohos.geoLocationManager';
try {
geoLocationManager.requestEnableLocation((err, data) => {
if (err) {
console.log('requestEnableLocation: err=' + JSON.stringify(err));
}
if (data) {
console.log('requestEnableLocation: data=' + JSON.stringify(data));
}
});
let location = geoLocationManager.getLastLocation();
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
```
## geoLocationManager.requestEnableLocation
requestEnableLocation(): Promise&lt;boolean&gt;
## geoLocationManager.isLocationEnabled
Requests to enable the location service. This API uses a promise to return the result.
isLocationEnabled(): boolean
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
Checks whether the location service is enabled.
**System capability**: SystemCapability.Location.Location.Core
......@@ -943,7 +1139,7 @@ Requests to enable the location service. This API uses a promise to return the r
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Promise&lt;boolean&gt; | boolean | NA | Promise used to return the result. The value **true** indicates that the user agrees to enable the location service, and the value **false** indicates the opposite.|
| boolean | boolean | NA | Result indicating whether the location service is enabled.|
**Error codes**
......@@ -952,19 +1148,13 @@ For details about the following error codes, see [Location Error Codes](../error
| ID| Error Message|
| -------- | ---------------------------------------- |
|3301000 | Location service is unavailable. |
|3301700 | No response to the request. |
**Example**
```ts
import geoLocationManager from '@ohos.geoLocationManager';
try {
geoLocationManager.requestEnableLocation().then((result) => {
console.log('promise, requestEnableLocation: ' + JSON.stringify(result));
})
.catch((error) => {
console.log('promise, requestEnableLocation: error=' + JSON.stringify(error));
});
let locationEnabled = geoLocationManager.isLocationEnabled();
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
......@@ -1092,7 +1282,7 @@ For details about the following error codes, see [Location Error Codes](../error
getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback&lt;Array&lt;GeoAddress&gt;&gt;): void
Converts coordinates into geographic description through reverse geocoding. This API uses an asynchronous callback to return the result.
Converts coordinates into geographic descriptions through reverse geocoding. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Location.Location.Geocoder
......@@ -1116,7 +1306,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
let reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
try {
geoLocationManager.getAddressesFromLocation(reverseGeocodeRequest, (err, data) => {
if (err) {
......@@ -1136,7 +1326,7 @@ For details about the following error codes, see [Location Error Codes](../error
getAddressesFromLocation(request: ReverseGeoCodeRequest): Promise&lt;Array&lt;GeoAddress&gt;&gt;;
Converts coordinates into geographic description through reverse geocoding. This API uses a promise to return the result.
Converts coordinates into geographic descriptions through reverse geocoding. This API uses a promise to return the result.
**System capability**: SystemCapability.Location.Location.Geocoder
......@@ -1165,7 +1355,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
let reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
try {
geoLocationManager.getAddressesFromLocation(reverseGeocodeRequest).then((data) => {
console.log('getAddressesFromLocation: ' + JSON.stringify(data));
......@@ -1183,7 +1373,7 @@ For details about the following error codes, see [Location Error Codes](../error
getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback&lt;Array&lt;GeoAddress&gt;&gt;): void
Converts geographic description into coordinates through geocoding. This API uses an asynchronous callback to return the result.
Converts geographic descriptions into coordinates through geocoding. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Location.Location.Geocoder
......@@ -1207,7 +1397,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
let geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
try {
geoLocationManager.getAddressesFromLocationName(geocodeRequest, (err, data) => {
if (err) {
......@@ -1227,7 +1417,7 @@ For details about the following error codes, see [Location Error Codes](../error
getAddressesFromLocationName(request: GeoCodeRequest): Promise&lt;Array&lt;GeoAddress&gt;&gt;
Converts geographic description into coordinates through geocoding. This API uses a promise to return the result.
Converts geographic descriptions into coordinates through geocoding. This API uses a promise to return the result.
**System capability**: SystemCapability.Location.Location.Geocoder
......@@ -1256,7 +1446,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
let geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
try {
geoLocationManager.getAddressesFromLocationName(geocodeRequest).then((result) => {
console.log('getAddressesFromLocationName: ' + JSON.stringify(result));
......@@ -1296,7 +1486,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
try {
var isAvailable = geoLocationManager.isGeocoderAvailable();
let isAvailable = geoLocationManager.isGeocoderAvailable();
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
......@@ -1309,7 +1499,7 @@ getCachedGnssLocationsSize(callback: AsyncCallback&lt;number&gt;): void;
Obtains the number of cached GNSS locations.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Gnss
......@@ -1353,7 +1543,7 @@ getCachedGnssLocationsSize(): Promise&lt;number&gt;;
Obtains the number of cached GNSS locations.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Gnss
......@@ -1395,7 +1585,7 @@ flushCachedGnssLocations(callback: AsyncCallback&lt;void&gt;): void;
Obtains all cached GNSS locations and clears the GNSS cache queue.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Gnss
......@@ -1437,7 +1627,7 @@ flushCachedGnssLocations(): Promise&lt;void&gt;;
Obtains all cached GNSS locations and clears the GNSS cache queue.
**Permission required**: ohos.permission.APPROXIMATELY_LOCATION
**Required permissions**: ohos.permission.APPROXIMATELY_LOCATION
**System capability**: SystemCapability.Location.Location.Gnss
......@@ -1501,7 +1691,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var requestInfo = {'scenario': 0x301, 'command': "command_1"};
let requestInfo = {'scenario': 0x301, 'command': "command_1"};
try {
geoLocationManager.sendCommand(requestInfo, (err, result) => {
if (err) {
......@@ -1546,7 +1736,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var requestInfo = {'scenario': 0x301, 'command': "command_1"};
let requestInfo = {'scenario': 0x301, 'command': "command_1"};
try {
geoLocationManager.sendCommand(requestInfo).then((result) => {
console.log('promise, sendCommand success');
......@@ -1614,7 +1804,7 @@ Obtains the current country code.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Promise&lt;[CountryCode](#countrycode)&gt; | [CountryCode](#countrycode) | NA | Callback used to return the country code.|
| Promise&lt;[CountryCode](#countrycode)&gt; | [CountryCode](#countrycode) | NA | Promise used to return the country code.|
**Error codes**
......@@ -1711,6 +1901,8 @@ setMockedLocations(config: LocationMockConfig): void;
Sets the mock location information. The mock locations will be reported at the interval specified in this API.
This API can be invoked only after [geoLocationManager.enableLocationMock](#geolocationmanagerenablelocationmock) is called.
**System capability**: SystemCapability.Location.Location.Core
**System API**: This is a system API and cannot be called by third-party applications.
......@@ -1734,15 +1926,16 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var locations = [
let locations = [
{"latitude": 30.12, "longitude": 120.11, "altitude": 123, "accuracy": 1, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 1000000000, "additionSize": 0, "isFromMock": true},
{"latitude": 31.13, "longitude": 121.11, "altitude": 123, "accuracy": 2, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 2000000000, "additionSize": 0, "isFromMock": true},
{"latitude": 32.14, "longitude": 122.11, "altitude": 123, "accuracy": 3, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 3000000000, "additionSize": 0, "isFromMock": true},
{"latitude": 33.15, "longitude": 123.11, "altitude": 123, "accuracy": 4, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 4000000000, "additionSize": 0, "isFromMock": true},
{"latitude": 34.16, "longitude": 124.11, "altitude": 123, "accuracy": 5, "speed": 5.2, "timeStamp": 16594326109, "direction": 123.11, "timeSinceBoot": 5000000000, "additionSize": 0, "isFromMock": true}
];
var config = {"timeInterval": 5, "locations": locations};
let config = {"timeInterval": 5, "locations": locations};
try {
geoLocationManager.enableLocationMock();
geoLocationManager.setMockedLocations(config);
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
......@@ -1816,6 +2009,8 @@ setReverseGeocodingMockInfo(mockInfos: Array&lt;ReverseGeocodingMockInfo&gt;): v
Sets information of the mock reverse geocoding function, including the mapping between a location and geographic name. If the location is contained in the configurations during reverse geocoding query, the corresponding geographic name will be returned.
This API can be invoked only after [geoLocationManager.enableReverseGeocodingMock](#geolocationmanagerenablereversegeocodingmock) is called.
**System capability**: SystemCapability.Location.Location.Core
**System API**: This is a system API and cannot be called by third-party applications.
......@@ -1824,7 +2019,7 @@ Sets information of the mock reverse geocoding function, including the mapping b
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| mockInfos | Array&lt;[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)&gt; | Yes| Array of information of the mock reverse geocoding function, including a location and a geographic name.|
| mockInfos | Array&lt;[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)&gt; | Yes| Array of information of the mock reverse geocoding function, including a location and a geographic address.|
**Error codes**
......@@ -1838,7 +2033,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
var mockInfos = [
let mockInfos = [
{"location": {"locale": "zh", "latitude": 30.12, "longitude": 120.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 30.12, "longitude": 120.11, "maxItems": 1, "isFromMock": true}},
{"location": {"locale": "zh", "latitude": 31.12, "longitude": 121.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 31.12, "longitude": 121.11, "maxItems": 1, "isFromMock": true}},
{"location": {"locale": "zh", "latitude": 32.12, "longitude": 122.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 32.12, "longitude": 122.11, "maxItems": 1, "isFromMock": true}},
......@@ -1846,6 +2041,7 @@ For details about the following error codes, see [Location Error Codes](../error
{"location": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "maxItems": 1, "isFromMock": true}},
];
try {
geoLocationManager.enableReverseGeocodingMock();
geoLocationManager.setReverseGeocodingMockInfo(mockInfos);
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
......@@ -1873,7 +2069,7 @@ Checks whether a user agrees with the privacy statement of the location service.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| boolean | boolean | NA | Result indicating whether the user agrees with the privacy statement.|
| boolean | boolean | NA | Whether the user agrees with the privacy statement.|
**Error codes**
......@@ -1888,7 +2084,7 @@ For details about the following error codes, see [Location Error Codes](../error
```ts
import geoLocationManager from '@ohos.geoLocationManager';
try {
var isConfirmed = geoLocationManager.isLocationPrivacyConfirmed(1);
let isConfirmed = geoLocationManager.isLocationPrivacyConfirmed(1);
} catch (err) {
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
......@@ -1932,276 +2128,3 @@ For details about the following error codes, see [Location Error Codes](../error
console.error("errCode:" + err.code + ",errMessage:" + err.message);
}
```
## LocationRequestPriority
Sets the priority of the location request.
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| UNSET | 0x200 | Priority unspecified.|
| ACCURACY | 0x201 | Location accuracy.|
| LOW_POWER | 0x202 | Power efficiency.|
| FIRST_FIX | 0x203 | Fast location. Use this option if you want to obtain a location as fast as possible.|
## LocationRequestScenario
Sets the scenario of the location request.
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| UNSET | 0x300 | Scenario unspecified.|
| NAVIGATION | 0x301 | Navigation.|
| TRAJECTORY_TRACKING | 0x302 | Trajectory tracking.|
| CAR_HAILING | 0x303 | Ride hailing.|
| DAILY_LIFE_SERVICE | 0x304 | Daily life services.|
| NO_POWER | 0x305 | Power efficiency. 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. In this way, your application will not consume extra power for obtaining the user location.|
## ReverseGeoCodeRequest
Defines a reverse geocoding request.
**System capability**: SystemCapability.Location.Location.Geocoder
| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| latitude | number | Yes| Yes| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.|
| longitude | number | Yes| Yes| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.|
| maxItems | number | Yes| Yes| Maximum number of location records to be returned.|
## GeoCodeRequest
Defines a geocoding request.
**System capability**: SystemCapability.Location.Location.Geocoder
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| description | string | Yes| Yes| Location description, for example, **No. xx, xx Road, Pudong New District, Shanghai**.|
| maxItems | number | Yes| Yes| Maximum number of location records to be returned.|
| minLatitude | number | Yes| Yes| Minimum latitude. This parameter is used with **minLongitude**, **maxLatitude**, and **maxLongitude** to specify the latitude and longitude ranges.|
| minLongitude | number | Yes| Yes| Minimum longitude.|
| maxLatitude | number | Yes| Yes| Maximum latitude.|
| maxLongitude | number | Yes| Yes| Maximum longitude.|
## GeoAddress
Defines a geographic location.
**System capability**: SystemCapability.Location.Location.Geocoder
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| latitude | number | Yes| No | Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.|
| longitude | number | Yes| No | Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.|
| locale | string | Yes| No | Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| placeName | string | Yes| No | Landmark of the location.|
| countryCode | string | Yes| No | Country code.|
| countryName | string| Yes| No| Country name.|
| administrativeArea | string | Yes| No| Administrative region name.|
| subAdministrativeArea | string | Yes| No| Sub-administrative region name.|
| locality | string | Yes| No| Locality information.|
| subLocality | string | Yes| No| Sub-locality information.|
| roadName | string | Yes| No|Road name.|
| subRoadName | string | Yes| No| Auxiliary road information.|
| premises | string| Yes| No|House information.|
| postalCode | string | Yes| No| Postal code.|
| phoneNumber | string | Yes| No| Phone number.|
| addressUrl | string | Yes| No| Website URL.|
| descriptions | Array&lt;string&gt; | Yes| No| Additional descriptions.|
| descriptionsSize | number | Yes| No| Total number of additional descriptions.|
| isFromMock | Boolean | Yes| No| Whether the geographic name is from the mock reverse geocoding function.|
## LocationRequest
Defines a location request.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request.|
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes| Scenario of the location request.|
| timeInterval | number | Yes| Yes| Time interval at which location information is reported.|
| distanceInterval | number | Yes| Yes| Distance interval at which location information is reported.|
| maxAccuracy | number | Yes| Yes| Location accuracy. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled.|
## CurrentLocationRequest
Defines the current location request.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request.|
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes| Scenario of the location request.|
| maxAccuracy | number | Yes| Yes| Location accuracy, in meters. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled.|
| timeoutMs | number | Yes| Yes| Timeout duration, in milliseconds. The minimum value is **1000**.|
## SatelliteStatusInfo
Defines the satellite status information.
**System capability**: SystemCapability.Location.Location.Gnss
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| satellitesNumber | number | Yes| No| Number of satellites.|
| satelliteIds | Array&lt;number&gt; | Yes| No| Array of satellite IDs.|
| carrierToNoiseDensitys | Array&lt;number&gt; | Yes| No| Carrier-to-noise density ratio, that is, **cn0**.|
| altitudes | Array&lt;number&gt; | Yes| No| Altitude information.|
| azimuths | Array&lt;number&gt; | Yes| No| Azimuth information.|
| carrierFrequencies | Array&lt;number&gt; | Yes| No| Carrier frequency.|
## CachedGnssLocationsRequest
Represents a request for reporting cached GNSS locations.
**System capability**: SystemCapability.Location.Location.Gnss
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| reportingPeriodSec | number | Yes| Yes| Interval for reporting the cached GNSS locations, in milliseconds.|
| wakeUpCacheQueueFull | boolean | Yes| Yes | **true**: reports the cached GNSS locations to the application when the cache queue is full.<br>**false**: discards the cached GNSS locations when the cache queue is full.|
## Geofence
Defines a GNSS geofence. Currently, only circular geofences are supported.
**System capability**: SystemCapability.Location.Location.Geofence
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| latitude | number | Yes| Yes|Latitude information.|
| longitude | number | Yes|Yes| Longitude information.|
| radius | number | Yes|Yes| Radius of a circular geofence.|
| expiration | number | Yes|Yes| Expiration period of a geofence, in milliseconds.|
## GeofenceRequest
Represents a GNSS geofencing request.
**System capability**: SystemCapability.Location.Location.Geofence
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes | Location scenario.|
| geofence | [Geofence](#geofence)| Yes| Yes | Geofence information.|
## LocationPrivacyType
Defines the privacy statement type.
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| OTHERS | 0 | Other scenarios.|
| STARTUP | 1 | Privacy statement displayed in the startup wizard.|
| CORE_LOCATION | 2 | Privacy statement displayed when enabling the location service.|
## LocationCommand
Defines an extended command.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes | Location scenario.|
| command | string | Yes| Yes | Extended command, in the string format.|
## Location
Defines a location.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| latitude | number| Yes| No| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.|
| longitude | number| Yes| No| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.|
| altitude | number | Yes| No| Location altitude, in meters.|
| accuracy | number | Yes| No| Location accuracy, in meters.|
| speed | number | Yes| No|Speed, in m/s.|
| timeStamp | number | Yes| No| Location timestamp in the UTC format.|
| direction | number | Yes| No| Direction information.|
| timeSinceBoot | number | Yes| No| Location timestamp since boot.|
| additions | Array&lt;string&gt; | Yes| No| Additional description.|
| additionSize | number | Yes| No| Number of additional descriptions.|
| isFromMock | Boolean | Yes| No| Whether the location information is from the mock location function.|
## ReverseGeocodingMockInfo
Represents information of the mock reverse geocoding function.
**System capability**: SystemCapability.Location.Location.Core
**System API**: This is a system API and cannot be called by third-party applications.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| location | [ReverseGeoCodeRequest](#reversegeocoderequest) | Yes| Yes| Latitude and longitude information.|
| geoAddress | [GeoAddress](#geoaddress) | Yes| Yes|Geographic name.|
## LocationMockConfig
Represents the information of the mock location function.
**System capability**: SystemCapability.Location.Location.Core
**System API**: This is a system API and cannot be called by third-party applications.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| timeInterval | number | Yes| Yes| Interval at which mock locations are reported, in seconds.|
| locations | Array&lt;Location&gt; | Yes| Yes| Array of mocked locations.|
## CountryCode
Represents country code information.
**System capability**: SystemCapability.Location.Location.Core
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| country | string | Yes| No| Country code.|
| type | [CountryCodeType](#countrycodetype) | Yes| No| Country code source.|
## CountryCodeType
Represents the country code source type.
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| COUNTRY_CODE_FROM_LOCALE | 1 | Country code obtained from the language configuration of the globalization module.|
| COUNTRY_CODE_FROM_SIM | 2 | Country code obtained from the SIM card.|
| COUNTRY_CODE_FROM_LOCATION | 3 | Country code obtained using the reverse geocoding function based on the user's location information.|
| COUNTRY_CODE_FROM_NETWORK | 4 | Country code obtained from the cellular network registration information.|
en/application-dev/reference/apis/js-apis-geolocation.md
浏览文件 @ d7b16f6e
# @ohos.geolocation (Geolocation)
# Geolocation
The **geolocation** module provides location services such as GNSS positioning, network positioning, geocoding, reverse geocoding, country code and geofencing.
The **geolocation** module provides a wide array of location services, including GNSS positioning, network positioning, geocoding, reverse geocoding, and geofencing.
> **NOTE**
>
> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The APIs provided by this module are no longer maintained since API version 9. You are advised to use [geoLocationManager](js-apis-geoLocationManager.md) instead.
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs provided by this module are no longer maintained since API version 9. You are advised to use [geoLocationManager](js-apis-geoLocationManager.md) instead.
## Applying for Permissions
......@@ -20,18 +19,18 @@ The system provides the following location permissions:
If your application needs to access the device location information, it must first apply for required permissions. Specifically speaking:
- API versions earlier than 9: Apply for **ohos.permission.LOCATION**.
API versions earlier than 9: Apply for **ohos.permission.LOCATION**.
- API version 9 and later: Apply for **ohos.permission.APPROXIMATELY\_LOCATION**, or apply for **ohos.permission.APPROXIMATELY\_LOCATION** and **ohos.permission.LOCATION**. Note that **ohos.permission.LOCATION** cannot be applied for separately.
API version 9 and later: Apply for **ohos.permission.APPROXIMATELY_LOCATION**, or apply for **ohos.permission.APPROXIMATELY_LOCATION** and **ohos.permission.LOCATION**. Note that **ohos.permission.LOCATION** cannot be applied for separately.
| API Version| Location Permission| Permission Application Result| Location Accuracy|
| -------- | -------- | -------- | -------- |
| Earlier than 9| ohos.permission.LOCATION | Success| Location accurate to meters|
| 9 and later| ohos.permission.LOCATION | Failure| No location obtained|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION | Success| Location accurate to 5 kilometers|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Success| Location accurate to meters|
| Earlier than 9| ohos.permission.LOCATION | Successful| Location accurate to meters.|
| 9 and later| ohos.permission.LOCATION | Failed| No location obtained.|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION | Successful| Location accurate to 5 kilometers.|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Successful| Location accurate to meters.|
If your application needs to access the device location information when running in the background, it must be configured to be able to run in the background and be granted the **ohos.permission.LOCATION\_IN\_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background.
If your application needs to access the device location information when running in the background, it must be configured to be able to run in the background and be granted the **ohos.permission.LOCATION_IN_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background.
You can declare the required permission in your application's configuration file. For details, see [Access Control (Permission) Development](../../security/accesstoken-guidelines.md).
......@@ -42,11 +41,11 @@ You can declare the required permission in your application's configuration file
import geolocation from '@ohos.geolocation';
```
## geolocation.on('locationChange')<sup>(deprecated) </sup>
## geolocation.on('locationChange')<sup>(deprecated)</sup>
on(type: 'locationChange', request: LocationRequest, callback: Callback&lt;Location&gt;): void
Registers a listener for location changes with a location request initiated. The location result is reported through [LocationRequest](#locationrequest).
Registers a listener for location changes with a location request initiated.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.on('locationChange')](js-apis-geoLocationManager.md#geolocationmanageronlocationchange).
......@@ -60,23 +59,24 @@ Registers a listener for location changes with a location request initiated. The
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **locationChange** indicates a location change event.|
| request | [LocationRequest](#locationrequest) | Yes| Location request.|
| callback | Callback&lt;[Location](#location)&gt; | Yes| Callback used to return the location change event.|
| request | [LocationRequest](#locationrequestdeprecated) | Yes| Location request.|
| callback | Callback&lt;[Location](#locationdeprecated)&gt; | Yes| Callback used to return the location change event.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
var locationChange = (location) => {
let requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
let locationChange = (location) => {
console.log('locationChanger: data: ' + JSON.stringify(location));
};
geolocation.on('locationChange', requestInfo, locationChange);
```
## geolocation.off('locationChange')<sup>(deprecated) </sup>
## geolocation.off('locationChange')<sup>(deprecated)</sup>
off(type: 'locationChange', callback?: Callback&lt;Location&gt;): void
......@@ -94,15 +94,15 @@ Unregisters the listener for location changes with the corresponding location re
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **locationChange** indicates a location change event.|
| callback | Callback&lt;[Location](#location)&gt; | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
| callback | Callback&lt;[Location](#locationdeprecated)&gt; | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
var locationChange = (location) => {
let requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0};
let locationChange = (location) => {
console.log('locationChanger: data: ' + JSON.stringify(location));
};
geolocation.on('locationChange', requestInfo, locationChange);
......@@ -110,7 +110,7 @@ Unregisters the listener for location changes with the corresponding location re
```
## geolocation.on('locationServiceState')<sup>(deprecated) </sup>
## geolocation.on('locationServiceState')<sup>(deprecated)</sup>
on(type: 'locationServiceState', callback: Callback&lt;boolean&gt;): void
......@@ -135,14 +135,14 @@ Registers a listener for location service status change events.
```ts
import geolocation from '@ohos.geolocation';
var locationServiceState = (state) => {
let locationServiceState = (state) => {
console.log('locationServiceState: ' + JSON.stringify(state));
}
geolocation.on('locationServiceState', locationServiceState);
```
## geolocation.off('locationServiceState')<sup>(deprecated) </sup>
## geolocation.off('locationServiceState')<sup>(deprecated)</sup>
off(type: 'locationServiceState', callback?: Callback&lt;boolean&gt;): void;
......@@ -167,7 +167,7 @@ Unregisters the listener for location service status change events.
```ts
import geolocation from '@ohos.geolocation';
var locationServiceState = (state) => {
let locationServiceState = (state) => {
console.log('locationServiceState: state: ' + JSON.stringify(state));
}
geolocation.on('locationServiceState', locationServiceState);
......@@ -175,14 +175,13 @@ Unregisters the listener for location service status change events.
```
## geolocation.on('cachedGnssLocationsReporting')<sup>(deprecated) </sup>
## geolocation.on('cachedGnssLocationsReporting')<sup>(deprecated)</sup>
on(type: 'cachedGnssLocationsReporting', request: CachedGnssLocationsRequest, callback: Callback&lt;Array&lt;Location&gt;&gt;): void;
Registers a listener for cached GNSS location reports.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.on('cachedGnssLocationsChange')](js-apis-geoLocationManager.md#geolocationmanageroncachedgnsslocationschange).
......@@ -195,30 +194,29 @@ Registers a listener for cached GNSS location reports.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **cachedGnssLocationsReporting** indicates reporting of cached GNSS locations.|
| request | [CachedGnssLocationsRequest](#cachedgnsslocationsrequest) | Yes| Request for reporting cached GNSS location.|
| callback | Callback&lt;Array&lt;[Location](#location)&gt;&gt; | Yes| Callback used to return cached GNSS locations.|
| request | [CachedGnssLocationsRequest](#cachedgnsslocationsrequestdeprecated) | Yes| Request for reporting cached GNSS location.|
| callback | Callback&lt;Array&lt;[Location](#locationdeprecated)&gt;&gt; | Yes| Callback used to return cached GNSS locations.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var cachedLocationsCb = (locations) => {
let cachedLocationsCb = (locations) => {
console.log('cachedGnssLocationsReporting: locations: ' + JSON.stringify(locations));
}
var requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true};
let requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true};
geolocation.on('cachedGnssLocationsReporting', requestInfo, cachedLocationsCb);
```
## geolocation.off('cachedGnssLocationsReporting')<sup>(deprecated) </sup>
## geolocation.off('cachedGnssLocationsReporting')<sup>(deprecated)</sup>
off(type: 'cachedGnssLocationsReporting', callback?: Callback&lt;Array&lt;Location&gt;&gt;): void;
Unregisters the listener for cached GNSS location reports.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.off('cachedGnssLocationsChange')](js-apis-geoLocationManager.md#geolocationmanageroffcachedgnsslocationschange).
......@@ -231,30 +229,29 @@ Unregisters the listener for cached GNSS location reports.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **cachedGnssLocationsReporting** indicates reporting of cached GNSS locations.|
| callback | Callback&lt;Array&lt;[Location](#location)&gt;&gt; | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
| callback | Callback&lt;Array&lt;[Location](#locationdeprecated)&gt;&gt; | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var cachedLocationsCb = (locations) => {
let cachedLocationsCb = (locations) => {
console.log('cachedGnssLocationsReporting: locations: ' + JSON.stringify(locations));
}
var requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true};
let requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true};
geolocation.on('cachedGnssLocationsReporting', requestInfo, cachedLocationsCb);
geolocation.off('cachedGnssLocationsReporting');
```
## geolocation.on('gnssStatusChange')<sup>(deprecated) </sup>
## geolocation.on('gnssStatusChange')<sup>(deprecated)</sup>
on(type: 'gnssStatusChange', callback: Callback&lt;SatelliteStatusInfo&gt;): void;
Registers a listener for GNSS satellite status change events.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.on('satelliteStatusChange')](js-apis-geoLocationManager.md#geolocationmanageronsatellitestatuschange).
......@@ -267,28 +264,27 @@ Registers a listener for GNSS satellite status change events.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **gnssStatusChange** indicates a GNSS satellite status change.|
| callback | Callback&lt;[SatelliteStatusInfo](#satellitestatusinfo)&gt; | Yes| Callback used to return GNSS satellite status changes.|
| callback | Callback&lt;[SatelliteStatusInfo](#satellitestatusinfodeprecated)&gt; | Yes| Callback used to return GNSS satellite status changes.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var gnssStatusCb = (satelliteStatusInfo) => {
let gnssStatusCb = (satelliteStatusInfo) => {
console.log('gnssStatusChange: ' + JSON.stringify(satelliteStatusInfo));
}
geolocation.on('gnssStatusChange', gnssStatusCb);
```
## geolocation.off('gnssStatusChange')<sup>(deprecated) </sup>
## geolocation.off('gnssStatusChange')<sup>(deprecated)</sup>
off(type: 'gnssStatusChange', callback?: Callback&lt;SatelliteStatusInfo&gt;): void;
Unregisters the listener for GNSS satellite status change events.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.off('satelliteStatusChange')](js-apis-geoLocationManager.md#geolocationmanageroffsatellitestatuschange).
......@@ -301,13 +297,13 @@ Unregisters the listener for GNSS satellite status change events.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **gnssStatusChange** indicates a GNSS satellite status change.|
| callback | Callback&lt;[SatelliteStatusInfo](#satellitestatusinfo)&gt; | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
| callback | Callback&lt;[SatelliteStatusInfo](#satellitestatusinfodeprecated)&gt; | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var gnssStatusCb = (satelliteStatusInfo) => {
let gnssStatusCb = (satelliteStatusInfo) => {
console.log('gnssStatusChange: ' + JSON.stringify(satelliteStatusInfo));
}
geolocation.on('gnssStatusChange', gnssStatusCb);
......@@ -315,14 +311,13 @@ Unregisters the listener for GNSS satellite status change events.
```
## geolocation.on('nmeaMessageChange')<sup>(deprecated) </sup>
## geolocation.on('nmeaMessageChange')<sup>(deprecated)</sup>
on(type: 'nmeaMessageChange', callback: Callback&lt;string&gt;): void;
Registers a listener for GNSS NMEA message change events.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.on('nmeaMessage')](js-apis-geoLocationManager.md#geolocationmanageronnmeamessage).
......@@ -342,21 +337,20 @@ Registers a listener for GNSS NMEA message change events.
```ts
import geolocation from '@ohos.geolocation';
var nmeaCb = (str) => {
let nmeaCb = (str) => {
console.log('nmeaMessageChange: ' + JSON.stringify(str));
}
geolocation.on('nmeaMessageChange', nmeaCb );
```
## geolocation.off('nmeaMessageChange')<sup>(deprecated) </sup>
## geolocation.off('nmeaMessageChange')<sup>(deprecated)</sup>
off(type: 'nmeaMessageChange', callback?: Callback&lt;string&gt;): void;
Unregisters the listener for GNSS NMEA message change events.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.off('nmeaMessage')](js-apis-geoLocationManager.md#geolocationmanageroffnmeamessage).
......@@ -376,7 +370,7 @@ Unregisters the listener for GNSS NMEA message change events.
```ts
import geolocation from '@ohos.geolocation';
var nmeaCb = (str) => {
let nmeaCb = (str) => {
console.log('nmeaMessageChange: ' + JSON.stringify(str));
}
geolocation.on('nmeaMessageChange', nmeaCb);
......@@ -384,14 +378,13 @@ Unregisters the listener for GNSS NMEA message change events.
```
## geolocation.on('fenceStatusChange')<sup>(deprecated) </sup>
## geolocation.on('fenceStatusChange')<sup>(deprecated)</sup>
on(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent): void;
Registers a listener for status change events of the specified geofence.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.on('gnssFenceStatusChange')](js-apis-geoLocationManager.md#geolocationmanagerongnssfencestatuschange).
......@@ -404,21 +397,20 @@ Registers a listener for status change events of the specified geofence.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **fenceStatusChange** indicates a geofence status change.|
| request | [GeofenceRequest](#geofencerequest) | Yes| Geofencing request.|
| want | WantAgent | Yes| **WantAgent** used to return geofence (entrance or exit) events.|
| request | [GeofenceRequest](#geofencerequestdeprecated) | Yes| Geofencing request.|
| want | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes| **WantAgent** used to return geofence (entrance or exit) events.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
import wantAgent from '@ohos.wantAgent';
import wantAgent from '@ohos.app.ability.wantAgent';
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility",
abilityName: "EntryAbility",
action: "action1",
}
],
......@@ -428,20 +420,19 @@ Registers a listener for status change events of the specified geofence.
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
var requestInfo = {'priority': 0x201, 'scenario': 0x301, "geofence": {"latitude": 121, "longitude": 26, "radius": 100, "expiration": 10000}};
let requestInfo = {'priority': 0x201, 'scenario': 0x301, "geofence": {"latitude": 121, "longitude": 26, "radius": 100, "expiration": 10000}};
geolocation.on('fenceStatusChange', requestInfo, wantAgentObj);
});
```
## geolocation.off('fenceStatusChange')<sup>(deprecated) </sup>
## geolocation.off('fenceStatusChange')<sup>(deprecated)</sup>
off(type: 'fenceStatusChange', request: GeofenceRequest, want: WantAgent): void;
Unregisters the listener for status change events of the specified geofence.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.off('gnssFenceStatusChange')](js-apis-geoLocationManager.md#geolocationmanageroffgnssfencestatuschange).
......@@ -454,20 +445,20 @@ Unregisters the listener for status change events of the specified geofence.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value **fenceStatusChange** indicates a geofence status change.|
| request | [GeofenceRequest](#geofencerequest) | Yes| Geofencing request.|
| want | WantAgent | Yes| **WantAgent** used to return geofence (entrance or exit) events.|
| request | [GeofenceRequest](#geofencerequestdeprecated) | Yes| Geofencing request.|
| want | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes| **WantAgent** used to return geofence (entrance or exit) events.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
import wantAgent from '@ohos.wantAgent';
import wantAgent from '@ohos.app.ability.wantAgent';
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility",
abilityName: "EntryAbility",
action: "action1",
}
],
......@@ -477,14 +468,14 @@ Unregisters the listener for status change events of the specified geofence.
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
var requestInfo = {'priority': 0x201, 'scenario': 0x301, "geofence": {"latitude": 121, "longitude": 26, "radius": 100, "expiration": 10000}};
let requestInfo = {'priority': 0x201, 'scenario': 0x301, "geofence": {"latitude": 121, "longitude": 26, "radius": 100, "expiration": 10000}};
geolocation.on('fenceStatusChange', requestInfo, wantAgentObj);
geolocation.off('fenceStatusChange', requestInfo, wantAgentObj);
});
```
## geolocation.getCurrentLocation<sup>(deprecated) </sup>
## geolocation.getCurrentLocation<sup>(deprecated)</sup>
getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback&lt;Location&gt;): void
......@@ -501,15 +492,15 @@ Obtains the current location. This API uses an asynchronous callback to return t
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| request | [CurrentLocationRequest](#currentlocationrequest) | Yes| Location request.|
| callback | AsyncCallback&lt;[Location](#location)&gt; | Yes| Callback used to return the current location.|
| request | [CurrentLocationRequest](#currentlocationrequestdeprecated) | Yes| Location request.|
| callback | AsyncCallback&lt;[Location](#locationdeprecated)&gt; | Yes| Callback used to return the current location.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0};
var locationChange = (err, location) => {
let requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0};
let locationChange = (err, location) => {
if (err) {
console.log('locationChanger: err=' + JSON.stringify(err));
}
......@@ -521,7 +512,7 @@ Obtains the current location. This API uses an asynchronous callback to return t
```
## geolocation.getCurrentLocation<sup>(deprecated) </sup>
## geolocation.getCurrentLocation<sup>(deprecated)</sup>
getCurrentLocation(callback: AsyncCallback&lt;Location&gt;): void
......@@ -539,13 +530,13 @@ Obtains the current location. This API uses an asynchronous callback to return t
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[Location](#location)&gt; | Yes| Callback used to return the current location.|
| callback | AsyncCallback&lt;[Location](#locationdeprecated)&gt; | Yes| Callback used to return the current location.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var locationChange = (err, location) => {
let locationChange = (err, location) => {
if (err) {
console.log('locationChanger: err=' + JSON.stringify(err));
}
......@@ -557,7 +548,7 @@ Obtains the current location. This API uses an asynchronous callback to return t
```
## geolocation.getCurrentLocation<sup>(deprecated) </sup>
## geolocation.getCurrentLocation<sup>(deprecated)</sup>
getCurrentLocation(request?: CurrentLocationRequest): Promise&lt;Location&gt;
......@@ -574,27 +565,27 @@ Obtains the current location. This API uses a promise to return the result.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| request | [CurrentLocationRequest](#currentlocationrequest) | No| Location request.|
| request | [CurrentLocationRequest](#currentlocationrequestdeprecated) | No| Location request.|
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Promise&lt;[Location](#location)&gt; |[Location](#location)|NA| Promise used to return the current location.|
| Promise&lt;[Location](#locationdeprecated)&gt; |[Location](#locationdeprecated)|NA| Promise used to return the current location.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0};
let requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0};
geolocation.getCurrentLocation(requestInfo).then((result) => {
console.log('current location: ' + JSON.stringify(result));
});
```
## geolocation.getLastLocation<sup>(deprecated) </sup>
## geolocation.getLastLocation<sup>(deprecated)</sup>
getLastLocation(callback: AsyncCallback&lt;Location&gt;): void
......@@ -611,7 +602,7 @@ Obtains the previous location. This API uses an asynchronous callback to return
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;[Location](#location)&gt; | Yes| Callback used to return the previous location.|
| callback | AsyncCallback&lt;[Location](#locationdeprecated)&gt; | Yes| Callback used to return the previous location.|
**Example**
......@@ -629,7 +620,7 @@ Obtains the previous location. This API uses an asynchronous callback to return
```
## geolocation.getLastLocation<sup>(deprecated) </sup>
## geolocation.getLastLocation<sup>(deprecated)</sup>
getLastLocation(): Promise&lt;Location&gt;
......@@ -646,7 +637,7 @@ Obtains the previous location. This API uses a promise to return the result.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Promise&lt;[Location](#location)&gt; | [Location](#location)|NA|Promise used to return the previous location.|
| Promise&lt;[Location](#locationdeprecated)&gt; | [Location](#locationdeprecated)|NA|Promise used to return the previous location.|
**Example**
......@@ -659,7 +650,7 @@ Obtains the previous location. This API uses a promise to return the result.
```
## geolocation.isLocationEnabled<sup>(deprecated) </sup>
## geolocation.isLocationEnabled<sup>(deprecated)</sup>
isLocationEnabled(callback: AsyncCallback&lt;boolean&gt;): void
......@@ -693,7 +684,7 @@ Checks whether the location service is enabled. This API uses an asynchronous ca
```
## geolocation.isLocationEnabled<sup>(deprecated) </sup>
## geolocation.isLocationEnabled<sup>(deprecated)</sup>
isLocationEnabled(): Promise&lt;boolean&gt;
......@@ -722,14 +713,14 @@ Checks whether the location service is enabled. This API uses a promise to retur
```
## geolocation.requestEnableLocation<sup>(deprecated) </sup>
## geolocation.requestEnableLocation<sup>(deprecated)</sup>
requestEnableLocation(callback: AsyncCallback&lt;boolean&gt;): void
Requests to enable the location service. This API uses an asynchronous callback to return the result.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.requestEnableLocation](js-apis-geoLocationManager.md#geolocationmanagerrequestenablelocation).
> This API has been discarded since API version 9. It is recommended that a dialog box be displayed in the application to request the user to go to Settings to enable the location function and specify the scenarios in which the location information will be used in the dialog box.
**Required permissions**: ohos.permission.LOCATION
......@@ -756,14 +747,14 @@ Requests to enable the location service. This API uses an asynchronous callback
```
## geolocation.requestEnableLocation<sup>(deprecated) </sup>
## geolocation.requestEnableLocation<sup>(deprecated)</sup>
requestEnableLocation(): Promise&lt;boolean&gt;
Requests to enable the location service. This API uses a promise to return the result.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.requestEnableLocation](js-apis-geoLocationManager.md#geolocationmanagerrequestenablelocation-1).
> This API has been discarded since API version 9. It is recommended that a dialog box be displayed in the application to request the user to go to Settings to enable the location function and specify the scenarios in which the location information will be used in the dialog box.
**Required permissions**: ohos.permission.LOCATION
......@@ -785,7 +776,7 @@ Requests to enable the location service. This API uses a promise to return the r
```
## geolocation.isGeoServiceAvailable<sup>(deprecated) </sup>
## geolocation.isGeoServiceAvailable<sup>(deprecated)</sup>
isGeoServiceAvailable(callback: AsyncCallback&lt;boolean&gt;): void
......@@ -819,7 +810,7 @@ Checks whether the (reverse) geocoding service is available. This API uses an as
```
## geolocation.isGeoServiceAvailable<sup>(deprecated) </sup>
## geolocation.isGeoServiceAvailable<sup>(deprecated)</sup>
isGeoServiceAvailable(): Promise&lt;boolean&gt;
......@@ -848,11 +839,11 @@ Checks whether the (reverse) geocoding service is available. This API uses a pro
```
## geolocation.getAddressesFromLocation<sup>(deprecated) </sup>
## geolocation.getAddressesFromLocation<sup>(deprecated)</sup>
getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback&lt;Array&lt;GeoAddress&gt;&gt;): void
Converts coordinates into geographic description through reverse geocoding. This API uses an asynchronous callback to return the result.
Converts coordinates into geographic descriptions through reverse geocoding. This API uses an asynchronous callback to return the result.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.getAddressesFromLocation](js-apis-geoLocationManager.md#geolocationmanagergetaddressesfromlocation).
......@@ -865,14 +856,14 @@ Converts coordinates into geographic description through reverse geocoding. This
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| request | [ReverseGeoCodeRequest](#reversegeocoderequest) | Yes| Reverse geocoding request.|
| callback | AsyncCallback&lt;Array&lt;[GeoAddress](#geoaddress)&gt;&gt; | Yes| Callback used to return the reverse geocoding result.|
| request | [ReverseGeoCodeRequest](#reversegeocoderequestdeprecated) | Yes| Reverse geocoding request.|
| callback | AsyncCallback&lt;Array&lt;[GeoAddress](#geoaddressdeprecated)&gt;&gt; | Yes| Callback used to return the reverse geocoding result.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
let reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
geolocation.getAddressesFromLocation(reverseGeocodeRequest, (err, data) => {
if (err) {
console.log('getAddressesFromLocation: err=' + JSON.stringify(err));
......@@ -884,11 +875,11 @@ Converts coordinates into geographic description through reverse geocoding. This
```
## geolocation.getAddressesFromLocation<sup>(deprecated) </sup>
## geolocation.getAddressesFromLocation<sup>(deprecated)</sup>
getAddressesFromLocation(request: ReverseGeoCodeRequest): Promise&lt;Array&lt;GeoAddress&gt;&gt;;
Converts coordinates into geographic description through reverse geocoding. This API uses a promise to return the result.
Converts coordinates into geographic descriptions through reverse geocoding. This API uses a promise to return the result.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.getAddressesFromLocation](js-apis-geoLocationManager.md#geolocationmanagergetaddressesfromlocation-1).
......@@ -901,30 +892,30 @@ Converts coordinates into geographic description through reverse geocoding. This
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| request | [ReverseGeoCodeRequest](#reversegeocoderequest) | Yes| Reverse geocoding request.|
| request | [ReverseGeoCodeRequest](#reversegeocoderequestdeprecated) | Yes| Reverse geocoding request.|
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Promise&lt;Array&lt;[GeoAddress](#geoaddress)&gt;&gt; | Array&lt;[GeoAddress](#geoaddress)&gt;|NA|Promise used to return the reverse geocoding result.|
| Promise&lt;Array&lt;[GeoAddress](#geoaddressdeprecated)&gt;&gt; | Array&lt;[GeoAddress](#geoaddressdeprecated)&gt;|NA|Promise used to return the reverse geocoding result.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
let reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1};
geolocation.getAddressesFromLocation(reverseGeocodeRequest).then((data) => {
console.log('getAddressesFromLocation: ' + JSON.stringify(data));
});
```
## geolocation.getAddressesFromLocationName<sup>(deprecated) </sup>
## geolocation.getAddressesFromLocationName<sup>(deprecated)</sup>
getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback&lt;Array&lt;GeoAddress&gt;&gt;): void
Converts geographic description into coordinates through geocoding. This API uses an asynchronous callback to return the result.
Converts geographic descriptions into coordinates through geocoding. This API uses an asynchronous callback to return the result.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.getAddressesFromLocationName](js-apis-geoLocationManager.md#geolocationmanagergetaddressesfromlocationname).
......@@ -937,14 +928,14 @@ Converts geographic description into coordinates through geocoding. This API use
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| request | [GeoCodeRequest](#geocoderequest) | Yes| Geocoding request.|
| callback | AsyncCallback&lt;Array&lt;[GeoAddress](#geoaddress)&gt;&gt; | Yes| Callback used to return the geocoding result.|
| request | [GeoCodeRequest](#geocoderequestdeprecated) | Yes| Geocoding request.|
| callback | AsyncCallback&lt;Array&lt;[GeoAddress](#geoaddressdeprecated)&gt;&gt; | Yes| Callback used to return the geocoding result.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
let geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
geolocation.getAddressesFromLocationName(geocodeRequest, (err, data) => {
if (err) {
console.log('getAddressesFromLocationName: err=' + JSON.stringify(err));
......@@ -956,11 +947,11 @@ Converts geographic description into coordinates through geocoding. This API use
```
## geolocation.getAddressesFromLocationName<sup>(deprecated) </sup>
## geolocation.getAddressesFromLocationName<sup>(deprecated)</sup>
getAddressesFromLocationName(request: GeoCodeRequest): Promise&lt;Array&lt;GeoAddress&gt;&gt;
Converts geographic description into coordinates through geocoding. This API uses a promise to return the result.
Converts geographic descriptions into coordinates through geocoding. This API uses a promise to return the result.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.getAddressesFromLocationName](js-apis-geoLocationManager.md#geolocationmanagergetaddressesfromlocationname-1).
......@@ -973,33 +964,32 @@ Converts geographic description into coordinates through geocoding. This API use
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| request | [GeoCodeRequest](#geocoderequest) | Yes| Geocoding request.|
| request | [GeoCodeRequest](#geocoderequestdeprecated) | Yes| Geocoding request.|
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| Promise&lt;Array&lt;[GeoAddress](#geoaddress)&gt;&gt; | Array&lt;[GeoAddress](#geoaddress)&gt;|NA|Promise used to return the geocoding result.|
| Promise&lt;Array&lt;[GeoAddress](#geoaddressdeprecated)&gt;&gt; | Array&lt;[GeoAddress](#geoaddressdeprecated)&gt;|NA|Promise used to return the geocoding result.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
let geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1};
geolocation.getAddressesFromLocationName(geocodeRequest).then((result) => {
console.log('getAddressesFromLocationName: ' + JSON.stringify(result));
});
```
## geolocation.getCachedGnssLocationsSize<sup>(deprecated) </sup>
## geolocation.getCachedGnssLocationsSize<sup>(deprecated)</sup>
getCachedGnssLocationsSize(callback: AsyncCallback&lt;number&gt;): void;
Obtains the number of cached GNSS locations.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.getCachedGnssLocationsSize](js-apis-geoLocationManager.md#geolocationmanagergetcachedgnsslocationssize).
......@@ -1028,14 +1018,13 @@ Obtains the number of cached GNSS locations.
```
## geolocation.getCachedGnssLocationsSize<sup>(deprecated) </sup>
## geolocation.getCachedGnssLocationsSize<sup>(deprecated)</sup>
getCachedGnssLocationsSize(): Promise&lt;number&gt;;
Obtains the number of cached GNSS locations.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.getCachedGnssLocationsSize](js-apis-geoLocationManager.md#geolocationmanagergetcachedgnsslocationssize-1).
......@@ -1059,14 +1048,13 @@ Obtains the number of cached GNSS locations.
```
## geolocation.flushCachedGnssLocations<sup>(deprecated) </sup>
## geolocation.flushCachedGnssLocations<sup>(deprecated)</sup>
flushCachedGnssLocations(callback: AsyncCallback&lt;boolean&gt;): void;
Obtains all cached GNSS locations and clears the GNSS cache queue.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.flushCachedGnssLocations](js-apis-geoLocationManager.md#geolocationmanagerflushcachedgnsslocations).
......@@ -1095,14 +1083,13 @@ Obtains all cached GNSS locations and clears the GNSS cache queue.
```
## geolocation.flushCachedGnssLocations<sup>(deprecated) </sup>
## geolocation.flushCachedGnssLocations<sup>(deprecated)</sup>
flushCachedGnssLocations(): Promise&lt;boolean&gt;;
Obtains all cached GNSS locations and clears the GNSS cache queue.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.flushCachedGnssLocations](js-apis-geoLocationManager.md#geolocationmanagerflushcachedgnsslocations-1).
......@@ -1126,14 +1113,13 @@ Obtains all cached GNSS locations and clears the GNSS cache queue.
```
## geolocation.sendCommand<sup>(deprecated) </sup>
## geolocation.sendCommand<sup>(deprecated)</sup>
sendCommand(command: LocationCommand, callback: AsyncCallback&lt;boolean&gt;): void;
Sends an extended command to the location subsystem.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.sendCommand](js-apis-geoLocationManager.md#geolocationmanagersendcommand).
......@@ -1145,14 +1131,14 @@ Sends an extended command to the location subsystem.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| command | [LocationCommand](#locationcommand) | Yes| Extended command (string) to be sent.|
| command | [LocationCommand](#locationcommanddeprecated) | Yes| Extended command (string) to be sent.|
| callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return the operation result.|
**Example**
```ts
import geolocation from '@ohos.geolocation';
var requestInfo = {'scenario': 0x301, 'command': "command_1"};
let requestInfo = {'scenario': 0x301, 'command': "command_1"};
geolocation.sendCommand(requestInfo, (err, result) => {
if (err) {
console.log('sendCommand: err=' + JSON.stringify(err));
......@@ -1164,14 +1150,13 @@ Sends an extended command to the location subsystem.
```
## geolocation.sendCommand<sup>(deprecated) </sup>
## geolocation.sendCommand<sup>(deprecated)</sup>
sendCommand(command: LocationCommand): Promise&lt;boolean&gt;;
Sends an extended command to the location subsystem.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.sendCommand](js-apis-geoLocationManager.md#geolocationmanagersendcommand).
......@@ -1183,7 +1168,7 @@ Sends an extended command to the location subsystem.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| command | [LocationCommand](#locationcommand) | Yes| Extended command (string) to be sent.|
| command | [LocationCommand](#locationcommanddeprecated) | Yes| Extended command (string) to be sent.|
**Return value**
......@@ -1195,76 +1180,14 @@ Sends an extended command to the location subsystem.
```ts
import geolocation from '@ohos.geolocation';
var requestInfo = {'scenario': 0x301, 'command': "command_1"};
let requestInfo = {'scenario': 0x301, 'command': "command_1"};
geolocation.sendCommand(requestInfo).then((result) => {
console.log('promise, sendCommand: ' + JSON.stringify(result));
});
```
## LocationRequestPriority<sup>(deprecated) </sup>
Sets the priority of the location request.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.LocationRequestPriority](js-apis-geoLocationManager.md#locationrequestpriority).
**Required permissions**: ohos.permission.LOCATION
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| UNSET | 0x200 | Priority unspecified.|
| ACCURACY | 0x201 | Location accuracy.|
| LOW_POWER | 0x202 | Power efficiency.|
| FIRST_FIX | 0x203 | Fast location. Use this option if you want to obtain a location as fast as possible.|
## LocationRequestScenario<sup>(deprecated) </sup>
Sets the scenario of the location request.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.LocationRequestScenario](js-apis-geoLocationManager.md#locationrequestscenario).
**Required permissions**: ohos.permission.LOCATION
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| UNSET | 0x300 | Scenario unspecified.|
| NAVIGATION | 0x301 | Navigation.|
| TRAJECTORY_TRACKING | 0x302 | Trajectory tracking.|
| CAR_HAILING | 0x303 | Ride hailing.|
| DAILY_LIFE_SERVICE | 0x304 | Daily life services.|
| NO_POWER | 0x305 | Power efficiency. 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. In this way, your application will not consume extra power for obtaining the user location.|
## GeoLocationErrorCode<sup>(deprecated) </sup>
Enumerates error codes of the location service.
> **NOTE**<br>
> This API is deprecated since API version 9.
**Required permissions**: ohos.permission.LOCATION
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| INPUT_PARAMS_ERROR<sup>7+</sup> | 101 | Incorrect input parameters.|
| REVERSE_GEOCODE_ERROR<sup>7+</sup> | 102 | Failed to call the reverse geocoding API.|
| GEOCODE_ERROR<sup>7+</sup> | 103 | Failed to call the geocoding API.|
| LOCATOR_ERROR<sup>7+</sup> | 104 | Failed to obtain the location.|
| LOCATION_SWITCH_ERROR<sup>7+</sup> | 105 | Failed to change the location service switch.|
| LAST_KNOWN_LOCATION_ERROR<sup>7+</sup> | 106 | Failed to obtain the previous location.|
| LOCATION_REQUEST_TIMEOUT_ERROR<sup>7+</sup> | 107 | Failed to obtain the location within the specified time.|
## ReverseGeoCodeRequest<sup>(deprecated) </sup>
## ReverseGeoCodeRequest<sup>(deprecated)</sup>
Defines a reverse geocoding request.
......@@ -1278,12 +1201,12 @@ Defines a reverse geocoding request.
| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| latitude | number | Yes| Yes| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.|
| longitude | number | Yes| Yes| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.|
| maxItems | number | Yes| Yes| Maximum number of location records to be returned.|
| latitude | number | Yes| Yes| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude. The value ranges from **-90** to **90**.|
| longitude | number | Yes| Yes| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude . The value ranges from **-180** to **180**.|
| maxItems | number | Yes| Yes| Maximum number of location records to be returned. The value must be greater than or equal to **0**. A value smaller than **10** is recommended.|
## GeoCodeRequest<sup>(deprecated) </sup>
## GeoCodeRequest<sup>(deprecated)</sup>
Defines a geocoding request.
......@@ -1298,14 +1221,14 @@ Defines a geocoding request.
| -------- | -------- | -------- | -------- | -------- |
| locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| description | string | Yes| Yes| Location description, for example, **No. xx, xx Road, Pudong New District, Shanghai**.|
| maxItems | number | Yes| Yes| Maximum number of location records to be returned.|
| minLatitude | number | Yes| Yes| Minimum latitude. This parameter is used with **minLongitude**, **maxLatitude**, and **maxLongitude** to specify the latitude and longitude ranges.|
| minLongitude | number | Yes| Yes| Minimum longitude.|
| maxLatitude | number | Yes| Yes| Maximum latitude.|
| maxLongitude | number | Yes| Yes| Maximum longitude.|
| maxItems | number | Yes| Yes| Maximum number of location records to be returned. The value must be greater than or equal to **0**. A value smaller than **10** is recommended.|
| minLatitude | number | Yes| Yes| Minimum latitude. This parameter is used with **minLongitude**, **maxLatitude**, and **maxLongitude** to specify the latitude and longitude ranges. The value ranges from **-90** to **90**.|
| minLongitude | number | Yes| Yes| Minimum longitude. The value ranges from **-180** to **180**.|
| maxLatitude | number | Yes| Yes| Maximum latitude. The value ranges from **-90** to **90**.|
| maxLongitude | number | Yes| Yes| Maximum longitude. The value ranges from **-180** to **180**.|
## GeoAddress<sup>(deprecated) </sup>
## GeoAddress<sup>(deprecated)</sup>
Defines a geographic location.
......@@ -1318,8 +1241,8 @@ Defines a geographic location.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| latitude<sup>7+</sup> | number | Yes| No| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.|
| longitude<sup>7+</sup> | number | Yes| No| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.|
| latitude<sup>7+</sup> | number | Yes| No| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude. The value ranges from **-90** to **90**.|
| longitude<sup>7+</sup> | number | Yes| No| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude . The value ranges from **-180** to **180**.|
| locale<sup>7+</sup> | string | Yes| No| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| placeName<sup>7+</sup> | string | Yes| No| Landmark of the location.|
| countryCode<sup>7+</sup> | string | Yes| No| Country code.|
......@@ -1335,10 +1258,10 @@ Defines a geographic location.
| phoneNumber<sup>7+</sup> | string | Yes| No| Phone number.|
| addressUrl<sup>7+</sup> | string | Yes| No| Website URL.|
| descriptions<sup>7+</sup> | Array&lt;string&gt; | Yes| No| Additional descriptions.|
| descriptionsSize<sup>7+</sup> | number | Yes| No| Total number of additional descriptions.|
| descriptionsSize<sup>7+</sup> | number | Yes| No| Total number of additional descriptions. The value must be greater than or equal to **0**. A value smaller than **10** is recommended.|
## LocationRequest<sup>(deprecated) </sup>
## LocationRequest<sup>(deprecated)</sup>
Defines a location request.
......@@ -1351,14 +1274,14 @@ Defines a location request.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request.|
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes| Scenario of the location request.|
| timeInterval | number | Yes| Yes| Time interval at which location information is reported.|
| distanceInterval | number | Yes| Yes| Distance interval at which location information is reported.|
| maxAccuracy | number | Yes| Yes| Location accuracy. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled.|
| priority | [LocationRequestPriority](#locationrequestprioritydeprecated) | Yes| Yes| Priority of the location request. For details about the value range, see [LocationRequestPriority](#locationrequestprioritydeprecated).|
| scenario | [LocationRequestScenario](#locationrequestscenariodeprecated) | Yes| Yes| Scenario of the location request. For details about the value range, see [LocationRequestScenario](#locationrequestscenariodeprecated).|
| timeInterval | number | Yes| Yes| Time interval at which location information is reported, in seconds. The value must be greater than **0**.|
| distanceInterval | number | Yes| Yes| Distance interval at which location information is reported. The value must be greater than **0**, in meters.|
| maxAccuracy | number | Yes| Yes| Location accuracy. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled. The value must be greater than **0**.|
## CurrentLocationRequest<sup>(deprecated) </sup>
## CurrentLocationRequest<sup>(deprecated)</sup>
Defines the current location request.
......@@ -1371,18 +1294,17 @@ Defines the current location request.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request.|
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes| Scenario of the location request.|
| maxAccuracy | number | Yes| Yes| Location accuracy, in meters. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled.|
| timeoutMs | number | Yes| Yes| Timeout duration, in milliseconds. The minimum value is **1000**.|
| priority | [LocationRequestPriority](#locationrequestprioritydeprecated) | Yes| Yes| Priority of the location request. For details about the value range, see [LocationRequestPriority](#locationrequestprioritydeprecated).|
| scenario | [LocationRequestScenario](#locationrequestscenariodeprecated) | Yes| Yes| Scenario of the location request. For details about the value range, see [LocationRequestScenario](#locationrequestscenariodeprecated).|
| maxAccuracy | number | Yes| Yes| Location accuracy, in meters. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled. The value must be greater than **0**.|
| timeoutMs | number | Yes| Yes| Timeout duration, in milliseconds. The minimum value is **1000**. The value must be greater than or equal to **1000**.|
## SatelliteStatusInfo<sup>(deprecated) </sup>
## SatelliteStatusInfo<sup>(deprecated)</sup>
Defines the satellite status information.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.SatelliteStatusInfo](js-apis-geoLocationManager.md#satellitestatusinfo).
......@@ -1392,20 +1314,19 @@ Defines the satellite status information.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| satellitesNumber | number | Yes| No| Number of satellites.|
| satelliteIds | Array&lt;number&gt; | Yes| No| Array of satellite IDs.|
| carrierToNoiseDensitys | Array&lt;number&gt; | Yes| No| Carrier-to-noise density ratio, that is, **cn0**.|
| altitudes | Array&lt;number&gt; | Yes| No| Altitude information.|
| azimuths | Array&lt;number&gt; | Yes| No| Azimuth information.|
| carrierFrequencies | Array&lt;number&gt; | Yes| No| Carrier frequency.|
| satellitesNumber | number | Yes| No| Number of satellites. The value must be greater than or equal to **0**.|
| satelliteIds | Array&lt;number&gt; | Yes| No| Array of satellite IDs. The value must be greater than or equal to **0**.|
| carrierToNoiseDensitys | Array&lt;number&gt; | Yes| No| Carrier-to-noise density ratio, that is, **cn0**. The value must be greater than **0**.|
| altitudes | Array&lt;number&gt; | Yes| No| Satellite altitude angle information. The value ranges from **-90** to **90**, in degrees.|
| azimuths | Array&lt;number&gt; | Yes| No| Azimuth information. The value ranges from **0** to **360**, in degrees.|
| carrierFrequencies | Array&lt;number&gt; | Yes| No| Carrier frequency. The value must be greater than or equal to **0**, in Hz.|
## CachedGnssLocationsRequest<sup>(deprecated) </sup>
## CachedGnssLocationsRequest<sup>(deprecated)</sup>
Represents a request for reporting cached GNSS locations.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.CachedGnssLocationsRequest](js-apis-geoLocationManager.md#cachedgnsslocationsrequest).
......@@ -1415,16 +1336,15 @@ Represents a request for reporting cached GNSS locations.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| reportingPeriodSec | number | Yes| Yes| Interval for reporting the cached GNSS locations, in milliseconds.|
| reportingPeriodSec | number | Yes| Yes| Interval for reporting the cached GNSS locations, in milliseconds. The value must be greater than **0**.|
| wakeUpCacheQueueFull | boolean | Yes| Yes | **true**: reports the cached GNSS locations to the application when the cache queue is full.<br>**false**: discards the cached GNSS locations when the cache queue is full.|
## Geofence<sup>(deprecated) </sup>
## Geofence<sup>(deprecated)</sup>
Defines a GNSS geofence. Currently, only circular geofences are supported.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.Geofence](js-apis-geoLocationManager.md#geofence).
......@@ -1434,18 +1354,17 @@ Defines a GNSS geofence. Currently, only circular geofences are supported.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| latitude | number | Yes| Yes | Latitude information.|
| longitude | number | Yes| Yes | Longitude information.|
| radius | number | Yes| Yes | Radius of a circular geofence.|
| expiration | number | Yes| Yes | Expiration period of a geofence, in milliseconds.|
| latitude | number | Yes| Yes|Latitude information. The value ranges from **-90** to **90**.|
| longitude | number | Yes|Yes| Longitude information. The value ranges from **-180** to **180**.|
| radius | number | Yes|Yes| Radius of a circular geofence. The value must be greater than **0**, in meters.|
| expiration | number | Yes|Yes| Expiration period of a geofence, in milliseconds. The value must be greater than **0**.|
## GeofenceRequest<sup>(deprecated) </sup>
## GeofenceRequest<sup>(deprecated)</sup>
Represents a GNSS geofencing request.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.GeofenceRequest](js-apis-geoLocationManager.md#geofencerequest).
......@@ -1455,37 +1374,16 @@ Represents a GNSS geofencing request.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes | Priority of the location information.|
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes | Location scenario.|
| geofence | [Geofence](#geofence)| Yes| Yes | Geofence information.|
## LocationPrivacyType<sup>(deprecated) </sup>
Defines the privacy statement type.
> **NOTE**
>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.LocationPrivacyType](js-apis-geoLocationManager.md#locationprivacytype).
**Required permissions**: ohos.permission.LOCATION
**System capability**: SystemCapability.Location.Location.Core
| priority | [LocationRequestPriority](#locationrequestprioritydeprecated) | Yes| Yes | Priority of the location information.|
| scenario | [LocationRequestScenario](#locationrequestscenariodeprecated) | Yes| Yes | Location scenario.|
| geofence | [Geofence](#geofencedeprecated)| Yes| Yes | Geofence information.|
| Name| Value| Description|
| -------- | -------- | -------- |
| OTHERS | 0 | Other scenarios.|
| STARTUP | 1 | Privacy statement displayed in the startup wizard.|
| CORE_LOCATION | 2 | Privacy statement displayed when enabling the location service.|
## LocationCommand<sup>(deprecated) </sup>
## LocationCommand<sup>(deprecated)</sup>
Defines an extended command.
> **NOTE**
>
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.LocationCommand](js-apis-geoLocationManager.md#locationcommand).
......@@ -1495,11 +1393,11 @@ Defines an extended command.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes | Location scenario.|
| scenario | [LocationRequestScenario](#locationrequestscenariodeprecated) | Yes| Yes | Location scenario.|
| command | string | Yes| Yes | Extended command, in the string format.|
## Location<sup>(deprecated) </sup>
## Location<sup>(deprecated)</sup>
Defines a location.
......@@ -1512,13 +1410,94 @@ Defines a location.
| Name| Type| Readable|Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| latitude<sup>7+</sup> | number | Yes| No| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude.|
| longitude<sup>7+</sup> | number | Yes| No| Longitude information. A positive value indicates east longitude, and a negative value indicates west longitude.|
| latitude<sup>7+</sup> | number | Yes| No| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude. The value ranges from **-90** to **90**.|
| longitude<sup>7+</sup> | number | Yes| No| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude . The value ranges from **-180** to **180**.|
| altitude<sup>7+</sup> | number | Yes| No| Location altitude, in meters.|
| accuracy<sup>7+</sup> | number | Yes| No| Location accuracy, in meters.|
| speed<sup>7+</sup> | number | Yes| No| Speed, in m/s.|
| timeStamp<sup>7+</sup> | number | Yes| No| Location timestamp in the UTC format.|
| direction<sup>7+</sup> | number | Yes| No| Direction information.|
| direction<sup>7+</sup> | number | Yes| No| Direction information. The value ranges from **0** to **360**, in degrees.|
| timeSinceBoot<sup>7+</sup> | number | Yes| No| Location timestamp since boot.|
| additions<sup>7+</sup> | Array&lt;string&gt; | Yes| No| Additional description.|
| additionSize<sup>7+</sup> | number | Yes| No| Number of additional descriptions.|
| additionSize<sup>7+</sup> | number | Yes| No| Number of additional descriptions. The value must be greater than or equal to **0**.|
## LocationPrivacyType<sup>(deprecated)</sup>
Defines the privacy statement type.
> **NOTE**<br>
> This API is supported since API version 8.
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.LocationPrivacyType](js-apis-geoLocationManager.md#locationprivacytype).
**Required permissions**: ohos.permission.LOCATION
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| OTHERS | 0 | Other scenarios. Reserved field.|
| STARTUP | 1 | Privacy statement displayed in the startup wizard. |
| CORE_LOCATION | 2 | Privacy statement displayed when enabling the location service.|
## LocationRequestPriority<sup>(deprecated)</sup>
Sets the priority of the location request.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.LocationRequestPriority](js-apis-geoLocationManager.md#locationrequestpriority).
**Required permissions**: ohos.permission.LOCATION
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| UNSET | 0x200 | Priority unspecified.<br>If this option is used, [LocationRequestPriority](#locationrequestprioritydeprecated) is invalid.|
| ACCURACY | 0x201 | Location accuracy preferred.<br>This policy mainly uses the GNSS positioning technology. In an open area, the technology can achieve the meter-level location accuracy, depending on the hardware performance of the device. However, in a shielded environment, the location accuracy may significantly decrease.|
| LOW_POWER | 0x202 | Power efficiency preferred.<br>This policy mainly uses the base station positioning, WLAN positioning, and Bluetooth positioning technologies to obtain device location in both indoor and outdoor scenarios. The location accuracy depends on the distribution of surrounding base stations, visible WLANs, and Bluetooth devices and therefore may fluctuate greatly. This policy is recommended and can reduce power consumption when your application does not require high location accuracy or when base stations, visible WLANs, and Bluetooth devices are densely distributed.|
| FIRST_FIX | 0x203 | Fast location preferred. Use this option if you want to obtain a location as fast as possible.<br>This policy uses the GNSS positioning, base station positioning, WLAN positioning, and Bluetooth positioning technologies simultaneously to obtain the device location in both the indoor and outdoor scenarios. When all positioning technologies provide a location result, the system provides the most accurate location result for your application. It can lead to significant hardware resource consumption and power consumption.|
## LocationRequestScenario<sup>(deprecated)</sup>
Sets the scenario of the location request.
> **NOTE**<br>
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.LocationRequestScenario](js-apis-geoLocationManager.md#locationrequestscenario).
**Required permissions**: ohos.permission.LOCATION
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| UNSET | 0x300 | Scenario unspecified.<br>If this option is used, [LocationRequestScenario](#locationrequestscenariodeprecated) is invalid.|
| NAVIGATION | 0x301 | 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>In this scenario, GNSS positioning is used to provide location services to ensure the optimal location accuracy of the system.<br>The location result is reported at a minimum interval of 1 second by default.|
| TRAJECTORY_TRACKING | 0x302 | Trajectory tracking scenario.<br>This option is applicable when your application needs to record user trajectories, for example, the track recording function of sports applications. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy.<br>The location result is reported at a minimum interval of 1 second by default.|
| CAR_HAILING | 0x303 | Ride hailing scenario.<br>This option is applicable when your application needs to obtain the current location of a user who is hailing a taxi.<br>The location result is reported at a minimum interval of 1 second by default.|
| DAILY_LIFE_SERVICE | 0x304 | Daily life service scenario.<br>This option is applicable when your application only needs the approximate user location for recommendations and push notifications in scenarios such as when the user is browsing news, shopping online, and ordering food.<br>The location result is reported at a minimum interval of 1 second by default.|
| NO_POWER | 0x305 | Power efficiency scenario.<br>This option is applicable when 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. In this way, your application will not consume extra power for obtaining the user location.|
## GeoLocationErrorCode<sup>(deprecated)</sup>
Enumerates error codes of the location service.
> **NOTE**<br>
> This API is deprecated since API version 9.
**Required permissions**: ohos.permission.LOCATION
**System capability**: SystemCapability.Location.Location.Core
| Name| Value| Description|
| -------- | -------- | -------- |
| INPUT_PARAMS_ERROR<sup>7+</sup> | 101 | Incorrect input parameters.|
| REVERSE_GEOCODE_ERROR<sup>7+</sup> | 102 | Failed to call the reverse geocoding API.|
| GEOCODE_ERROR<sup>7+</sup> | 103 | Failed to call the geocoding API.|
| LOCATOR_ERROR<sup>7+</sup> | 104 | Failed to obtain the location.|
| LOCATION_SWITCH_ERROR<sup>7+</sup> | 105 | Failed to change the location service switch.|
| LAST_KNOWN_LOCATION_ERROR<sup>7+</sup> | 106 | Failed to obtain the previous location.|
| LOCATION_REQUEST_TIMEOUT_ERROR<sup>7+</sup> | 107 | Failed to obtain the location within the specified time.|
en/application-dev/reference/apis/js-apis-system-location.md
浏览文件 @ d7b16f6e
# @system.geolocation (Geographic Location)
# @system.geolocation (Geolocation)
The **geolocation** module provides only basic functions such as GNSS positioning and network positioning.
> **NOTE**
>
> - The APIs of this module are no longer maintained since API version 7. You are advised to use [`@ohos.geolocation`](js-apis-geolocation.md).
> - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> - The APIs provided by this module are no longer maintained since API version 9. You are advised to use [geoLocationManager](js-apis-geoLocationManager.md) instead.
## Modules to Import
```
import geolocation from '@system.geolocation';
```
......@@ -19,43 +19,46 @@ import geolocation from '@system.geolocation';
ohos.permission.LOCATION
## geolocation.getLocation
## geolocation.getLocation<sup>(deprecated)</sup>
getLocation(Object): void
Obtains the geographic location.
> **NOTE**
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.getCurrentLocation](js-apis-geoLocationManager.md#geolocationmanagergetcurrentlocation).
**System capability**: SystemCapability.Location.Location.Lite
**Parameters**
| Parameter | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| timeout | number | No | Timeout&nbsp;duration,&nbsp;in&nbsp;milliseconds.&nbsp;The&nbsp;default&nbsp;value&nbsp;is&nbsp;**30000**.<br>The&nbsp;timeout&nbsp;duration&nbsp;is&nbsp;necessary&nbsp;in&nbsp;case&nbsp;the&nbsp;request&nbsp;to&nbsp;obtain&nbsp;the&nbsp;geographic&nbsp;location&nbsp;is&nbsp;rejected&nbsp;for&nbsp;the&nbsp;lack&nbsp;of&nbsp;the&nbsp;required&nbsp;permission,&nbsp;weak&nbsp;positioning&nbsp;signal,&nbsp;or&nbsp;incorrect&nbsp;location&nbsp;settings.&nbsp;After&nbsp;the&nbsp;timeout&nbsp;duration&nbsp;expires,&nbsp;the&nbsp;fail&nbsp;function&nbsp;will&nbsp;be&nbsp;called.<br>The&nbsp;value&nbsp;is&nbsp;a&nbsp;32-digit&nbsp;positive&nbsp;integer.&nbsp;If&nbsp;the&nbsp;value&nbsp;set&nbsp;is&nbsp;less&nbsp;than&nbsp;or&nbsp;equal&nbsp;to&nbsp;**0**,&nbsp;the&nbsp;default&nbsp;value&nbsp;will&nbsp;be&nbsp;used. |
| coordType | string | No | Coordinate&nbsp;system&nbsp;type.&nbsp;Available&nbsp;types&nbsp;can&nbsp;be&nbsp;obtained&nbsp;by&nbsp;**getSupportedCoordTypes**.&nbsp;The&nbsp;default&nbsp;type&nbsp;is&nbsp;**wgs84**. |
| success | Function | No | Called&nbsp;when&nbsp;the&nbsp;operation&nbsp;is&nbsp;successful. |
| fail | Function | No | Called&nbsp;when&nbsp;the&nbsp;operation&nbsp;fails. |
| complete | Function | No | Called&nbsp;when&nbsp;the&nbsp;execution&nbsp;is&nbsp;complete |
| timeout | number | No| Timeout duration, in ms. The default value is **30000**.<br>The timeout duration is necessary in case the request to obtain the geographic location is rejected for the lack of the required permission, weak positioning signal, or incorrect location settings. After the timeout duration expires, the fail function will be called.<br>The value is a 32-digit positive integer. If the specified value is less than or equal to **0**, the default value will be used.|
| coordType | string | No| Coordinate system type. Available types can be obtained by **getSupportedCoordTypes**. The default type is **wgs84**.|
| success | Function | No| Called when API call is successful.|
| fail | Function | No| Called when API call has failed.|
| complete | Function | No| Called when API call is complete.|
The following values will be returned when the operation is successful.
**Return value of success()**
| Parameter | Type | Description |
| Name| Type| Description|
| -------- | -------- | -------- |
| longitude | number | Longitude |
| latitude | number | Latitude |
| altitude | number | Altitude |
| accuracy | number | Location&nbsp;accuracy |
| time | number | Time&nbsp;when&nbsp;the&nbsp;location&nbsp;is&nbsp;obtained |
| longitude | number | Longitude.|
| latitude | number | Latitude.|
| altitude | number | Altitude.|
| accuracy | number | Location accuracy.|
| time | number | Time when the location is obtained.|
One of the following error codes will be returned if the operation fails.
**Return value of fail()**
| Error&nbsp;Code | Description |
| Error Code| Description|
| -------- | -------- |
| 601 | Failed&nbsp;to&nbsp;obtain&nbsp;the&nbsp;required&nbsp;permission&nbsp;because&nbsp;the&nbsp;user&nbsp;rejected&nbsp;the&nbsp;request. |
| 602 | Permission&nbsp;not&nbsp;declared. |
| 800 | Operation&nbsp;times&nbsp;out&nbsp;due&nbsp;to&nbsp;a&nbsp;poor&nbsp;network&nbsp;condition&nbsp;or&nbsp;unavailable&nbsp;GPS. |
| 801 | System&nbsp;location&nbsp;disabled. |
| 802 | The&nbsp;method&nbsp;is&nbsp;called&nbsp;again&nbsp;while&nbsp;the&nbsp;previous&nbsp;execution&nbsp;result&nbsp;is&nbsp;not&nbsp;returned&nbsp;yet. |
| 601 | Failed to obtain the required permission because the user rejected the request.|
| 602 | Permission not declared.|
| 800 | Operation times out due to a poor network condition or GNSS unavailability.|
| 801 | System location disabled.|
| 802 | API called again while the previous execution result is not returned yet.|
**Example**
......@@ -75,27 +78,30 @@ export default {
```
## geolocation.getLocationType
## geolocation.getLocationType<sup>(deprecated)</sup>
getLocationType(Object): void
Obtains the supported location types.
> **NOTE**
> This API is deprecated since API version 9. The location subsystem supports only two location types: GNSS positioning and network positioning. No APIs will be provided to query the supported location types.
**System capability**: SystemCapability.Location.Location.Lite
**Parameters**
| Parameter | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| success | Function | No | Called&nbsp;when&nbsp;the&nbsp;execution&nbsp;is&nbsp;successful. |
| fail | Function | No | Called&nbsp;when&nbsp;the&nbsp;operation&nbsp;fails. |
| complete | Function | No | Called&nbsp;when&nbsp;the&nbsp;execution&nbsp;is&nbsp;complete |
| success | Function | No| Called when API call is successful.|
| fail | Function | No| Called when API call has failed.|
| complete | Function | No| Called when API call is complete.|
The following values will be returned when the operation is successful.
**Return value of success()**
| Parameter | Type | Description |
| Name| Type| Description|
| -------- | -------- | -------- |
| types | Array&lt;string&gt; | Available&nbsp;location&nbsp;types,&nbsp;['gps',&nbsp;'network'] |
| types | Array&lt;string&gt; | Available location types, ['gnss', 'network']|
**Example**
......@@ -115,39 +121,42 @@ export default {
```
## geolocation.subscribe
## geolocation.subscribe<sup>(deprecated)</sup>
subscribe(Object): void
Listens to the geographical location. If this method is called multiple times, the last call takes effect.
Listens to the geographic location. If this method is called multiple times, the last call takes effect.
> **NOTE**
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.on('locationChange')](js-apis-geoLocationManager.md#geolocationmanageronlocationchange).
**System capability**: SystemCapability.Location.Location.Lite
**Parameters**
| Parameter | Type | Mandatory | Description |
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| coordType | string | No | Coordinate&nbsp;system&nbsp;type.&nbsp;Available&nbsp;types&nbsp;can&nbsp;be&nbsp;obtained&nbsp;by&nbsp;**getSupportedCoordTypes**.&nbsp;The&nbsp;default&nbsp;type&nbsp;is&nbsp;**wgs84**. |
| success | Function | Yes | Called&nbsp;when&nbsp;the&nbsp;geographical&nbsp;location&nbsp;changes |
| fail | Function | No | Called&nbsp;when&nbsp;the&nbsp;listening&nbsp;fails |
| coordType | string | No| Coordinate system type. Available types can be obtained by **getSupportedCoordTypes**. The default type is **wgs84**.|
| success | Function | Yes| Called when the geographic location changes.|
| fail | Function | No| Called when API call has failed.|
The following values will be returned when the network type is obtained.
**Return value of success()**
| Parameter | Type | Description |
| Name| Type| Description|
| -------- | -------- | -------- |
| longitude | number | Longitude |
| latitude | number | Latitude |
| altitude | number | Altitude |
| accuracy | number | Location&nbsp;accuracy |
| time | number | Time&nbsp;when&nbsp;the&nbsp;location&nbsp;is&nbsp;obtained |
| longitude | number | Longitude.|
| latitude | number | Latitude.|
| altitude | number | Altitude.|
| accuracy | number | Location accuracy.|
| time | number | Time when the location is obtained.|
One of the following error codes will be returned if the operation fails.
**Return value of fail()**
| Error&nbsp;Code | Description |
| Error Code| Description|
| -------- | -------- |
| 601 | Failed&nbsp;to&nbsp;obtain&nbsp;the&nbsp;required&nbsp;permission&nbsp;because&nbsp;the&nbsp;user&nbsp;rejected&nbsp;the&nbsp;request. |
| 602 | Permission&nbsp;not&nbsp;declared. |
| 801 | System&nbsp;location&nbsp;disabled. |
| 601 | Failed to obtain the required permission because the user rejected the request.|
| 602 | Permission not declared.|
| 801 | System location disabled.|
**Example**
......@@ -167,11 +176,14 @@ export default {
```
## geolocation.unsubscribe
## geolocation.unsubscribe<sup>(deprecated)</sup>
unsubscribe(): void
Cancels listening to the geographical location.
Cancels listening to the geographic location.
> **NOTE**
> This API is deprecated since API version 9. You are advised to use [geoLocationManager.off('locationChange')](js-apis-geoLocationManager.md#geolocationmanagerofflocationchange).
**System capability**: SystemCapability.Location.Location.Lite
......@@ -186,19 +198,22 @@ export default {
```
## geolocation.getSupportedCoordTypes
## geolocation.getSupportedCoordTypes<sup>(deprecated)</sup>
getSupportedCoordTypes(): Array&lt;string&gt;
Obtains coordinate system types supported by the device.
> **NOTE**
> This API is deprecated since API version 9. The location subsystem supports only the wgs84 coordinate system. No APIs will be provided to query the supported coordinate system types.
**System capability**: SystemCapability.Location.Location.Lite
**Return Value**
**Return value**
| Type | Non-Null | Description |
| Type| Not empty| Description|
| -------- | -------- | -------- |
| Array&lt;string&gt; | Yes | Coordinate&nbsp;system&nbsp;types,&nbsp;for&nbsp;example,&nbsp;**[wgs84,&nbsp;gcj02]**. |
| Array&lt;string&gt; | Yes| Coordinate system types, for example, **[wgs84, gcj02]**.|
**Example**
......
en/device-dev/get-code/sourcecode-acquire.md
浏览文件 @ d7b16f6e
......@@ -65,9 +65,9 @@ The OpenHarmony source code is open to you as [HPM parts](../hpm-part/hpm-part-a
### How to Use<a name="section429012478331"></a>
>![](../public_sys-resources/icon-note.gif) **NOTE**
> **NOTE**
>
>Download the release code, which is more stable, if you want to develop commercial functionalities. Download the master code if you want to get quick access to the latest features for your development.
> Download the release code, which is more stable, if you want to develop commercial functionalities. Download the master code if you want to get quick access to the latest features for your development.
- **Obtaining OpenHarmony release code**
......@@ -168,7 +168,7 @@ You must install **Node.js** and HPM on your local PC. The installation procedur
To ensure the download performance, you are advised to download the source code or the corresponding solution from the image library of the respective site listed in the table below.
The table below provides only the sites for downloading the latest OpenHarmony LTS code. For details about how to obtain the source code of earlier versions, see the [Release Notes]([Release Notes](../../release-notes/Readme.md).
The table below provides only the sites for downloading the latest OpenHarmony LTS code. For details about how to obtain the source code of earlier versions, see the [Release Notes](../../release-notes/Readme.md).
**Table 1** Sites for acquiring source code
......@@ -181,7 +181,7 @@ The table below provides only the sites for downloading the latest OpenHarmony L
| Hi3516 solution-LiteOS (binary)| 3.0 | [Download](https://repo.huaweicloud.com/openharmony/os/3.0/hispark_taurus.tar.gz) | [Download](https://repo.huaweicloud.com/openharmony/os/3.0/hispark_taurus.tar.gz)| 248.9 MB |
| Hi3516 solution-Linux (binary)| 3.0 | [Download](https://repo.huaweicloud.com/openharmony/os/3.0/hispark_taurus_linux.tar.gz)| [Download](https://repo.huaweicloud.com/openharmony/os/3.0/hispark_taurus_linux.tar.gz.sha256) | 418.1 MB |
| RELEASE-NOTES | 3.0 | [Download](https://gitee.com/openharmony/docs/blob/OpenHarmony-3.0-LTS/en/release-notes/OpenHarmony-v3.0-LTS.md)| - | - |
| **Source code of the Latest Release**| **Version**| **Site**| **SHA-256 Checksum**| **Software Package Size**|
| **Source Code of the Latest Release**| **Version**| **Site**| **SHA-256 Checksum**| **Software Package Size**|
| Full code base (for mini, small, and standard systems)| 3.2 Beta4 | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/code-v3.2-Beta4.tar.gz) | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/code-v3.2-Beta4.tar.gz.sha256) | 19.0 GB |
| RK3568 standard system solution (binary)| 3.2 Beta4 | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/dayu200_standard_arm32.tar.gz) | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/dayu200_standard_arm32.tar.gz.sha256) | 3.2 GB |
| Hi3861 solution (binary)| 3.2 Beta4 | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/hispark_pegasus.tar.gz) | [Download](https://repo.huaweicloud.com/harmonyos/os/3.2-Beta4/hispark_pegasus.tar.gz.sha256) | 22.6 MB |
......@@ -193,7 +193,7 @@ The table below provides only the sites for downloading the latest OpenHarmony L
## Method 4: Acquiring Source Code from the GitHub Image Repository<a name="section23448418360"></a>
>![](../public_sys-resources/icon-note.gif) **NOTE**
> **NOTE**
>
> The image repository is synchronized at 23:00 (UTC +8:00) every day.
......
en/release-notes/changelogs/OpenHarmony_4.0.1.5/changelogs-geoLocationManager.md
浏览文件 @ d7b16f6e
......@@ -2,9 +2,9 @@
## cl.location.1 Deletion of the geoLocationManager.requestEnableLocation API in API Version 9
When the location function is disabled, your application can call the **geoLocationManager.requestEnableLocation** API to request the user to enable the location function. However, this API is seldom used, and user experience for this API is not very good because the user is not notified of the scenario in which your application uses the location information.
When the location function is disabled, your application can call the **geoLocationManager.requestEnableLocation** API to request the user to enable the location function. However, this API is seldom used because the user is not notified of the scenario in which your application uses the location information.
Therefore, your app shows a popup, asking the user to go to the settings page and enable the location function. In addition, the popup clearly states the scenarios in which the location information will be used, improving user experience.
Therefore, your application shows a popup, asking the user to go to the settings page and enable the location function. In addition, the popup clearly states the scenarios in which the location information will be used, improving user experience.
**Change Impacts**
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或