目录

@ohos.telephony.data (Cellular Data)

The data module provides basic mobile data management functions. With the APIs provided by this module, you can obtain the default slot of the SIM card used for mobile data, obtain the cellular data flow type and connection status, and check whether cellular data and roaming are enabled.

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { data } from '@kit.TelephonyKit';

data.getDefaultCellularDataSlotId

getDefaultCellularDataSlotId(callback: AsyncCallback<number>): void

Obtains the default slot of the SIM card used for mobile data. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Telephony.CellularData

Parameters

Name Type Mandatory Description
callback AsyncCallback<number> Yes

Callback used to return the result.

- 0: card slot 1.

- 1: card slot 2

- 2: slot ID of the mobile data in the eSIM and SkyTone scenarios.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.getDefaultCellularDataSlotId((err: BusinessError, contextData: number) => {
    if(err) {
        console.error(`getDefaultCellularDataSlotId fail. code: ${err.code}, message: ${err.message}, contextData: ${contextData}`);
    } else {
        console.info(`getDefaultCellularDataSlotId success`);
    }
});

data.getDefaultCellularDataSlotId

getDefaultCellularDataSlotId(): Promise<number>

Obtains the default slot of the SIM card used for mobile data. This API uses a promise to return the result.

System capability: SystemCapability.Telephony.CellularData

Return value

Type Description
Promise<number>

Promise used to return the result.

- 0: card slot 1.

- 1: card slot 2

- 2: slot ID of the mobile data in the eSIM and SkyTone scenarios.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.getDefaultCellularDataSlotId().then((contextData: number) => {
    console.info(`getDefaultCellularDataSlotId success, contextData: ${contextData}`);
}).catch((err: BusinessError) => {
    console.error(`getDefaultCellularDataSlotId fail. code: ${err.code}, message: ${err.message}`);
});

data.getDefaultCellularDataSlotIdSync9+

getDefaultCellularDataSlotIdSync(): number

Obtains the default SIM card used for mobile data synchronously.

System capability: SystemCapability.Telephony.CellularData

Return value

Type Description
number

SIM card slot.

- 0: card slot 1.

- 1: card slot 2

- 2: slot ID of the mobile data in the eSIM and SkyTone scenarios.

Example

import { data } from '@kit.TelephonyKit';

console.info("Result: "+ data.getDefaultCellularDataSlotIdSync())

data.getCellularDataFlowType

getCellularDataFlowType(callback: AsyncCallback<DataFlowType>): void

Obtains the data flow type of the cellular network (corresponding to the uplink and downlink arrows next to the signal bar). This API uses an asynchronous callback to return the result.

Required permissions:

System capability: SystemCapability.Telephony.CellularData

Parameters

Name Type Mandatory Description
callback AsyncCallback<DataFlowType> Yes Callback used to return the result.

Error codes

For details about the following error codes, see Universal Error Codes.

ID Error Message
201

Permission denied.

Applicable versions: 22+

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.getCellularDataFlowType((err: BusinessError, contextData: data.DataFlowType) => {
    if(err) {
        console.error(`getCellularDataFlowType fail. code: ${err.code}, message: ${err.message}, contextData: ${contextData}`);
    } else {
        console.info(`getCellularDataFlowType success`);
    }
});

data.getCellularDataFlowType

getCellularDataFlowType(): Promise<DataFlowType>

Obtains the data flow type of the cellular network (corresponding to the uplink and downlink arrows next to the signal bar). This API uses a promise to return the result.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.CellularData

Return value

Type Description
Promise<DataFlowType> Promise used to return the data flow type of the cellular network (corresponding to the uplink and downlink arrows next to the signal bar).

Error codes

For details about the following error codes, see Universal Error Codes.

ID Error Message
201

Permission denied.

Applicable versions: 22+

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.getCellularDataFlowType().then((contextData: data.DataFlowType) => {
    console.info(`getCellularDataFlowType success, contextData: ${contextData}`);
}).catch((err: BusinessError) => {
    console.error(`getCellularDataFlowType fail. code: ${err.code}, message: ${err.message}`);
});

data.getCellularDataState

getCellularDataState(callback: AsyncCallback<DataConnectState>): void

Obtains the cellular data connection status. This API uses an asynchronous callback to return the result.

Required permissions:

System capability: SystemCapability.Telephony.CellularData

Parameters

Name Type Mandatory Description
callback AsyncCallback<DataConnectState> Yes Callback used to return the result.

Error codes

For details about the following error codes, see Universal Error Codes.

ID Error Message
201

Permission denied.

Applicable versions: 22+

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.getCellularDataState((err: BusinessError, contextData: data.DataConnectState) => {
    if(err) {
        console.error(`getCellularDataState fail. code: ${err.code}, message: ${err.message}, contextData: ${contextData}`);
    } else {
        console.info(`getCellularDataState success`);
    }
});

data.getCellularDataState

getCellularDataState(): Promise<DataConnectState>

Obtains the cellular data connection status. This API uses a promise to return the result.

Required permissions:

System capability: SystemCapability.Telephony.CellularData

Return value

Type Description
Promise<DataConnectState> Promise used to return the result.

Error codes

For details about the following error codes, see Universal Error Codes.

ID Error Message
201

Permission denied.

Applicable versions: 22+

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.getCellularDataState().then((contextData: data.DataConnectState) => {
    console.info(`getCellularDataState success, contextData: ${contextData}`);
}).catch((err: BusinessError) => {
    console.error(`getCellularDataState fail. code: ${err.code}, message: ${err.message}`);
});

data.isCellularDataEnabled

isCellularDataEnabled(callback: AsyncCallback<boolean>): void

Checks whether the cellular data service is enabled. This API uses an asynchronous callback to return the result.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.CellularData

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes

Callback used to return the result.

true: The cellular data service is enabled.

false: The cellular data service is disabled.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.isCellularDataEnabled((err: BusinessError, contextData: boolean) => {
    if(err) {
        console.error(`isCellularDataEnabled fail. code: ${err.code}, message: ${err.message}, contextData: ${contextData}`);
    } else {
        console.info(`isCellularDataEnabled success`);
    }
});

data.isCellularDataEnabled

isCellularDataEnabled(): Promise<boolean>

Checks whether the cellular data service is enabled. This API uses a promise to return the result.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.CellularData

Return value

Type Description
Promise<boolean>

Promise used to return the result.

true: The cellular data service is enabled.

false: The cellular data service is disabled.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.isCellularDataEnabled().then((contextData: boolean) => {
    console.info(`isCellularDataEnabled success, contextData: ${contextData}`);
}).catch((err: BusinessError) => {
    console.error(`isCellularDataEnabled fail. code: ${err.code}, message: ${err.message}`);
});

data.isCellularDataEnabledSync12+

isCellularDataEnabledSync(): boolean

Checks whether the cellular data service is enabled. This API returns the result synchronously.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.CellularData

Return value

Type Description
boolean

Whether the cellular data service is enabled.

true: The cellular data service is enabled.

false: The cellular data service is disabled.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
8300002 Operation failed. Cannot connect to service.
8300003 System internal error.
8300999 Unknown error code.

Example

import { data } from '@kit.TelephonyKit';

try {
    let isEnabled: boolean = data.isCellularDataEnabledSync();
    console.info(`isCellularDataEnabledSync success : ${isEnabled}`);
} catch (err) {
    console.error(`isCellularDataEnabledSync fail. code: ${err.code}, message: ${err.message}`);
}

data.isCellularDataRoamingEnabled

isCellularDataRoamingEnabled(slotId: number, callback: AsyncCallback<boolean>): void

Checks whether roaming is enabled for the cellular data service. This API uses an asynchronous callback to return the result.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.CellularData

Parameters

Name Type Mandatory Description
slotId number Yes

Card slot ID.

- 0: card slot 1.

- 1: card slot 2
callback AsyncCallback<boolean> Yes

Callback used to return the result.

true: Roaming is enabled for the cellular data service.

false: Roaming is disabled for the cellular data service.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.isCellularDataRoamingEnabled(0, (err: BusinessError, contextData: boolean) => {
    if(err) {
        console.error(`isCellularDataRoamingEnabled fail. code: ${err.code}, message: ${err.message}, contextData: ${contextData}`);
    } else {
        console.info(`isCellularDataRoamingEnabled success`);
    }
});

data.isCellularDataRoamingEnabled

isCellularDataRoamingEnabled(slotId: number): Promise<boolean>

Checks whether roaming is enabled for the cellular data service. This API uses a promise to return the result.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.CellularData

Parameters

Name Type Mandatory Description
slotId number Yes

Card slot ID.

- 0: card slot 1.

- 1: card slot 2

Return value

Type Description
Promise<boolean>

Promise used to return the result.

true: Roaming is enabled for the cellular data service.

false: Roaming is disabled for the cellular data service.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Service connection failed.
8300003 System internal error.
8300999 Unknown error.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.isCellularDataRoamingEnabled(0).then((contextData: boolean) => {
    console.info(`isCellularDataRoamingEnabled success, contextData: ${contextData}`);
}).catch((err: BusinessError) => {
    console.error(`isCellularDataRoamingEnabled fail. code: ${err.code}, message: ${err.message}`);
});

data.isCellularDataRoamingEnabledSync12+

isCellularDataRoamingEnabledSync(slotId: number): boolean

Checks whether roaming is enabled for the cellular data service. This API returns the result synchronously.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.CellularData

Parameters

Name Type Mandatory Description
slotId number Yes

Card slot ID.

- 0: card slot 1.

- 1: card slot 2

Return value

Type Description
boolean

Whether roaming is enabled for the cellular data service.

true: Roaming is enabled for the cellular data service.

false: Roaming is disabled for the cellular data service.

Error codes

For details about the error codes, see Universal Error Codes and Telephony Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
8300001 Invalid parameter value.
8300002 Operation failed. Cannot connect to service.
8300003 System internal error.
8300999 Unknown error code.

Example

import { data } from '@kit.TelephonyKit';

try {
    let isEnabled: boolean = data.isCellularDataRoamingEnabledSync(0);
    console.info(`isCellularDataRoamingEnabledSync success : ${isEnabled}`);
} catch (err) {
    console.error(`isCellularDataRoamingEnabledSync fail. code: ${err.code}, message: ${err.message}`);
}

data.getDefaultCellularDataSimId10+

getDefaultCellularDataSimId(): number

Obtains the default ID of the SIM card used for mobile data.

System capability: SystemCapability.Telephony.CellularData

Return value

Type Description
number

Obtains the default ID of the SIM card used for mobile data.

The return value is bound to the SIM card and increases from 1.

- 0: no SIM card.

- 9999: ID of the SIM card used for mobile data in the eSIM scenario.

- 99999: ID of the SIM card used for mobile data in the SkyTone scenario. The default value is 99999.

Example

import { data } from '@kit.TelephonyKit';

console.info("Result: "+ data.getDefaultCellularDataSimId());

data.queryAllApns16+

queryAllApns(): Promise<Array<ApnInfo>>

Obtains the access point name (APN) of the default SIM card used for mobile data. This API returns the result asynchronously.

Required permissions: ohos.permission.MANAGE_APN_SETTING (Restricted permission used only when you need to connect to the mobile data private network for office tasks. For details, see Restricted Permissions.)

System capability: SystemCapability.Telephony.CellularData

Return value

Type Description
Promise<Array<ApnInfo>> Promise used to return the result.

Error codes

For details about the following error codes, see Universal Error Codes.

ID Error Message
201 Permission denied.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.queryAllApns().then((apnInfos: Array<data.ApnInfo>) => {
    console.info(`queryAllApns success, promise: apnInfos->${JSON.stringify(apnInfos)}`);
}).catch((err: BusinessError) => {
    console.error(`queryAllApns failed. code: ${err.code}, message: ${err.message}`);
});

data.queryApnIds16+

queryApnIds(apnInfo: ApnInfo): Promise<Array<number>>

Obtains the APN ID corresponding to the specified ApnInfo. This API returns the result asynchronously.

Required permissions: ohos.permission.MANAGE_APN_SETTING (Restricted permission used only when you need to connect to the mobile data private network for office tasks. For details, see Restricted Permissions.)

System capability: SystemCapability.Telephony.CellularData

Parameters

Name Type Mandatory Description
apnInfo ApnInfo Yes APN to query.

Return value

Type Description
Promise<Array<number>> Promise used to return the result.

Error codes

For details about the following error codes, see Universal Error Codes.

ID Error Message
201 Permission denied.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

let apnInfo: data.ApnInfo;
apnInfo = {
  apnName: "CMNET",
  apn: "cmnet",
  mcc: "460",
  mnc: "07",
};

data.queryApnIds(apnInfo).then((apnIds: Array<number>) => {
    console.info(`queryApnIds success, apnIds: ${apnIds}`);
}).catch((err: BusinessError) => {
    console.error(`queryApnIds failed. code: ${err.code}, message: ${err.message}`);
});

data.setPreferredApn16+

setPreferredApn(apnId: number): Promise<boolean>

Sets the APN corresponding to the specified apnId as the preferred APN. This API returns the result asynchronously.

If the passed apnId is invalid, the system switches back to the preferred APN configured by the carrier by default.

Required permissions: ohos.permission.MANAGE_APN_SETTING (Restricted permission used only when you need to connect to the mobile data private network for office tasks. For details, see Restricted Permissions.)

System capability: SystemCapability.Telephony.CellularData

Parameters

Name Type Mandatory Description
apnId number Yes APN ID, which can be obtained by calling queryApnIds.

Return value

Type Description
Promise<boolean> Promise used to return the result. If no SIM card is installed, the value false is returned.

Error codes

For details about the following error codes, see Universal Error Codes.

ID Error Message
201 Permission denied.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

let apnId: number = 0; // apnId is a valid value returned by queryApnIds. If an invalid APN ID is passed to setPreferredApn, the default preferred APN configured by the carrier is used.
data.setPreferredApn(apnId).then((result: boolean) => {
    console.info(`setPreferredApn result: ${result}`);
}).catch((err: BusinessError) => {
    console.error(`setPreferredApn failed. code: ${err.code}, message: ${err.message}`);
});

data.getActiveApnName20+

getActiveApnName(): Promise<string>

Obtains the access point name (APN) of the default SIM card used for mobile data. This API returns the result asynchronously.

Required permission: ohos.permission.GET_NETWORK_INFO

System capability: SystemCapability.Telephony.CellularData

Return value

Type Description
Promise<string> Promise used to return the result. If mobile data is not activated, an empty string is returned.

Error codes

For details about the following error codes, see Universal Error Codes.

ID Error Message
201 Permission denied.

Example

import { data } from '@kit.TelephonyKit';
import { BusinessError } from '@kit.BasicServicesKit';

data.getActiveApnName().then((apn: string) => {
    console.info(`getActiveApnName success, apn: ${apn}`);
}).catch((err: BusinessError) => {
    console.error(`getActiveApnName failed. code: ${err.code}, message: ${err.message}`);
});

data.showSystemApnSettings

showSystemApnSettings(context: Context): Promise<void>

Opens the APN configuration page of the default SIM card. This API uses a promise to return the result.

  • This API allows you to view and select only the existing general APNs. Creation or modification of APN is not supported.

  • If no SIM card is inserted or the device does not support APN configuration, the configuration page cannot be opened.

Since: 26.0.0

System capability: SystemCapability.Telephony.CellularData

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

Device behavior differences: This API can be properly called on phones and tablets. If it is called on other device types, it does not work.

Parameters

Name Type Mandatory Description
context Context Yes Application context of the stage model. (Only UIAbilityContext and ExtensionContext are supported.)

Return value

Type Description
Promise<void> Promise that returns no value.

Example

In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.

import { data } from '@kit.TelephonyKit';
import { common } from '@kit.AbilityKit';

let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
data.showSystemApnSettings(context).then(() => {
  console.info("showSystemApnSettings success");
}).catch(() => {
  console.error("showSystemApnSettings failed");
});

DataFlowType

Defines the cellular data flow type.

System capability: SystemCapability.Telephony.CellularData

Name Value Description
DATA_FLOW_TYPE_NONE 0 No uplink or downlink data is available.
DATA_FLOW_TYPE_DOWN 1 Only the downlink data is available.
DATA_FLOW_TYPE_UP 2 Only the uplink data is available.
DATA_FLOW_TYPE_UP_DOWN 3 Both the uplink data and downlink data are available.
DATA_FLOW_TYPE_DORMANT 4 No uplink or downlink data is available because the lower-layer link is in the dormant state.

DataConnectState

Describes the connection status of a cellular data link.

System capability: SystemCapability.Telephony.CellularData

Name Value Description
DATA_STATE_UNKNOWN -1 The status of the cellular data link is unknown.
DATA_STATE_DISCONNECTED 0 The cellular data link is disconnected.
DATA_STATE_CONNECTING 1 The cellular data link is being connected.
DATA_STATE_CONNECTED 2 The cellular data link is connected.
DATA_STATE_SUSPENDED 3 The cellular data link is suspended.

ApnInfo16+

Defines the APN information.

System capability: SystemCapability.Telephony.CellularData

Name Type Read-Only Optional Description
apnName string No No APN name.
apn string No No APN.
mcc string No No Mobile country code (MCC) of the SIM card.
mnc string No No Mobile network code (MNC) of the SIM card.
user string No Yes User name.
type string No Yes APN type.
proxy string No Yes Proxy address.
mmsproxy string No Yes Multimedia messaging service (MMS) proxy.