1# @ohos.telephony.data (蜂窝数据)
2
3蜂窝数据提供了移动数据管理能力，包括获取默认移动数据的SIM卡，获取蜂窝数据业务的上下行和分组交换域（PS域）的连接状态，以及检查蜂窝数据业务和漫游是否启用等。
4
5>**说明：**
6>
7>本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { data } from '@kit.TelephonyKit';
13```
14
15## data.getDefaultCellularDataSlotId
16
17getDefaultCellularDataSlotId(callback: AsyncCallback\<number\>): void
18
19获取默认移动数据的SIM卡，使用callback方式作为异步方法。
20
21**系统能力**：SystemCapability.Telephony.CellularData
22
23**参数：**
24
25| 参数名   | 类型                    | 必填 | 说明                                       |
26| -------- | ----------------------- | ---- | ------------------------------------------ |
27| callback | AsyncCallback\<number\> | 是   | 以callback形式异步返回结果。<br />0：卡槽1。<br />1：卡槽2。 |
28
29**示例：**
30
31```ts
32import { data } from '@kit.TelephonyKit';
33import { BusinessError } from '@kit.BasicServicesKit';
34
35data.getDefaultCellularDataSlotId((err: BusinessError, contextData: number) => {
36    if(err){
37        console.error(`getDefaultCellularDataSlotId fail,callback: err->${JSON.stringify(err)}, contextData->${JSON.stringify(contextData)}`);
38    }else{
39        console.log(`getDefaultCellularDataSlotId success`);
40    }
41});
42```
43
44## data.getDefaultCellularDataSlotId
45
46getDefaultCellularDataSlotId(): Promise\<number\>
47
48获取默认移动数据的SIM卡，使用Promise方式作为异步方法。
49
50**系统能力**：SystemCapability.Telephony.CellularData
51
52**返回值：**
53
54| 类型              | 说明                                                         |
55| ----------------- | ------------------------------------------------------------ |
56| Promise\<number\> | 以Promise形式返回获取默认移动数据的SIM卡。<br />0：卡槽1。<br />1：卡槽2。 |
57
58**示例：**
59
60```ts
61import { data } from '@kit.TelephonyKit';
62import { BusinessError } from '@kit.BasicServicesKit';
63
64data.getDefaultCellularDataSlotId().then((contextData: number) => {
65    console.log(`getDefaultCellularDataSlotId success, promise: contextData->${JSON.stringify(contextData)}`);
66}).catch((err: BusinessError) => {
67    console.error(`getDefaultCellularDataSlotId fail, promise: err->${JSON.stringify(err)}`);
68});
69```
70
71## data.getDefaultCellularDataSlotIdSync<sup>9+</sup>
72
73getDefaultCellularDataSlotIdSync(): number
74
75获取默认移动数据的SIM卡
76
77**系统能力**：SystemCapability.Telephony.CellularData
78
79**返回值：**
80
81| 类型              | 说明                                                         |
82| ------ | -------------------------------------------------- |
83| number | 获取默认移动数据的SIM卡。<br />0：卡槽1。<br />1：卡槽2。 |
84
85**示例：**
86
87```ts
88import { data } from '@kit.TelephonyKit';
89
90console.log("Result: "+ data.getDefaultCellularDataSlotIdSync())
91```
92
93
94## data.getCellularDataFlowType
95
96getCellularDataFlowType(callback: AsyncCallback\<DataFlowType\>): void
97
98获取蜂窝数据业务的上下行状态，使用callback方式作为异步方法。
99
100**系统能力**：SystemCapability.Telephony.CellularData
101
102**参数：**
103
104| 参数名   | 类型                                           | 必填 | 说明       |
105| -------- | ---------------------------------------------- | ---- | ---------- |
106| callback | AsyncCallback\<[DataFlowType](#dataflowtype)\> | 是   | 以callback形式异步返回结果。 |
107
108**示例：**
109
110```ts
111import { data } from '@kit.TelephonyKit';
112import { BusinessError } from '@kit.BasicServicesKit';
113
114data.getCellularDataFlowType((err: BusinessError, contextData: data.DataFlowType) => {
115    if(err){
116        console.error(`getCellularDataFlowType fail,callback: err->${JSON.stringify(err)}, contextData->${JSON.stringify(contextData)}`);
117    }else{
118        console.log(`getCellularDataFlowType success`);
119    }
120});
121```
122
123## data.getCellularDataFlowType
124
125getCellularDataFlowType(): Promise\<DataFlowType\>
126
127获取蜂窝数据业务的上下行状态，使用Promise方式作为异步方法。
128
129**系统能力**：SystemCapability.Telephony.CellularData
130
131**返回值：**
132
133| 类型                                     | 说明                                            |
134| ---------------------------------------- | ----------------------------------------------- |
135| Promise\<[DataFlowType](#dataflowtype)\> | 以Promise形式返回获取蜂窝数据业务的上下行状态。 |
136
137**示例：**
138
139```ts
140import { data } from '@kit.TelephonyKit';
141import { BusinessError } from '@kit.BasicServicesKit';
142
143data.getCellularDataFlowType().then((contextData: data.DataFlowType) => {
144    console.log(`getCellularDataFlowType success, promise: contextData->${JSON.stringify(contextData)}`);
145}).catch((err: BusinessError) => {
146    console.error(`getCellularDataFlowType fail, promise: err->${JSON.stringify(err)}`);
147});
148```
149
150## data.getCellularDataState
151
152getCellularDataState(callback: AsyncCallback\<DataConnectState\>): void
153
154获取分组交换域（PS域）的连接状态，使用callback方式作为异步方法。
155
156**系统能力**：SystemCapability.Telephony.CellularData
157
158**参数：**
159
160| 参数名   | 类型                                                   | 必填 | 说明       |
161| -------- | ------------------------------------------------------ | ---- | ---------- |
162| callback | AsyncCallback\<[DataConnectState](#dataconnectstate)\> | 是   | 以callback形式异步返回结果。 |
163
164**示例：**
165
166```ts
167import { data } from '@kit.TelephonyKit';
168import { BusinessError } from '@kit.BasicServicesKit';
169
170data.getCellularDataState((err: BusinessError, contextData: data.DataConnectState) => {
171    if(err){
172        console.error(`getCellularDataState fail,callback: err->${JSON.stringify(err)}, contextData->${JSON.stringify(contextData)}`);
173    }else{
174        console.log(`getCellularDataState success`);
175    }
176});
177```
178
179## data.getCellularDataState
180
181getCellularDataState(): Promise\<DataConnectState\>
182
183获取分组交换域(PS域)的连接状态，使用Promise方式作为异步方法。
184
185**系统能力**：SystemCapability.Telephony.CellularData
186
187**返回值：**
188
189| 类型                                             | 说明                                  |
190| ------------------------------------------------ | ------------------------------------- |
191| Promise\<[DataConnectState](#dataconnectstate)\> | 以Promise形式返回获取PS域的连接状态。 |
192
193**示例：**
194
195```ts
196import { data } from '@kit.TelephonyKit';
197import { BusinessError } from '@kit.BasicServicesKit';
198
199data.getCellularDataState().then((contextData: data.DataConnectState) => {
200    console.log(`getCellularDataState success, promise: contextData->${JSON.stringify(contextData)}`);
201}).catch((err: BusinessError) => {
202    console.error(`getCellularDataState fail, promise: err->${JSON.stringify(err)}`);
203});
204```
205
206## data.isCellularDataEnabled
207
208isCellularDataEnabled(callback: AsyncCallback\<boolean\>): void
209
210检查蜂窝数据业务是否启用，使用callback方式作为异步方法。
211
212**需要权限**：ohos.permission.GET_NETWORK_INFO
213
214**系统能力**：SystemCapability.Telephony.CellularData
215
216**参数：**
217
218| 参数名   | 类型                     | 必填 | 说明                                                         |
219| -------- | ------------------------ | ---- | ------------------------------------------------------------ |
220| callback | AsyncCallback\<boolean\> | 是   | 以callback形式异步返回结果。<br />true：蜂窝数据业务已启用。<br />false：蜂窝数据业务已禁用。 |
221
222**错误码：**
223
224以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。
225
226| 错误码ID |                 错误信息                     |
227| -------- | -------------------------------------------- |
228| 201      | Permission denied.                           |
229| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.                             |
230| 8300001  | Invalid parameter value.                     |
231| 8300002  | Service connection failed.                   |
232| 8300003  | System internal error.                       |
233| 8300999  | Unknown error.                               |
234
235**示例：**
236
237```ts
238import { data } from '@kit.TelephonyKit';
239import { BusinessError } from '@kit.BasicServicesKit';
240
241data.isCellularDataEnabled((err: BusinessError, contextData: boolean) => {
242    if(err){
243        console.error(`isCellularDataEnabled fail,callback: callback: err->${JSON.stringify(err)}, contextData->${JSON.stringify(contextData)}`);
244    }else{
245        console.log(`isCellularDataEnabled success`);
246    }
247});
248```
249
250## data.isCellularDataEnabled
251
252isCellularDataEnabled(): Promise\<boolean\>
253
254检查蜂窝数据业务是否启用，使用Promise方式作为异步方法。
255
256**需要权限**：ohos.permission.GET_NETWORK_INFO
257
258**系统能力**：SystemCapability.Telephony.CellularData
259
260**返回值：**
261
262| 类型               | 说明                                                         |
263| ------------------ | ------------------------------------------------------------ |
264| Promise\<boolean\> | 以Promise形式返回检查蜂窝数据业务是否启用。<br />true：蜂窝数据业务已启用。<br />false：蜂窝数据业务已禁用。 |
265
266**错误码：**
267
268以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。
269
270| 错误码ID |                 错误信息                     |
271| -------- | -------------------------------------------- |
272| 201      | Permission denied.                           |
273| 8300002  | Service connection failed.                   |
274| 8300003  | System internal error.                       |
275| 8300999  | Unknown error.                               |
276
277**示例：**
278
279```ts
280import { data } from '@kit.TelephonyKit';
281import { BusinessError } from '@kit.BasicServicesKit';
282
283data.isCellularDataEnabled().then((contextData: boolean) => {
284    console.log(`isCellularDataEnabled success, promise: contextData->${JSON.stringify(contextData)}`);
285}).catch((err: BusinessError) => {
286    console.error(`isCellularDataEnabled fail, promise: err->${JSON.stringify(err)}`);
287});
288```
289
290## data.isCellularDataEnabledSync<sup>12+</sup>
291
292isCellularDataEnabledSync(): boolean
293
294检查蜂窝数据业务是否启用，调用此API返回结果。
295
296**需要权限**：ohos.permission.GET_NETWORK_INFO
297
298**系统能力**：SystemCapability.Telephony.CellularData
299
300**返回值：**
301
302| 类型    | 说明                                                         |
303| ------- | ------------------------------------------------------------ |
304| boolean | 用来返回检查蜂窝数据业务是否启用。<br />true：蜂窝数据业务已启用。<br />false：蜂窝数据业务已禁用。 |
305
306**错误码：**
307
308以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。
309
310| 错误码ID | 错误信息                                     |
311| -------- | -------------------------------------------- |
312| 201      | Permission denied.                           |
313| 8300002  | Operation failed. Cannot connect to service. |
314| 8300003  | System internal error.                       |
315| 8300999  | Unknown error code.                          |
316
317**示例：**
318
319<!--code_no_check-->
320
321```ts
322import { data } from '@kit.TelephonyKit';
323
324try {
325    let isEnabled: boolean = data.isCellularDataEnabledSync();
326    console.log(`isCellularDataEnabledSync success : ${isEnabled}`);
327} catch (error) {
328    console.error(`isCellularDataEnabledSync fail : err->${JSON.stringify(error)}`);
329}
330```
331
332## data.isCellularDataRoamingEnabled
333
334isCellularDataRoamingEnabled(slotId: number, callback: AsyncCallback\<boolean\>): void
335
336检查蜂窝数据业务是否启用漫游，使用callback方式作为异步方法。
337
338**需要权限**：ohos.permission.GET_NETWORK_INFO
339
340**系统能力**：SystemCapability.Telephony.CellularData
341
342**参数：**
343
344| 参数名   | 类型                     | 必填 | 说明                                                         |
345| -------- | ------------------------ | ---- | ------------------------------------------------------------ |
346| slotId   | number                   | 是   | 卡槽ID。<br />0：卡槽1。<br />1：卡槽2。                     |
347| callback | AsyncCallback\<boolean\> | 是   | 以callback形式异步返回结果。<br />true：蜂窝数据业务已启用漫游。<br />false：蜂窝数据业务已禁用漫游。 |
348
349**错误码：**
350
351以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。
352
353| 错误码ID |                  错误信息                    |
354| -------- | -------------------------------------------- |
355| 201      | Permission denied.                           |
356| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.                             |
357| 8300001  | Invalid parameter value.                     |
358| 8300002  | Service connection failed.                   |
359| 8300003  | System internal error.                       |
360| 8300999  | Unknown error.                               |
361
362**示例：**
363
364```ts
365import { data } from '@kit.TelephonyKit';
366import { BusinessError } from '@kit.BasicServicesKit';
367
368data.isCellularDataRoamingEnabled(0, (err: BusinessError, contextData: boolean) => {
369    if(err){
370        console.error(`isCellularDataRoamingEnabled fail,callback: err->${JSON.stringify(err)}, contextData->${JSON.stringify(contextData)}`);
371    }else{
372        console.log(`isCellularDataRoamingEnabled success`);
373    }
374});
375```
376
377## data.isCellularDataRoamingEnabled
378
379isCellularDataRoamingEnabled(slotId: number): Promise\<boolean\>
380
381检查蜂窝数据业务是否启用漫游，使用Promise方式作为异步方法。
382
383**需要权限**：ohos.permission.GET_NETWORK_INFO
384
385**系统能力**：SystemCapability.Telephony.CellularData
386
387**参数：**
388
389| 参数名 | 类型   | 必填 | 说明                                     |
390| ------ | ------ | ---- | ---------------------------------------- |
391| slotId | number | 是   | 卡槽ID。<br />0：卡槽1。<br />1：卡槽2。 |
392
393**返回值：**
394
395| 类型               | 说明                                                         |
396| ------------------ | ------------------------------------------------------------ |
397| Promise\<boolean\> | 以Promise形式返回检查蜂窝数据业务是否启用漫游。<br />true：蜂窝数据业务已启用漫游。<br />false：蜂窝数据业务已禁用漫游。 |
398
399**错误码：**
400
401以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。
402
403| 错误码ID |                  错误信息                    |
404| -------- | -------------------------------------------- |
405| 201      | Permission denied.                           |
406| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.                             |
407| 8300001  | Invalid parameter value.                     |
408| 8300002  | Service connection failed.                   |
409| 8300003  | System internal error.                       |
410| 8300999  | Unknown error.                               |
411
412**示例：**
413
414```ts
415import { data } from '@kit.TelephonyKit';
416import { BusinessError } from '@kit.BasicServicesKit';
417
418data.isCellularDataRoamingEnabled(0).then((contextData: boolean) => {
419    console.log(`isCellularDataRoamingEnabled success, promise: contextData->${JSON.stringify(contextData)}`);
420}).catch((err: BusinessError) => {
421    console.error(`isCellularDataRoamingEnabled fail, promise: err->${JSON.stringify(err)}`);
422});
423```
424
425## data.isCellularDataRoamingEnabledSync<sup>12+</sup>
426
427isCellularDataRoamingEnabledSync(slotId: number): boolean
428
429检查蜂窝数据业务是否启用漫游，调用此API返回结果。
430
431**需要权限**：ohos.permission.GET_NETWORK_INFO
432
433**系统能力**：SystemCapability.Telephony.CellularData
434
435**参数：**
436
437| 参数名 | 类型   | 必填 | 说明                                     |
438| ------ | ------ | ---- | ---------------------------------------- |
439| slotId | number | 是   | 卡槽ID。<br />0：卡槽1。<br />1：卡槽2。 |
440
441**返回值：**
442
443| 类型    | 说明                                                         |
444| ------- | ------------------------------------------------------------ |
445| boolean | 用来返回检查蜂窝数据业务是否启用漫游。<br />true：蜂窝数据业务已启用漫游。<br />false：蜂窝数据业务已禁用漫游。 |
446
447**错误码：**
448
449以下错误码的详细介绍请参见[ohos.telephony(电话子系统)错误码](errorcode-telephony.md)。
450
451| 错误码ID | 错误信息                                                     |
452| -------- | ------------------------------------------------------------ |
453| 201      | Permission denied.                                           |
454| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; |
455| 8300001  | Invalid parameter value.                                     |
456| 8300002  | Operation failed. Cannot connect to service.                 |
457| 8300003  | System internal error.                                       |
458| 8300999  | Unknown error code.                                          |
459
460**示例：**
461
462<!--code_no_check-->
463
464```ts
465import { data } from '@kit.TelephonyKit';
466
467try {
468    let isEnabled: boolean = data.isCellularDataRoamingEnabledSync(0);
469    console.log(`isCellularDataRoamingEnabledSync success : ${isEnabled}`);
470} catch (error) {
471    console.error(`isCellularDataRoamingEnabledSync fail : err->${JSON.stringify(error)}`);
472}
473```
474
475## data.getDefaultCellularDataSimId<sup>10+</sup>
476
477getDefaultCellularDataSimId(): number
478
479获取默认移动数据的SIM卡ID。
480
481**系统能力**：SystemCapability.Telephony.CellularData
482
483**返回值：**
484
485| 类型              | 说明                                                         |
486| ------ | -------------------------------------------------- |
487| number | 获取默认移动数据的SIM卡ID。<br/>与SIM卡绑定，从1开始递增。 |
488
489**示例：**
490
491```ts
492import { data } from '@kit.TelephonyKit';
493
494console.log("Result: "+ data.getDefaultCellularDataSimId());
495```
496
497## DataFlowType
498
499描述蜂窝数据流类型。
500
501**系统能力**：SystemCapability.Telephony.CellularData
502
503| 名称                   | 值   | 说明                                       |
504| ---------------------- | ---- | ------------------------------------------ |
505| DATA_FLOW_TYPE_NONE    | 0    | 表示没有上行或下行数据。                   |
506| DATA_FLOW_TYPE_DOWN    | 1    | 表示只有下行数据。                         |
507| DATA_FLOW_TYPE_UP      | 2    | 表示只有上行数据。                         |
508| DATA_FLOW_TYPE_UP_DOWN | 3    | 表示有上下行数据。                         |
509| DATA_FLOW_TYPE_DORMANT | 4    | 表示没有上下行数据，底层链路处于休眠状态。 |
510
511## DataConnectState
512
513描述蜂窝数据链路连接状态。
514
515**系统能力**：SystemCapability.Telephony.CellularData
516
517| 名称                    | 值   | 说明                       |
518| ----------------------- | ---- | -------------------------- |
519| DATA_STATE_UNKNOWN      | -1   | 表示蜂窝数据链路未知。     |
520| DATA_STATE_DISCONNECTED | 0    | 表示蜂窝数据链路断开。     |
521| DATA_STATE_CONNECTING   | 1    | 表示正在连接蜂窝数据链路。 |
522| DATA_STATE_CONNECTED    | 2    | 表示蜂窝数据链路已连接。   |
523| DATA_STATE_SUSPENDED    | 3    | 表示蜂窝数据链路被挂起。   |
524