目录

netHandover (Network Handover)

This module provides network handover capabilities. When the network signal is weak and the device initiates a network handover (such as between Wi-Fi and cellular network or between primary and secondary SIM cards), the device will notify your app upon the start and end of the handover. Then your app can re-establish the link accordingly and swiftly restore services, providing users with a smooth, fast, and low-latency network experience.

Since: 5.0.0(12)

Modules to Import

import { netHandover } from '@kit.NetworkBoostKit';

netHandover.on('handoverChange')

on(type: 'handoverChange', callback: Callback<HandoverInfo>): void

Subscribes to network handover information.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.GET_NETWORK_INFO

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The value is always handoverChange, indicating network handover events.
callback Callback<HandoverInfo> Yes Callback used to return the details about the start and end of a network handover.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

ID Error Message
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  netHandover.on('handoverChange', (info: netHandover.HandoverInfo) => {
    if (info.handoverStart) {
      // Callback for the start of network handover. Adjust the data transmission policy based on the suggestion in HandoverStart.
      console.info('handover start');
    } else if (info.handoverComplete) {
      // Callback for the end of network handover. Adjust the network speed and re-establish the link based on the suggestion in HandoverComplete.
      console.info('handover complete');
    }
  });
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

netHandover.off('handoverChange')

off(type: 'handoverChange', callback?: Callback<HandoverInfo>): void

Unsubscribes from network handover information.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.GET_NETWORK_INFO

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The value is always handoverChange, indicating network handover events.
callback Callback<HandoverInfo> No Callback to be unregistered, which must be the same as that passed upon subscription. If this parameter is not passed, all callbacks will be unregistered.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

ID Error Message
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  netHandover.off('handoverChange');
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

netHandover.setHandoverMode

setHandoverMode(mode: HandoverMode): void

Defines the network handover mode. Your app can call the relevant API to change the network handover mode between delegation mode and proactive mode. The default mode is delegation. If the setting fails, the API will throw an exception.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.GET_NETWORK_INFO

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
mode HandoverMode Yes Network handover mode that the app needs to notify the device of.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

ID Error Message
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  // Set the mode to proactive mode, making the app to initiate handovers by itself.
  let mode: netHandover.HandoverMode = netHandover.HandoverMode.DISCRETION;
  netHandover.setHandoverMode(mode);
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

netHandover.getMultiPathQuotaStats

getMultiPathQuotaStats(): MultiPathQuota

Obtains the quota information of multi-network concurrency, including the used and remaining quotas.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.LINKTURBO

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Returns

Type Description
MultiPathQuota Multi-network concurrency quota information of an app.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
201 Permission denied.
1013600001 Internal error.
1013600002 System service error.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  let multiquota : netHandover.MultiPathQuota = netHandover.getMultiPathQuotaStats();
  console.info('getMultiPathQuotaStats multiPathQuota.used.count is:' + multiquota.used.count)
  console.info('getMultiPathQuotaStats multiPathQuota.used.duration is:' + multiquota.used.duration)
  console.info('getMultiPathQuotaStats multiPathQuota.remaining.count is:' + multiquota.remaining.count)
  console.info('getMultiPathQuotaStats multiPathQuota.remaining.duration is:' + multiquota.remaining.duration)
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

netHandover.requestMultiPath

requestMultiPath(callback: Callback<MultiPathRequestResult>): void

Initiates a multi-network concurrency request.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.LINKTURBO

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Parameters

Parameter Type Mandatory Description
callback Callback<MultiPathRequestResult> Yes Callback used to return the multi-network concurrency initiation result.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
201 Permission denied.
1013600001 Internal error.
1013600002 System service error.
1013620000 Multi-path capability is disabled.
1013620001 Multi-path links are already active or in the process of being established.
1013620002 App request limit reached.
1013620003 Request denied due to power consumption restrictions.
1013620004 No quota.
1013620005 Conflict.
1013620006 Requests are too frequent.
1013620007 No suitable path.
1013620008 Insufficient traffic.
1013620009 Concurrency is not allowed.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  netHandover.requestMultiPath((data: netHandover.MultiPathRequestResult) => {
   console.info(` requestMultiPath result:` + JSON.stringify(data));
  });
 } catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

netHandover.releaseMultiPath

releaseMultiPath(): void

Releases multi-network concurrency.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.LINKTURBO

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
201 Permission denied.
1013600001 Internal error.
1013600002 System service error.
1013620100 Release request mismatch.
1013620101 Multi-path not activated.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  netHandover.releaseMultiPath();
 } catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

netHandover.on('multiPathStateChange')

on(type: 'multiPathStateChange', callback: Callback<MultiPathStateInfo>): void

Subscribes to the multi-network concurrency status change events.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.LINKTURBO

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The value is always multiPathStateChange, indicating multi-network concurrency status change events.
callback Callback<MultiPathStateInfo> Yes Callback used to return multi-network concurrency status change information.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
201 Permission denied.
1013600001 Internal error.
1013600002 System service error.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  netHandover.on('multiPathStateChange', (data: netHandover.MultiPathStateInfo) => {
    // Callback information processing.
    console.info('on multiPathStateChange multiPathState:', data.multiPathState);
    console.info('on multiPathStateChange cause:', data.cause);
    console.info('on multiPathStateChange netHandle:', data.netHandle.netId);
    console.info('on multiPathStateChange pathState:', data.pathState);
    console.info('on multiPathStateChange pathType:', data.pathType);
  });
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

netHandover.off('multiPathStateChange')

off(type: 'multiPathStateChange', callback?: Callback<MultiPathStateInfo>): void

Unsubscribes from multi-network concurrency status change events.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.LINKTURBO

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The value is always multiPathStateChange, indicating multi-network concurrency status change events.
callback Callback<MultiPathStateInfo> No Callback to be unregistered, which must be the same as that passed upon subscription. If this parameter is not passed, all callbacks will be unregistered.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
201 Permission denied.
1013600001 Internal error.
1013600002 System service error.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  netHandover.off('multiPathStateChange');
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

netHandover.on('multiPathRecommendation')

on(type: 'multiPathRecommendation', callback: Callback<MultiPathRecommendationInfo>): void

Subscribes to changes on multi-network suggestions provided by the device.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.LINKTURBO

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The value is always multiPathRecommendation, indicating multi-network suggestion change events.
callback Callback<MultiPathRecommendationInfo> Yes Callback used to return multi-network suggestion change information.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
201 Permission denied.
1013600001 Internal error.
1013600002 System service error.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  netHandover.on('multiPathRecommendation', (data: netHandover.MultiPathRecommendationInfo) => {
    // Callback information processing.
    console.info("on multiPathRecommendation: " + JSON.stringify(data));
  });
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

netHandover.off('multiPathRecommendation')

off(type: 'multiPathRecommendation', callback?: Callback<MultiPathRecommendationInfo>): void

Unsubscribes from changes on multi-network concurrency suggestions provided by the device.

Model restriction: This API can be used only in the stage model.

Required permission: ohos.permission.LINKTURBO

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Parameters

Parameter Type Mandatory Description
type string Yes Event type. The value is always multiPathRecommendation, indicating multi-network suggestion change events.
callback Callback<MultiPathRecommendationInfo> No Callback to be unregistered, which must be the same as that passed upon subscription. If this parameter is not passed, all callbacks will be unregistered.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes and Universal Error Codes.

ID Error Message
201 Permission denied.
1013600001 Internal error.
1013600002 System service error.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { netHandover } from '@kit.NetworkBoostKit';
try {
  netHandover.off('multiPathRecommendation');
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

HandoverInfo

Defines the network handover information that is returned.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Name Type Read-Only Optional Description
handoverStart HandoverStart Yes Yes Information indicating that network handover starts.
handoverComplete HandoverComplete Yes Yes Information indicating that network handover ends.

HandoverStart

Defines the information about the start of network handover.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Name Type Read-Only Optional Description
expires number No No Timeout interval of the entire network handover process, in seconds. The value can be any positive integer or 0.
dataSpeedAction DataSpeedAction No No Recommended packet transmission rate for the link before handover.

HandoverComplete

Defines the information about the end of network handover.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Name Type Read-Only Optional Description
result ErrorResult No No Network handover result.
handoverContinue boolean No No

Indicates whether there will be a subsequent HandoverComplete message. The options are as follows:

true: There will be more links to be activated and a subsequent HandoverComplete message will be sent when multiple target networks exist.

false: This is already the last HandoverComplete message and the handover process ends.
oldPathLifetime number No No Remaining lifetime of the old link, in seconds. The value can be any positive integer or 0.
oldDataSpeedAction DataSpeedAction No No Recommended packet transmission rate for the link before handover.
pathTypeChanged boolean No No Indicates whether the types of the old and new links are different. The value true indicates yes (for example, from Wi-Fi to cellular network), and false indicates no.
newNetHandle connection.NetHandle No Yes If the network handover succeeds, newNetHandle contains the network handle information of the new link. If the network handover fails, this field is not returned. In this case, there is no new link, and the value of netdId in NetHandle of the new link is 0.
reEstAction ReEstAction No No Link re-establishment type.
newDataSpeedAction DataSpeedAction No No Recommended packet transmission rate for the link after handover.

DataSpeedAction

Defines the recommended packet transmission rate.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Name Type Read-Only Optional Description
dataSpeedSimpleAction netQuality.DataSpeedSimpleAction No No Simple suggested packet transmission policy.
linkUpBandwidth netQuality.RateBps No No Uplink bandwidth of the link before handover.
linkDownBandwidth netQuality.RateBps No No Downlink bandwidth of the link before handover.

MultiPathStateInfo

Defines multi-network concurrency status information.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Type Read-Only Optional Description
multiPathState MultiPathState No No Multi-network concurrency status.
cause MultiPathChangeCause No No Reason for a multi-network concurrency status change.
netHandle connection.NetHandle No No Network handle of the multi-network concurrency.
pathState PathState No No Status of the data path other than the default path in multi-network concurrency.
pathType netQuality.PathType No No Type of the data path other than the default path in multi-network concurrency.

MultiPathRecommendationInfo

Defines multi-network concurrency suggestion information.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Type Read-Only Optional Description
action MultiPathAction No No Multi-network concurrency action that is suggested.

MultiPathQuota

Defines the quota usage information for multi-network concurrency.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Type Read-Only Optional Description
used MultiPathQuotaInfo Yes No Used quota information of an app.
remaining MultiPathQuotaInfo Yes No Remaining quota information of an app.

MultiPathQuotaInfo

Defines multi-network concurrency quota information.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Type Read-Only Optional Description
count number No No Number of quota sessions.
duration number No No Quota duration, in seconds.

MultiPathRequestResult

Defines the multi-network concurrency request result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Type Read-Only Optional Description
result MultiPathErrorResult No No Multi-network concurrency request result.

MultiPathAction

Defines the enumeration of suggested multi-network concurrency actions.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Value Description
MULTIPATH_ACTION_REQUEST 0 Initiate a multi-network concurrency request.
MULTIPATH_ACTION_RELEASE 1 Release multi-network concurrency.

MultiPathErrorResult

Defines the enumeration of multi-network concurrency initiation results.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Value Description
MULTIPATH_ERROR_NONE 0 Multi-network concurrency initiated successfully.
MULTIPATH_ERROR_NETWORK_REFUSED 1 Multi-network concurrency rejected.
MULTIPATH_ERROR_TIMEOUT 2 Multi-network concurrency timed out.
MULTIPATH_ERROR_LOCAL 3 Multi-network concurrency is released locally when it is being initiated. For example, multi-network concurrency conditions are no longer met due to cellular data switch being turned off or other events during the startup.

MultiPathState

Defines multi-network concurrency status values.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Value Description
MULTIPATH_IDLE 0 Multi-network concurrency is available.
MULTIPATH_CREATING 1 Multi-network concurrency is being initiated.
MULTIPATH_CREATED 2 Multi-network concurrency has been initiated.
MULTIPATH_RELEASING 3 Multi-network concurrency is being released.

PathState

Defines the status values of a data path other than the default path in multi-network concurrency.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Value Description
PATH_IDLE 0 The path in multi-network concurrency is idle.
PATH_CONNECTED 1 The path in multi-network concurrency is set up.
PATH_SUSPENDED 2 The path in multi-network concurrency is suspended.

MultiPathChangeCause

Defines the enumeration of the reasons why multi-network concurrency status changes.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 6.0.0(20)

Name Value Description
MULTIPATH_CHANGE_CAUSE_REQUEST_NORMAL 0 A multi-network concurrency request is normally initiated.
MULTIPATH_CHANGE_CAUSE_RELEASE_NORMAL 50 Multi-network concurrency is normally released.
MULTIPATH_CHANGE_CAUSE_RELEASE_NETWORK 51 Multi-network concurrency is released due to poor network conditions.
MULTIPATH_CHANGE_CAUSE_RELEASE_USER_REFUSED 52 Multi-network concurrency is released as the user turns off a relevant switch.
MULTIPATH_CHANGE_CAUSE_RELEASE_NO_QUOTA 53 Multi-network concurrency is released due to quota exhaustion.
MULTIPATH_CHANGE_CAUSE_RELEASE_POWER_CONSUMPTION 54 Multi-network concurrency is released due to power consumption factors.
MULTIPATH_CHANGE_CAUSE_RELEASE_INSUFFICIENT_TRAFFIC 55 Multi-network concurrency is released due to traffic consumption factors.
MULTIPATH_CHANGE_CAUSE_RELEASE_CONFLICT 56 Multi-network concurrency is released due to scenario conflicts.
MULTIPATH_CHANGE_CAUSE_RELEASE_SYS_FUSING 57 Multi-network concurrency is released by the device after an app improperly uses multi-network concurrency, for example, keeping multi-network concurrency on for a long time.
MULTIPATH_CHANGE_CAUSE_RELEASE_SYS_DEFAULT 99 Multi-network concurrency is released due to network status changes of the device.
MULTIPATH_CHANGE_CAUSE_SUSPEND_ENTER 100 Multi-network concurrency is suspended. In this case, it is not released, but data transmission is actually suspended.
MULTIPATH_CHANGE_CAUSE_SUSPEND_LEAVE 101 Multi-network concurrency leaves the suspended state.
MULTIPATH_CHANGE_CAUSE_CONN_PROPERTIES_UPDATE 102 Link attributes are updated for multi-network concurrency. For example, the IP address changes.

HandoverMode

Defines the enumeration of network handover modes.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Name Value Description
DELEGATION 0 Delegation mode, indicating that the device initiates network handover. This mode is used by default if the app does not call the setHandoverMode API.
DISCRETION 1 Proactive mode, indicating that the app initiates network handover. The app can call this API to forbid the device to initiate network handover. However, in some cases, for example, when the app is switched to the background, the device may still initiate network handover even if the API is called.

ReEstAction

Defines the enumeration of link re-establishment types.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Name Value Description
DEFAULT 0 The app needs to re-establish the link to the same remote IP address.
QUERY_DNS 1 The link type changes, for example, from Wi-Fi to cellular network, or the carrier information of the link changes.
CHANGE_REMOTE_IP 2 The app needs to re-establish the link to a different remote IP address.
CHANGE_IP_VERSION 3 The app needs to re-establish the link by changing the IP address type, for example, from IPv4 to IPv6 or from IPv6 to IPv4.
NO_EST 4 The app needs to request network resources through the original data link, without the need to re-establish the link.

ErrorResult

Defines the enumeration of network handover results.

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

System capability: SystemCapability.Communication.NetworkBoost.Core

Since: 5.0.0(12)

Name Value Description
ERROR_NONE 0 The network handover is successful.
ERROR_HANDOVER_TIMEOUT 1 The network handover timed out.
ERROR_NEW_PATH_ACTIVATION_FAILED 2 The new link failed to be activated.
ERROR_ABORT 3 Network handover was canceled.