diff --git a/en/application-dev/connectivity/Readme-EN.md b/en/application-dev/connectivity/Readme-EN.md index c09ca21b6d0814bd1cd2cecb95b0d2896fada8c4..729e641a3f526025ff218a4b64b32f064038b5ba 100755 --- a/en/application-dev/connectivity/Readme-EN.md +++ b/en/application-dev/connectivity/Readme-EN.md @@ -9,6 +9,7 @@ - [Ethernet Connection](net-ethernet.md) - [Network Connection Management](net-connection-manager.md) - [mDNS Management](net-mdns.md) + - [VPN Management](net-vpn.md) - IPC & RPC - [IPC & RPC Overview](ipc-rpc-overview.md) - [IPC & RPC Development](ipc-rpc-development-guideline.md) diff --git a/en/application-dev/connectivity/net-connection-manager.md b/en/application-dev/connectivity/net-connection-manager.md index c443c93759caddbc5203b65022426882c0bb960b..fba108e73cd8e5e3dd81a43880cf25a54aee6ee5 100644 --- a/en/application-dev/connectivity/net-connection-manager.md +++ b/en/application-dev/connectivity/net-connection-manager.md @@ -107,7 +107,7 @@ conn.on('netAvailable', (data => { // Listen to network status change events. If the network is unavailable, an on_netUnavailable event is returned. conn.on('netUnavailable', (data => { - console.log("net is unavailable, netId is " + data.netId); + console.log("net is unavailable, data is " + JSON.stringify(data)); })); // Register an observer for network status changes. diff --git a/en/application-dev/connectivity/net-vpn.md b/en/application-dev/connectivity/net-vpn.md new file mode 100644 index 0000000000000000000000000000000000000000..adf38f9676f29937532579e0bbdb4a94467095f3 --- /dev/null +++ b/en/application-dev/connectivity/net-vpn.md @@ -0,0 +1,362 @@ +# VPN Management + +## Overview + +A virtual private network (VPN) is a dedicated network established on a public network. On a VPN, the connection between any two nodes does not have an end-to-end physical link required by the traditional private network. Instead, user data is transmitted over a logical link because a VPN is a logical network deployed over the network platform (such as the Internet) provided by the public network service provider. + +> **NOTE** +> To maximize the application running efficiency, most API calls are called asynchronously in callback or promise mode. The following code examples use the callback mode. For details about the APIs, see [Traffic Management](../reference/apis/js-apis-net-vpn.md). + +The following describes the development procedure specific to each application scenario. + +## Available APIs + +For the complete list of APIs and example code, see [VPN Management](../reference/apis/js-apis-net-vpn.md). + +| Type| API| Description| +| ---- | ---- | ---- | +| ohos.net.vpn | setUp(config: VpnConfig, callback: AsyncCallback\): void | Establishes a VPN. This API uses an asynchronous callback to return the result.| +| ohos.net.vpn | protect(socketFd: number, callback: AsyncCallback\): void | Enables VPN tunnel protection. This API uses an asynchronous callback to return the result.| +| ohos.net.vpn | destroy(callback: AsyncCallback\): void | Destroys a VPN. This API uses an asynchronous callback to return the result.| + +## Starting a VPN + +1. Establish a VPN tunnel. The following uses the UDP tunnel as an example. +2. Enable protection for the UDP tunnel. +3. Establish a VPN. +4. Process data of the virtual network interface card (vNIC), such as reading or writing data. +5. Destroy the VPN. + +This example shows how to develop an application using native C++ code. For details, see [Simple Native C++ Example (ArkTS) (API9)] (https://gitee.com/openharmony/codelabs/tree/master/NativeAPI/NativeTemplateDemo). + +The sample application consists of two parts: JS code and C++ code. + +## JS Code +The JS code is used to implement the service logic, such as creating a tunnel, establishing a VPN, enabling VPN protection, and destroying a VPN. + +```js +import hilog from '@ohos.hilog'; +import vpn from '@ohos.net.vpn'; +import UIAbility from '@ohos.app.ability.UIAbility'; +import vpn_client from "libvpn_client.so" + +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage) { + globalThis.context = this.context; + } +} + +let TunnelFd = -1 +let VpnConnection = vpn.createVpnConnection(globalThis.context) + +@Entry +@Component +struct Index { + @State message: string = 'Test VPN' + + //1. Establish a VPN tunnel. The following uses the UDP tunnel as an example. + CreateTunnel() { + TunnelFd = vpn_client.udpConnect("192.168.43.208", 8888) + } + + // 2. Enable protection for the UDP tunnel. + Protect() { + VpnConnection.protect(TunnelFd).then(function () { + console.info("vpn Protect Success.") + }).catch(function (err) { + console.info("vpn Protect Failed " + JSON.stringify(err)) + }) + } + + SetupVpn() { + let config = { + addresses: [{ + address: { + address: "10.0.0.5", + family: 1 + }, + prefixLength: 24, + }], + routes: [], + mtu: 1400, + dnsAddresses: [ + "114.114.114.114" + ], + acceptedApplications: [], + refusedApplications: [] + } + + try { + // 3. Create a VPN. + VpnConnection.setUp(config, (error, data) => { + console.info("tunfd: " + JSON.stringify(data)); + // 4. Process data of the virtual vNIC, such as reading or writing data. + vpn_client.startVpn(data, TunnelFd) + }) + } catch (error) { + console.info("vpn setUp fail " + JSON.stringify(error)); + } + } + + // 5. Destroy the VPN. + Destroy() { + vpn_client.stopVpn(TunnelFd) + VpnConnection.destroy().then(function () { + console.info("vpn Destroy Success.") + }).catch(function (err) { + console.info("vpn Destroy Failed " + JSON.stringify(err)) + }) + } + + build() { + Row() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + .onClick(() => { + console.info("vpn Client") + }) + Button('CreateTunnel').onClick(() => { + this.CreateTunnel() + }).fontSize(50) + Button('Protect').onClick(() => { + this.Protect() + }).fontSize(50) + Button('SetupVpn').onClick(() => { + this.SetupVpn() + }).fontSize(50) + Button('Destroy').onClick(() => { + this.Destroy() + }).fontSize(50) + } + .width('100%') + } + .height('100%') + } +} +``` + +## C++ Code +The C++ code is used for underlying service implementation, such as UDP tunnel client implementation and vNIC data read and write. + +```c++ +#include "napi/native_api.h" +#include "hilog/log.h" + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include + +#define BUFFER_SIZE 2048 + +#define VPN_LOG_TAG "NetMgrVpn" +#define VPN_LOG_DOMAIN 0x15b0 +#define MAKE_FILE_NAME (strrchr(__FILE__, '/') + 1) + +#define NETMANAGER_VPN_LOGE(fmt, ...) \ + OH_LOG_Print(LOG_APP, LOG_ERROR, VPN_LOG_DOMAIN, VPN_LOG_TAG, "vpn [%{public}s %{public}d] " fmt, MAKE_FILE_NAME, \ + __LINE__, ##__VA_ARGS__) + +#define NETMANAGER_VPN_LOGI(fmt, ...) \ + OH_LOG_Print(LOG_APP, LOG_INFO, VPN_LOG_DOMAIN, VPN_LOG_TAG, "vpn [%{public}s %{public}d] " fmt, MAKE_FILE_NAME, \ + __LINE__, ##__VA_ARGS__) + +#define NETMANAGER_VPN_LOGD(fmt, ...) \ + OH_LOG_Print(LOG_APP, LOG_DEBUG, VPN_LOG_DOMAIN, VPN_LOG_TAG, "vpn [%{public}s %{public}d] " fmt, MAKE_FILE_NAME, \ + __LINE__, ##__VA_ARGS__) + +struct FdInfo { + int32_t tunFd = 0; + int32_t tunnelFd = 0; + struct sockaddr_in serverAddr; +}; + +static FdInfo fdInfo; +static bool threadRunF = false; +static std::thread threadt1; +static std::thread threadt2; + +// Obtain the IP address of the UDP server. +static constexpr const int MAX_STRING_LENGTH = 1024; +std::string GetStringFromValueUtf8(napi_env env, napi_value value) { + std::string result; + char str[MAX_STRING_LENGTH] = {0}; + size_t length = 0; + napi_get_value_string_utf8(env, value, str, MAX_STRING_LENGTH, &length); + if (length > 0) { + return result.append(str, length); + } + return result; +} + +void HandleReadTunfd(FdInfo fdInfo) { + uint8_t buffer[BUFFER_SIZE] = {0}; + while (threadRunF) { + int ret = read(fdInfo.tunFd, buffer, sizeof(buffer)); + if (ret <= 0) { + if (errno != 11) { + NETMANAGER_VPN_LOGE("read tun device error: %{public}d, tunfd: %{public}d", errno, fdInfo.tunFd); + } + continue; + } + + // Read data from the vNIC and send the data to the UDP server through the UDP tunnel. + NETMANAGER_VPN_LOGD("buffer: %{public}s, len: %{public}d", buffer, ret); + ret = sendto(fdInfo.tunnelFd, buffer, ret, 0, (struct sockaddr *)&fdInfo.serverAddr, sizeof(fdInfo.serverAddr)); + if (ret <= 0) { + NETMANAGER_VPN_LOGE("send to server[%{public}s:%{public}d] failed, ret: %{public}d, error: %{public}s", + inet_ntoa(fdInfo.serverAddr.sin_addr), ntohs(fdInfo.serverAddr.sin_port), ret, + strerror(errno)); + continue; + } + } +} + +void HandleTcpReceived(FdInfo fdInfo) { + int addrlen = sizeof(struct sockaddr_in); + uint8_t buffer[BUFFER_SIZE] = {0}; + while (threadRunF) { + int length = recvfrom(fdInfo.tunnelFd, buffer, sizeof(buffer), 0, (struct sockaddr *)&fdInfo.serverAddr, + (socklen_t *)&addrlen); + if (length < 0) { + if (errno != 11) { + NETMANAGER_VPN_LOGE("read tun device error: %{public}d, tunnelfd: %{public}d", errno, fdInfo.tunnelFd); + } + continue; + } + + // Receive data from the UDP server and write the data to the vNIC. + NETMANAGER_VPN_LOGD("from [%{public}s:%{public}d] data: %{public}s, len: %{public}d", + inet_ntoa(fdInfo.serverAddr.sin_addr), ntohs(fdInfo.serverAddr.sin_port), buffer, length); + int ret = write(fdInfo.tunFd, buffer, length); + if (ret <= 0) { + NETMANAGER_VPN_LOGE("error Write To Tunfd, errno: %{public}d", errno); + } + } +} + +static napi_value UdpConnect(napi_env env, napi_callback_info info) { + size_t argc = 2; + napi_value args[2] = {nullptr}; + napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); + + int32_t port = 0; + napi_get_value_int32(env, args[1], &port); + std::string ipAddr = GetStringFromValueUtf8(env, args[0]); + + NETMANAGER_VPN_LOGI("ip: %{public}s port: %{public}d", ipAddr.c_str(), port); + + // Establish a UDP tunnel. + int32_t sockFd = socket(AF_INET, SOCK_DGRAM, 0); + if (sockFd == -1) { + NETMANAGER_VPN_LOGE("socket() error"); + return 0; + } + + struct timeval timeout = {1, 0}; + setsockopt(sockFd, SOL_SOCKET, SO_RCVTIMEO, (char *)&timeout, sizeof(struct timeval)); + + memset(&fdInfo.serverAddr, 0, sizeof(fdInfo.serverAddr)); + fdInfo.serverAddr.sin_family = AF_INET; + fdInfo.serverAddr.sin_addr.s_addr = inet_addr(ipAddr.c_str()); // server's IP addr + fdInfo.serverAddr.sin_port = htons(port); // port + + NETMANAGER_VPN_LOGI("Connection successful"); + + napi_value tunnelFd; + napi_create_int32(env, sockFd, &tunnelFd); + return tunnelFd; +} + +static napi_value StartVpn(napi_env env, napi_callback_info info) { + size_t argc = 2; + napi_value args[2] = {nullptr}; + napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); + + napi_get_value_int32(env, args[0], &fdInfo.tunFd); + napi_get_value_int32(env, args[1], &fdInfo.tunnelFd); + + if (threadRunF) { + threadRunF = false; + threadt1.join(); + threadt2.join(); + } + + // Start two threads. One is used to read data from the vNIC, and the other is used to receive data from the server. + threadRunF = true; + std::thread tt1(HandleReadTunfd, fdInfo); + std::thread tt2(HandleTcpReceived, fdInfo); + + threadt1 = std::move(tt1); + threadt2 = std::move(tt2); + + NETMANAGER_VPN_LOGI("StartVpn successful"); + + napi_value retValue; + napi_create_int32(env, 0, &retValue); + return retValue; +} + +static napi_value StopVpn(napi_env env, napi_callback_info info) { + size_t argc = 1; + napi_value args[1] = {nullptr}; + napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); + + int32_t tunnelFd; + napi_get_value_int32(env, args[0], &tunnelFd); + if (tunnelFd) { + close(tunnelFd); + tunnelFd = 0; + } + + // Stop the two threads. + if (threadRunF) { + threadRunF = false; + threadt1.join(); + threadt2.join(); + } + + NETMANAGER_VPN_LOGI("StopVpn successful"); + + napi_value retValue; + napi_create_int32(env, 0, &retValue); + return retValue; +} + +EXTERN_C_START +static napi_value Init(napi_env env, napi_value exports) { + napi_property_descriptor desc[] = { + {"udpConnect", nullptr, UdpConnect, nullptr, nullptr, nullptr, napi_default, nullptr}, + {"startVpn", nullptr, StartVpn, nullptr, nullptr, nullptr, napi_default, nullptr}, + {"stopVpn", nullptr, StopVpn, nullptr, nullptr, nullptr, napi_default, nullptr}, + }; + napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); + return exports; +} +EXTERN_C_END + +static napi_module demoModule = { + .nm_version = 1, + .nm_flags = 0, + .nm_filename = nullptr, + .nm_register_func = Init, + .nm_modname = "entry", + .nm_priv = ((void *)0), + .reserved = {0}, +}; + +extern "C" __attribute__((constructor)) void RegisterEntryModule(void) { + napi_module_register(&demoModule); +} +``` diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 4fc3fb5005d7ac0208b083be1a084bd5c66b4865..49b419c555b92ded66cb4805bf48b717621de110 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -315,6 +315,7 @@ - [@ohos.net.statistics (Traffic Management)](js-apis-net-statistics.md) - [@ohos.net.webSocket (WebSocket Connection)](js-apis-webSocket.md) - [@ohos.request (Upload and Download)](js-apis-request.md) + - [@ohos.net.vpn (VPN Management)](js-apis-net-vpn.md) - Connectivity - [@ohos.bluetooth.a2dp (Bluetooth a2dp Module)(Recommended)](js-apis-bluetooth-a2dp.md) diff --git a/en/application-dev/reference/apis/js-apis-geoLocationManager.md b/en/application-dev/reference/apis/js-apis-geoLocationManager.md index 263a1a525e0fa1dffcbd9e79703d2d359ac49dcc..47f6eb18cc6581dbb9d5fa5b1b975a9f5ddfc9ed 100644 --- a/en/application-dev/reference/apis/js-apis-geoLocationManager.md +++ b/en/application-dev/reference/apis/js-apis-geoLocationManager.md @@ -53,7 +53,7 @@ Defines a reverse geocoding request. | locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.| | latitude | number | Yes| Yes| Latitude information. A positive value indicates north latitude, and a negative value indicates south latitude. The value ranges from **-90** to **90**.| | longitude | number | Yes| Yes| Longitude information. A positive value indicates east longitude , and a negative value indicates west longitude . The value ranges from **-180** to **180**.| -| maxItems | number | Yes| Yes| Maximum number of location records to be returned. The value must be greater than or equal to **0**. A value smaller than **10** is recommended.| +| maxItems | number | Yes| Yes| Maximum number of location records to be returned. The specified value must be greater than or equal to **0**. A value smaller than **10** is recommended.| ## GeoCodeRequest @@ -66,7 +66,7 @@ Defines a geocoding request. | -------- | -------- | -------- | -------- | -------- | | locale | string | Yes| Yes| Language used for the location description. **zh** indicates Chinese, and **en** indicates English.| | description | string | Yes| Yes| Location description, for example, **No. xx, xx Road, Pudong New District, Shanghai**.| -| maxItems | number | Yes| Yes| Maximum number of location records to be returned. The value must be greater than or equal to **0**. A value smaller than **10** is recommended.| +| maxItems | number | Yes| Yes| Maximum number of location records to be returned. The specified value must be greater than or equal to **0**. A value smaller than **10** is recommended.| | minLatitude | number | Yes| Yes| Minimum latitude. This parameter is used with **minLongitude**, **maxLatitude**, and **maxLongitude** to specify the latitude and longitude ranges. The value ranges from **-90** to **90**.| | minLongitude | number | Yes| Yes| Minimum longitude. The value ranges from **-180** to **180**.| | maxLatitude | number | Yes| Yes| Maximum latitude. The value ranges from **-90** to **90**.| @@ -98,7 +98,7 @@ Defines a geographic location. | 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. The value must be greater than or equal to **0**. A value smaller than **10** is recommended.| +| descriptionsSize | number | Yes| No| Total number of additional descriptions. The specified value must be greater than or equal to **0**. A value smaller than **10** is recommended.| | isFromMock | Boolean | Yes| No| Whether the geographical name is from the mock reverse geocoding function.
**System API**: This is a system API.| @@ -110,11 +110,11 @@ Defines a location request. | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request. For details about the value range, see [LocationRequestPriority](#locationrequestpriority).| -| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes| Scenario of the location request. For details about the value range, see [LocationRequestScenario](#locationrequestscenario).| -| timeInterval | number | Yes| Yes| Time interval at which location information is reported, in seconds. The value must be greater than **0**.| -| distanceInterval | number | Yes| Yes| Distance interval at which location information is reported. The value must be greater than **0**, in meters.| -| maxAccuracy | number | Yes| Yes| Location accuracy. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled. The value must be greater than **0**.| +| priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request. This parameter is effective only when **scenario** is set to **UNSET**. If this parameter and **scenario** are set to **UNSET**, the attempt to initiate a location request will fail. For details about the value range, see [LocationRequestPriority](#locationrequestpriority).| +| scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes| Scenario of the location request. The **priority** parameter is effective only when this parameter is set to **UNSET**. If this parameter and **priority** are set to **UNSET**, the attempt to initiate a location request will fail. For details about the value range, see [LocationRequestScenario](#locationrequestscenario).| +| timeInterval | number | Yes| Yes| Time interval at which location information is reported, in seconds. The specified value must be greater than or equal to **0**. The default value is **1**.| +| distanceInterval | number | Yes| Yes| Distance interval at which location information is reported, in meters. The specified value must be greater than or equal to **0**. The default value is **0**.| +| maxAccuracy | number | Yes| Yes| Location accuracy, in meters. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled. The specified value must be greater than or equal to **0**. The default value is **0**.| ## CurrentLocationRequest @@ -127,8 +127,8 @@ Defines the current location request. | -------- | -------- | -------- | -------- | -------- | | priority | [LocationRequestPriority](#locationrequestpriority) | Yes| Yes| Priority of the location request. For details about the value range, see [LocationRequestPriority](#locationrequestpriority).| | scenario | [LocationRequestScenario](#locationrequestscenario) | Yes| Yes| Scenario of the location request. For details about the value range, see [LocationRequestScenario](#locationrequestscenario).| -| maxAccuracy | number | Yes| Yes| Location accuracy, in meters. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled. The value must be greater than **0**.| -| timeoutMs | number | Yes| Yes| Timeout duration, in milliseconds. The minimum value is **1000**. The value must be greater than or equal to **1000**.| +| maxAccuracy | number | Yes| Yes| Location accuracy, in meters. This parameter is valid only when the precise location function is enabled, and is invalid when the approximate location function is enabled. The specified value must be greater than **0**.| +| timeoutMs | number | Yes| Yes| Timeout duration, in milliseconds. The minimum value is **1000**. The specified value must be greater than or equal to **1000**.| ## SatelliteStatusInfo @@ -139,23 +139,23 @@ Defines the satellite status information. | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| satellitesNumber | number | Yes| No| Number of satellites. The value must be greater than or equal to **0**.| -| satelliteIds | Array<number> | Yes| No| Array of satellite IDs. The value must be greater than or equal to **0**.| -| carrierToNoiseDensitys | Array<number> | Yes| No| Carrier-to-noise density ratio, that is, **cn0**. The value must be greater than **0**.| +| satellitesNumber | number | Yes| No| Number of satellites. The specified value must be greater than or equal to **0**.| +| satelliteIds | Array<number> | Yes| No| Array of satellite IDs. The specified value must be greater than or equal to **0**.| +| carrierToNoiseDensitys | Array<number> | Yes| No| Carrier-to-noise density ratio, that is, **cn0**. The specified value must be greater than **0**.| | altitudes | Array<number> | Yes| No| Satellite altitude angle information. The value ranges from **-90** to **90**, in degrees.| | azimuths | Array<number> | Yes| No| Azimuth information. The value ranges from **0** to **360**, in degrees.| -| carrierFrequencies | Array<number> | Yes| No| Carrier frequency. The value must be greater than or equal to **0**, in Hz.| +| carrierFrequencies | Array<number> | Yes| No| Carrier frequency, in Hz. The specified value must be greater than or equal to **0**.| ## CachedGnssLocationsRequest -Represents a request for reporting cached GNSS locations. +Defines a request for reporting cached GNSS locations. **System capability**: SystemCapability.Location.Location.Gnss | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| reportingPeriodSec | number | Yes| Yes| Interval for reporting the cached GNSS locations, in milliseconds. The value must be greater than **0**.| +| reportingPeriodSec | number | Yes| Yes| Interval for reporting the cached GNSS locations, in milliseconds. The specified value must be greater than **0**.| | wakeUpCacheQueueFull | boolean | Yes| Yes | **true**: reports the cached GNSS locations to the application when the cache queue is full.
**false**: discards the cached GNSS locations when the cache queue is full.| @@ -169,13 +169,13 @@ Defines a GNSS geofence. Currently, only circular geofences are supported. | -------- | -------- | -------- | -------- | -------- | | latitude | number | Yes| Yes|Latitude information. The value ranges from **-90** to **90**.| | longitude | number | Yes|Yes| Longitude information. The value ranges from **-180** to **180**.| -| radius | number | Yes|Yes| Radius of a circular geofence. The value must be greater than **0**, in meters.| -| expiration | number | Yes|Yes| Expiration period of a geofence, in milliseconds. The value must be greater than **0**.| +| radius | number | Yes|Yes| Radius of a circular geofence, in meters. The specified value must be greater than **0**.| +| expiration | number | Yes|Yes| Expiration period of a geofence, in milliseconds. The specified value must be greater than **0**.| ## GeofenceRequest -Represents a GNSS geofencing request. +Defines a GNSS geofencing request. **System capability**: SystemCapability.Location.Location.Geofence @@ -214,17 +214,17 @@ Defines a location. | direction | number | Yes| No| Direction information. The value ranges from **0** to **360**, in degrees.| | timeSinceBoot | number | Yes| No| Location timestamp since boot.| | additions | Array<string> | Yes| No| Additional description.| -| additionSize | number | Yes| No| Number of additional descriptions. The value must be greater than or equal to **0**. | +| additionSize | number | Yes| No| Number of additional descriptions. The specified value must be greater than or equal to **0**. | | isFromMock | Boolean | Yes| No| Whether the location information is from the mock location function.
**System API**: This is a system API.| ## ReverseGeocodingMockInfo -Represents information of the mock reverse geocoding function. +Defines the configuration of the mock reverse geocoding function. **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | @@ -234,21 +234,21 @@ Represents information of the mock reverse geocoding function. ## LocationMockConfig -Represents the information of the mock location function. +Defines the configuration of the mock location function. **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. | Name| Type| Readable|Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| timeInterval | number | Yes| Yes| Interval at which mock locations are reported, in seconds.| +| timeInterval | number | Yes| Yes| Time interval at which mock locations are reported, in seconds.| | locations | Array<[Location](#location)> | Yes| Yes| Array of mocked locations.| ## CountryCode -Represents country code information. +Defines the country code information. **System capability**: SystemCapability.Location.Location.Core @@ -258,6 +258,69 @@ Represents country code information. | type | [CountryCodeType](#countrycodetype) | Yes| No| Country code source.| +## LocatingRequiredDataConfig10+ + +Defines the configuration for obtaining the required data of the location service. + +**System capability**: SystemCapability.Location.Location.Core + +**System API**: This is a system API. + +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| type | [LocatingRequiredDataType](#locatingrequireddatatype10) | Yes| Yes| Type of the required data.| +| needStartScan | boolean | Yes| Yes| Whether to initiate scanning.| +| scanInterval | number | Yes| Yes| Scanning interval, in ms. The specified value must be greater than **0**. The default value is **10000**.| +| scanTimeout | number | Yes| Yes| Scanning timeout interval, in ms. The value ranges from **0** to **600000**. The default value is **10000**.| + + +## LocatingRequiredData10+ + +Defines the required data of the location service, including the Wi-Fi or Bluetooth scanning result. After obtaining the data, an application can use the data for services such as network positioning. + +**System capability**: SystemCapability.Location.Location.Core + +**System API**: This is a system API. + +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| wifiData | [WifiScanInfo](#wifiscaninfo10) | Yes| No| Wi-Fi scanning result.| +| bluetoothData | [BluetoothScanInfo](#bluetoothscaninfo10) | Yes| No| Bluetooth scanning result.| + + +## WifiScanInfo10+ + +Defines the Wi-Fi scanning information, including the SSID, BSSID, and RSSI of the scanned Wi-Fi hotspot. + +**System capability**: SystemCapability.Location.Location.Core + +**System API**: This is a system API. + +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| ssid | string | Yes| No| Service set identifier (SSID) of a Wi-Fi hotspot, in UTF-8 format.| +| bssid | string | Yes| No| Base station subsystem identifier (BSSID) of a Wi-Fi hotspot.| +| rssi | number | Yes| No| Received signal strength indicator (RSSI) of a Wi-Fi hotspot, in dBm.| +| frequency | number | Yes| No| Frequency of a Wi-Fi hotspot.| +| timestamp | number | Yes| No| Scanning timestamp.| + + +## BluetoothScanInfo10+ + +Defines the Bluetooth scanning information. + +**System capability**: SystemCapability.Location.Location.Core + +**System API**: This is a system API. + +| Name| Type| Readable|Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| deviceName | string | Yes| No| Name of a Bluetooth device.| +| macAddress | string | Yes| No| MAC address of a Bluetooth device.| +| rssi | number | Yes| No| Signal strength of a Bluetooth device, in dBm.| +| timestamp | number | Yes| No| Scanning timestamp.| + + ## LocationRequestPriority Sets the priority of the location request. @@ -280,7 +343,7 @@ Sets the priority of the location request. | Name| Value| Description| | -------- | -------- | -------- | -| UNSET | 0x300 | Scenario unspecified.
If this option is used, [LocationRequestScenario](#locationrequestscenario) is invalid.| +| UNSET | 0x300 | Scenario unspecified.
If this option is used, [LocationRequestScenario](#locationrequest scenario) is invalid.| | NAVIGATION | 0x301 | Navigation.
This option is applicable when your application needs to obtain the real-time location of a mobile device outdoors, such as navigation for driving or walking.
In this scenario, GNSS positioning is used to provide location services to ensure the optimal location accuracy of the system.
The location result is reported at a minimum interval of 1 second by default.| | TRAJECTORY_TRACKING | 0x302 | Trajectory tracking.
This option is applicable when your application needs to record user trajectories, for example, the track recording function of sports applications. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy.
The location result is reported at a minimum interval of 1 second by default.| | CAR_HAILING | 0x303 | Ride hailing.
This option is applicable when your application needs to obtain the current location of a user who is hailing a taxi.
The location result is reported at a minimum interval of 1 second by default.| @@ -294,7 +357,7 @@ Defines the privacy statement type. **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. | Name| Value| Description| | -------- | -------- | -------- | @@ -305,7 +368,7 @@ Defines the privacy statement type. ## CountryCodeType -Represents the country code source type. +Defines the country code source type. **System capability**: SystemCapability.Location.Location.Core @@ -317,11 +380,25 @@ Represents the country code source type. | COUNTRY_CODE_FROM_NETWORK | 4 | Country code obtained from the cellular network registration information.| +## LocatingRequiredDataType10+ + +Defines the type of the required data of the location service. + +**System capability**: SystemCapability.Location.Location.Core + +**System API**: This is a system API. + +| Name| Value| Description| +| -------- | -------- | -------- | +| WIFI | 1 | Wi-Fi scanning information.| +| BLUETOOTH | 2 | Bluetooth scanning information.| + + ## geoLocationManager.on('locationChange') on(type: 'locationChange', request: LocationRequest, callback: Callback<Location>): void -Registers a listener for location changes with a location request initiated. +Subscribes to location change events with a location request initiated. **Permission required**: ohos.permission.APPROXIMATELY_LOCATION @@ -331,13 +408,13 @@ Registers a listener for location changes with a location request initiated. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value **locationChange** indicates a location change event.| + | type | string | Yes| Event type. The value **locationChange** indicates a location change.| | request | [LocationRequest](#locationrequest) | Yes| Location request.| - | callback | Callback<[Location](#location)> | Yes| Callback used to return the location change event.| + | callback | Callback<[Location](#location)> | Yes| Callback used to receive location change events.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -349,7 +426,7 @@ For details about the following error codes, see [Location Error Codes](../error ```ts import geoLocationManager from '@ohos.geoLocationManager'; - let requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; + let requestInfo = {'priority': geoLocationManager.LocationRequestPriority.FIRST_FIX, 'scenario': geoLocationManager.LocationRequestScenario.UNSET, 'timeInterval': 1, 'distanceInterval': 0, 'maxAccuracy': 0}; let locationChange = (location) => { console.log('locationChanger: data: ' + JSON.stringify(location)); }; @@ -366,7 +443,7 @@ For details about the following error codes, see [Location Error Codes](../error off(type: 'locationChange', callback?: Callback<Location>): void -Unregisters the listener for location changes with the corresponding location request deleted. +Unsubscribes from location change events with the corresponding location request deleted. **Permission required**: ohos.permission.APPROXIMATELY_LOCATION @@ -376,12 +453,12 @@ Unregisters the listener for location changes with the corresponding location re | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value **locationChange** indicates a location change event.| + | type | string | Yes| Event type. The value **locationChange** indicates a location change.| | callback | Callback<[Location](#location)> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -393,7 +470,7 @@ For details about the following error codes, see [Location Error Codes](../error ```ts import geoLocationManager from '@ohos.geoLocationManager'; - let requestInfo = {'priority': 0x203, 'scenario': 0x300, 'timeInterval': 0, 'distanceInterval': 0, 'maxAccuracy': 0}; + let requestInfo = {'priority': geoLocationManager.LocationRequestPriority.FIRST_FIX, 'scenario': geoLocationManager.LocationRequestScenario.UNSET, 'timeInterval': 1, 'distanceInterval': 0, 'maxAccuracy': 0}; let locationChange = (location) => { console.log('locationChanger: data: ' + JSON.stringify(location)); }; @@ -410,7 +487,7 @@ For details about the following error codes, see [Location Error Codes](../error on(type: 'locationEnabledChange', callback: Callback<boolean>): void -Registers a listener for location service status change events. +Subscribes to location service status change events. **System capability**: SystemCapability.Location.Location.Core @@ -418,12 +495,12 @@ Registers a listener for location service status change events. | 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.| + | type | string | Yes| Event type. The value **locationEnabledChange** indicates a location service status change.| + | callback | Callback<boolean> | Yes| Callback used to receive location service status change events.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -448,7 +525,7 @@ For details about the following error codes, see [Location Error Codes](../error off(type: 'locationEnabledChange', callback?: Callback<boolean>): void; -Unregisters the listener for location service status change events. +Unsubscribes from location service status change events. **System capability**: SystemCapability.Location.Location.Core @@ -456,12 +533,12 @@ Unregisters the listener for location service status change events. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value **locationEnabledChange** indicates a location service status change event.| + | type | string | Yes| Event type. The value **locationEnabledChange** indicates a location service status change.| | callback | Callback<boolean> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -487,7 +564,7 @@ For details about the following error codes, see [Location Error Codes](../error on(type: 'cachedGnssLocationsChange', request: CachedGnssLocationsRequest, callback: Callback<Array<Location>>): void; -Registers a listener for cached GNSS location reports. +Subscribes to cached GNSS location reports. **Permission required**: ohos.permission.APPROXIMATELY_LOCATION @@ -499,11 +576,11 @@ Registers a listener for cached GNSS location reports. | -------- | -------- | -------- | -------- | | 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.| + | callback | Callback<boolean> | Yes| Callback used to receive cached GNSS locations.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -531,7 +608,7 @@ For details about the following error codes, see [Location Error Codes](../error off(type: 'cachedGnssLocationsChange', callback?: Callback<Array<Location>>): void; -Unregisters the listener for cached GNSS location reports. +Unsubscribes from cached GNSS location reports. **Permission required**: ohos.permission.APPROXIMATELY_LOCATION @@ -546,7 +623,7 @@ Unregisters the listener for cached GNSS location reports. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -575,7 +652,7 @@ For details about the following error codes, see [Location Error Codes](../error on(type: 'satelliteStatusChange', callback: Callback<SatelliteStatusInfo>): void; -Registers a listener for GNSS satellite status change events. +Subscribes to GNSS satellite status change events. **Permission required**: ohos.permission.APPROXIMATELY_LOCATION @@ -585,12 +662,12 @@ Registers a listener for GNSS satellite status change events. | 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.| + | type | string | Yes| Event type. The value **satelliteStatusChange** indicates a GNSS satellite status change.| + | callback | Callback<[SatelliteStatusInfo](#satellitestatusinfo)> | Yes| Callback used to receive GNSS satellite status change events.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -617,7 +694,7 @@ For details about the following error codes, see [Location Error Codes](../error off(type: 'satelliteStatusChange', callback?: Callback<SatelliteStatusInfo>): void; -Unregisters the listener for GNSS satellite status change events. +Unsubscribes from GNSS satellite status change events. **Permission required**: ohos.permission.APPROXIMATELY_LOCATION @@ -627,12 +704,12 @@ Unregisters the listener for GNSS satellite status change events. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value **satelliteStatusChange** indicates a GNSS satellite status change event.| + | type | string | Yes| Event type. The value **satelliteStatusChange** indicates a GNSS satellite status change.| | callback | Callback<[SatelliteStatusInfo](#satellitestatusinfo)> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -660,7 +737,7 @@ For details about the following error codes, see [Location Error Codes](../error on(type: 'nmeaMessage', callback: Callback<string>): void; -Registers a listener for GNSS NMEA message change events. +Subscribes to GNSS NMEA message change events. **Required permissions**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION @@ -670,12 +747,12 @@ Registers a listener for GNSS NMEA message change events. | 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.| + | type | string | Yes| Event type. The value **nmeaMessage** indicates a GNSS NMEA message change.| + | callback | Callback<string> | Yes| Callback used to receive GNSS NMEA message change events.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -703,7 +780,7 @@ For details about the following error codes, see [Location Error Codes](../error off(type: 'nmeaMessage', callback?: Callback<string>): void; -Unregisters the listener for GNSS NMEA message change events. +Unsubscribes from GNSS NMEA message change events. **Required permissions**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION @@ -713,12 +790,12 @@ Unregisters the listener for GNSS NMEA message change events. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value **nmeaMessage** indicates a GNSS NMEA message change event.| + | type | string | Yes| Event type. The value **nmeaMessage** indicates a GNSS NMEA message change.| | callback | Callback<string> | No| Callback to unregister. If this parameter is not specified, all callbacks of the specified event type are unregistered.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -747,7 +824,7 @@ For details about the following error codes, see [Location Error Codes](../error on(type: 'gnssFenceStatusChange', request: GeofenceRequest, want: WantAgent): void; -Registers a listener for status change events of the specified geofence. +Subscribes to status change events of the specified geofence. **Permission required**: ohos.permission.APPROXIMATELY_LOCATION @@ -757,13 +834,13 @@ Registers a listener for status change events of the specified geofence. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value **gnssFenceStatusChange** indicates a geofence status change event.| + | type | string | Yes| Event type. The value **gnssFenceStatusChange** indicates a geofence status change.| | request | [GeofenceRequest](#geofencerequest) | Yes| Geofencing request.| - | want | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes| **WantAgent** used to return geofence (entrance or exit) events.| + | want | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes| **WantAgent** used to receive geofence (entrance or exit) events.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -805,7 +882,7 @@ For details about the following error codes, see [Location Error Codes](../error off(type: 'gnssFenceStatusChange', request: GeofenceRequest, want: WantAgent): void; -Unregisters the listener for status change events of the specified geofence. +Unsubscribes from status change events of the specified geofence. **Permission required**: ohos.permission.APPROXIMATELY_LOCATION @@ -815,13 +892,13 @@ Unregisters the listener for status change events of the specified geofence. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value **gnssFenceStatusChange** indicates a geofence status change event.| + | type | string | Yes| Event type. The value **gnssFenceStatusChange** indicates a geofence status change.| | request | [GeofenceRequest](#geofencerequest) | Yes| Geofencing request.| - | want | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes| **WantAgent** used to return geofence (entrance or exit) events.| + | want | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes| **WantAgent** used to receive geofence (entrance or exit) events.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -864,7 +941,7 @@ For details about the following error codes, see [Location Error Codes](../error on(type: 'countryCodeChange', callback: Callback<CountryCode>): void; -Registers a listener for country code change events. +Subscribes to country code change events. **System capability**: SystemCapability.Location.Location.Core @@ -872,12 +949,12 @@ Registers a listener for country code change events. | 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.| + | type | string | Yes| Event type. The value **countryCodeChange** indicates a country code change.| + | callback | Callback<[CountryCode](#countrycode)> | Yes| Callback used to receive country code change events.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -905,7 +982,7 @@ For details about the following error codes, see [Location Error Codes](../error off(type: 'countryCodeChange', callback?: Callback<CountryCode>): void; -Unregisters the listener for country code change events. +Unsubscribes from country code change events. **System capability**: SystemCapability.Location.Location.Core @@ -913,12 +990,12 @@ Unregisters the listener for country code change events. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value **countryCodeChange** indicates a country code change event.| + | type | string | Yes| Event type. The value **countryCodeChange** indicates a country code change.| | 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 [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -942,6 +1019,89 @@ For details about the following error codes, see [Location Error Codes](../error ``` +## geoLocationManager.on('locatingRequiredDataChange')10+ + +on(type: 'locatingRequiredDataChange', config: LocatingRequiredDataConfig, callback: Callback<Array<LocatingRequiredData>>): void; + +Subscribes to changes in the required data of the location service, including Wi-Fi and Bluetooth scanning information. An application can then determine whether to enable Wi-Fi and Bluetooth scanning based on the return result. + +**Required permissions**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Core + +**System API**: This is a system API. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value **locatingRequiredDataChange** indicates a change in the required data of the location service.| + | config | [LocatingRequiredDataConfig](#locatingrequireddataconfig10) | Yes| Configuration for obtaining the required data of the location service.| + | callback | Callback<Array<[LocatingRequiredData](#locatingrequireddata10)>> | Yes| Callback used to receive the required data of the location service.| + +**Error codes** + +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). + +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301800 | Failed to start WiFi or Bluetooth scanning. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + let callback = (code) => { + console.log('locatingRequiredDataChange: ' + JSON.stringify(code)); + } + let config = {'type': 1, 'needStartScan': true, 'scanInterval': 10000}; + try { + geoLocationManager.on('locatingRequiredDataChange', config, callback); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + + +## geoLocationManager.off('locatingRequiredDataChange')10+ + +off(type: 'locatingRequiredDataChange', callback?: Callback<Array<LocatingRequiredData>>): void; + +Unsubscribes from changes in the required data of the location service and stops Wi-Fi and Bluetooth scanning. + +**Required permissions**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Core + +**System API**: This is a system API. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value **locatingRequiredDataChange** indicates a change in the required data of the location service.| + | callback | Callback<Array<[LocatingRequiredData](#locatingrequireddata10)>> | 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 error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + let callback = (code) => { + console.log('locatingRequiredDataChange: ' + JSON.stringify(code)); + } + let config = {'type': 1, 'needStartScan': true, 'scanInterval': 10000}; + try { + geoLocationManager.on('locatingRequiredDataChange', config, callback); + geoLocationManager.off('locatingRequiredDataChange', callback); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` + ## geoLocationManager.getCurrentLocation @@ -958,11 +1118,11 @@ Obtains the current location. This API uses an asynchronous callback to return t | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | request | [CurrentLocationRequest](#currentlocationrequest) | Yes| Location request.| - | callback | AsyncCallback<[Location](#location)> | Yes| Callback used to return the current location.| + | callback | AsyncCallback<[Location](#location)> | Yes| Callback used to receive the current location.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -974,7 +1134,7 @@ For details about the following error codes, see [Location Error Codes](../error ```ts import geoLocationManager from '@ohos.geoLocationManager'; - let requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0}; + let requestInfo = {'priority': geoLocationManager.LocationRequestPriority.FIRST_FIX, 'scenario': geoLocationManager.LocationRequestScenario.UNSET,'maxAccuracy': 0}; let locationChange = (err, location) => { if (err) { console.log('locationChanger: err=' + JSON.stringify(err)); @@ -1005,11 +1165,11 @@ Obtains the current location. This API uses an asynchronous callback to return t | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[Location](#location)> | Yes| Callback used to return the current location.| + | callback | AsyncCallback<[Location](#location)> | Yes| Callback used to receive the current location.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1061,7 +1221,7 @@ Obtains the current location. This API uses a promise to return the result. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1073,7 +1233,7 @@ For details about the following error codes, see [Location Error Codes](../error ```ts import geoLocationManager from '@ohos.geoLocationManager'; - let requestInfo = {'priority': 0x203, 'scenario': 0x300,'maxAccuracy': 0}; + let requestInfo = {'priority': geoLocationManager.LocationRequestPriority.FIRST_FIX, 'scenario': geoLocationManager.LocationRequestScenario.UNSET,'maxAccuracy': 0}; try { geoLocationManager.getCurrentLocation(requestInfo).then((result) => { console.log('current location: ' + JSON.stringify(result)); @@ -1105,7 +1265,7 @@ Obtains the last location. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1141,7 +1301,7 @@ Checks whether the location service is enabled. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1165,7 +1325,7 @@ 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. +**System API**: This is a system API. **Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS @@ -1175,11 +1335,11 @@ Enables the location service. This API uses an asynchronous callback to return t | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<void> | Yes| Callback used to return the error message.| + | callback | AsyncCallback<void> | Yes| Callback used to receive the error message.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1207,7 +1367,7 @@ 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. +**System API**: This is a system API. **Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS @@ -1221,7 +1381,7 @@ Enables the location service. This API uses a promise to return the result. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1249,7 +1409,7 @@ disableLocation(): void; Disables the location service. -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS @@ -1257,7 +1417,7 @@ Disables the location service. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1275,7 +1435,6 @@ For details about the following error codes, see [Location Error Codes](../error ``` - ## geoLocationManager.getAddressesFromLocation getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>): void @@ -1289,11 +1448,11 @@ Converts coordinates into geographic description through reverse geocoding. This | 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.| + | callback | AsyncCallback<Array<[GeoAddress](#geoaddress)>> | Yes| Callback used to receive the reverse geocoding result.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1342,7 +1501,7 @@ Converts coordinates into geographic description through reverse geocoding. This **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1380,11 +1539,11 @@ Converts geographic description into coordinates through geocoding. This API use | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | request | [GeoCodeRequest](#geocoderequest) | Yes| Geocoding request.| - | callback | AsyncCallback<Array<[GeoAddress](#geoaddress)>> | Yes| Callback used to return the geocoding result.| + | callback | AsyncCallback<Array<[GeoAddress](#geoaddress)>> | Yes| Callback used to receive the geocoding result.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1433,7 +1592,7 @@ Converts geographic description into coordinates through geocoding. This API use **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1473,7 +1632,7 @@ Obtains the (reverse) geocoding service status. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1505,11 +1664,11 @@ Obtains the number of cached GNSS locations. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<number> | Yes| Callback used to return the number of cached GNSS locations. | + | callback | AsyncCallback<number> | Yes| Callback used to receive the number of cached GNSS locations. | **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1553,7 +1712,7 @@ Obtains the number of cached GNSS locations. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1591,11 +1750,11 @@ Obtains all cached GNSS locations and clears the GNSS cache queue. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<void> | Yes| Callback used to return the error message.| + | callback | AsyncCallback<void> | Yes| Callback used to receive the error message.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1633,11 +1792,11 @@ Obtains all cached GNSS locations and clears the GNSS cache queue. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | Promise<void> | void | NA | Promise used to return the error code.| + | Promise<void> | void | NA | Promise used to receive the error code.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1675,11 +1834,11 @@ Sends an extended command to the location subsystem. | 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.| + | callback | AsyncCallback<void> | Yes| Callback used to receive the error code.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1720,11 +1879,11 @@ Sends an extended command to the location subsystem. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | Promise<void> | void | NA | Promise used to return the error code.| + | Promise<void> | void | NA | Promise used to receive the error code.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1760,11 +1919,11 @@ Obtains the current country code. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<[CountryCode](#countrycode)> | Yes| Callback used to return the country code.| + | callback | AsyncCallback<[CountryCode](#countrycode)> | Yes| Callback used to receive the country code.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1802,11 +1961,11 @@ Obtains the current country code. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | Promise<[CountryCode](#countrycode)> | [CountryCode](#countrycode) | NA | Promise used to return the country code.| + | Promise<[CountryCode](#countrycode)> | [CountryCode](#countrycode) | NA | Promise used to receive the country code.| **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1839,11 +1998,11 @@ 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. +**System API**: This is a system API. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1870,11 +2029,11 @@ 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. +**System API**: This is a system API. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1903,7 +2062,7 @@ This API can be invoked only after [geoLocationManager.enableLocationMock](#geol **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Parameters** @@ -1913,7 +2072,7 @@ This API can be invoked only after [geoLocationManager.enableLocationMock](#geol **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1949,11 +2108,11 @@ 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. +**System API**: This is a system API. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -1979,11 +2138,11 @@ Disables the mock geocoding function. **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -2011,7 +2170,7 @@ This API can be invoked only after [geoLocationManager.enableReverseGeocodingMoc **System capability**: SystemCapability.Location.Location.Core -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Parameters** @@ -2021,7 +2180,7 @@ This API can be invoked only after [geoLocationManager.enableReverseGeocodingMoc **Error codes** -For details about the following error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -2053,7 +2212,7 @@ isLocationPrivacyConfirmed(type: LocationPrivacyType): boolean; 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 API**: This is a system API. **System capability**: SystemCapability.Location.Location.Core @@ -2067,11 +2226,11 @@ Checks whether a user agrees with the privacy statement of the location service. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | boolean | boolean | NA | Callback used to return the result, which indicates whether the user agrees with the privacy statement.| + | boolean | boolean | NA | 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). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -2095,7 +2254,7 @@ setLocationPrivacyConfirmStatus(type: LocationPrivacyType, isConfirmed: boolean) 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. +**System API**: This is a system API. **Required permissions**: ohos.permission.MANAGE_SECURE_SETTINGS @@ -2106,11 +2265,11 @@ Sets the user confirmation status for the privacy statement of the location serv | 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.| + | isConfirmed | boolean | Yes| 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). +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). | ID| Error Message| | -------- | ---------------------------------------- | @@ -2126,3 +2285,53 @@ For details about the following error codes, see [Location Error Codes](../error console.error("errCode:" + err.code + ",errMessage:" + err.message); } ``` + + +## geoLocationManager.getLocatingRequiredData10+ + +getLocatingRequiredData(config: LocatingRequiredDataConfig): Promise<Array<LocatingRequiredData>>; + +Obtains the required data of the location service. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION + +**System capability**: SystemCapability.Location.Location.Core + +**System API**: This is a system API. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [LocatingRequiredDataConfig](#locatingrequireddataconfig10) | Yes| Configuration for obtaining the required data of the location service.| + +**Return value** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | Promise<Array<[LocatingRequiredData](#locatingrequireddata10)>> | [LocatingRequiredData](#locatingrequireddata10) | NA | Callback used to receive the required data of the location service, such as the Wi-Fi and Bluetooth scanning information.| + +**Error codes** + +For details about the error codes, see [Location Error Codes](../errorcodes/errorcode-geoLocationManager.md). + +| ID| Error Message| +| -------- | ---------------------------------------- | +|3301800 | Failed to start WiFi or Bluetooth scanning. | + +**Example** + + ```ts + import geoLocationManager from '@ohos.geoLocationManager'; + let config = {'type': 1, 'needStartScan': true, 'scanInterval': 10000}; + try { + geoLocationManager.getLocatingRequiredData(config).then((result) => { + console.log('getLocatingRequiredData return: ' + JSON.stringify(result)); + }) + .catch((error) => { + console.log('promise, getLocatingRequiredData: error=' + JSON.stringify(error)); + }); + } catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-net-policy.md b/en/application-dev/reference/apis/js-apis-net-policy.md index 295332057ba4042e12ff1c0009efe8a54acec759..1c1bb3adecc5c67136b722cbc9de1eacdf87f462 100644 --- a/en/application-dev/reference/apis/js-apis-net-policy.md +++ b/en/application-dev/reference/apis/js-apis-net-policy.md @@ -89,9 +89,11 @@ Specifies whether background applications are allowed to access the network. Thi **Example** ```js -policy.setBackgroundAllowed(true).then(function (error) { - console.log(JSON.stringify(error)) -}) +policy.setBackgroundAllowed(true).then(() => { + console.log("setBackgroundAllowed success"); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.isBackgroundAllowed10+ @@ -164,10 +166,11 @@ Checks whether the current application is allowed to access the network when run **Example** ```js -policy.isBackgroundAllowed().then(function (error, data) { - console.log(JSON.stringify(error)) - console.log(JSON.stringify(data)) -}) +policy.isBackgroundAllowed().then((data) => { + console.log(JSON.stringify(data)); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.setPolicyByUid10+ @@ -248,9 +251,11 @@ Sets the metered network access policy for the application specified by a given **Example** ```js -policy.setPolicyByUid(11111, policy.NetUidPolicy.NET_POLICY_NONE).then(function (error) { - console.log(JSON.stringify(error)) -}) +policy.setPolicyByUid(11111, policy.NetUidPolicy.NET_POLICY_NONE).then(() => { + console.log("setPolicyByUid success"); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.getPolicyByUid10+ @@ -329,10 +334,11 @@ Obtains the network access policy for the application specified by a given UID. **Example** ```js -policy.getPolicyByUid(11111).then(function (error, data) { - console.log(JSON.stringify(error)) - console.log(JSON.stringify(data)) -}) +policy.getPolicyByUid(11111).then((data) => { + console.log(JSON.stringify(data)); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.getUidsByPolicy10+ @@ -412,10 +418,11 @@ Obtains all UIDs that match the specified network policy. This API uses a promis **Example** ```js -policy.getUidsByPolicy(11111).then(function (error, data) { - console.log(JSON.stringify(error)) - console.log(JSON.stringify(data)) -}) +policy.getUidsByPolicy(11111).then((data) => { + console.log(JSON.stringify(data)); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.getNetQuotaPolicies10+ @@ -487,11 +494,11 @@ Obtains the network quota policies. This API uses a promise to return the result **Example** ```js -policy.getNetQuotaPolicies().then(function (error, data) { - console.log(JSON.stringify(error)) - console.log(JSON.stringify(data)) -}) - +policy.getNetQuotaPolicies().then((data) => { + console.log(JSON.stringify(data)); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.setNetQuotaPolicies10+ @@ -608,9 +615,11 @@ let netquotapolicy = { netQuotaPolicyList.push(netquotapolicy); -policy.setNetQuotaPolicies(netQuotaPolicyList).then(function (error) { - console.log(JSON.stringify(error)) -}) +policy.setNetQuotaPolicies(netQuotaPolicyList).then(() => { + console.log("setNetQuotaPolicies success"); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.isUidNetAllowed10+ @@ -692,10 +701,11 @@ Checks whether the application specified by a given UID is allowed to access a m **Example** ```js -policy.isUidNetAllowed(11111, true).then(function (error, data) { - console.log(JSON.stringify(error)) - console.log(JSON.stringify(data)) -}) +policy.isUidNetAllowed(11111, true).then((data) => { + console.log(JSON.stringify(data)); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.isUidNetAllowed10+ @@ -777,10 +787,11 @@ Checks whether the application specified by a given UID is allowed to access the **Example** ```js -policy.isUidNetAllowed(11111, 'wlan0').then(function (error, data) { - console.log(JSON.stringify(error)) - console.log(JSON.stringify(data)) -}) +policy.isUidNetAllowed(11111, 'wlan0').then((data) => { + console.log(JSON.stringify(data)); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.setDeviceIdleTrustlist10+ @@ -861,9 +872,11 @@ Adds applications specified by given UIDs to the device idle allowlist. This API **Example** ```js -policy.setDeviceIdleTrustlist([11111,22222], true).then(function (error) { - console.log(JSON.stringify(error)) -}) +policy.setDeviceIdleTrustlist([11111,22222], true).then(() => { + console.log("setDeviceIdleTrustlist success"); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.getDeviceIdleTrustlist10+ @@ -934,10 +947,11 @@ Obtains the UIDs of applications that are on the device idle allowlist. This API **Example** ```js -policy.getDeviceIdleTrustlist().then(function (error, data) { - console.log(JSON.stringify(error)) - console.log(JSON.stringify(data)) -}) +policy.getDeviceIdleTrustlist().then((data) => { + console.log(JSON.stringify(data)); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.getBackgroundPolicyByUid10+ @@ -1017,10 +1031,11 @@ Obtains the background network policy for the application specified by a given U **Example** ```js -policy.getBackgroundPolicyByUid(11111).then(function (error, data) { - console.log(JSON.stringify(error)) - console.log(JSON.stringify(data)) -}) +policy.getBackgroundPolicyByUid(11111).then((data) => { + console.log(JSON.stringify(data)); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.resetPolicies10+ @@ -1099,9 +1114,11 @@ Restores all the policies (cellular network, background network, firewall, and a **Example** ```js -policy.resetPolicies('1').then(function (error) { - console.log(JSON.stringify(error)) -}) +policy.resetPolicies('1').then(() => { + console.log("resetPolicies success"); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.updateRemindPolicy10+ @@ -1186,9 +1203,11 @@ Updates a reminder policy. This API uses a promise to return the result. ```js import connection from '@ohos.net.connection'; -policy.updateRemindPolicy(connection.NetBearType.BEARER_CELLULAR, '1', policy.RemindType.REMIND_TYPE_WARNING).then(function (error) { - console.log(JSON.stringify(error)) -}) +policy.updateRemindPolicy(connection.NetBearType.BEARER_CELLULAR, '1', policy.RemindType.REMIND_TYPE_WARNING).then(() => { + console.log("updateRemindPolicy success"); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.setPowerSaveTrustlist10+ @@ -1269,9 +1288,11 @@ Sets whether to add the application specified by a given UID to the power-saving **Example** ```js -policy.setPowerSaveTrustlist([11111,22222], true).then(function (error) { - console.log(JSON.stringify(error)) -}) +policy.setPowerSaveTrustlist([11111,22222], true).then(() => { + console.log("setPowerSaveTrustlist success"); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.getPowerSaveTrustlist10+ @@ -1343,10 +1364,11 @@ Obtains the UID array of applications that are on the device idle allowlist. Thi **Example** ```js -policy.getPowerSaveTrustlist().then(function (error, data) { - console.log(JSON.stringify(error)) - console.log(JSON.stringify(data)) -}) +policy.getPowerSaveTrustlist().then((data) => { + console.log(JSON.stringify(data)); +}).catch(error => { + console.log(JSON.stringify(error)); +}); ``` ## policy.on diff --git a/en/application-dev/reference/apis/js-apis-net-vpn.md b/en/application-dev/reference/apis/js-apis-net-vpn.md new file mode 100644 index 0000000000000000000000000000000000000000..9fbca9235ee22b561d8ed5f414ac37be7454767f --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-net-vpn.md @@ -0,0 +1,406 @@ +# @ohos.net.vpn (VPN Management) + +The **vpn** module implements virtual private network (VPN) management, such as starting and stopping a VPN. + +> **NOTE** +> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```js +import vpn from '@ohos.net.vpn'; +``` + +## vpn.createVpnConnection + +createVpnConnection(context: AbilityContext): VpnConnection + +Creates a VPN connection. + +**System capability**: SystemCapability.Communication.NetManager.Vpn + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| context | [AbilityContext](js-apis-inner-application-uiAbilityContext.md#uiabilitycontext) | Yes | Specified context. | + +**Return value** + +| Type | Description | +| :--------------------------------- | :---------------------- | +| [VpnConnection](#vpnconnection) | VPN connection object.| + +**Error codes** + +For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md). + +| ID| Error Message | +| ------- | ----------------------------- | +| 401 | Parameter error. | + +**Example** +Stage model: + +```ts +// Obtain the context. +import UIAbility from '@ohos.app.ability.UIAbility'; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + globalThis.context = this.context; + } +} +let context = globalThis.context; +VpnConnection = vpn.createVpnConnection(context); +console.info("vpn onInit: " + JSON.stringify(VpnConnection)); +``` + +## VpnConnection + +Defines a VPN connection object. Before calling **VpnConnection** APIs, you need to create a VPN connection object by calling [vpn.createVpnConnection](#vpncreatevpnconnection). + +### setUp + +setUp(config: VpnConfig, callback: AsyncCallback\): void + +Creates a VPN based on the specified configuration. This API uses an asynchronous callback to return the result. + +**System API**: This is a system API. + +**Required permissions**: ohos.permission.MANAGE_VPN + +**System capability**: SystemCapability.Communication.NetManager.Vpn + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| config | [VpnConfig](#vpnconfig) | Yes | VPN configuration. | +| callback | AsyncCallback\ | Yes | Callback used to return the result. If a VPN is created successfully, **error** is **undefined** and **data** is the file descriptor of the vNIC. Otherwise, **error** is an error object.| + +**Error codes** + +For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md). + +| ID| Error Message | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200001 | Invalid parameter value. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2200003 | System internal error. | +| 2203001 | VPN creation denied, please check the user type. | +| 2203002 | VPN exist already, please execute destroy first. | + +**Example** + +```js + let config = { + addresses: [{ + address: { + address: "10.0.0.5", + family: 1 + }, + prefixLength: 24, + }], + routes: [], + mtu: 1400, + dnsAddresses:[ + "114.114.114.114" + ], + trustedApplications:[], + blockedApplications:[] + } + VpnConnection.setUp(config, (error, data) => { + console.info(JSON.stringify(error)); + console.info("tunfd: " + JSON.stringify(data)); + }) +``` + +### setUp + +setUp(config: VpnConfig): Promise\ + +Creates a VPN based on the specified configuration. This API uses a promise to return the result. + +**System API**: This is a system API. + +**Required permissions**: ohos.permission.MANAGE_VPN + +**System capability**: SystemCapability.Communication.NetManager.Vpn + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| config | [VpnConfig](#vpnconfig) | Yes | VPN configuration. | + +**Return value** + +| Type | Description | +| --------------------------------- | ------------------------------------- | +| Promise\ | The obtaining result is returned in Promise format. The file descriptor fd of the specified virtual network adapter is returned.| + +**Error codes** + +For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md). + +| ID| Error Message | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200001 | Invalid parameter value. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2200003 | System internal error. | +| 2203001 | VPN creation denied, please check the user type. | +| 2203002 | VPN exist already, please execute destroy first. | + +**Example** + +```js + let config = { + addresses: [{ + address: { + address: "10.0.0.5", + family: 1 + }, + prefixLength: 24, + }], + routes: [], + mtu: 1400, + dnsAddresses:[ + "114.114.114.114" + ], + trustedApplications:[], + blockedApplications:[] + } + VpnConnection.setUp(config).then((data) => { + console.info(TAG + "setUp success, tunfd: " + JSON.stringify(data)) + }).catch(err => { + console.info(TAG + "setUp fail" + JSON.stringify(err)) + }) +``` + +### protect + +protect(socketFd: number, callback: AsyncCallback\): void + +Protects sockets against a VPN connection. The data sent through sockets is directly transmitted over the physical network and therefore the traffic does not traverse through the VPN. This API uses an asynchronous callback to return the result. + +**System API**: This is a system API. + +**Required permissions**: ohos.permission.MANAGE_VPN + +**System capability**: SystemCapability.Communication.NetManager.Vpn + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| socketFd | number | Yes | Socket file descriptor. It can be obtained through [getSocketFd](js-apis-socket.md#getsocketfd10). | +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, **error** is **undefined**. If the operation fails, an error message is returned.| + +**Error codes** + +For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md). + +| ID| Error Message | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200001 | Invalid parameter value. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2200003 | System internal error. | +| 2203004 | Invalid socket file descriptor. | + +**Example** + +```js + import socket from "@ohos.net.socket"; + var tcp = socket.constructTCPSocketInstance(); + tcp.bind({ + address: "0.0.0.0", + family: 1 + }) + let connectAddress = { + address: "192.168.1.11", + port: 8888, + family: 1 + }; + tcp.connect({ + address: connectAddress, timeout: 6000 + }) + tcp.getSocketFd().then((tunnelfd) => { + console.info("tunenlfd: " + tunnelfd); + VpnConnection.protect(tunnelfd, (error) => { + console.info(JSON.stringify(error)); + }) + }) +``` + +### protect + +protect(socketFd: number): Promise\ + +Protects sockets against a VPN connection. The data sent through sockets is directly transmitted over the physical network and therefore traffic does not traverse through the VPN. This API uses a promise to return the result. + +**System API**: This is a system API. + +**Required permissions**: ohos.permission.MANAGE_VPN + +**System capability**: SystemCapability.Communication.NetManager.Vpn + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| socketFd | number | Yes | Socket file descriptor. It can be obtained through [getSocketFd](js-apis-socket.md#getsocketfd10-1). | + +**Return value** + +| Type | Description | +| --------------------------------- | ------------------------------------- | +| Promise\ | Promise used to return the result. If the operation is successful, the operation result is returned. If the operation fails, an error message is returned.| + +**Error codes** + +For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md). + +| ID| Error Message | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200001 | Invalid parameter value. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2200003 | System internal error. | +| 2203004 | Invalid socket file descriptor. | + +**Example** + +```js + import socket from "@ohos.net.socket"; + var tcp = socket.constructTCPSocketInstance(); + tcp.bind({ + address: "0.0.0.0", + family: 1 + }) + let connectAddress = { + address: "192.168.1.11", + port: 8888, + family: 1 + }; + tcp.connect({ + address: connectAddress, timeout: 6000 + }) + tcp.getSocketFd().then((tunnelfd) => { + console.info("tunenlfd: " + tunnelfd); + VpnConnection.protect(tunnelfd).then(() => { + console.info("protect success.") + }).catch(err => { + console.info("protect fail" + JSON.stringify(err)) + }) + }) +``` + +### destroy + +destroy(callback: AsyncCallback\): void + +Destroys a VPN. This API uses an asynchronous callback to return the result. + +**System API**: This is a system API. + +**Required permissions**: ohos.permission.MANAGE_VPN + +**System capability**: SystemCapability.Communication.NetManager.Vpn + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, **error** is **undefined**. If the operation fails, an error message is returned.| + +**Error codes** + +For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md). + +| ID| Error Message | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 401 | Parameter error. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2200003 | System internal error. | + +**Example** + +```js + VpnConnection.destroy((error) => { + console.info(JSON.stringify(error)); + }) +``` + +### destroy + +destroy(): Promise\ + +Destroys a VPN. This API uses a promise to return the result. + +**System API**: This is a system API. + +**Required permissions**: ohos.permission.MANAGE_VPN + +**System capability**: SystemCapability.Communication.NetManager.Vpn + +**Return value** + +| Type | Description | +| --------------------------------- | ------------------------------------- | +| Promise\ | Promise used to return the result. If the operation is successful, the operation result is returned. If the operation fails, an error message is returned.| + +**Error codes** + +For details about the error codes, see [VPN Error Codes](../errorcodes/errorcode-net-vpn.md). + +| ID| Error Message | +| ------- | ----------------------------- | +| 201 | Permission denied. | +| 202 | Non-system applications use system APIs. | +| 2200002 | Operation failed. Cannot connect to service. | +| 2200003 | System internal error. | + +**Example** + +```js + VpnConnection.destroy().then(() => { + console.info("destroy success.") + }).catch(err => { + console.info("destroy fail" + JSON.stringify(err)) + }); +``` + +## VpnConfig + +Defines the VPN configuration. + +**System API**: This is a system API. + +**System capability**: SystemCapability.Communication.NetManager.Vpn + +| Name| Type| Mandatory| Description| +| ------- | ------ | -- |------------------------------ | +| addresses | Array\<[LinkAddress](js-apis-net-connection.md#linkaddress8)\> | Yes| IP address of the vNIC.| +| routes | Array\<[RouteInfo](js-apis-net-connection.md#routeinfo8)\> | No| Route information of the vNIC.| +| dnsAddresses | Array\ | No| IP address of the DNS server.| +| searchDomains | Array\ | No| List of DNS search domains.| +| mtu | number | No| Maximum transmission unit (MTU), in bytes.| +| isIPv4Accepted | boolean | No| Whether IPv4 is supported. The default value is **true**.| +| isIPv6Accepted | boolean | No| Whether IPv6 is supported. The default value is **false**.| +| isLegacy | boolean | No| Whether the built-in VPN is supported. The default value is **false**.| +| isBlocking | boolean | No| Whether the blocking mode is used. The default value is **false**.| +| trustedApplications | Array\ | No| List of trusted applications, which are represented by bundle names of the string type.| +| blockedApplications | Array\ | No| List of blocked applications, which are represented by bundle names of the string type.| diff --git a/en/application-dev/reference/errorcodes/errorcode-geoLocationManager.md b/en/application-dev/reference/errorcodes/errorcode-geoLocationManager.md index dc6a45cfa530873862570dfaa50eb0d00a3766cb..9ee64ae1ded01f042fde5ce24488183d54cf2668 100644 --- a/en/application-dev/reference/errorcodes/errorcode-geoLocationManager.md +++ b/en/application-dev/reference/errorcodes/errorcode-geoLocationManager.md @@ -6,7 +6,7 @@ ## 3301000 Location Service Unavailable -**Error Message** +**Error Information** Location service is unavailable. @@ -28,7 +28,7 @@ Stop calling the API. ## 3301100 Location Service Unavailable Because of Switch Toggled Off -**Error Message** +**Error Information** The location switch is off. @@ -44,15 +44,15 @@ The location service switch is toggled off, which makes basic functions such as Display a prompt asking for enabling the location service. -## 3301200 Failure to Obtain the Positioning Result +## 3301200 Failed to Obtain the Positioning Result -**Error Message** +**Error Information** Failed to obtain the geographical location. **Description** -This error code is reported when the location service fails, and no positioning result is obtained. +This error code is reported if the location service has failed, leading to a failure to obtain the positioning result. **Possible Causes** @@ -64,15 +64,15 @@ This error code is reported when the location service fails, and no positioning Initiate a positioning request again. -## 3301300 Reverse Geocoding Query Failure +## 3301300 Query Failed During Reverse Geocoding -**Error Message** +**Error Information** Reverse geocoding query failed. **Description** -This error code is reported for a reverse geocoding query failure. +This error code is reported if the query during reverse geocoding has failed. **Possible Causes** @@ -80,17 +80,17 @@ Network connection is poor, which makes the request fail to be sent from the dev **Solution** -Try the reverse geocoding query again. +Perform a query again. -## 3301400 Geocoding Query Failure +## 3301400 Query Failed During Geocoding -**Error Message** +**Error Information** Geocoding query failed. **Description** -This error code is reported for a geocoding query failure. +This error code is reported if the query during geocoding has failed. **Possible Causes** @@ -98,17 +98,17 @@ Network connection is poor, which makes the request fail to be sent from the dev **Solution** -Try the geocoding query again. +Perform a query again. -## 3301500 Area Information Query Failure +## 3301500 Area Information Query Failed -**Error Message** +**Error Information** Failed to query the area information. **Description** -This error code is reported for the failure to query the area information (including the country code). +This error code is reported if the query of the area information (including the country code) has failed. **Possible Causes** @@ -118,15 +118,15 @@ The correct area information is not found. Stop calling the API for querying the country code. -## 3301600 Geofence Operation Failure +## 3301600 Geofence Operation Failed -**Error Message** +**Error Information** Failed to operate the geofence. **Description** -This error code is reported when an operation (like adding, deleting, pausing, and resuming) fails to be performed on the geofence. +This error code is reported if a geofence operation, for example, adding, deleting, pausing, or resuming a geofence, has failed. **Possible Causes** @@ -140,13 +140,13 @@ Stop calling the geofence operation API. ## 3301700 No Response to the Request -**Error Message** +**Error Information** No response to the request. **Description** -This error code is reported when no response is received for an asynchronous request that requires a user to click a button for confirmation or requires a response from the GNSS chip or network server. +This error code is reported if no response is received for an asynchronous request that requires a user to click a button for confirmation or requires a response from the GNSS chip or network server. **Possible Causes** @@ -159,3 +159,25 @@ This error code is reported when no response is received for an asynchronous req **Solution** Stop calling relevant APIs. + +## 3301800 Failed to Start Wi-Fi or Bluetooth Scanning + +**Error Information** + +Failed to start WiFi or Bluetooth scanning. + +**Description** + +This error code is reported if Wi-Fi or Bluetooth scanning fails to start. + +**Possible Causes** + +1. The Wi-Fi or Bluetooth service incurs an internal error. + +2. Power consumption control is activated because of low battery level. + +3. Wi-Fi or Bluetooth is not enabled. + +**Solution** + +Turn off Wi-Fi or Bluetooth, and then turn it on again. diff --git a/en/application-dev/reference/errorcodes/errorcode-net-vpn.md b/en/application-dev/reference/errorcodes/errorcode-net-vpn.md new file mode 100644 index 0000000000000000000000000000000000000000..f8b7e31afaa81bcf033e31568f1f5678f38039ff --- /dev/null +++ b/en/application-dev/reference/errorcodes/errorcode-net-vpn.md @@ -0,0 +1,61 @@ +# VPN Error Codes + +> **NOTE** +> +> This topic describes only module-specific error codes. For details about universal error codes, see [Universal Error Codes](errorcode-universal.md). + +## 2203001 Failed to Create a VPN + +**Error Information** + +VPN creation denied, please check the user type. + +**Description** + +This error code is reported if a VPN fails to be created. + +**Possible Causes** + +The login user does not have the operation permission. Specifically, the GUEST user does not have the permission to call the **setUp** API. + +**Solution** + +Check the type of the login user. + + +## 2203002 VPN Already Exists + +**Error Information** + +VPN exist already, please execute destroy first. + +**Description** + +This error code is reported if a VPN already exists. + +**Possible Causes** + +The VPN has been created. + +**Solution** + +Call the **destroy** API to destroy the existing VPN, and then call the **setUp** API. + + +## 2203004 Invalid Descriptor + +**Error Information** + +Invalid socket file descriptor. + +**Description** + +This error code is reported if the socket file descriptor is invalid. + +**Possible Causes** + +A TCP socket connection fails to be established. + +**Solution** + +Check whether a TCP socket connection is set up successfully.