1# @ohos.net.statistics (流量管理)（系统接口） 2 3流量管理模块，支持基于网卡/UID 的实时流量统计和历史流量统计查询能力。 4 5> **说明：** 6> 本模块首批接口从 API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.net.statistics (流量管理)](js-apis-net-statistics.md) 8 9## 导入模块 10 11```js 12import { statistics } from '@kit.NetworkKit'; 13``` 14 15 16## statistics.on('netStatsChange')<sup>10+</sup> 17 18on(type: 'netStatsChange', callback: Callback\<NetStatsChangeInfo\>): void 19 20订阅流量改变事件通知。 21 22**系统接口**：此接口为系统接口。 23 24**需要权限**：ohos.permission.GET_NETWORK_STATS 25 26**系统能力**：SystemCapability.Communication.NetManager.Core 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| -------- | ------------------------------------------- | ---- | ----------------------------------------------------------------- | 32| type | string | 是 | 订阅事件，固定为'netStatsChange'。 | 33| callback | Callback\<[NetStatsChangeInfo](#netstatschangeinfo11)\> | 是 | 当流量有改变时触发回调函数。 | 34 35**错误码：** 36 37以下错误码的详细介绍参见[statistics 错误码](errorcode-net-statistics.md)。 38 39| 错误码 ID | 错误信息 | 40| --------- | -------------------------------------------- | 41| 201 | Permission denied. | 42| 202 | Non-system applications use system APIs. | 43| 401 | Parameter error. | 44| 2100002 | Failed to connect to the service. | 45| 2100003 | System internal error. | 46 47**示例：** 48 49```js 50import { statistics } from '@kit.NetworkKit'; 51 52class IFace { 53 iface: string = "" 54 uid?: number = 0 55} 56statistics.on('netStatsChange', (data: IFace) => { 57 console.log('on netStatsChange' + JSON.stringify(data)); 58}); 59``` 60 61## statistics.off('netStatsChange')<sup>10+</sup> 62 63off(type: 'netStatsChange', callback?: Callback\<NetStatsChangeInfo>): void; 64 65取消订阅流量改变事件通知。 66 67**系统接口**：此接口为系统接口。 68 69**需要权限**：ohos.permission.GET_NETWORK_STATS 70 71**系统能力**：SystemCapability.Communication.NetManager.Core 72 73**参数：** 74 75| 参数名 | 类型 | 必填 | 说明 | 76| -------- | ------------------------------------------- | ---- | ----------------------------------------------------------------- | 77| type | string | 是 | 注销订阅事件，固定为'netStatsChange'。 | 78| callback | Callback\<[NetStatsChangeInfo](#netstatschangeinfo11)\> | 否 | 当流量有改变时触发回调函数。 | 79 80**错误码：** 81 82以下错误码的详细介绍参见[statistics 错误码](errorcode-net-statistics.md)。 83 84| 错误码 ID | 错误信息 | 85| --------- | -------------------------------------------- | 86| 201 | Permission denied. | 87| 202 | Non-system applications use system APIs. | 88| 401 | Parameter error. | 89| 2100002 | Failed to connect to the service. | 90| 2100003 | System internal error. | 91 92**示例：** 93 94```js 95import { statistics } from '@kit.NetworkKit'; 96 97class IFace { 98 iface: string = "" 99 uid?: number = 0 100} 101let callback: (data: IFace) => void = (data: IFace) => { 102 console.log("on netStatsChange, iFace:" + data.iface + " uid: " + data.uid); 103} 104statistics.on('netStatsChange', callback); 105// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 106statistics.off('netStatsChange', callback); 107statistics.off('netStatsChange'); 108``` 109 110## statistics.getTrafficStatsByIface<sup>10+</sup> 111 112getTrafficStatsByIface(ifaceInfo: IfaceInfo, callback: AsyncCallback\<NetStatsInfo>): void; 113 114获取指定网卡历史流量信息，使用 callback 方式作为异步方法。 115 116**系统接口**：此接口为系统接口。 117 118**需要权限**：ohos.permission.GET_NETWORK_STATS 119 120**系统能力**：SystemCapability.Communication.NetManager.Core 121 122**参数：** 123 124| 参数名 | 类型 | 必填 | 说明 | 125| --------- | ----------------------------------------------- | ---- | -------------------------------------------------------------------------------------- | 126| ifaceInfo | [IfaceInfo](#ifaceinfo10) | 是 | 指定查询的网卡信息，参见[IfaceInfo](#ifaceinfo10)。 | 127| callback | AsyncCallback\<[NetStatsInfo](#netstatsinfo10)> | 是 | 回调函数。成功时 statsInfo 返回包含网卡历史流量信息，error 为 undefined，否则为错误对象。 | 128 129**错误码：** 130 131以下错误码的详细介绍参见[statistics 错误码](errorcode-net-statistics.md)。 132 133| 错误码 ID | 错误信息 | 134| --------- | -------------------------------------------- | 135| 201 | Permission denied. | 136| 202 | Non-system applications use system APIs. | 137| 401 | Parameter error. | 138| 2100001 | Invalid parameter value. | 139| 2100002 | Failed to connect to the service. | 140| 2100003 | System internal error. | 141| 2103017 | Failed to read the database. | 142 143**示例：** 144 145```js 146import { BusinessError } from '@kit.BasicServicesKit'; 147import { statistics } from '@kit.NetworkKit'; 148 149let iFaceInfo: statistics.IfaceInfo | null = null; 150if (iFaceInfo) { 151 statistics.getTrafficStatsByIface(iFaceInfo as statistics.IfaceInfo, (error: BusinessError, statsInfo: statistics.NetStatsInfo) => { 152 console.log(JSON.stringify(error)); 153 console.log( 154 "getTrafficStatsByIface bytes of received = " + 155 JSON.stringify(statsInfo.rxBytes) 156 ); 157 console.log( 158 "getTrafficStatsByIface bytes of sent = " + 159 JSON.stringify(statsInfo.txBytes) 160 ); 161 console.log( 162 "getTrafficStatsByIface packets of received = " + 163 JSON.stringify(statsInfo.rxPackets) 164 ); 165 console.log( 166 "getTrafficStatsByIface packets of sent = " + 167 JSON.stringify(statsInfo.txPackets) 168 ); 169 }); 170} 171``` 172 173## statistics.getTrafficStatsByIface<sup>10+</sup> 174 175getTrafficStatsByIface(ifaceInfo: IfaceInfo): Promise\<NetStatsInfo>; 176 177获取指定网卡历史流量信息，使用 Promise 方式作为异步方法。 178 179**系统接口**：此接口为系统接口。 180 181**需要权限**：ohos.permission.GET_NETWORK_STATS 182 183**系统能力**：SystemCapability.Communication.NetManager.Core 184 185| 参数名 | 类型 | 必填 | 说明 | 186| --------- | ------------------------- | ---- | --------------------------------------------------- | 187| ifaceInfo | [IfaceInfo](#ifaceinfo10) | 是 | 指定查询的网卡信息，参见[IfaceInfo](#ifaceinfo10)。 | 188 189**返回值：** 190| 类型 | 说明 | 191| -------- | -------- | 192| Promise\<[NetStatsInfo](#netstatsinfo10)> | 以 Promise 形式返回获取结果,返回网卡历史流量信息。 | 193 194**错误码：** 195 196以下错误码的详细介绍参见[statistics 错误码](errorcode-net-statistics.md)。 197 198| 错误码 ID | 错误信息 | 199| --------- | -------------------------------------------- | 200| 201 | Permission denied. | 201| 202 | Non-system applications use system APIs. | 202| 401 | Parameter error. | 203| 2100001 | Invalid parameter value. | 204| 2100002 | Failed to connect to the service. | 205| 2100003 | System internal error. | 206| 2103017 | Failed to read the database. | 207 208**示例：** 209 210```js 211import { statistics } from '@kit.NetworkKit'; 212 213let iFaceInfo: statistics.IfaceInfo | null = null; 214if (iFaceInfo) { 215 statistics.getTrafficStatsByIface(iFaceInfo as statistics.IfaceInfo).then((statsInfo: statistics.NetStatsInfo) => { 216 console.log( 217 "getTrafficStatsByIface bytes of received = " + 218 JSON.stringify(statsInfo.rxBytes) 219 ); 220 console.log( 221 "getTrafficStatsByIface bytes of sent = " + 222 JSON.stringify(statsInfo.txBytes) 223 ); 224 console.log( 225 "getTrafficStatsByIface packets of received = " + 226 JSON.stringify(statsInfo.rxPackets) 227 ); 228 console.log( 229 "getTrafficStatsByIface packets of sent = " + 230 JSON.stringify(statsInfo.txPackets) 231 ); 232 }); 233} 234``` 235 236## statistics.getTrafficStatsByUid<sup>10+</sup> 237 238getTrafficStatsByUid(uidInfo: UidInfo, callback: AsyncCallback\<NetStatsInfo>): void; 239 240获取指定应用历史流量信息，使用 callback 方式作为异步方法。 241 242**系统接口**：此接口为系统接口。 243 244**需要权限**：ohos.permission.GET_NETWORK_STATS 245 246**系统能力**：SystemCapability.Communication.NetManager.Core 247 248**参数：** 249 250| 参数名 | 类型 | 必填 | 说明 | 251| -------- | ----------------------------------------------- | ---- | -------------------------------------------------------------------------------------- | 252| uidInfo | [UidInfo](#uidinfo10) | 是 | 指定查询的应用信息，参见[UidInfo](#uidinfo10)。 | 253| callback | AsyncCallback\<[NetStatsInfo](#netstatsinfo10)> | 是 | 回调函数。成功时 statsInfo 返回包含应用历史流量信息，error 为 undefined，否则为错误对象。 | 254 255**错误码：** 256 257以下错误码的详细介绍参见[statistics 错误码](errorcode-net-statistics.md)。 258 259| 错误码 ID | 错误信息 | 260| --------- | -------------------------------------------- | 261| 201 | Permission denied. | 262| 202 | Non-system applications use system APIs. | 263| 401 | Parameter error. | 264| 2100001 | Invalid parameter value. | 265| 2100002 | Failed to connect to the service. | 266| 2100003 | System internal error. | 267| 2103017 | Failed to read the database. | 268 269**示例：** 270 271```js 272import { BusinessError } from '@kit.BasicServicesKit'; 273import { statistics } from '@kit.NetworkKit'; 274 275let uidInfo: statistics.UidInfo = { 276 uid: 20010037, 277 ifaceInfo: { 278 iface: '', 279 startTime: 1, 280 endTime: 3, 281 } 282} 283 284statistics.getTrafficStatsByUid( 285 uidInfo, 286 (error: BusinessError, statsInfo: statistics.NetStatsInfo) => { 287 console.log(JSON.stringify(error)); 288 console.log( 289 "getTrafficStatsByUid bytes of received = " + 290 JSON.stringify(statsInfo.rxBytes) 291 ); 292 console.log( 293 "getTrafficStatsByUid bytes of sent = " + 294 JSON.stringify(statsInfo.txBytes) 295 ); 296 console.log( 297 "getTrafficStatsByUid packets of received = " + 298 JSON.stringify(statsInfo.rxPackets) 299 ); 300 console.log( 301 "getTrafficStatsByUid packets of sent = " + 302 JSON.stringify(statsInfo.txPackets) 303 ); 304 } 305); 306``` 307 308## statistics.getTrafficStatsByUid<sup>10+</sup> 309 310getTrafficStatsByUid(uidInfo: UidInfo): Promise\<NetStatsInfo>; 311 312获取指定应用历史流量信息，使用 Promise 方式作为异步方法。 313 314**系统接口**：此接口为系统接口。 315 316**需要权限**：ohos.permission.GET_NETWORK_STATS 317 318**系统能力**：SystemCapability.Communication.NetManager.Core 319 320**参数：** 321 322| 参数名 | 类型 | 必填 | 说明 | 323| ------- | --------------------- | ---- | ----------------------------------------------- | 324| uidInfo | [UidInfo](#uidinfo10) | 是 | 指定查询的应用信息，参见[UidInfo](#uidinfo10)。 | 325 326**返回值：** 327 328| 类型 | 说明 | 329| ----------------------------------------- | -------------------------------------------------- | 330| Promise\<[NetStatsInfo](#netstatsinfo10)> | 以 Promise 形式返回获取结果,返回应用历史流量信息。 | 331 332**错误码：** 333 334以下错误码的详细介绍参见[statistics 错误码](errorcode-net-statistics.md)。 335 336| 错误码 ID | 错误信息 | 337| --------- | -------------------------------------------- | 338| 201 | Permission denied. | 339| 202 | Non-system applications use system APIs. | 340| 401 | Parameter error. | 341| 2100001 | Invalid parameter value. | 342| 2100002 | Failed to connect to the service. | 343| 2100003 | System internal error. | 344| 2103017 | Failed to read the database. | 345 346**示例：** 347 348```js 349import statistics from '@ohos.net.statistics' 350 351let uidInfo: statistics.UidInfo = { 352 uid: 20010037, 353 ifaceInfo: { 354 iface: '', 355 startTime: 1, 356 endTime: 3, 357 } 358} 359 360statistics.getTrafficStatsByUid(uidInfo).then((statsInfo: statistics.NetStatsInfo) => { 361 console.log("getTrafficStatsByUid bytes of received = " + JSON.stringify(statsInfo.rxBytes)); 362 console.log("getTrafficStatsByUid bytes of sent = " + JSON.stringify(statsInfo.txBytes)); 363 console.log("getTrafficStatsByUid packets of received = " + JSON.stringify(statsInfo.rxPackets)); 364 console.log("getTrafficStatsByUid packets of sent = " + JSON.stringify(statsInfo.txPackets)); 365}) 366``` 367 368## statistics.getTrafficStatsByNetwork<sup>12+</sup> 369 370getTrafficStatsByNetwork(networkInfo: NetworkInfo): Promise\<UidNetStatsInfo> 371 372获取指定时间段内所有应用在指定网络中的流量使用详情，使用 Promise 方式作为异步方法。 373 374**系统接口**：此接口为系统接口。 375 376**需要权限**：ohos.permission.GET_NETWORK_STATS 377 378**系统能力**：SystemCapability.Communication.NetManager.Core 379 380**参数：** 381 382| 参数名 | 类型 | 必填 | 说明 | 383|-------------|-------------------------------|----|--------------------------------------------| 384| networkInfo | [NetworkInfo](#networkinfo12) | 是 | 指定查询的网络信息，参见[NetworkInfo](#networkinfo12)。 | 385 386**返回值：** 387 388| 类型 | 说明 | 389|-------------------------------------------------|----------------------------------| 390| Promise\<[UidNetStatsInfo](#uidnetstatsinfo12)> | 以 Promise 形式返回获取结果,返回所有应用历史流量信息。 | 391 392**错误码：** 393 394以下错误码的详细介绍参见[statistics 错误码](errorcode-net-statistics.md)。 395 396| 错误码 ID | 错误信息 | 397| --------- | -------------------------------------------- | 398| 201 | Permission denied. | 399| 202 | Non-system applications use system APIs. | 400| 401 | Parameter error. | 401| 2100001 | Invalid parameter value. | 402| 2100002 | Failed to connect to the service. | 403| 2100003 | System internal error. | 404| 2103017 | Failed to read the database. | 405 406**示例** 407 408```js 409import { connection, statistics } from '@kit.NetworkKit'; 410 411let networkInfo: statistics.NetworkInfo = { 412 type: connection.NetBearType.BEARER_CELLULAR, 413 startTime: Math.floor(Date.now() / 1000) - 86400 * 7, 414 endTime: Math.floor(Date.now() / 1000) + 5, 415 simId: 1, 416} 417 418statistics.getTrafficStatsByNetwork(networkInfo).then((statsInfo: statistics.UidNetStatsInfo) => { 419 let rank: Map<string, object> = new Map<string, object>(Object.entries(statsInfo)); 420 rank.forEach((value: object, key: string) => { 421 console.info("getTrafficStatsByNetwork key=" + key + ", value=" + JSON.stringify(value)); 422 }) 423}) 424``` 425 426## statistics.getTrafficStatsByUidNetwork<sup>12+</sup> 427 428getTrafficStatsByUidNetwork(uid: number, networkInfo: NetworkInfo): Promise\<NetStatsInfoSequence> 429 430获取指定时间段内，应用在指定网络中的流量使用详情，使用 Promise 方式作为异步方法。 431 432**系统接口**：此接口为系统接口。 433 434**需要权限**：ohos.permission.GET_NETWORK_STATS 435 436**系统能力**：SystemCapability.Communication.NetManager.Core 437 438**参数：** 439 440| 参数名 | 类型 | 必填 | 说明 | 441|-------------|-------------------------------|----|--------------------------------------------| 442| uid | number | 是 | 指定查询的应用 UID。 | 443| networkInfo | [NetworkInfo](#networkinfo12) | 是 | 指定查询的网络信息，参见[NetworkInfo](#networkinfo12)。 | 444 445**返回值：** 446 447| 类型 | 说明 | 448|-----------------------------------------------------------|----------------------------------| 449| Promise\<[NetStatsInfoSequence](#netstatsinfosequence12)> | 以 Promise 形式返回获取结果,返回应用历史流量统计信息。 | 450 451**错误码：** 452 453以下错误码的详细介绍参见[statistics 错误码](errorcode-net-statistics.md)。 454 455| 错误码 ID | 错误信息 | 456| --------- | -------------------------------------------- | 457| 201 | Permission denied. | 458| 202 | Non-system applications use system APIs. | 459| 401 | Parameter error. | 460| 2100001 | Invalid parameter value. | 461| 2100002 | Failed to connect to the service. | 462| 2100003 | System internal error. | 463| 2103017 | Failed to read the database. | 464 465**示例** 466 467```js 468import { connection, statistics } from '@kit.NetworkKit'; 469 470let uid: number = 20020147; 471let networkInfo: statistics.NetworkInfo = { 472 type: connection.NetBearType.BEARER_CELLULAR, 473 startTime: Math.floor(Date.now() / 1000) - 86400 * 7, 474 endTime: Math.floor(Date.now() / 1000) + 5, 475 simId: 1, 476} 477 478statistics.getTrafficStatsByUidNetwork(uid, networkInfo).then((statsInfoSequence: statistics.NetStatsInfoSequence) => { 479 for (let i = 0; i < statsInfoSequence.length; i--) { 480 console.info("getTrafficStatsByUidNetwork item:" + JSON.stringify(statsInfoSequence[i])); 481 } 482}) 483``` 484 485## IfaceInfo<sup>10+</sup> 486 487查询网卡历史流量参数信息。 488 489**系统接口**：此接口为系统接口。 490 491**系统能力**：SystemCapability.Communication.NetManager.Core 492 493| 名称 | 类型 | 必填 | 说明 | 494| --------- | ------ | ---- | --------------------------------- | 495| iface | string | 是 | 查询的网卡名。 | 496| startTime | number | 是 | 查询的开始时间(时间戳;单位：秒)。 | 497| endTime | number | 是 | 查询的结束时间(时间戳;单位：秒)。 | 498 499## UidInfo<sup>10+</sup> 500 501查询应用历史流量参数信息。 502 503**系统接口**：此接口为系统接口。 504 505**系统能力**：SystemCapability.Communication.NetManager.Core 506 507| 名称 | 类型 | 必填 | 说明 | 508| --------- | ------------------------------------- | ---- | -------------------------- | 509| ifaceInfo | IfaceInfo\<[IfaceInfo](#ifaceinfo10)> | 是 | 需查询的网卡和时间参数信息。 | 510| uid | number | 是 | 需查询的应用 uid。 | 511 512## NetStatsInfo<sup>10+</sup> 513 514获取的历史流量信息。 515 516**系统接口**：此接口为系统接口。 517 518**系统能力**：SystemCapability.Communication.NetManager.Core 519 520| 名称 | 类型 | 必填 | 说明 | 521| --------- | ------ | ---- | ------------------------ | 522| rxBytes | number | 是 | 流量下行数据(单位:字节)。 | 523| txBytes | number | 是 | 流量上行数据(单位:字节)。 | 524| rxPackets | number | 是 | 流量下行包个数。 | 525| txPackets | number | 是 | 流量上行包个数。 | 526 527## NetStatsChangeInfo<sup>11+</sup> 528 529监听和管理网络接口的状态和使用情况 530 531**系统接口**：此接口为系统接口。 532 533**系统能力**：SystemCapability.Communication.NetManager.Core 534 535| 名称 | 类型 | 必填 | 说明 | 536| --------- | ------ | ---- | --------- | 537| iface | string | 是 | 网卡名称。 | 538| uid | number | 否 | 应用UID。 | 539 540## NetworkInfo<sup>12+</sup> 541 542网络信息。 543 544**系统接口**：此接口为系统接口。 545 546**系统能力**：SystemCapability.Communication.NetManager.Core 547 548| 名称 | 类型 | 必填 | 说明 | 549|-----------|------------------------------------------------------|----|--------------| 550| type | [NetBearType](js-apis-net-connection.md#netbeartype) | 是 | 网络类型。 | 551| startTime | number | 是 | 开始时间戳(单位:秒)。 | 552| endTime | number | 是 | 结束时间戳(单位:秒)。 | 553| simId | number | 否 | SIM 卡 ID。 | 554 555## UidNetStatsInfo<sup>12+</sup> 556 557获取的所有应用历史流量信息。 558 559**系统接口**：此接口为系统接口。 560 561**系统能力**：SystemCapability.Communication.NetManager.Core 562 563| 名称 | 类型 | 必填 | 说明 | 564|-----------|-----------------------------------------------|----|--------------| 565| undefined | [uid:number]: [NetStatsInfo](#netstatsinfo10) | 是 | 所有应用的历史流量信息。 | 566 567## NetStatsInfoSequence<sup>12+</sup> 568 569获取的应用历史流量信息。 570 571**系统接口**：此接口为系统接口。 572 573**系统能力**：SystemCapability.Communication.NetManager.Core 574 575| 名称 | 类型 | 必填 | 说明 | 576|-----------|---------------------------------|----|--------------| 577| startTime | number | 是 | 开始时间戳(单位:秒)。 | 578| endTime | number | 是 | 结束时间戳(单位:秒)。 | 579| info | [NetStatsInfo](#netstatsinfo10) | 是 | 获取的应用历史流量信息。 |