@@ -23,12 +23,12 @@ If your application needs to access the device location information, it must fir
...
@@ -23,12 +23,12 @@ If your application needs to access the device location information, it must fir
- 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.
| Earlier than 9 | ohos.permission.LOCATION | Success | Location accurate to meters|
| 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.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 | Success| Location accurate to 5 kilometers|
| 9 and later | ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Success | Location accurate to meters|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Success| 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.
...
@@ -42,31 +42,615 @@ import geoLocationManager from '@ohos.geoLocationManager';
...
@@ -42,31 +42,615 @@ import geoLocationManager from '@ohos.geoLocationManager';
Registers a listener for location changes with a location request initiated. The location result is reported through [LocationRequest](#locationrequest).
| type | string | Yes| Event type. The value **locationChange** indicates a location change event.|
| callback | Callback<[Location](#location)> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
**Error codes**
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| type | string | Yes| Event type. The value **locationEnabledChange** indicates a location service status change event.|
| callback | Callback<boolean> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
**Error codes**
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| type | string | Yes| Event type. The value **cachedGnssLocationsChange** indicates reporting of cached GNSS locations.|
| callback | Callback<boolean> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
**Error codes**
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| type | string | Yes| Event type. The value **satelliteStatusChange** indicates a GNSS satellite status change event.|
| callback | Callback<[SatelliteStatusInfo](#satellitestatusinfo)> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
**Error codes**
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| type | string | Yes| Event type. The value **nmeaMessage** indicates a GNSS NMEA message change event.|
| callback | Callback<string> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
**Error codes**
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| type | string | Yes | Event type. The value **countryCodeChange** indicates to subscribe to the country code change event.|
| type | string | Yes| Event type. The value **countryCodeChange** indicates a country code change event.|
| callback | Callback<[CountryCode](#countrycode)> | Yes | Callback used to return the country code change event. |
| callback | Callback<[CountryCode](#countrycode)> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| callback | Callback<[CountryCode](#countrycode)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified event type are unsubscribed from.|
| callback | AsyncCallback<[Location](#location)> | Yes| Callback used to return the current location.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| callback | AsyncCallback<boolean> | 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.|
**Error codes**
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| Promise<boolean> | 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.|
**Error codes**
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| Promise<void> | void | No | Promise used to return the error code.|
| Promise<Array<[GeoAddress](#geoaddress)>> | Array<[GeoAddress](#geoaddress)> | NA | Promise used to return the reverse geocoding result.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| type | [LocationPrivacyType](#locationprivacytype) | Yes | Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled. |
| callback | AsyncCallback<boolean> | Yes | Callback used to return the result, which indicates whether the user agrees with the privacy statement. |
| callback | AsyncCallback<Array<[GeoAddress](#geoaddress)>> | Yes| Callback used to return the geocoding result.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| type | [LocationPrivacyType](#locationprivacytype) | Yes | Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled. |
| type | [LocationPrivacyType](#locationprivacytype) | Yes | Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled. |
| callback | AsyncCallback<number> | Yes| Callback used to return the number of cached GNSS locations. |
| isConfirmed | boolean | Yes | Callback used to return the result, which indicates whether the user agrees with the privacy statement. |
| callback | AsyncCallback<void> | Yes | Callback used to return the error message. |
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| type | [LocationPrivacyType](#locationprivacytype) | Yes | Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled. |
| isConfirmed | boolean | Yes | Callback used to return the result, which indicates whether the user agrees with the privacy statement. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result indicating whether it is successful to enable the function. If so, **nullptr** is returned. Otherwise, an error message is returned.|
| command | [LocationCommand](#locationcommand) | Yes| Extended command (string) to be sent.|
| callback | AsyncCallback<void> | Yes| Callback used to return the error code.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| Promise<void> | void | No | Promise used to return the result indicating whether it is successful to enable the function. If so, **nullptr** is returned; an error message otherwise.|
| Promise<void> | void | NA | Promise used to return the error code.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| callback | AsyncCallback<void> | Yes | Callback used to return the result indicating whether it is successful to disable the function. If so, **nullptr** is returned; an error message otherwise.|
| callback | AsyncCallback<[CountryCode](#countrycode)> | Yes| Callback used to return the country code.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| Promise<void> | void | No | Promise used to return the result indicating whether it is successful to disable the function. If so, **nullptr** is returned; an error message otherwise.|
| Promise<[CountryCode](#countrycode)> | [CountryCode](#countrycode) | NA | Promise used to return the country code.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| config | [LocationMockConfig](#locationmockconfig) | Yes | Mock location information, including the interval for reporting the mock locations and the array of the mock locations.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result indicating whether it is successful to set the information. If so, **nullptr** is returned; an error message otherwise.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| config | [LocationMockConfig](#locationmockconfig) | Yes | Mock location information, including the interval for reporting the mock locations and the array of the mock locations.|
| Promise<void> | void | No | Promise used to return the result indicating whether it is successful to set the information. If so, **nullptr** is returned; an error message otherwise.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| callback | AsyncCallback<void> | Yes | Callback used to return the result indicating whether it is successful to enable the function. If so, **nullptr** is returned; an error message otherwise.|
| config | [LocationMockConfig](#locationmockconfig) | Yes| Mock location information, including the interval for reporting the mock locations and the array of the mock locations.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| Promise<void> | void | No | Promise used to return the result indicating whether it is successful to enable the function. If so, **nullptr** is returned; an error message otherwise.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| callback | AsyncCallback<void> | Yes | Callback used to return the result indicating whether it is successful to disable the function. If so, **nullptr** is returned; an error message otherwise.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
Sets information of the mock reverse geocoding function, including the mapping between a location and geographical name. If the location is contained in the configurations during reverse geocoding query, the corresponding geographical name will be returned.
| Promise<void> | void | No | Promise used to return the result indicating whether it is successful to disable the function. If so, **nullptr** is returned; an error message otherwise.|
| mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | Yes| Array of information of the mock reverse geocoding function, including a location and a geographical name.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
Sets information of the mock reverse geocoding function, including the mapping between a location and geographical name. If the location is contained in the configurations during reverse geocoding query, the corresponding geographical name will be returned.
| mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | Yes | Array of information of the mock reverse geocoding function, including a location and a geographical name.|
| type | [LocationPrivacyType](#locationprivacytype)| Yes| Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled.|
| callback | AsyncCallback<void> | Yes | Callback used to return the result indicating whether it is successful to set the information. If so, **nullptr** is returned; an error message otherwise.|
**Return value**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| boolean | boolean | NA | Callback used to return the result, which indicates whether the user agrees with the privacy statement.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
Sets information of the mock reverse geocoding function, including the mapping between a location and geographical name. If the location is contained in the configurations during reverse geocoding query, the corresponding geographical name will be returned.
| mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | Yes | Array of information of the mock reverse geocoding function, including a location and a geographical name.|
| Promise<void> | void | No | Promise used to return the result indicating whether it is successful to set the information. If so, **nullptr** is returned; an error message otherwise.|
| type | [LocationPrivacyType](#locationprivacytype) | Yes| Privacy statement type, for example, privacy statement displayed in the startup wizard or privacy statement displayed when the location service is enabled.|
| isConfirmed | boolean | Yes| Callback used to return the result, which indicates whether the user agrees with the privacy statement.|
**Error codes**
**Error codes**
For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md).
For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md).
| DAILY_LIFE_SERVICE | 0x304 | Daily life services. |
| 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.|
| 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.|
...
@@ -1063,12 +1971,12 @@ Defines a reverse geocoding request.
...
@@ -1063,12 +1971,12 @@ Defines a reverse geocoding request.
| locale | string | Yes | Yes | Language used for the location description. **zh** indicates Chinese, and **en** indicates English.|
| 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. |
| 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 . |
| 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. |
| maxItems | number | Yes| Yes| Maximum number of location records to be returned.|
## GeoCodeRequest
## GeoCodeRequest
...
@@ -1077,15 +1985,15 @@ Defines a geocoding request.
...
@@ -1077,15 +1985,15 @@ Defines a geocoding request.
| locale | string | Yes | Yes | Language used for the location description. **zh** indicates Chinese, and **en** indicates English. |
| 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**. |
| 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. |
| 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.|
| minLatitude | number | Yes| Yes| Minimum latitude. This parameter is used with **minLongitude**, **maxLatitude**, and **maxLongitude** to specify the latitude and longitude ranges.|
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes | Yes | Priority of the location request. |
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request.|
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes | Yes | Scenario 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. |
| timeInterval | number | Yes| Yes| Time interval at which location information is reported.|
| distanceInterval | number | Yes | Yes | Distance 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.|
| 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
## CurrentLocationRequest
...
@@ -1138,12 +2046,12 @@ Defines the current location request.
...
@@ -1138,12 +2046,12 @@ Defines the current location request.
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes | Yes | Priority of the location request. |
| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request.|
| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes | Yes | Scenario 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.|
| 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**. |
| timeoutMs | number | Yes| Yes| Timeout duration, in milliseconds. The minimum value is **1000**.|
## SatelliteStatusInfo
## SatelliteStatusInfo
...
@@ -1152,14 +2060,14 @@ Defines the satellite status information.
...
@@ -1152,14 +2060,14 @@ Defines the satellite status information.
| 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.|
| 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. |
| 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
## Geofence
...
@@ -1180,12 +2088,12 @@ Defines a GNSS geofence. Currently, only circular geofences are supported.
...
@@ -1180,12 +2088,12 @@ Defines a GNSS geofence. Currently, only circular geofences are supported.