1# 流量管理
2
3## 简介
4
5流量管理提供了基于物理网络的数据流量统计能力，支持基于网卡/UID 的流量统计。
6
7流量管理主要实现功能有：
8
9- 支持基于网卡/UID 的实时流量统计。
10- 支持基于网卡/UID 的历史流量统计。
11- 支持基于网卡/UID 的流量变化订阅。
12
13> **说明：**
14> 为了保证应用的运行效率，大部分 API 调用都是异步的，对于异步调用的 API 均提供了 callback 和 Promise 两种方式，以下示例均采用 Promise 函数，更多方式可以查阅[API 参考](../reference/apis-network-kit/js-apis-net-statistics.md)。
15
16以下分别介绍具体开发方式。
17
18## 接口说明
19
20完整的 JS API 说明以及实例代码请参考：[statistics 链接](../reference/apis-network-kit/js-apis-net-statistics.md)。
21
22| 接口名                                                       | 描述                                                         |
23| ------------------------------------------------------------ | ------------------------------------------------------------ |
24| getIfaceRxBytes(nic: string, callback: AsyncCallback\<number>): void; | 获取指定网卡实时下行流量数据。                               |
25| getIfaceTxBytes(nic: string, callback: AsyncCallback\<number>): void; | 获取指定网卡实时上行流量数据。                               |
26| getCellularRxBytes(callback: AsyncCallback\<number>): void;  | 获取蜂窝实时下行流量数据。                                   |
27| getCellularTxBytes(callback: AsyncCallback\<number>): void;  | 获取蜂窝实时上行流量数据。                                   |
28| getAllRxBytes(callback: AsyncCallback\<number>): void;       | 获取所有网卡实时下行流量数据。                               |
29| getAllTxBytes(callback: AsyncCallback\<number>): void;       | 获取所有网卡实时上行流量数据。                               |
30| getUidRxBytes(uid: number, callback: AsyncCallback\<number>): void; | 获取指定应用实时下行流量数据。                               |
31| getUidTxBytes(uid: number, callback: AsyncCallback\<number>): void; | 获取指定应用实时上行流量数据。                               |
32| <!--DelRow-->getTrafficStatsByIface(ifaceInfo: IfaceInfo, callback: AsyncCallback\<NetStatsInfo>): void; | 获取指定网卡历史流量信息。系统接口，[详情参考文档](../reference/apis-network-kit/js-apis-net-statistics-sys.md#statisticsgettrafficstatsbyiface10) |
33| <!--DelRow-->getTrafficStatsByUid(uidInfo: UidInfo, callback: AsyncCallback\<NetStatsInfo>): void; | 获取指定应用历史流量信息。系统接口，[详情参考文档](../reference/apis-network-kit/js-apis-net-statistics-sys.md#statisticsgettrafficstatsbyuid10) |
34| getSockfdRxBytes(sockfd: number, callback: AsyncCallback\<number>): void; | 获取指定socket实时下行流量数据。                             |
35| getSockfdTxBytes(sockfd: number, callback: AsyncCallback\<number>): void; | 获取指定socket实时上行流量数据。                             |
36| <!--DelRow-->on(type: 'netStatsChange', callback: Callback\<{ iface: string, uid?: number }>): void; | 订阅流量改变事件通知。系统接口，[详情参考文档](../reference/apis-network-kit/js-apis-net-statistics-sys.md#statisticsonnetstatschange10) |
37| <!--DelRow-->off(type: 'netStatsChange', callback?: Callback\<{ iface: string, uid?: number }>): void; | 取消订阅流量改变事件通知。系统接口，[详情参考文档](../reference/apis-network-kit/js-apis-net-statistics-sys.md#statisticsoffnetstatschange10) |
38| <!--DelRow-->getTrafficStatsByNetwork(networkInfo: NetworkInfo): Promise\<UidNetStatsInfo\>; | 获取指定时间段内所有应用在指定网络中的流量使用详情。系统接口，[详情参考文档](../reference/apis-network-kit/js-apis-net-statistics-sys.md#statisticsgettrafficstatsbynetwork12) |
39| <!--DelRow-->getTrafficStatsByUidNetwork(uid: number, networkInfo: NetworkInfo): Promise\<NetStatsInfoSequence\>; | 获取指定时间段内，应用在指定网络中的流量使用详情。系统接口，[详情参考文档](../reference/apis-network-kit/js-apis-net-statistics-sys.md#statisticsgettrafficstatsbynetwork12) |
40
41## 获取网卡/UID 的实时流量统计数据
42
431. 获取指定网卡实时流量数据。
442. 获取蜂窝实时流量数据。
453. 获取所有网卡实时流量数据。
464. 获取指定应用实时流量数据。
475. 获取指定socket实时流量数据。
48
49```ts
50// 从@kit.NetworkKit中导入statistics命名空间
51import { statistics, socket } from '@kit.NetworkKit';
52import { BusinessError } from '@kit.BasicServicesKit';
53
54// 获取指定网卡实时下行流量数据。
55statistics.getIfaceRxBytes("wlan0").then((stats: number) => {
56  console.log(JSON.stringify(stats));
57});
58
59// 获取指定网卡实时上行流量数据。
60statistics.getIfaceTxBytes("wlan0").then((stats: number) => {
61  console.log(JSON.stringify(stats));
62});
63
64// 获取蜂窝实时下行流量数据。
65statistics.getCellularRxBytes().then((stats: number) => {
66  console.log(JSON.stringify(stats));
67});
68
69// 获取蜂窝实时上行流量数据。
70statistics.getCellularTxBytes().then((stats: number) => {
71  console.log(JSON.stringify(stats));
72});
73
74// 获取所有网卡实时下行流量数据。
75statistics.getAllRxBytes().then((stats: number) => {
76  console.log(JSON.stringify(stats));
77});
78
79// 获取所有网卡实时上行流量数据。
80statistics.getAllTxBytes().then((stats: number) => {
81  console.log(JSON.stringify(stats));
82});
83
84// 获取指定应用实时下行流量数据。
85let uid = 20010038;
86statistics.getUidRxBytes(uid).then((stats: number) => {
87  console.log(JSON.stringify(stats));
88});
89
90// 获取指定应用实时上行流量数据。
91let uids = 20010038;
92statistics.getUidTxBytes(uids).then((stats: number) => {
93  console.log(JSON.stringify(stats));
94});
95
96// 获取指定socket实时下行流量数据。
97let tcp: socket.TCPSocket = socket.constructTCPSocketInstance();
98tcp.getSocketFd().then((sockfd: number) => {
99  statistics.getSockfdRxBytes(sockfd).then((stats: number) => {
100    console.log(JSON.stringify(stats));
101  }).catch((err: BusinessError) => {
102    console.error(JSON.stringify(err));
103  });
104});
105
106// 获取指定socket实时上行流量数据。
107tcp.getSocketFd().then((sockfd: number) => {
108  statistics.getSockfdTxBytes(sockfd).then((stats: number) => {
109    console.log(JSON.stringify(stats));
110  }).catch((err: BusinessError) => {
111    console.error(JSON.stringify(err));
112  });
113});
114```
115
116<!--Del-->
117## 获取网卡/UID 的历史流量统计数据
118
1191. 获取指定网卡历史流量信息。
1202. 获取指定应用历史流量信息。
121
122```ts
123import { statistics } from '@kit.NetworkKit';
124import { BusinessError } from '@kit.BasicServicesKit';
125
126class IfaceInfo {
127  iface: string = "wlan0"
128  startTime: number = 1685948465
129  endTime: number = 16859485670
130}
131// 获取指定网卡历史流量信息。
132statistics.getTrafficStatsByIface(new IfaceInfo()).then((statsInfo: statistics.NetStatsInfo) => {
133  console.log(
134    "getTrafficStatsByIface bytes of received = " +
135    JSON.stringify(statsInfo.rxBytes)
136  );
137  console.log(
138    "getTrafficStatsByIface bytes of sent = " +
139    JSON.stringify(statsInfo.txBytes)
140  );
141  console.log(
142    "getTrafficStatsByIface packets of received = " +
143    JSON.stringify(statsInfo.rxPackets)
144  );
145  console.log(
146    "getTrafficStatsByIface packets of sent = " +
147    JSON.stringify(statsInfo.txPackets)
148  );
149});
150
151class UidInfo {
152  uid: number = 20010037
153  ifaceInfo: IfaceInfo = new IfaceInfo()
154}
155
156let uidInfo = new UidInfo()
157
158// 获取指定应用历史流量信息。
159statistics.getTrafficStatsByUid(uidInfo).then((statsInfo: statistics.NetStatsInfo) => {
160  console.log("getTrafficStatsByUid bytes of received = " + JSON.stringify(statsInfo.rxBytes));
161  console.log("getTrafficStatsByUid bytes of sent = " + JSON.stringify(statsInfo.txBytes));
162  console.log("getTrafficStatsByUid packets of received = " + JSON.stringify(statsInfo.rxPackets));
163  console.log("getTrafficStatsByUid packets of sent = " + JSON.stringify(statsInfo.txPackets));
164})
165```
166
167## 订阅流量变化事件
168
1691. 订阅流量改变事件通知。
1702. 取消订阅流量改变事件通知。
171
172```ts
173import { statistics } from '@kit.NetworkKit';
174
175class Data {
176  iface: string = ""
177  uid?: number = 0
178}
179
180let callback = (data: Data) => {
181  console.log('on netStatsChange, data:' + JSON.stringify(data));
182};
183// 订阅流量改变事件通知。
184statistics.on('netStatsChange', callback);
185
186// 取消订阅流量改变事件通知。可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。
187statistics.off('netStatsChange', callback);
188statistics.off('netStatsChange');
189```
190<!--DelEnd-->