README.md
1# Cellular Data<a name="EN-US_TOPIC_0000001105538940"></a>
2
3- [Introduction](#section117mcpsimp)
4- [Directory Structure](#section121mcpsimp)
5- [Constraints](#section125mcpsimp)
6- [Available APIs](#section131mcpsimp)
7- [Usage Guidelines](#section160mcpsimp)
8 - [Checking the Cellular Data Status](#section192mcpsimp)
9 - [Obtaining the Cellular Data Status](#section213mcpsimp)
10
11- [Repositories Involved](#section234mcpsimp)
12
13## Introduction<a name="section117mcpsimp"></a>
14
15The cellular data module is a tailorable component of the Telephony subsystem. It depends on the telephony core service \(core\_service\) and RIL Adapter \(ril\_adapter\). The module provides functions such as cellular data activation, cellular data fault detection and rectification, cellular data status management, cellular data switch management, cellular data roaming management, APN management, and network management and interaction.
16
17**Figure 1** Architecture of the cellular data module<a name="fig332493822512"></a>
18
19
20## Directory Structure<a name="section121mcpsimp"></a>
21
22```
23base/telephony/cellular_data/
24├── figures
25├── frameworks
26│ ├── js
27│ │ └── napi
28│ │ ├── include # js head files
29│ │ └── src # js source files
30│ └── native
31├── interfaces # externally exposed interface
32│ ├── innerkits
33│ └── kits
34│ └── js
35│ └── declaration # external JS API interfaces
36├── sa_profile # SA profiles
37├── services
38│ ├── include # head files
39│ │ ├── apn_manager
40│ │ ├── common
41│ │ ├── state_machine
42│ │ └── utils
43│ └── src # source files
44│ ├── apn_manager
45│ ├── state_machine
46│ └── utils
47└── test
48 └── unit_test # unit test code
49
50```
51
52## Constraints<a name="section125mcpsimp"></a>
53
54- Programming language: JavaScript
55- In terms of software, this module needs to work with the telephony core service \(core\_service\) and RIL Adapter \(call\_manger\).
56- In terms of hardware, the accommodating device must be equipped with a modem and a SIM card capable of independent cellular communication.
57
58## Available APIs<a name="section131mcpsimp"></a>
59
60**Table 1** External APIs provided by the cellular data module
61
62<a name="table133mcpsimp"></a>
63
64| API | Description | Required Permission |
65| ------------------------------------------------------------ | ------------------------------------------- | -------------------------------- |
66| function isCellularDataEnabled(callback: AsyncCallback\<boolean>): void; | Checks whether the cellular data is enabled | ohos.permission.GET_NETWORK_INFO |
67| function getCellularDataState(callback: AsyncCallback\<DataConnectState>): void; | Obtains the cellular data status. | ohos.permission.GET_NETWORK_INFO |
68
69
70## Usage Guidelines<a name="section160mcpsimp"></a>
71
72### Checking the Cellular Data Status<a name="section192mcpsimp"></a>
73
741. Call the **IsCellularDataEnabled** method in callback or Promise mode to check whether the cellular data is enabled.
752. This method works in asynchronous mode. The execution result is returned through the callback.
76
77 ```
78 import data from "@ohos.telephony.data";
79
80 // Call the API in callback mode.
81 data.isCellularDataEnabled((err, value) => {
82 if (err) {
83 // If the API call failed, err is not empty.
84 console.error(`failed to isCellularDataEnabled because ${err.message}`);
85 return;
86 }
87 // If the API call succeeded, err is empty.
88 console.log(`success to isCellularDataEnabled: ${value}`);
89 });
90
91 // Call the API in Promise mode.
92 let promise = data.isCellularDataEnabled();
93 promise.then((value) => {
94 // The API call succeeded.
95 console.log(`success to isCellularDataEnabled: ${value}`);
96 }).catch((err) => {
97 // The API call failed.
98 console.error(`failed to isCellularDataEnabled because ${err.message}`);
99 });
100 ```
101
102
103### Obtaining the Cellular Data Status<a name="section213mcpsimp"></a>
104
105**Table 2** Description of DataConnectState enum values
106
107<a name="table21531410101919"></a>
108
109| Name | ValueDescription | |
110| ----------------------- | ---------------- | ------------ |
111| DATA_STATE_UNKNOWN | -1 | Unknown |
112| DATA_STATE_DISCONNECTED | 0 | Disconnected |
113| DATA_STATE_CONNECTING | 1 | Connecting |
114| DATA_STATE_CONNECTED | 2 | Connected |
115| DATA_STATE_SUSPENDED | 3 | Suspended |
116
117
1181. Call the **getCellularDataState** method in callback or Promise mode to obtain the cellular data status.
1192. This method works in asynchronous mode. The execution result is returned through the callback.
120
121 ```
122 import data from "@ohos.telephony.data";
123
124 // Call the API in callback mode.
125 data.getCellularDataState((err, value) => {
126 if (err) {
127 // If the API call failed, err is not empty.
128 console.error(`failed to getCellularDataState because ${err.message}`);
129 return;
130 }
131 // If the API call succeeded, err is empty.
132 console.log(`success to getCellularDataState: ${value}`);
133 });
134
135 // Call the API in Promise mode.
136 let promise = data.getCellularDataState();
137 promise.then((value) => {
138 // The API call succeeded.
139 console.log(`success to getCellularDataState: ${value}`);
140 }).catch((err) => {
141 // The API call failed.
142 console.error(`failed to getCellularDataState because ${err.message}`);
143 });
144 ```
145
146
147## Repositories Involved<a name="section234mcpsimp"></a>
148
149Telephony
150
151telephony_cellular_data
152
153telephony_core_service
154
155telephony_ril_adapter
156
README_zh.md
1# 蜂窝数据<a name="ZH-CN_TOPIC_0000001105538940"></a>
2
3- [简介](#section117mcpsimp)
4- [目录](#section121mcpsimp)
5- [约束](#section125mcpsimp)
6- [接口说明](#section131mcpsimp)
7- [使用说明](#section160mcpsimp)
8 - [获取蜂窝数据开关是否打开](#section192mcpsimp)
9 - [获取蜂窝数据状态](#section213mcpsimp)
10
11- [相关仓](#section234mcpsimp)
12
13## 简介<a name="section117mcpsimp"></a>
14
15蜂窝数据模块作为电话子系统可裁剪部件，依赖于core\_service核心服务、ril\_adapter。 具有蜂窝数据激活、蜂窝数据异常检测与恢复、蜂窝数据状态管理、蜂窝数据开关管理、蜂窝数据漫游管理、APN管理、网络管理交互等功能。
16
17**图 1** 蜂窝数据模块架构图<a name="fig332493822512"></a>
18
19
20## 目录<a name="section121mcpsimp"></a>
21
22```
23base/telephony/cellular_data/
24├── figures
25├── frameworks
26│ ├── js
27│ │ └── napi
28│ │ ├── include # js头文件
29│ │ └── src # js源文件
30│ └── native
31├── interfaces # 对外暴露的接口
32│ ├── innerkits
33│ └── kits
34│ └── js
35│ └── declaration # 外部 JS API 接口
36├── sa_profile # SA配置
37├── services
38│ ├── include # 头文件
39│ │ ├── apn_manager
40│ │ ├── common
41│ │ ├── state_machine
42│ │ └── utils
43│ └── src # 源文件
44│ ├── apn_manager
45│ ├── state_machine
46│ └── utils
47└── test
48 └── unit_test # 单元测试相关代码
49```
50
51## 约束<a name="section125mcpsimp"></a>
52
53- 开发语言：Java Script。
54- 软件上，需要与以下服务配合使用：Telephony核心服务（core\_service）、RIL适配（ril\_adapter）。
55- 硬件上，需要搭载的设备支持以下硬件：可以进行独立蜂窝通信的Modem以及SIM卡。
56
57## 接口说明<a name="section131mcpsimp"></a>
58
59**表 1** 蜂窝数据对外提供的接口
60
61<a name="table133mcpsimp"></a>
62
63| 接口名称 | 接口描述 | 所需权限 |
64| ------------------------------------------------------------ | ------------------------ | -------------------------------- |
65| function isCellularDataEnabled(callback: AsyncCallback\<boolean>): void; | 获取蜂窝数据开关是否打开 | ohos.permission.GET_NETWORK_INFO |
66| function getCellularDataState(callback: AsyncCallback\<DataConnectState>): void; | 获取蜂窝数据状态 | ohos.permission.GET_NETWORK_INFO |
67
68## 使用说明<a name="section160mcpsimp"></a>
69
70### 获取蜂窝数据开关是否打开<a name="section192mcpsimp"></a>
71
721. 可以通过callback或者Promise的方式调用IsCellularDataEnabled获取蜂窝数据开关是否打开。
732. 该接口为异步接口，相关执行结果会从callback中返回。
74
75 ```
76 import data from "@ohos.telephony.data";
77
78 // 调用接口【callback方式】
79 data.isCellularDataEnabled((err, value) => {
80 if (err) {
81 // 接口调用失败，err非空
82 console.error(`failed to isCellularDataEnabled because ${err.message}`);
83 return;
84 }
85 // 接口调用成功，err为空
86 console.log(`success to isCellularDataEnabled: ${value}`);
87 });
88
89 // 调用接口【Promise方式】
90 let promise = data.isCellularDataEnabled();
91 promise.then((value) => {
92 // 接口调用成功，此处可以实现成功场景分支代码。
93 console.log(`success to isCellularDataEnabled: ${value}`);
94 }).catch((err) => {
95 // 接口调用失败，此处可以实现失败场景分支代码。
96 console.error(`failed to isCellularDataEnabled because ${err.message}`);
97 });
98 ```
99
100
101### 获取蜂窝数据状态<a name="section213mcpsimp"></a>
102
103**表 2** DataConnectState枚举值
104
105<a name="table21531410101919"></a>
106
107| 名称 | 值 | 说明 |
108| ----------------------- | ---- | -------- |
109| DATA_STATE_UNKNOWN | -1 | 未知 |
110| DATA_STATE_DISCONNECTED | 0 | 连接断开 |
111| DATA_STATE_CONNECTING | 1 | 连接中 |
112| DATA_STATE_CONNECTED | 2 | 已连接 |
113| DATA_STATE_SUSPENDED | 3 | 已挂起 |
114
115
1161. 可以通过callback或者Promise的方式调用getCellularDataState获取蜂窝数据状态。
1172. 该接口为异步接口，相关执行结果会从callback中返回。
118
119 ```
120 import data from "@ohos.telephony.data";
121
122 // 调用接口【callback方式】
123 data.getCellularDataState((err, value) => {
124 if (err) {
125 // 接口调用失败，err非空
126 console.error(`failed to getCellularDataState because ${err.message}`);
127 return;
128 }
129 // 接口调用成功，err为空
130 console.log(`success to getCellularDataState: ${value}`);
131 });
132
133 // 调用接口【Promise方式】
134 let promise = data.getCellularDataState();
135 promise.then((value) => {
136 // 接口调用成功，此处可以实现成功场景分支代码。
137 console.log(`success to getCellularDataState: ${value}`);
138 }).catch((err) => {
139 // 接口调用失败，此处可以实现失败场景分支代码。
140 console.error(`failed to getCellularDataState because ${err.message}`);
141 });
142 ```
143
144## 相关仓<a name="section234mcpsimp"></a>
145
146电话服务子系统
147
148telephony_cellular_data
149
150telephony_core_service
151
152telephony_ril_adapter
153
