From d1157ec1ed96f1c1582c80a8c67d4130b7d50ae0 Mon Sep 17 00:00:00 2001 From: shawn_he Date: Thu, 22 Dec 2022 11:36:54 +0800 Subject: [PATCH] update doc Signed-off-by: shawn_he --- .../apis/js-apis-geoLocationManager.md | 2213 ++++++++++++----- 1 file changed, 1560 insertions(+), 653 deletions(-) diff --git a/en/application-dev/reference/apis/js-apis-geoLocationManager.md b/en/application-dev/reference/apis/js-apis-geoLocationManager.md index ddafa13161..9c09d17472 100644 --- a/en/application-dev/reference/apis/js-apis-geoLocationManager.md +++ b/en/application-dev/reference/apis/js-apis-geoLocationManager.md @@ -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| 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| +| 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| 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,823 +42,1675 @@ import geoLocationManager from '@ohos.geoLocationManager'; ``` -## geoLocationManager.on('countryCodeChange') +## geoLocationManager.on('locationChange') -on(type: 'countryCodeChange', callback: Callback<CountryCode>): void; +on(type: 'locationChange', request: LocationRequest, callback: Callback<Location>): void -Subscribes to the country code change event. +Registers a listener for location changes with a location request initiated. The location result is reported through [LocationRequest](#locationrequest). + +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION **System capability**: SystemCapability.Location.Location.Core **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type. The value **countryCodeChange** indicates to subscribe to the country code change event.| -| callback | Callback<[CountryCode](#countrycode)> | Yes | Callback used to return the country code change event. | + | 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<[Location](#location)> | Yes| Callback used to return the location change event.| **Error codes** -For details about the following error codes, see [error codes of the location service](../errorcodes/errorcode-geoLocationManager.md). - -| Code| Error Message | -| -------- | ------------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301100 | The location switch is off. | -| 3301500 | Failed to query the area information. | +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 callback = (code) => { - console.log('countryCodeChange: ' + JSON.stringify(code)); - } - + var requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; + var locationChange = (location) => { + console.log('locationChanger: data: ' + JSON.stringify(location)); + }; try { - geoLocationManager.on('countryCodeChange', callback); + geoLocationManager.on('locationChange', requestInfo, locationChange); } catch (err) { console.error("errCode:" + err.code + ",errMessage:" + err.message); } + ``` -## geoLocationManager.off('countryCodeChange') +## geoLocationManager.off('locationChange') -off(type: 'countryCodeChange', callback?: Callback<CountryCode>): void; +off(type: 'locationChange', callback?: Callback<Location>): void -Unsubscribes from the country code change event. +Unregisters the listener for location changes with the corresponding location request deleted. + +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION **System capability**: SystemCapability.Location.Location.Core **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | string | Yes | Event type. The value **countryCodeChange** indicates to unsubscribe from the country code change event.| -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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 [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). -| Code| Error Message | -| -------- | ------------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301100 | The location switch is off. | -| 3301500 | Failed to query the area information. | +| 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 callback = (code) => { - console.log('countryCodeChange: ' + JSON.stringify(code)); - } + var requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; + var locationChange = (location) => { + console.log('locationChanger: data: ' + JSON.stringify(location)); + }; try { - geoLocationManager.on('countryCodeChange', callback); - geoLocationManager.off('countryCodeChange', callback); + geoLocationManager.on('locationChange', requestInfo, locationChange); + geoLocationManager.off('locationChange', locationChange); } catch (err) { console.error("errCode:" + err.code + ",errMessage:" + err.message); } ``` -## geoLocationManager.enableLocation - -enableLocation(callback: AsyncCallback<void>): void; - -Enables the location service. This API uses an asynchronous callback to return the result. +## geoLocationManager.on('locationEnabledChange') -**System API**: This is a system API and cannot be called by third-party applications. +on(type: 'locationEnabledChange', callback: Callback<boolean>): void -**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS +Registers a listener for location service status change events. **System capability**: SystemCapability.Location.Location.Core **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | -------------------- | -| callback| AsyncCallback<void> | Yes | Callback used to return the error message.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value **locationEnabledChange** indicates a location service status change event.| + | callback | Callback<boolean> | Yes| Callback used to return the location service status change event.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.enableLocation((err, data) => { - if (err) { - console.log('enableLocation: err=' + JSON.stringify(err)); - } - }); + var locationEnabledChange = (state) => { + console.log('locationEnabledChange: ' + JSON.stringify(state)); + } + try { + geoLocationManager.on('locationEnabledChange', locationEnabledChange); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.enableLocation - -enableLocation(): Promise<void> - -Enables the location service. This API uses a promise to return the result. +## geoLocationManager.off('locationEnabledChange') -**System API**: This is a system API and cannot be called by third-party applications. +off(type: 'locationEnabledChange', callback?: Callback<boolean>): void; -**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS +Unregisters the listener for location service status change events. **System capability**: SystemCapability.Location.Location.Core -**Return value** +**Parameters** -| Name | Type| Mandatory| Description | -| ------------------- | ---- | ---- | ---------------- | -| Promise<void> | void | No | Promise used to return the error message.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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 [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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.enableLocation().then((result) => { - console.log('promise, enableLocation succeed'); - }) - .catch((error) => { - console.log('promise, enableLocation: error=' + JSON.stringify(error)); - }); + var locationEnabledChange = (state) => { + console.log('locationEnabledChange: state: ' + JSON.stringify(state)); + } + try { + geoLocationManager.on('locationEnabledChange', locationEnabledChange); + geoLocationManager.off('locationEnabledChange', locationEnabledChange); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.disableLocation -disableLocation(callback: AsyncCallback<void>): void; +## geoLocationManager.on('cachedGnssLocationsChange') -Disables the location service. This function uses an asynchronous callback to return the result. +on(type: 'cachedGnssLocationsChange', request: CachedGnssLocationsRequest, callback: Callback<Array<Location>>): void; -**System API**: This is a system API and cannot be called by third-party applications. +Registers a listener for cached GNSS location reports. -**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION -**System capability**: SystemCapability.Location.Location.Core +**System capability**: SystemCapability.Location.Location.Gnss **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ---------------------- | -| callback | AsyncCallback<void> | Yes | Callback used to return the error code.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value **cachedGnssLocationsChange** indicates reporting of cached GNSS locations.| + | request | [CachedGnssLocationsRequest](#cachedgnsslocationsrequest) | Yes| Request for reporting cached GNSS location.| + | callback | Callback<boolean> | Yes| Callback used to return cached GNSS locations.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| 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 cachedLocationsCb = (locations) => { + console.log('cachedGnssLocationsChange: locations: ' + JSON.stringify(locations)); + } + var requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true}; try { - geoLocationManager.disableLocation((err, data) => { - if (err) { - console.log('disableLocation: err=' + JSON.stringify(err)); - } - }); + geoLocationManager.on('cachedGnssLocationsChange', requestInfo, cachedLocationsCb); } catch (err) { console.error("errCode:" + err.code + ",errMessage:" + err.message); } ``` -## geoLocationManager.disableLocation - -disableLocation(): Promise<void> +## geoLocationManager.off('cachedGnssLocationsChange') -Disables the location service. This function uses a promise to return the result. +off(type: 'cachedGnssLocationsChange', callback?: Callback<Array<Location>>): void; -**System API**: This is a system API and cannot be called by third-party applications. +Unregisters the listener for cached GNSS location reports. -**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION -**System capability**: SystemCapability.Location.Location.Core +**System capability**: SystemCapability.Location.Location.Gnss -**Return value** +**Parameters** -| Name | Type| Mandatory| Description | -| ------------------- | ---- | ---- | ------------ | -| Promise<void> | void | No | Promise used to return the error code.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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 [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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| 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'; - geoLocationManager.disableLocation().then((result) => { - console.log('promise, disableLocation succeed'); - }) - .catch((error) => { - console.log('promise, disableLocation: error=' + JSON.stringify(error)); - }); + var cachedLocationsCb = (locations) => { + console.log('cachedGnssLocationsChange: locations: ' + JSON.stringify(locations)); + } + var requestInfo = {'reportingPeriodSec': 10, 'wakeUpCacheQueueFull': true}; + try { + geoLocationManager.on('cachedGnssLocationsChange', requestInfo, cachedLocationsCb); + geoLocationManager.off('cachedGnssLocationsChange'); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.isLocationPrivacyConfirmed +## geoLocationManager.on('satelliteStatusChange') -isLocationPrivacyConfirmed(type : LocationPrivacyType, callback: AsyncCallback<boolean>): void; +on(type: 'satelliteStatusChange', callback: Callback<SatelliteStatusInfo>): void; -Checks whether a user agrees with the privacy statement of the location service. This API can only be called by system applications. +Registers a listener for GNSS satellite status change events. -**System API**: This is a system API and cannot be called by third-party applications. +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION -**System capability**: SystemCapability.Location.Location.Core +**System capability**: SystemCapability.Location.Location.Gnss **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | -| 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. | + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value **satelliteStatusChange** indicates a GNSS satellite status change event.| + | callback | Callback<[SatelliteStatusInfo](#satellitestatusinfo)> | Yes| Callback used to return GNSS satellite status changes.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off. | **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.isLocationPrivacyConfirmed(1, (err, result) => { - if (err) { - console.log('isLocationPrivacyConfirmed: err=' + JSON.stringify(err)); - } - if (result) { - console.log('isLocationPrivacyConfirmed: result=' + JSON.stringify(result)); - } - }); + var gnssStatusCb = (satelliteStatusInfo) => { + console.log('satelliteStatusChange: ' + JSON.stringify(satelliteStatusInfo)); + } + + try { + geoLocationManager.on('satelliteStatusChange', gnssStatusCb); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.isLocationPrivacyConfirmed +## geoLocationManager.off('satelliteStatusChange') -isLocationPrivacyConfirmed(type : LocationPrivacyType,): Promise<boolean>; +off(type: 'satelliteStatusChange', callback?: Callback<SatelliteStatusInfo>): void; -Checks whether a user agrees with the privacy statement of the location service. This API can only be called by system applications. +Unregisters the listener for GNSS satellite status change events. -**System API**: This is a system API and cannot be called by third-party applications. +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION -**System capability**: SystemCapability.Location.Location.Core +**System capability**: SystemCapability.Location.Location.Gnss **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | -| 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. | - -**Return value** - -| Name | Type | Mandatory| Description | -| ---------------------- | ------- | ---- | ---------------------------------- | -| Promise<boolean> | boolean | No | Callback used to return the result, which indicates whether the user agrees with the privacy statement.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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 [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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off. | -**Example** +**Example** + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.isLocationPrivacyConfirmed(1).then((result) => { - console.log('promise, isLocationPrivacyConfirmed: ' + JSON.stringify(result)); - }); + var gnssStatusCb = (satelliteStatusInfo) => { + console.log('satelliteStatusChange: ' + JSON.stringify(satelliteStatusInfo)); + } + try { + geoLocationManager.on('satelliteStatusChange', gnssStatusCb); + geoLocationManager.off('satelliteStatusChange', gnssStatusCb); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.setLocationPrivacyConfirmStatus - -setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed: boolean, callback: AsyncCallback<void>): void; +## geoLocationManager.on('nmeaMessage') -Sets the user confirmation status for the privacy statement of the location service. This API can only be called by system applications. +on(type: 'nmeaMessage', callback: Callback<string>): void; -**System API**: This is a system API and cannot be called by third-party applications. +Registers a listener for GNSS NMEA message change events. -**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS +**Permission required**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION -**System capability**: SystemCapability.Location.Location.Core +**System capability**: SystemCapability.Location.Location.Gnss **Parameters** -| Name | Type | Mandatory| Description | -| ----------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | -| 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 error message. | + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value **nmeaMessage** indicates a GNSS NMEA message change event.| + | callback | Callback<string> | Yes| Callback used to return GNSS NMEA message changes.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off. | -**Example** +**Example** + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.setLocationPrivacyConfirmStatus(1, true, (err, result) => { - if (err) { - console.log('setLocationPrivacyConfirmStatus: err=' + JSON.stringify(err)); - } - }); - ``` + var nmeaCb = (str) => { + console.log('nmeaMessage: ' + JSON.stringify(str)); + } + try { + geoLocationManager.on('nmeaMessage', nmeaCb ); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` -## geoLocationManager.setLocationPrivacyConfirmStatus -setLocationPrivacyConfirmStatus(type : LocationPrivacyType, isConfirmed : boolean): Promise<void>; +## geoLocationManager.off('nmeaMessage') -Sets the user confirmation status for the privacy statement of the location service. This API can only be called by system applications. +off(type: 'nmeaMessage', callback?: Callback<string>): void; -**System API**: This is a system API and cannot be called by third-party applications. +Unregisters the listener for GNSS NMEA message change events. -**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS +**Permission required**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION -**System capability**: SystemCapability.Location.Location.Core +**System capability**: SystemCapability.Location.Location.Gnss **Parameters** -| Name | Type | Mandatory| Description | -| ----------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | -| 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. | - -**Return value** - -| Name | Type| Mandatory| Description | -| ------------------- | ---- | ---- | ------------ | -| Promise<void> | void | No | Promise used to return the error code.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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 [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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off. | -**Example** +**Example** + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.setLocationPrivacyConfirmStatus(1, true).then((result) => { - console.log('promise, setLocationPrivacyConfirmStatus succeed'); - }) - .catch((error) => { - console.log('promise, disableLocation: error=' + JSON.stringify(error)); - }); + var nmeaCb = (str) => { + console.log('nmeaMessage: ' + JSON.stringify(str)); + } + + try { + geoLocationManager.on('nmeaMessage', nmeaCb); + geoLocationManager.off('nmeaMessage', nmeaCb); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.getCountryCode +## geoLocationManager.on('gnssFenceStatusChange') -getCountryCode(callback: AsyncCallback<CountryCode>): void; +on(type: 'gnssFenceStatusChange', request: GeofenceRequest, want: WantAgent): void; -Obtains the current country code. +Registers a listener for status change events of the specified geofence. -**System capability**: SystemCapability.Location.Location.Core +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Geofence **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------ | ---- | ---------------- | -| callback | AsyncCallback<[CountryCode](#countrycode)> | Yes | Callback used to return the country code.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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.| **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). -| Code| Error Message | -| -------- | ------------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301500 | Failed to query the area information. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off. | +|3301600 | Failed to operate the geofence. | **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.getCountryCode((err, result) => { - if (err) { - console.log('getCountryCode: err=' + JSON.stringify(err)); - } - if (result) { - console.log('getCountryCode: result=' + JSON.stringify(result)); - } + import wantAgent from '@ohos.wantAgent'; + + let wantAgentInfo = { + wants: [ + { + bundleName: "com.example.myapplication", + abilityName: "com.example.myapplication.MainAbility", + action: "action1", + } + ], + operationType: wantAgent.OperationType.START_ABILITY, + requestCode: 0, + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG], + }; + + wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { + var 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); + } }); ``` -## geoLocationManager.getCountryCode +## geoLocationManager.off('gnssFenceStatusChange') -getCountryCode(): Promise<CountryCode>; +off(type: 'gnssFenceStatusChange', request: GeofenceRequest, want: WantAgent): void; -Obtains the current country code. +Unregisters the listener for status change events of the specified geofence. -**System capability**: SystemCapability.Location.Location.Core +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION -**Return value** +**System capability**: SystemCapability.Location.Location.Geofence + +**Parameters** -| Name | Type | Mandatory| Description | -| ------------------------------------------ | --------------------------- | ---- | ---------------- | -| Promise<[CountryCode](#countrycode)> | [CountryCode](#countrycode) | No | Promise used to return the country code.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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.| **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). -| Code| Error Message | -| -------- | ------------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301500 | Failed to query the area information. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off. | +|3301600 | Failed to operate the geofence. | **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.getCountryCode() - .then((result) => { - console.log('promise, getCountryCode: result=' + JSON.stringify(result)); - }) - .catch((error) => { - console.log('promise, getCountryCode: error=' + JSON.stringify(error)); + import wantAgent from '@ohos.wantAgent'; + + let wantAgentInfo = { + wants: [ + { + bundleName: "com.example.myapplication", + abilityName: "com.example.myapplication.MainAbility", + action: "action1", + } + ], + operationType: wantAgent.OperationType.START_ABILITY, + requestCode: 0, + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] + }; + + wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { + var 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); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } }); ``` -## geoLocationManager.enableLocationMock +## geoLocationManager.on('countryCodeChange') -enableLocationMock(callback: AsyncCallback<void>): void; +on(type: 'countryCodeChange', callback: Callback<CountryCode>): void; -Enables the mock location function. +Registers a listener for country code change events. **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. - **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301100 | The location switch is off. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off. | +|3301500 | Failed to query the area information. | -**Example** +**Example** + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.enableLocationMock((err, result) => { - if (err) { - console.log('enableLocationMock: err=' + JSON.stringify(err)); - } - }); + var callback = (code) => { + console.log('countryCodeChange: ' + JSON.stringify(code)); + } + + try { + geoLocationManager.on('countryCodeChange', callback); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.enableLocationMock -enableLocationMock(): Promise<void>; +## geoLocationManager.off('countryCodeChange') + +off(type: 'countryCodeChange', callback?: Callback<CountryCode>): void; -Enables the mock location function +Unregisters the listener for country code change events. **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. - -**Return value** +**Parameters** -| Name | Type| Mandatory| Description | -| ------------------- | ---- | ---- | ------------------------------------------------------------ | -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value **countryCodeChange** indicates a 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** -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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301100 | The location switch is off. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off. | +|3301500 | Failed to query the area information. | **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.enableLocationMock() - .then((result) => { - console.log('promise, enableLocationMock: succeed'); - }) - .catch((error) => { - if (error) { - console.log('promise, enableLocationMock: error=' + JSON.stringify(error)); - } - }); + var callback = (code) => { + console.log('countryCodeChange: ' + JSON.stringify(code)); + } + + try { + geoLocationManager.on('countryCodeChange', callback); + geoLocationManager.off('countryCodeChange', callback); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.disableLocationMock -disableLocationMock(callback: AsyncCallback<void>): void; +## geoLocationManager.getCurrentLocation -Disables the mock location function. +getCurrentLocation(request: CurrentLocationRequest, callback: AsyncCallback<Location>): void -**System capability**: SystemCapability.Location.Location.Core +Obtains the current location. This API uses an asynchronous callback to return the result. -**System API**: This is a system API and cannot be called by third-party applications. +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Core **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | request | [CurrentLocationRequest](#currentlocationrequest) | Yes| Location request.| + | callback | AsyncCallback<[Location](#location)> | Yes| Callback used to return the current location.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301100 | The location switch is off. | +| 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'; - geoLocationManager.disableLocationMock((err, result) => { + var requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0}; + var locationChange = (err, location) => { if (err) { - console.log('disableLocationMock: err=' + JSON.stringify(err)); + console.log('locationChanger: err=' + JSON.stringify(err)); } - }); + if (location) { + console.log('locationChanger: location=' + JSON.stringify(location)); + } + }; + + try { + geoLocationManager.getCurrentLocation(requestInfo, locationChange); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` +## geoLocationManager.getCurrentLocation -## geoLocationManager.disableLocationMock +getCurrentLocation(callback: AsyncCallback<Location>): void; -disableLocationMock(): Promise<void>; +Obtains the current location. This API uses an asynchronous callback to return the result. -Disables the mock location function. +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. - -**Return value** +**Parameters** -| Name | Type| Mandatory| Description | -| ------------------- | ---- | ---- | ------------------------------------------------------------ | -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[Location](#location)> | Yes| Callback used to return the current location.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301100 | The location switch is off. | +| 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'; - geoLocationManager.disableLocationMock() - .then((result) => { - console.log('promise, disableLocationMock succeed'); - }) - .catch((error) => { - if (error) { - console.log('promise, disableLocationMock: error=' + JSON.stringify(error)); + var locationChange = (err, location) => { + if (err) { + console.log('locationChanger: err=' + JSON.stringify(err)); } - }); + if (location) { + console.log('locationChanger: location=' + JSON.stringify(location)); + } + }; + + try { + geoLocationManager.getCurrentLocation(locationChange); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` +## geoLocationManager.getCurrentLocation -## geoLocationManager.setMockedLocations +getCurrentLocation(request?: CurrentLocationRequest): Promise<Location> -setMockedLocations(config: LocationMockConfig, callback: AsyncCallback<void>): void; +Obtains the current location. This API uses a promise to return the result. -Sets the mock location information. The mock locations will be reported at the interval specified in this API. +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. - **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | request | [CurrentLocationRequest](#currentlocationrequest) | No| Location request.| + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | Promise<[Location](#location)> | [Location](#location) | NA | Promise used to return the current location.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301100 | The location switch is off. | +| 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 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}; - geoLocationManager.setMockedLocations(config, (err, data) => { - if (err) { - console.log('setMockedLocations: err=' + JSON.stringify(err)); - } - }); - ``` + 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.| + +**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. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + var locationEnabled = geoLocationManager.isLocationEnabled(); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.requestEnableLocation + +requestEnableLocation(callback: AsyncCallback<boolean>): void + +Requests to enable the location service. This API uses an asynchronous callback to return the result. + +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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). + +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301700 | No response to the request. | + +**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)); + } + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.requestEnableLocation + +requestEnableLocation(): Promise<boolean> + +Requests to enable the location service. This API uses a promise to return the result. + +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Core + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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). + +| 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)); + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.enableLocation + +enableLocation(callback: AsyncCallback<void>): void; + +Enables the location service. This API uses an asynchronous callback to return the result. + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS + +**System capability**: SystemCapability.Location.Location.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | Yes| Callback used to return the error message.| + +**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. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + geoLocationManager.enableLocation((err, data) => { + if (err) { + console.log('enableLocation: err=' + JSON.stringify(err)); + } + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.enableLocation + +enableLocation(): Promise<void> + +Enables the location service. This API uses a promise to return the result. + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS + +**System capability**: SystemCapability.Location.Location.Core + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | Promise<void> | void | NA | Promise used to return the error message.| + +**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. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + geoLocationManager.enableLocation().then((result) => { + console.log('promise, enableLocation succeed'); + }) + .catch((error) => { + console.log('promise, enableLocation: error=' + JSON.stringify(error)); + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + +## geoLocationManager.disableLocation + +disableLocation(): void; + +Disables the location service. + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS + +**System capability**: SystemCapability.Location.Location.Core + +**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. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + geoLocationManager.disableLocation(); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + + +## geoLocationManager.getAddressesFromLocation + +getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>): void + +Converts coordinates into geographic description through reverse geocoding. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Location.Location.Geocoder + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | request | [ReverseGeoCodeRequest](#reversegeocoderequest) | Yes| Reverse geocoding request.| + | callback | AsyncCallback<Array<[GeoAddress](#geoaddress)>> | Yes| Callback used to return the reverse geocoding result.| + +**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. | +|3301300 | Reverse geocoding query failed. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1}; + try { + geoLocationManager.getAddressesFromLocation(reverseGeocodeRequest, (err, data) => { + if (err) { + console.log('getAddressesFromLocation: err=' + JSON.stringify(err)); + } + if (data) { + console.log('getAddressesFromLocation: data=' + JSON.stringify(data)); + } + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.getAddressesFromLocation + +getAddressesFromLocation(request: ReverseGeoCodeRequest): Promise<Array<GeoAddress>>; + +Converts coordinates into geographic description through reverse geocoding. This API uses a promise to return the result. + +**System capability**: SystemCapability.Location.Location.Geocoder + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | request | [ReverseGeoCodeRequest](#reversegeocoderequest) | Yes| Reverse geocoding request.| + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | Promise<Array<[GeoAddress](#geoaddress)>> | Array<[GeoAddress](#geoaddress)> | NA | Promise used to return the reverse geocoding result.| + +**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. | +|3301300 | Reverse geocoding query failed. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + var reverseGeocodeRequest = {"latitude": 31.12, "longitude": 121.11, "maxItems": 1}; + try { + geoLocationManager.getAddressesFromLocation(reverseGeocodeRequest).then((data) => { + console.log('getAddressesFromLocation: ' + JSON.stringify(data)); + }) + .catch((error) => { + console.log('promise, getAddressesFromLocation: error=' + JSON.stringify(error)); + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.getAddressesFromLocationName + +getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>): void + +Converts geographic description into coordinates through geocoding. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Location.Location.Geocoder + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | request | [GeoCodeRequest](#geocoderequest) | Yes| Geocoding request.| + | callback | AsyncCallback<Array<[GeoAddress](#geoaddress)>> | Yes| Callback used to return the geocoding result.| + +**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. | +|3301400 | Geocoding query failed. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + var 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)); + } + if (data) { + console.log('getAddressesFromLocationName: data=' + JSON.stringify(data)); + } + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.getAddressesFromLocationName + +getAddressesFromLocationName(request: GeoCodeRequest): Promise<Array<GeoAddress>> + +Converts geographic description into coordinates through geocoding. This API uses a promise to return the result. + +**System capability**: SystemCapability.Location.Location.Geocoder + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | request | [GeoCodeRequest](#geocoderequest) | Yes| Geocoding request.| + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | Promise<Array<[GeoAddress](#geoaddress)>> | Array<[GeoAddress](#geoaddress)> | NA | Promise used to return the geocoding result.| + +**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. | +|3301400 | Geocoding query failed. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + var geocodeRequest = {"description": "No. xx, xx Road, Pudong District, Shanghai", "maxItems": 1}; + try { + geoLocationManager.getAddressesFromLocationName(geocodeRequest).then((result) => { + console.log('getAddressesFromLocationName: ' + JSON.stringify(result)); + }) + .catch((error) => { + console.log('promise, getAddressesFromLocationName: error=' + JSON.stringify(error)); + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + +## geoLocationManager.isGeocoderAvailable + +isGeocoderAvailable(): boolean; + +Obtains the (reverse) geocoding service status. + +**System capability**: SystemCapability.Location.Location.Geocoder + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | boolean | boolean | NA | Result indicating whether the (reverse) geocoding service is available.| + +**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. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + var isAvailable = geoLocationManager.isGeocoderAvailable(); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.getCachedGnssLocationsSize + +getCachedGnssLocationsSize(callback: AsyncCallback<number>): void; + +Obtains the number of cached GNSS locations. + +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Gnss + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<number> | Yes| Callback used to return the number of cached GNSS locations. | + +**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. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + geoLocationManager.getCachedGnssLocationsSize((err, size) => { + if (err) { + console.log('getCachedGnssLocationsSize: err=' + JSON.stringify(err)); + } + if (size) { + console.log('getCachedGnssLocationsSize: size=' + JSON.stringify(size)); + } + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.getCachedGnssLocationsSize + +getCachedGnssLocationsSize(): Promise<number>; + +Obtains the number of cached GNSS locations. + +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Gnss + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | Promise<number> | number | NA | Promise used to return the number of cached GNSS locations.| + +**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. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + geoLocationManager.getCachedGnssLocationsSize().then((result) => { + console.log('promise, getCachedGnssLocationsSize: ' + JSON.stringify(result)); + }) + .catch((error) => { + console.log('promise, getCachedGnssLocationsSize: error=' + JSON.stringify(error)); + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.flushCachedGnssLocations + +flushCachedGnssLocations(callback: AsyncCallback<void>): void; + +Obtains all cached GNSS locations and clears the GNSS cache queue. + +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Gnss + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | Yes| Callback used to return the error message.| + +**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 { + geoLocationManager.flushCachedGnssLocations((err, result) => { + if (err) { + console.log('flushCachedGnssLocations: err=' + JSON.stringify(err)); + } + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` -## geoLocationManager.setMockedLocations -setMockedLocations(config: LocationMockConfig): Promise<void>; +## geoLocationManager.flushCachedGnssLocations -Sets the mock location information. The mock locations will be reported at the interval specified in this API. +flushCachedGnssLocations(): Promise<void>; + +Obtains all cached GNSS locations and clears the GNSS cache queue. + +**Permission required**: ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Gnss + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | Promise<void> | void | NA | Promise used to return the error code.| + +**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 { + geoLocationManager.flushCachedGnssLocations().then((result) => { + console.log('promise, flushCachedGnssLocations success'); + }) + .catch((error) => { + console.log('promise, flushCachedGnssLocations: error=' + JSON.stringify(error)); + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.sendCommand + +sendCommand(command: LocationCommand, callback: AsyncCallback<void>): void; + +Sends an extended command to the location subsystem. **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | command | [LocationCommand](#locationcommand) | Yes| Extended command (string) to be sent.| + | callback | AsyncCallback<void> | Yes| Callback used to return the error code.| + +**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. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + var requestInfo = {'scenario': 0x301, 'command': "command_1"}; + try { + geoLocationManager.sendCommand(requestInfo, (err, result) => { + if (err) { + console.log('sendCommand: err=' + JSON.stringify(err)); + } + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.sendCommand + +sendCommand(command: LocationCommand): Promise<void>; + +Sends an extended command to the location subsystem. + +**System capability**: SystemCapability.Location.Location.Core **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| config | [LocationMockConfig](#locationmockconfig) | Yes | Mock location information, including the interval for reporting the mock locations and the array of the mock locations.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | command | [LocationCommand](#locationcommand) | Yes| Extended command (string) to be sent.| **Return value** -| Name | Type| Mandatory| Description | -| ------------------- | ---- | ---- | ------------------------------------------------------------ | -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | Promise<void> | void | NA | Promise used to return the error code.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | -| 3301100 | The location switch is off. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - var 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}; - geoLocationManager.setMockedLocations(config) - .then((result) => { - console.log('promise, setMockedLocations succeed'); - }) - .catch((error) => { - if (error) { - console.log('promise, setMockedLocations: error=' + JSON.stringify(error)); - } - }); + var requestInfo = {'scenario': 0x301, 'command': "command_1"}; + try { + geoLocationManager.sendCommand(requestInfo).then((result) => { + console.log('promise, sendCommand success'); + }) + .catch((error) => { + console.log('promise, sendCommand: error=' + JSON.stringify(error)); + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.enableReverseGeocodingMock +## geoLocationManager.getCountryCode -enableReverseGeocodingMock(callback: AsyncCallback<void>): void; +getCountryCode(callback: AsyncCallback<CountryCode>): void; -Enables the mock reverse geocoding function. +Obtains the current country code. **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. - **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[CountryCode](#countrycode)> | Yes| Callback used to return the country code.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301500 | Failed to query the area information.| **Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + geoLocationManager.getCountryCode((err, result) => { + if (err) { + console.log('getCountryCode: err=' + JSON.stringify(err)); + } + if (result) { + console.log('getCountryCode: result=' + JSON.stringify(result)); + } + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.getCountryCode + +getCountryCode(): Promise<CountryCode>; + +Obtains the current country code. + +**System capability**: SystemCapability.Location.Location.Core + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | Promise<[CountryCode](#countrycode)> | [CountryCode](#countrycode) | NA | Promise used to return the country code.| + +**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. | +|3301500 | Failed to query the area information.| + +**Example** + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.enableReverseGeocodingMock((err, data) => { - if (err) { - console.log('enableReverseGeocodingMock: err=' + JSON.stringify(err)); - } - }); + try { + geoLocationManager.getCountryCode() + .then((result) => { + console.log('promise, getCountryCode: result=' + JSON.stringify(result)); + }) + .catch((error) => { + console.log('promise, getCountryCode: error=' + JSON.stringify(error)); + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.enableReverseGeocodingMock +## geoLocationManager.enableLocationMock -enableReverseGeocodingMock(): Promise<void>; +enableLocationMock(): void; -Enables the mock reverse geocoding function. +Enables 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. -**Return value** +**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.| + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + geoLocationManager.enableLocationMock(); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.disableLocationMock + +disableLocationMock(): void; -| Name | Type| Mandatory| Description | -| ------------------- | ---- | ---- | ------------------------------------------------------------ | -| 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.| +Disables 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. **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off.| **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.enableReverseGeocodingMock() - .then((result) => { - console.log('promise, enableReverseGeocodingMock succeed'); - }) - .catch((error) => { - if (error) { - console.log('promise, enableReverseGeocodingMock: error=' + JSON.stringify(error)); - } - }); + try { + geoLocationManager.disableLocationMock(); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.disableReverseGeocodingMock +## geoLocationManager.setMockedLocations -disableReverseGeocodingMock(callback: AsyncCallback<void>): void; +setMockedLocations(config: LocationMockConfig): void; -Disables the mock geocoding function. +Sets the mock location information. The mock locations will be reported at the interval specified in this API. **System capability**: SystemCapability.Location.Location.Core @@ -866,73 +1718,102 @@ Disables the mock geocoding function. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [LocationMockConfig](#locationmockconfig) | Yes| Mock location information, including the interval for reporting the mock locations and the array of the mock locations.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | +|3301100 | The location switch is off.| **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.disableReverseGeocodingMock((err, result) => { - if (err) { - console.log('disableReverseGeocodingMock: err=' + JSON.stringify(err)); - } - }); + var 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}; + try { + geoLocationManager.setMockedLocations(config); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.disableReverseGeocodingMock +## geoLocationManager.enableReverseGeocodingMock -disableReverseGeocodingMock(): Promise<void>; +enableReverseGeocodingMock(): void; -Disables the mock reverse geocoding function. +Enables 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. -**Return value** +**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. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + geoLocationManager.enableReverseGeocodingMock(); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.disableReverseGeocodingMock + +disableReverseGeocodingMock(): void; + +Disables the mock geocoding function. + +**System capability**: SystemCapability.Location.Location.Core -| Name | Type| Mandatory| Description | -| ------------------- | ---- | ---- | ------------------------------------------------------------ | -| 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.| +**System API**: This is a system API and cannot be called by third-party applications. **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - geoLocationManager.disableReverseGeocodingMock() - .then((result) => { - console.log('promise, disableReverseGeocodingMock succeed'); - }) - .catch((error) => { - if (error) { - console.log('promise, disableReverseGeocodingMock: error=' + JSON.stringify(error)); - } - }); + try { + geoLocationManager.disableReverseGeocodingMock(); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` ## geoLocationManager.setReverseGeocodingMockInfo -setReverseGeocodingMockInfo(mockInfos: Array<ReverseGeocodingMockInfo>, callback: AsyncCallback<void>): void; +setReverseGeocodingMockInfo(mockInfos: Array<ReverseGeocodingMockInfo>): void; 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. @@ -942,21 +1823,20 @@ Sets information of the mock reverse geocoding function, including the mapping b **Parameters** -| Name | Type | Mandatory| Description | -| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | Yes | Array of information of the mock reverse geocoding function, including a location and a geographical name.| -| 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.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | Yes| Array of information of the mock reverse geocoding function, including a location and a geographical name.| **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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | **Example** - + ```ts import geoLocationManager from '@ohos.geoLocationManager'; var mockInfos = [ @@ -966,64 +1846,92 @@ For details about the following error codes, see [error codes of the location se {"location": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "maxItems": 1, "isFromMock": true}}, {"location": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "maxItems": 1, "isFromMock": true}}, ]; - geoLocationManager.setReverseGeocodingMockInfo(mockInfos, (err, data) => { - if (err) { - console.log('promise, setReverseGeocodingMockInfo, err:' + JSON.stringify(err)); - } - }); + try { + geoLocationManager.setReverseGeocodingMockInfo(mockInfos); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` -## geoLocationManager.setReverseGeocodingMockInfo - -setReverseGeocodingMockInfo(mockInfos: Array<ReverseGeocodingMockInfo>): Promise<void>; +## geoLocationManager.isLocationPrivacyConfirmed -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. +isLocationPrivacyConfirmed(type: LocationPrivacyType): boolean; -**System capability**: SystemCapability.Location.Location.Core +Checks whether a user agrees with the privacy statement of the location service. This API can only be called by system applications. **System API**: This is a system API and cannot be called by third-party applications. +**System capability**: SystemCapability.Location.Location.Core + **Parameters** -| Name | Type | Mandatory| Description | -| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| mockInfos | Array<[ReverseGeocodingMockInfo](#reversegeocodingmockinfo)> | Yes | Array of information of the mock reverse geocoding function, including a location and a geographical name.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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.| **Return value** -| Name | Type| Mandatory| Description | -| ------------------- | ---- | ---- | ------------------------------------------------------------ | -| 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.| + | 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** -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). -| Code| Error Message | -| -------- | -------------------------------- | -| 3301000 | Location service is unavailable. | +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | **Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + try { + var isConfirmed = geoLocationManager.isLocationPrivacyConfirmed(1); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + +## geoLocationManager.setLocationPrivacyConfirmStatus + +setLocationPrivacyConfirmStatus(type: LocationPrivacyType, isConfirmed: boolean): void; + +Sets the user confirmation status for the privacy statement of the location service. This API can only be called by system applications. + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS + +**System capability**: SystemCapability.Location.Location.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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** + +For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). + +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301000 | Location service is unavailable. | + +**Example** + ```ts import geoLocationManager from '@ohos.geoLocationManager'; - var 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}}, - {"location": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 33.12, "longitude": 123.11, "maxItems": 1, "isFromMock": true}}, - {"location": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "maxItems": 1}, "geoAddress": {"locale": "zh", "latitude": 34.12, "longitude": 124.11, "maxItems": 1, "isFromMock": true}}, - ]; - geoLocationManager.setReverseGeocodingMockInfo(mockInfos) - .then((result) => { - console.log('promise, setReverseGeocodingMockInfo succeed'); - }) - .catch((error) => { - if (error) { - console.log('promise, setReverseGeocodingMockInfo: error=' + JSON.stringify(error)); - } - }); + try { + geoLocationManager.setLocationPrivacyConfirmStatus(1, true); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } ``` @@ -1033,11 +1941,11 @@ 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. | +| 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.| @@ -1047,14 +1955,14 @@ Sets the priority 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.| +| 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 @@ -1063,12 +1971,12 @@ 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. | +| 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 @@ -1077,15 +1985,15 @@ 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. | +| 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 @@ -1094,27 +2002,27 @@ 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<string> | Yes | No | Additional descriptions. | -| descriptionsSize | number | Yes | No | Total number of additional descriptions. | -| isFromMock | Boolean | Yes | No | Whether the geographical name is from the mock reverse geocoding function. | +| 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<string> | Yes| No| Additional descriptions.| +| descriptionsSize | number | Yes| No| Total number of additional descriptions.| +| isFromMock | Boolean | Yes| No| Whether the geographical name is from the mock reverse geocoding function.| ## LocationRequest @@ -1123,13 +2031,13 @@ 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.| +| 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 @@ -1138,12 +2046,12 @@ 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**. | +| 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 @@ -1152,14 +2060,14 @@ 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<number> | Yes | No | Array of satellite IDs. | -| carrierToNoiseDensitys | Array<number> | Yes | No | Carrier-to-noise density ratio, that is, **cn0**.| -| altitudes | Array<number> | Yes | No | Altitude information. | -| azimuths | Array<number> | Yes | No | Azimuth information. | -| carrierFrequencies | Array<number> | Yes | No | Carrier frequency. | +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| satellitesNumber | number | Yes| No| Number of satellites.| +| satelliteIds | Array<number> | Yes| No| Array of satellite IDs.| +| carrierToNoiseDensitys | Array<number> | Yes| No| Carrier-to-noise density ratio, that is, **cn0**.| +| altitudes | Array<number> | Yes| No| Altitude information.| +| azimuths | Array<number> | Yes| No| Azimuth information.| +| carrierFrequencies | Array<number> | Yes| No| Carrier frequency.| ## CachedGnssLocationsRequest @@ -1168,10 +2076,10 @@ 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.
**false**: discards the cached GNSS locations when the cache queue is full. | +| 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.
**false**: discards the cached GNSS locations when the cache queue is full.| ## Geofence @@ -1180,12 +2088,12 @@ 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.| +| 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 @@ -1194,11 +2102,10 @@ Represents a GNSS geofencing request. **System capability**: SystemCapability.Location.Location.Geofence -| 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. | +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes | Location scenario.| +| geofence | [Geofence](#geofence)| Yes| Yes | Geofence information.| ## LocationPrivacyType @@ -1207,11 +2114,11 @@ 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.| +| 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 @@ -1220,10 +2127,10 @@ 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.| +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes | Location scenario.| +| command | string | Yes| Yes | Extended command, in the string format.| ## Location @@ -1232,19 +2139,19 @@ 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<string> | 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. | +| 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<string> | 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 @@ -1255,10 +2162,10 @@ Represents information of the mock reverse geocoding function. **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 | Geographical name. | +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| location | [ReverseGeoCodeRequest](#reversegeocoderequest) | Yes| Yes| Latitude and longitude information.| +| geoAddress | [GeoAddress](#geoaddress) | Yes| Yes|Geographical name.| ## LocationMockConfig @@ -1269,10 +2176,10 @@ Represents the information of the mock location function. **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<Location> | Yes | Yes | Array of mocked locations. | +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| timeInterval | number | Yes| Yes| Interval at which mock locations are reported, in seconds.| +| locations | Array<Location> | Yes| Yes| Array of mocked locations.| ## CountryCode @@ -1281,10 +2188,10 @@ 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.| +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| country | string | Yes| No| Country code.| +| type | [CountryCodeType](#countrycodetype) | Yes| No| Country code source.| ## CountryCodeType @@ -1293,9 +2200,9 @@ 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. | +| 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.| -- GitLab