1# @ohos.net.connection (网络连接管理) 2 3网络连接管理提供管理网络一些基础能力，包括获取默认激活的数据网络、获取所有激活数据网络列表、开启关闭飞行模式、获取网络能力信息等功能。 4 5> **说明：** 6> 7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 无特殊说明，接口默认不支持并发。 10 11## 导入模块 12 13```ts 14import { connection } from '@kit.NetworkKit'; 15``` 16 17## connection.createNetConnection 18 19createNetConnection(netSpecifier?: NetSpecifier, timeout?: number): NetConnection 20 21创建一个NetConnection对象，[netSpecifier](#netspecifier)指定关注的网络的各项特征；timeout是超时时间(单位是毫秒)；netSpecifier是timeout的必要条件，两者都没有则表示关注默认网络。 22 23**注意：** createNetConnection注册回调函数的数量不能超过2000（个），否则无法继续注册网络监听。 24 25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 26 27**系统能力**：SystemCapability.Communication.NetManager.Core 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| ------------ | ----------------------------- | ---- | ------------------------------------------------------------ | 33| netSpecifier | [NetSpecifier](#netspecifier) | 否 | 指定网络的各项特征，不指定或为undefined时关注默认网络。 | 34| timeout | number | 否 | 获取netSpecifier指定的网络时的超时时间，传入值需为uint32_t范围内的整数，仅netSpecifier存在时生效，undefined时默认值为0。 | 35 36**返回值：** 37 38| 类型 | 说明 | 39| ------------------------------- | -------------------- | 40| [NetConnection](#netconnection) | 所关注的网络的句柄。 | 41 42**示例：** 43 44```ts 45import { connection } from '@kit.NetworkKit'; 46 47// 关注默认网络, 不需要传参 48let netConnection = connection.createNetConnection(); 49 50// 关注蜂窝网络，需要传入相关网络特征，timeout参数未传入说明未使用超时时间，此时timeout为0 51let netConnectionCellular = connection.createNetConnection({ 52 netCapabilities: { 53 bearerTypes: [connection.NetBearType.BEARER_CELLULAR] 54 } 55}); 56``` 57 58## connection.getDefaultNet 59 60getDefaultNet(callback: AsyncCallback\<NetHandle>): void 61 62获取默认激活的数据网络，使用callback方式作为异步方法。可以使用[getNetCapabilities](#connectiongetnetcapabilities)去获取网络的类型、拥有的能力等信息。 63 64**需要权限**：ohos.permission.GET_NETWORK_INFO 65 66**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 67 68**系统能力**：SystemCapability.Communication.NetManager.Core 69 70**参数：** 71 72| 参数名 | 类型 | 必填 | 说明 | 73| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 74| callback | AsyncCallback\<[NetHandle](#nethandle)> | 是 | 回调函数。当成功获取默认激活的数据网络时，error为undefined，data为默认激活的数据网络；否则为错误对象。 | 75 76**错误码：** 77 78以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 79 80| 错误码ID | 错误信息 | 81| ------- | ----------------------------- | 82| 201 | Permission denied. | 83| 401 | Parameter error. | 84| 2100002 | Failed to connect to the service. | 85| 2100003 | System internal error. | 86 87**示例：** 88 89```ts 90import { connection } from '@kit.NetworkKit'; 91import { BusinessError } from '@kit.BasicServicesKit'; 92 93connection.getDefaultNet((error: BusinessError, data: connection.NetHandle) => { 94 if (error) { 95 console.error(`Failed to get default net. Code:${error.code}, message:${error.message}`); 96 return; 97 } 98 console.info("Succeeded to get data " + JSON.stringify(data)); 99}); 100``` 101 102## connection.getDefaultNet 103 104getDefaultNet(): Promise\<NetHandle> 105 106获取默认激活的数据网络，使用Promise方式作为异步方法。可以使用[getNetCapabilities](#connectiongetnetcapabilities)去获取网络的类型、拥有的能力等信息。 107 108**需要权限**：ohos.permission.GET_NETWORK_INFO 109 110**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 111 112**系统能力**：SystemCapability.Communication.NetManager.Core 113 114**返回值：** 115 116| 类型 | 说明 | 117| --------------------------------- | ------------------------------------- | 118| Promise\<[NetHandle](#nethandle)> | 以Promise形式返回默认激活的数据网络。 | 119 120**错误码：** 121 122以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 123 124| 错误码ID | 错误信息 | 125| ------- | -------------------------------- | 126| 201 | Permission denied. | 127| 2100002 | Failed to connect to the service.| 128| 2100003 | System internal error. | 129 130**示例：** 131 132```ts 133import { connection } from '@kit.NetworkKit'; 134 135connection.getDefaultNet().then((data: connection.NetHandle) => { 136 console.info("Succeeded to get data: " + JSON.stringify(data)); 137}); 138``` 139 140## connection.getDefaultNetSync<sup>9+</sup> 141 142getDefaultNetSync(): NetHandle 143 144使用同步方法获取默认激活的数据网络。可以使用[getNetCapabilities](#connectiongetnetcapabilities)去获取网络的类型、拥有的能力等信息。 145 146**需要权限**：ohos.permission.GET_NETWORK_INFO 147 148**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 149 150**系统能力**：SystemCapability.Communication.NetManager.Core 151 152**返回值：** 153 154| 类型 | 说明 | 155| --------- | ---------------------------------- | 156| [NetHandle](#nethandle) | 以同步方式返回默认激活的数据网络。 | 157 158**错误码：** 159 160以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 161 162| 错误码ID | 错误信息 | 163| ------- | -------------------------------- | 164| 201 | Permission denied. | 165| 2100002 | Failed to connect to the service.| 166| 2100003 | System internal error. | 167 168**示例：** 169 170```ts 171import { connection } from '@kit.NetworkKit'; 172 173let netHandle = connection.getDefaultNetSync(); 174``` 175 176 177## connection.setAppHttpProxy<sup>11+</sup> 178 179setAppHttpProxy(httpProxy: HttpProxy): void 180 181设置网络应用级Http代理配置信息。 182 183**系统能力**：SystemCapability.Communication.NetManager.Core 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| --------- | ------------------------------------------------------------ | ---- | ---------------- | 189| httpProxy | [HttpProxy](#httpproxy10) | 是 | 网络应用级Http代理配置信息。 | 190 191**错误码：** 192 193以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 194 195| 错误码ID | 错误信息 | 196| ------- | ----------------------------- | 197| 401 | Parameter error. | 198| 2100001 | Invalid http proxy. | 199 200**示例：** 201 202```ts 203import { connection } from '@kit.NetworkKit'; 204import { BusinessError } from '@kit.BasicServicesKit'; 205 206let exclusionStr = "192.168,baidu.com"; 207let exclusionArray = exclusionStr.split(','); 208connection.setAppHttpProxy({ 209 host: "192.168.xx.xxx", 210 port: 8080, 211 exclusionList: exclusionArray 212} as connection.HttpProxy); 213``` 214 215**预置锁定证书PIN:** 216 217证书PIN是对证书文件用sha256算法计算出的hash值。对于证书server.pem, 可以用如下openssl命令计算它的PIN: 218 219```shell 220cat server.pem \ 221| sed -n '/-----BEGIN/,/-----END/p' \ 222| openssl x509 -noout -pubkey \ 223| openssl pkey -pubin -outform der \ 224| openssl dgst -sha256 -binary \ 225| openssl enc -base64 226``` 227 228**预置应用级证书:** 229 230直接把证书原文件预置在APP中。目前支持crt和pem格式的证书文件。 231 232**注意：** 233 234当前ohos.net.http和Image组件的证书锁定，会匹配证书链上所有证书的哈希值，如果服务器更新了任意一本证书，都会导致校验失败。如果服务器出现了更新证书的情况，APP版本应当随之更新并推荐消费者尽快升级APP版本，否则可能导致联网失败。 235 236**预置JSON配置文件:** 237 238预置的证书与网络服务器的对应关系通过JSON配置。配置文件在APP中的路径是：src/main/resources/base/profile/network_config.json 239 240**JSON配置文件:** 241 242证书锁定的配置例子如下: 243```json 244{ 245 "network-security-config": { 246 "domain-config": [ 247 { 248 "domains": [ 249 { 250 "include-subdomains": true, 251 "name": "server.com" 252 } 253 ], 254 "pin-set": { 255 "expiration": "2024-11-08", 256 "pin": [ 257 { 258 "digest-algorithm": "sha256", 259 "digest": "FEDCBA987654321" 260 } 261 ] 262 } 263 } 264 ] 265 }, 266 "trust-global-user-ca": false, 267 "trust-current-user-ca": false, 268} 269``` 270 271应用级证书的配置例子如下: 272```json 273{ 274 "network-security-config": { 275 "base-config": { 276 "trust-anchors": [ 277 { 278 "certificates": "/etc/security/certificates" 279 } 280 ] 281 }, 282 "domain-config": [ 283 { 284 "domains": [ 285 { 286 "include-subdomains": true, 287 "name": "example.com" 288 } 289 ], 290 "trust-anchors": [ 291 { 292 "certificates": "/data/storage/el1/bundle/entry/resources/resfile" 293 } 294 ] 295 } 296 ] 297 } 298} 299 300``` 301 302整体、按域名的明文HTTP是否允许的配置例子如下: 303```json 304{ 305 "network-security-config": { 306 "base-config": { 307 "cleartextTrafficPermitted": true 308 }, 309 "domain-config": [ 310 { 311 "domains": [ 312 { 313 "include-subdomains": true, 314 "name": "example.com" 315 } 316 ], 317 "cleartextTrafficPermitted": false 318 } 319 ] 320 } 321} 322 323``` 324 325**各个字段含义。** 326 327**network-security-config(object:网络安全配置)。** 328 329可包含0个或者1个base-config。 330 331必须包含1个domain-config。 332 333**trust-global-user-ca: 是否信任企业MDM系统或设备管理员用户手动安装的CA证书，默认true。** 334 335**trust-current-user-ca: 是否信任当前用户安装的证书，默认true。** 336 337**base-config(object:指示应用程序范围的安全配置)。** 338 339必须包含1个trust-anchors。 340 341可以包含0个或者1个cleartextTrafficPermitted(boolean:指示整体明文HTTP是否允许，默认为true)。 342 343**domain-config(array:指示每个域的安全配置)。** 344 345可以包含任意个item。 346 347item必须包含1个domain。 348 349item可以包含0个或者1个trust-anchors。 350 351item可包含0个或者1个pin-set。 352 353item可以包含0个或者1个cleartextTrafficPermitted(boolean:指示按域名的明文HTTP是否允许，默认为true)。 354 355**trust-anchors(array:受信任的CA)。** 356 357可以包含任意个item。 358 359item必须包含1个certificates(string:CA证书路径)。 360 361**domain(array:域)。** 362 363可以包含任意个item。 364 365item必须包含1个name(string:指示域名)。 366 367item可以包含0个或者1个include-subdomains(boolean:指示规则是否适用于子域)。 368 369**pin-set(object:证书PIN设置)。** 370 371必须包含1个pin。 372 373可以包含0个或者1个expiration(string:指示证书PIN的过期时间)。 374 375**pin(array:证书PIN)。** 376 377可以包含任意个item。 378 379item必须包含1个digest-algorithm(string:指示用于生成pin的摘要算法)。 380 381item必须包含1个digest(string:指示公钥PIN)。 382 383**cleartextTrafficPermitted(boolean:明文HTTP是否允许，默认为true)。** 384 385## connection.getDefaultHttpProxy<sup>10+</sup> 386 387getDefaultHttpProxy(callback: AsyncCallback\<HttpProxy>): void 388 389获取网络默认的代理配置信息。如果设置了全局代理，则会返回全局代理配置信息。如果进程使用[setAppNet](#connectionsetappnet9)绑定到指定[NetHandle](#nethandle)对应的网络，则返回[NetHandle](#nethandle)对应网络的代理配置信息。在其它情况下，将返回默认网络的代理配置信息。使用callback方式作为异步方法。 390 391**系统能力**：SystemCapability.Communication.NetManager.Core 392 393**参数：** 394 395| 参数名 | 类型 | 必填 | 说明 | 396| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 397| callback | AsyncCallback<[HttpProxy](#httpproxy10)> | 是 | 回调函数。当成功获取网络默认的代理配置信息时，error为undefined，data为网络默认的代理配置信息；否则为错误对象。 | 398 399**错误码：** 400 401以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 402 403| 错误码ID | 错误信息 | 404| -------- | -------------------------------------------- | 405| 2100002 | Failed to connect to the service. | 406| 2100003 | System internal error. | 407 408**示例：** 409 410```ts 411import { connection } from '@kit.NetworkKit'; 412import { BusinessError } from '@kit.BasicServicesKit'; 413 414connection.getDefaultHttpProxy((error: BusinessError, data: connection.HttpProxy) => { 415 if (error) { 416 console.error(`Failed to get default http proxy. Code:${error.code}, message:${error.message}`); 417 return; 418 } 419 console.log("Succeeded to get data" + JSON.stringify(data)); 420}); 421``` 422 423## connection.getDefaultHttpProxy<sup>10+</sup> 424 425getDefaultHttpProxy(): Promise\<HttpProxy> 426 427获取网络默认的代理配置信息。如果设置了全局代理，则会返回全局代理配置信息。如果进程使用[setAppNet](#connectionsetappnet9)绑定到指定[NetHandle](#nethandle)对应的网络，则返回[NetHandle](#nethandle)对应网络的代理配置信息。在其它情况下，将返回默认网络的代理配置信息。使用Promise方式作为异步方法。 428 429**系统能力**：SystemCapability.Communication.NetManager.Core 430 431**返回值：** 432 433| 类型 | 说明 | 434| -------------------------------- | ----------------------------------------- | 435| Promise<[HttpProxy](#httpproxy10)> | 以Promise形式返回网络默认的代理配置信息。 | 436 437**错误码：** 438 439以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 440 441| 错误码ID | 错误信息 | 442| -------- | -------------------------------------------- | 443| 2100002 | Failed to connect to the service. | 444| 2100003 | System internal error. | 445 446**示例：** 447 448```ts 449import { connection } from '@kit.NetworkKit'; 450import { BusinessError } from '@kit.BasicServicesKit'; 451 452connection.getDefaultHttpProxy().then((data: connection.HttpProxy) => { 453 console.info(JSON.stringify(data)); 454}).catch((error: BusinessError) => { 455 console.info(JSON.stringify(error)); 456}); 457``` 458 459## connection.getAppNet<sup>9+</sup> 460 461getAppNet(callback: AsyncCallback\<NetHandle>): void 462 463获取App绑定的网络信息，使用callback方式作为异步方法。 464 465**系统能力**：SystemCapability.Communication.NetManager.Core 466 467**参数：** 468 469| 参数名 | 类型 | 必填 | 说明 | 470| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 471| callback | AsyncCallback\<[NetHandle](#nethandle)> | 是 | 回调函数。当成功获取App绑定的网络信息时，error为undefined，data为获取到App绑定的网络信息；否则为错误对象。 | 472 473**错误码：** 474 475以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 476 477| 错误码ID | 错误信息 | 478| ------- | ----------------------------- | 479| 401 | Parameter error. | 480| 2100002 | Failed to connect to the service.| 481| 2100003 | System internal error. | 482 483**示例：** 484 485```ts 486import { connection } from '@kit.NetworkKit'; 487import { BusinessError } from '@kit.BasicServicesKit'; 488 489connection.getAppNet((error: BusinessError, data: connection.NetHandle) => { 490 if (error) { 491 console.error(`Failed to get app net. Code:${error.code}, message:${error.message}`); 492 return; 493 } 494 console.info("Succeeded to get data: " + JSON.stringify(data)); 495}) 496``` 497 498## connection.getAppNet<sup>9+</sup> 499 500getAppNet(): Promise\<NetHandle> 501 502获取App绑定的网络信息，使用Promise方式作为异步方法。 503 504**系统能力**：SystemCapability.Communication.NetManager.Core 505 506**返回值：** 507 508| 类型 | 说明 | 509| --------------------------------- | ------------------------------------- | 510| Promise\<[NetHandle](#nethandle)> | 以Promise形式返回App绑定的网络信息。 | 511 512**错误码：** 513 514以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 515 516| 错误码ID | 错误信息 | 517| ------- | ----------------------------- | 518| 2100002 | Failed to connect to the service.| 519| 2100003 | System internal error. | 520 521**示例：** 522 523```ts 524import { connection } from '@kit.NetworkKit'; 525import { BusinessError } from '@kit.BasicServicesKit'; 526 527connection.getAppNet().then((data: connection.NetHandle) => { 528 console.info(JSON.stringify(data)); 529}).catch((error: BusinessError) => { 530 console.info(JSON.stringify(error)); 531}); 532``` 533 534## connection.getAppNetSync<sup>10+</sup> 535 536getAppNetSync(): NetHandle 537 538使用同步方法获取App绑定的网络信息。 539 540**系统能力**：SystemCapability.Communication.NetManager.Core 541 542**返回值：** 543 544| 类型 | 说明 | 545| --------- | ---------------------------------- | 546| [NetHandle](#nethandle) | 返回APP绑定的数据网络。 | 547 548**错误码：** 549 550以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 551 552| 错误码ID | 错误信息 | 553| ------- | ----------------------------- | 554| 2100002 | Failed to connect to the service.| 555| 2100003 | System internal error. | 556 557**示例：** 558 559```ts 560import { connection } from '@kit.NetworkKit'; 561 562let netHandle = connection.getAppNetSync(); 563``` 564 565## connection.setAppNet<sup>9+</sup> 566 567setAppNet(netHandle: NetHandle, callback: AsyncCallback\<void>): void 568 569绑定App到指定网络，绑定后的App只能通过指定网络访问外网，使用callback方式作为异步方法。 570 571**需要权限**：ohos.permission.INTERNET 572 573**系统能力**：SystemCapability.Communication.NetManager.Core 574 575**参数：** 576 577| 参数名 | 类型 | 必填 | 说明 | 578| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 579| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | 580| callback | AsyncCallback\<void> | 是 | 回调函数。当成功绑定App到指定网络时，error为undefined，否则为错误对象。| 581 582**错误码：** 583 584以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 585 586| 错误码ID | 错误信息 | 587| ------- | ----------------------------- | 588| 201 | Permission denied. | 589| 401 | Parameter error. | 590| 2100001 | Invalid parameter value. | 591| 2100002 | Failed to connect to the service.| 592| 2100003 | System internal error. | 593 594**示例：** 595 596```ts 597import { connection } from '@kit.NetworkKit'; 598import { BusinessError } from '@kit.BasicServicesKit'; 599 600connection.getDefaultNet((error: BusinessError, netHandle: connection.NetHandle) => { 601 if (netHandle.netId == 0) { 602 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 603 return; 604 } 605 connection.setAppNet(netHandle, (error: BusinessError, data: void) => { 606 if (error) { 607 console.error(`Failed to get default net. Code:${error.code}, message:${error.message}`); 608 return; 609 } 610 console.info("Succeeded to get data: " + JSON.stringify(data)); 611 }); 612}); 613``` 614 615## connection.setAppNet<sup>9+</sup> 616 617setAppNet(netHandle: NetHandle): Promise\<void> 618 619绑定App到指定网络，绑定后的App只能通过指定网络访问外网，使用Promise方式作为异步方法。 620 621**需要权限**：ohos.permission.INTERNET 622 623**系统能力**：SystemCapability.Communication.NetManager.Core 624 625**参数：** 626 627| 参数名 | 类型 | 必填 | 说明 | 628| --------- | ------------------------------------------------------------ | ---- | ---------------- | 629| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | 630 631**返回值：** 632 633| 类型 | 说明 | 634| ------------------------------------------- | ----------------------------- | 635| Promise\<void> | 无返回值的Promise对象。 | 636 637**错误码：** 638 639以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 640 641| 错误码ID | 错误信息 | 642| ------- | ----------------------------- | 643| 201 | Permission denied. | 644| 401 | Parameter error. | 645| 2100001 | Invalid parameter value. | 646| 2100002 | Failed to connect to the service.| 647| 2100003 | System internal error. | 648 649**示例：** 650 651```ts 652import { connection } from '@kit.NetworkKit'; 653import { BusinessError } from '@kit.BasicServicesKit'; 654 655connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 656 if (netHandle.netId == 0) { 657 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 658 return; 659 } 660 661 connection.setAppNet(netHandle).then(() => { 662 console.log("success"); 663 }).catch((error: BusinessError) => { 664 console.log(JSON.stringify(error)); 665 }) 666}); 667``` 668 669## connection.getAllNets 670 671getAllNets(callback: AsyncCallback<Array<NetHandle>>): void 672 673获取所有处于连接状态的网络列表，使用callback方式作为异步方法。 674 675**需要权限**：ohos.permission.GET_NETWORK_INFO 676 677**系统能力**：SystemCapability.Communication.NetManager.Core 678 679**参数：** 680 681| 参数名 | 类型 | 必填 | 说明 | 682| -------- | -------- | -------- | -------- | 683| callback | AsyncCallback<Array<[NetHandle](#nethandle)>> | 是 | 回调函数。当成功获取所有处于连接状态的网络列表时，error为undefined，data为激活的数据网络列表；否则为错误对象。| 684 685**错误码：** 686 687以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 688 689| 错误码ID | 错误信息 | 690| ------- | ----------------------------- | 691| 201 | Permission denied. | 692| 401 | Parameter error. | 693| 2100002 | Failed to connect to the service.| 694| 2100003 | System internal error. | 695 696**示例：** 697 698```ts 699import { connection } from '@kit.NetworkKit'; 700import { BusinessError } from '@kit.BasicServicesKit'; 701 702connection.getAllNets((error: BusinessError, data: connection.NetHandle[]) => { 703 if (error) { 704 console.error(`Failed to get all nets. Code:${error.code}, message:${error.message}`); 705 return; 706 } 707 console.info("Succeeded to get data: " + JSON.stringify(data)); 708}); 709``` 710 711## connection.getAllNets 712 713getAllNets(): Promise<Array<NetHandle>> 714 715获取所有处于连接状态的网络列表，使用Promise方式作为异步方法。 716 717**需要权限**：ohos.permission.GET_NETWORK_INFO 718 719**系统能力**：SystemCapability.Communication.NetManager.Core 720 721**返回值：** 722 723| 类型 | 说明 | 724| -------- | -------- | 725| Promise<Array<[NetHandle](#nethandle)>> | 以Promise形式返回激活的数据网络列表。 | 726 727**错误码：** 728 729以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 730 731| 错误码ID | 错误信息 | 732| ------- | ----------------------------- | 733| 201 | Permission denied. | 734| 2100002 | Failed to connect to the service.| 735| 2100003 | System internal error. | 736 737**示例：** 738 739```ts 740import { connection } from '@kit.NetworkKit'; 741 742connection.getAllNets().then((data: connection.NetHandle[]) => { 743 console.info("Succeeded to get data: " + JSON.stringify(data)); 744}); 745``` 746 747## connection.getAllNetsSync<sup>10+</sup> 748 749getAllNetsSync(): Array<NetHandle> 750 751使用同步方法获取所有处于连接状态的网络列表。 752 753**需要权限**：ohos.permission.GET_NETWORK_INFO 754 755**系统能力**：SystemCapability.Communication.NetManager.Core 756 757**返回值：** 758 759| 类型 | 说明 | 760| --------- | ---------------------------------- | 761| Array<[NetHandle](#nethandle)> | 返回激活的数据网络列表。 | 762 763**错误码：** 764 765以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 766 767| 错误码ID | 错误信息 | 768| ------- | ----------------------------- | 769| 201 | Permission denied. | 770| 2100002 | Failed to connect to the service.| 771| 2100003 | System internal error. | 772 773**示例：** 774 775```ts 776import { connection } from '@kit.NetworkKit'; 777 778let netHandle = connection.getAllNetsSync(); 779``` 780 781## connection.getConnectionProperties 782 783getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback\<ConnectionProperties>): void 784 785获取netHandle对应的网络的连接信息，使用callback方式作为异步方法。 786 787**需要权限**：ohos.permission.GET_NETWORK_INFO 788 789**系统能力**：SystemCapability.Communication.NetManager.Core 790 791**参数：** 792 793| 参数名 | 类型 | 必填 | 说明 | 794| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 795| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | 796| callback | AsyncCallback\<[ConnectionProperties](#connectionproperties)> | 是 | 回调函数。当成功获取netHandle对应的网络的连接信息时，error为undefined，data为获取的网络连接信息；否则为错误对象。| 797 798**错误码：** 799 800以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 801 802| 错误码ID | 错误信息 | 803| ------- | ----------------------------- | 804| 201 | Permission denied. | 805| 401 | Parameter error. | 806| 2100001 | Invalid parameter value. | 807| 2100002 | Failed to connect to the service.| 808| 2100003 | System internal error. | 809 810**示例：** 811 812```ts 813import { connection } from '@kit.NetworkKit'; 814import { BusinessError } from '@kit.BasicServicesKit'; 815 816connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 817 if (netHandle.netId == 0) { 818 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 819 return; 820 } 821 connection.getConnectionProperties(netHandle, (error: BusinessError, data: connection.ConnectionProperties) => { 822 if (error) { 823 console.error(`Failed to get connection properties. Code:${error.code}, message:${error.message}`); 824 return; 825 } 826 console.info("Succeeded to get data: " + JSON.stringify(data)); 827 }) 828}); 829``` 830 831## connection.getConnectionProperties 832 833getConnectionProperties(netHandle: NetHandle): Promise\<ConnectionProperties> 834 835获取netHandle对应的网络的连接信息，使用Promise方式作为异步方法。 836 837**需要权限**：ohos.permission.GET_NETWORK_INFO 838 839**系统能力**：SystemCapability.Communication.NetManager.Core 840 841**参数：** 842 843| 参数名 | 类型 | 必填 | 说明 | 844| --------- | ----------------------- | ---- | ---------------- | 845| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | 846 847**返回值：** 848 849| 类型 | 说明 | 850| ------------------------------------------------------- | --------------------------------- | 851| Promise\<[ConnectionProperties](#connectionproperties)> | 以Promise形式返回网络的连接信息。 | 852 853**错误码：** 854 855以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 856 857| 错误码ID | 错误信息 | 858| ------- | ----------------------------- | 859| 201 | Permission denied. | 860| 401 | Parameter error. | 861| 2100001 | Invalid parameter value. | 862| 2100002 | Failed to connect to the service.| 863| 2100003 | System internal error. | 864 865**示例：** 866 867```ts 868import { connection } from '@kit.NetworkKit'; 869 870connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 871 if (netHandle.netId == 0) { 872 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 873 return; 874 } 875 876 connection.getConnectionProperties(netHandle).then((data: connection.ConnectionProperties) => { 877 console.info("Succeeded to get data: " + JSON.stringify(data)); 878 }) 879}); 880``` 881 882## connection.getConnectionPropertiesSync<sup>10+</sup> 883 884getConnectionPropertiesSync(netHandle: NetHandle): ConnectionProperties 885 886获取netHandle对应的网络的连接信息，使用同步方法返回。 887 888**需要权限**：ohos.permission.GET_NETWORK_INFO 889 890**系统能力**：SystemCapability.Communication.NetManager.Core 891 892**参数：** 893 894| 参数名 | 类型 | 必填 | 说明 | 895| --------- | ----------------------- | ---- | ---------------- | 896| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | 897 898**返回值：** 899 900| 类型 | 说明 | 901| ------------------------------------------------------- | --------------------------------- | 902| [ConnectionProperties](#connectionproperties) | 返回网络的连接信息。 | 903 904**错误码：** 905 906以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 907 908| 错误码ID | 错误信息 | 909| ------- | ----------------------------- | 910| 201 | Permission denied. | 911| 401 | Parameter error. | 912| 2100001 | Invalid parameter value. | 913| 2100002 | Failed to connect to the service.| 914| 2100003 | System internal error. | 915 916**示例：** 917 918```ts 919import { connection } from '@kit.NetworkKit'; 920import { BusinessError } from '@kit.BasicServicesKit'; 921 922let netHandle: connection.NetHandle; 923let connectionproperties: connection.ConnectionProperties; 924 925connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 926 if (netHandle.netId == 0) { 927 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 928 return; 929 } 930 netHandle = connection.getDefaultNetSync(); 931 connectionproperties = connection.getConnectionPropertiesSync(netHandle); 932 console.info("Succeeded to get connectionproperties: " + JSON.stringify(connectionproperties)); 933}); 934 935``` 936 937## connection.getNetCapabilities 938 939getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback\<NetCapabilities>): void 940 941获取netHandle对应的网络的能力信息，使用callback方式作为异步方法。 942 943**需要权限**：ohos.permission.GET_NETWORK_INFO 944 945**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 946 947**系统能力**：SystemCapability.Communication.NetManager.Core 948 949**参数：** 950 951| 参数名 | 类型 | 必填 | 说明 | 952| --------- | --------------------------------------------------- | ---- | ------------------------------------------------------------ | 953| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | 954| callback | AsyncCallback\<[NetCapabilities](#netcapabilities)> | 是 | 回调函数。当成功获取netHandle对应的网络的能力信息时，error为undefined，data为获取到的网络能力信息；否则为错误对象。| 955 956**错误码：** 957 958以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 959 960| 错误码ID | 错误信息 | 961| ------- | ----------------------------- | 962| 201 | Permission denied. | 963| 401 | Parameter error. | 964| 2100001 | Invalid parameter value. | 965| 2100002 | Failed to connect to the service.| 966| 2100003 | System internal error. | 967 968**示例：** 969 970```ts 971import { connection } from '@kit.NetworkKit'; 972import { BusinessError } from '@kit.BasicServicesKit'; 973 974connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 975 if (netHandle.netId == 0) { 976 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 977 return; 978 } 979 connection.getNetCapabilities(netHandle, (error: BusinessError, data: connection.NetCapabilities) => { 980 if (error) { 981 console.error(`Failed to get net capabilities. Code:${error.code}, message:${error.message}`); 982 return; 983 } 984 console.info("Succeeded to get data: " + JSON.stringify(data)); 985 }) 986}).catch((error: BusinessError) => { 987 console.error(JSON.stringify(error)); 988}); 989``` 990 991## connection.getNetCapabilities 992 993getNetCapabilities(netHandle: NetHandle): Promise\<NetCapabilities> 994 995获取netHandle对应的网络的能力信息，使用Promise方式作为异步方法。 996 997**需要权限**：ohos.permission.GET_NETWORK_INFO 998 999**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1000 1001**系统能力**：SystemCapability.Communication.NetManager.Core 1002 1003**参数：** 1004 1005| 参数名 | 类型 | 必填 | 说明 | 1006| --------- | ----------------------- | ---- | ---------------- | 1007| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | 1008 1009**返回值：** 1010 1011| 类型 | 说明 | 1012| --------------------------------------------- | --------------------------------- | 1013| Promise\<[NetCapabilities](#netcapabilities)> | 以Promise形式返回网络的能力信息。 | 1014 1015**错误码：** 1016 1017以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1018 1019| 错误码ID | 错误信息 | 1020| ------- | ----------------------------- | 1021| 201 | Permission denied. | 1022| 401 | Parameter error. | 1023| 2100001 | Invalid parameter value. | 1024| 2100002 | Failed to connect to the service.| 1025| 2100003 | System internal error. | 1026 1027**示例：** 1028 1029```ts 1030import { connection } from '@kit.NetworkKit'; 1031 1032connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 1033 if (netHandle.netId == 0) { 1034 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 1035 return; 1036 } 1037 connection.getNetCapabilities(netHandle).then((data: connection.NetCapabilities) => { 1038 console.info("Succeeded to get data: " + JSON.stringify(data)); 1039 }) 1040}).catch((error: BusinessError) => { 1041 console.error(JSON.stringify(error)); 1042}); 1043``` 1044 1045## connection.getNetCapabilitiesSync<sup>10+</sup> 1046 1047getNetCapabilitiesSync(netHandle: NetHandle): NetCapabilities 1048 1049获取netHandle对应的网络的能力信息，使用同步方式返回。 1050 1051**需要权限**：ohos.permission.GET_NETWORK_INFO 1052 1053**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1054 1055**系统能力**：SystemCapability.Communication.NetManager.Core 1056 1057**参数：** 1058 1059| 参数名 | 类型 | 必填 | 说明 | 1060| --------- | ----------------------- | ---- | ---------------- | 1061| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄。 | 1062 1063**返回值：** 1064 1065| 类型 | 说明 | 1066| --------------------------------------------- | --------------------------------- | 1067| [NetCapabilities](#netcapabilities) | 返回网络的能力信息。 | 1068 1069**错误码：** 1070 1071以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1072 1073| 错误码ID | 错误信息 | 1074| ------- | ----------------------------- | 1075| 201 | Permission denied. | 1076| 401 | Parameter error. | 1077| 2100001 | Invalid parameter value. | 1078| 2100002 | Failed to connect to the service.| 1079| 2100003 | System internal error. | 1080 1081**示例：** 1082 1083```ts 1084import { connection } from '@kit.NetworkKit'; 1085import { BusinessError } from '@kit.BasicServicesKit'; 1086 1087let netHandle: connection.NetHandle; 1088let getNetCapabilitiesSync: connection.NetCapabilities; 1089 1090connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 1091 if (netHandle.netId == 0) { 1092 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 1093 return; 1094 } 1095 1096 getNetCapabilitiesSync = connection.getNetCapabilitiesSync(netHandle); 1097 console.info("Succeeded to get net capabilities sync: " + JSON.stringify(getNetCapabilitiesSync)); 1098}); 1099 1100``` 1101 1102## connection.isDefaultNetMetered<sup>9+</sup> 1103 1104isDefaultNetMetered(callback: AsyncCallback\<boolean>): void 1105 1106检查当前网络上的数据流量使用是否被计量，使用callback方式作为异步方法。 1107 1108**需要权限**：ohos.permission.GET_NETWORK_INFO 1109 1110**系统能力**：SystemCapability.Communication.NetManager.Core 1111 1112**参数：** 1113 1114| 参数名 | 类型 | 必填 | 说明 | 1115| -------- | ----------------------- | ---- | -------------------------------------- | 1116| callback | AsyncCallback\<boolean> | 是 | 回调函数。当前网络上的数据流量使用被计量返回true。 | 1117 1118**错误码：** 1119 1120以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1121 1122| 错误码ID | 错误信息 | 1123| ------- | ----------------------------- | 1124| 201 | Permission denied. | 1125| 401 | Parameter error. | 1126| 2100002 | Failed to connect to the service.| 1127| 2100003 | System internal error. | 1128 1129**示例：** 1130 1131```ts 1132import { connection } from '@kit.NetworkKit'; 1133import { BusinessError } from '@kit.BasicServicesKit'; 1134 1135connection.isDefaultNetMetered((error: BusinessError, data: boolean) => { 1136 console.log(JSON.stringify(error)); 1137 console.log('data: ' + data); 1138}); 1139``` 1140 1141## connection.isDefaultNetMetered<sup>9+</sup> 1142 1143isDefaultNetMetered(): Promise\<boolean> 1144 1145检查当前网络上的数据流量使用是否被计量，使用Promise方式作为异步方法。 1146 1147**需要权限**：ohos.permission.GET_NETWORK_INFO 1148 1149**系统能力**：SystemCapability.Communication.NetManager.Core 1150 1151**返回值：** 1152 1153| 类型 | 说明 | 1154| ----------------- | ----------------------------------------------- | 1155| Promise\<boolean> | 以Promise形式返回，当前网络上的数据流量使用被计量true。 | 1156 1157**错误码：** 1158 1159以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1160 1161| 错误码ID | 错误信息 | 1162| ------- | -------------------------------- | 1163| 201 | Permission denied. | 1164| 2100002 | Failed to connect to the service.| 1165| 2100003 | System internal error. | 1166 1167**示例：** 1168 1169```ts 1170import { connection } from '@kit.NetworkKit'; 1171 1172connection.isDefaultNetMetered().then((data: boolean) => { 1173 console.log('data: ' + data); 1174}); 1175``` 1176 1177## connection.isDefaultNetMeteredSync<sup>10+</sup> 1178 1179isDefaultNetMeteredSync(): boolean 1180 1181检查当前网络上的数据流量使用是否被计量，使用同步方式返回。 1182 1183**需要权限**：ohos.permission.GET_NETWORK_INFO 1184 1185**系统能力**：SystemCapability.Communication.NetManager.Core 1186 1187**返回值：** 1188 1189| 类型 | 说明 | 1190| ----------------- | ----------------------------------------------- | 1191| boolean | 当前网络上的数据流量使用被计量true。 | 1192 1193**错误码：** 1194 1195以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1196 1197| 错误码ID | 错误信息 | 1198| ------- | -------------------------------- | 1199| 201 | Permission denied. | 1200| 2100002 | Failed to connect to the service.| 1201| 2100003 | System internal error. | 1202 1203**示例：** 1204 1205```ts 1206import { connection } from '@kit.NetworkKit'; 1207 1208let isMetered = connection.isDefaultNetMeteredSync(); 1209``` 1210 1211## connection.hasDefaultNet 1212 1213hasDefaultNet(callback: AsyncCallback\<boolean>): void 1214 1215检查默认数据网络是否被激活，使用callback方式作为异步方法。如果有默认数据网络，可以使用[getDefaultNet](#connectiongetdefaultnet)去获取。 1216 1217**需要权限**：ohos.permission.GET_NETWORK_INFO 1218 1219**系统能力**：SystemCapability.Communication.NetManager.Core 1220 1221**参数：** 1222 1223| 参数名 | 类型 | 必填 | 说明 | 1224| -------- | ----------------------- | ---- | -------------------------------------- | 1225| callback | AsyncCallback\<boolean> | 是 | 回调函数。默认数据网络被激活返回true。 | 1226 1227**错误码：** 1228 1229以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1230 1231| 错误码ID | 错误信息 | 1232| ------- | --------------------------------- | 1233| 201 | Permission denied. | 1234| 401 | Parameter error. | 1235| 2100002 | Failed to connect to the service. | 1236| 2100003 | System internal error. | 1237 1238**示例：** 1239 1240```ts 1241import { connection } from '@kit.NetworkKit'; 1242import { BusinessError } from '@kit.BasicServicesKit'; 1243 1244connection.hasDefaultNet((error: BusinessError, data: boolean) => { 1245 console.log(JSON.stringify(error)); 1246 console.log('data: ' + data); 1247}); 1248``` 1249 1250## connection.hasDefaultNet 1251 1252hasDefaultNet(): Promise\<boolean> 1253 1254检查默认数据网络是否被激活，使用Promise方式作为异步方法。如果有默认数据网络，可以使用[getDefaultNet](#connectiongetdefaultnet)去获取。 1255 1256**需要权限**：ohos.permission.GET_NETWORK_INFO 1257 1258**系统能力**：SystemCapability.Communication.NetManager.Core 1259 1260**返回值：** 1261 1262| 类型 | 说明 | 1263| ----------------- | ----------------------------------------------- | 1264| Promise\<boolean> | 以Promise形式返回，默认数据网络被激活返回true。 | 1265 1266**错误码：** 1267 1268以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1269 1270| 错误码ID | 错误信息 | 1271| ------- | ----------------------------- | 1272| 201 | Permission denied. | 1273| 2100002 | Failed to connect to the service. | 1274| 2100003 | System internal error. | 1275 1276**示例：** 1277 1278```ts 1279import { connection } from '@kit.NetworkKit'; 1280 1281connection.hasDefaultNet().then((data: boolean) => { 1282 console.log('data: ' + data); 1283}); 1284``` 1285 1286## connection.hasDefaultNetSync<sup>10+</sup> 1287 1288hasDefaultNetSync(): boolean 1289 1290检查默认数据网络是否被激活，使用同步方式返回接口，如果被激活则返回true。 1291 1292**需要权限**：ohos.permission.GET_NETWORK_INFO 1293 1294**系统能力**：SystemCapability.Communication.NetManager.Core 1295 1296**返回值：** 1297 1298| 类型 | 说明 | 1299| ----------------- | ----------------------------------------------- | 1300| boolean | 默认数据网络被激活返回true。 | 1301 1302**错误码：** 1303 1304以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1305 1306| 错误码ID | 错误信息 | 1307| ------- | ----------------------------- | 1308| 201 | Permission denied. | 1309| 2100002 | Failed to connect to the service.| 1310| 2100003 | System internal error. | 1311 1312**示例：** 1313 1314```ts 1315import { connection } from '@kit.NetworkKit'; 1316 1317let isDefaultNet = connection.hasDefaultNetSync(); 1318``` 1319 1320 1321## connection.reportNetConnected 1322 1323reportNetConnected(netHandle: NetHandle, callback: AsyncCallback<void>): void 1324 1325向网络管理报告网络处于可用状态，使用callback方式作为异步方法。 1326 1327**需要权限**：ohos.permission.GET_NETWORK_INFO 和 ohos.permission.INTERNET 1328 1329**系统能力**：SystemCapability.Communication.NetManager.Core 1330 1331**参数：** 1332 1333| 参数名 | 类型 | 必填 | 说明 | 1334| -------- | -------- | -------- | -------- | 1335| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄，参考[NetHandle](#nethandle)。 | 1336| callback | AsyncCallback<void> | 是 | 回调函数。当向网络管理报告网络处于可用状态成功，error为undefined，否则为错误对象。 | 1337 1338**错误码：** 1339 1340以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1341 1342| 错误码ID | 错误信息 | 1343| ------- | ----------------------------- | 1344| 201 | Permission denied. | 1345| 401 | Parameter error. | 1346| 2100001 | Invalid parameter value. | 1347| 2100002 | Failed to connect to the service. | 1348| 2100003 | System internal error. | 1349 1350**示例：** 1351 1352```ts 1353import { connection } from '@kit.NetworkKit'; 1354import { BusinessError } from '@kit.BasicServicesKit'; 1355 1356connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 1357 connection.reportNetConnected(netHandle, (error: BusinessError) => { 1358 console.log(JSON.stringify(error)); 1359 }); 1360}); 1361``` 1362 1363## connection.reportNetConnected 1364 1365reportNetConnected(netHandle: NetHandle): Promise\<void\> 1366 1367向网络管理报告网络处于可用状态，使用Promise方式作为异步方法。 1368 1369**需要权限**：ohos.permission.GET_NETWORK_INFO 和 ohos.permission.INTERNET 1370 1371**系统能力**：SystemCapability.Communication.NetManager.Core 1372 1373**参数：** 1374 1375| 参数名 | 类型 | 必填 | 说明 | 1376| -------- | -------- | -------- | -------- | 1377| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄，参考[NetHandle](#nethandle)。 | 1378 1379**返回值：** 1380| 类型 | 说明 | 1381| -------- | -------- | 1382| Promise<void> | 无返回值的Promise对象。 | 1383 1384**错误码：** 1385 1386以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1387 1388| 错误码ID | 错误信息 | 1389| ------- | --------------------------------- | 1390| 201 | Permission denied. | 1391| 401 | Parameter error. | 1392| 2100001 | Invalid parameter value. | 1393| 2100002 | Failed to connect to the service. | 1394| 2100003 | System internal error. | 1395 1396**示例：** 1397 1398```ts 1399import { connection } from '@kit.NetworkKit'; 1400 1401connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 1402 connection.reportNetConnected(netHandle).then(() => { 1403 console.log(`report success`); 1404 }); 1405}); 1406``` 1407 1408## connection.reportNetDisconnected 1409 1410reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback<void>): void 1411 1412向网络管理报告网络处于不可用状态，使用callback方式作为异步方法。 1413 1414**需要权限**：ohos.permission.GET_NETWORK_INFO 和 ohos.permission.INTERNET 1415 1416**系统能力**：SystemCapability.Communication.NetManager.Core 1417 1418**参数：** 1419 1420| 参数名 | 类型 | 必填 | 说明 | 1421| -------- | -------- | -------- | -------- | 1422| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄，参考[NetHandle](#nethandle)。 | 1423| callback | AsyncCallback<void> | 是 | 回调函数。当向网络管理报告网络处于不可用状态成功，error为undefined，否则为错误对象。 | 1424 1425**错误码：** 1426 1427以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1428 1429| 错误码ID | 错误信息 | 1430| ------- | ----------------------------- | 1431| 201 | Permission denied. | 1432| 401 | Parameter error. | 1433| 2100001 | Invalid parameter value. | 1434| 2100002 | Failed to connect to the service. | 1435| 2100003 | System internal error. | 1436 1437**示例：** 1438 1439```ts 1440import { connection } from '@kit.NetworkKit'; 1441 1442connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 1443 connection.reportNetDisconnected(netHandle).then( () => { 1444 console.log(`report success`); 1445 }); 1446}); 1447``` 1448 1449## connection.reportNetDisconnected 1450 1451reportNetDisconnected(netHandle: NetHandle): Promise<void> 1452 1453向网络管理报告网络处于不可用状态，使用Promise方式作为异步方法。 1454 1455**需要权限**：ohos.permission.GET_NETWORK_INFO 和 ohos.permission.INTERNET 1456 1457**系统能力**：SystemCapability.Communication.NetManager.Core 1458 1459**参数：** 1460 1461| 参数名 | 类型 | 必填 | 说明 | 1462| -------- | -------- | -------- | -------- | 1463| netHandle | [NetHandle](#nethandle) | 是 | 数据网络的句柄，参考[NetHandle](#nethandle)。 | 1464 1465**返回值：** 1466| 类型 | 说明 | 1467| -------- | -------- | 1468| Promise<void> | 无返回值的Promise对象。 | 1469 1470**错误码：** 1471 1472以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1473 1474| 错误码ID | 错误信息 | 1475| ------- | --------------------------------- | 1476| 201 | Permission denied. | 1477| 401 | Parameter error. | 1478| 2100001 | Invalid parameter value. | 1479| 2100002 | Failed to connect to the service. | 1480| 2100003 | System internal error. | 1481 1482**示例：** 1483 1484```ts 1485import { connection } from '@kit.NetworkKit'; 1486 1487connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 1488 connection.reportNetDisconnected(netHandle).then( () => { 1489 console.log(`report success`); 1490 }); 1491}); 1492``` 1493 1494## connection.getAddressesByName 1495 1496getAddressesByName(host: string, callback: AsyncCallback\<Array\<NetAddress>>): void 1497 1498使用对应网络解析主机名以获取所有IP地址，使用callback方式作为异步方法。 1499 1500**需要权限**：ohos.permission.INTERNET 1501 1502**系统能力**：SystemCapability.Communication.NetManager.Core 1503 1504**参数：** 1505 1506| 参数名 | 类型 | 必填 | 说明 | 1507| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 1508| host | string | 是 | 需要解析的主机名。 | 1509| callback | AsyncCallback\<Array\<[NetAddress](#netaddress)>> | 是 | 回调函数。当使用默认网络解析主机名成功获取所有IP地址，error为undefined，data为获取到的所有IP地址；否则为错误对象。 | 1510 1511**错误码：** 1512 1513以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1514 1515| 错误码ID | 错误信息 | 1516| ------- | --------------------------------- | 1517| 201 | Permission denied. | 1518| 401 | Parameter error. | 1519| 2100001 | Invalid parameter value. | 1520| 2100002 | Failed to connect to the service. | 1521| 2100003 | System internal error. | 1522 1523**示例：** 1524 1525```ts 1526import { connection } from '@kit.NetworkKit'; 1527import { BusinessError } from '@kit.BasicServicesKit'; 1528 1529connection.getAddressesByName("xxxx", (error: BusinessError, data: connection.NetAddress[]) => { 1530 if (error) { 1531 console.error(`Failed to get addresses. Code:${error.code}, message:${error.message}`); 1532 return; 1533 } 1534 console.info("Succeeded to get data: " + JSON.stringify(data)); 1535}); 1536``` 1537 1538## connection.getAddressesByName 1539 1540getAddressesByName(host: string): Promise\<Array\<NetAddress\>\> 1541 1542使用对应网络解析主机名以获取所有IP地址，使用Promise方式作为异步方法。 1543 1544**需要权限**：ohos.permission.INTERNET 1545 1546**系统能力**：SystemCapability.Communication.NetManager.Core 1547 1548**参数：** 1549 1550| 参数名 | 类型 | 必填 | 说明 | 1551| ------ | ------ | ---- | ------------------ | 1552| host | string | 是 | 需要解析的主机名。 | 1553 1554**返回值：** 1555 1556| 类型 | 说明 | 1557| ------------------------------------------- | ----------------------------- | 1558| Promise\<Array\<[NetAddress](#netaddress)>> | 以Promise形式返回所有IP地址。 | 1559 1560**错误码：** 1561 1562以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1563 1564| 错误码ID | 错误信息 | 1565| ------- | ----------------------------- | 1566| 201 | Permission denied. | 1567| 401 | Parameter error. | 1568| 2100001 | Invalid parameter value. | 1569| 2100002 | Failed to connect to the service. | 1570| 2100003 | System internal error. | 1571 1572**示例：** 1573 1574```ts 1575import { connection } from '@kit.NetworkKit'; 1576 1577connection.getAddressesByName("xxxx").then((data: connection.NetAddress[]) => { 1578 console.info("Succeeded to get data: " + JSON.stringify(data)); 1579}); 1580``` 1581 1582## connection.addCustomDnsRule<sup>11+</sup> 1583 1584addCustomDnsRule(host: string, ip: Array\<string\>, callback: AsyncCallback\<void\>): void 1585 1586为当前应用程序添加自定义host和对应的IP地址的映射，使用callback方式作为异步方法。 1587 1588**需要权限**：ohos.permission.INTERNET 1589 1590**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1591 1592**系统能力**：SystemCapability.Communication.NetManager.Core 1593 1594**参数：** 1595 1596| 参数名 | 类型 | 必填 | 说明 | 1597| -------- | -------------------- | ---- | ------------------------------------------------------------ | 1598| host | string | 是 | 需要自定义解析的主机名。 | 1599| ip | Array\<string> | 是 | 主机名所映射的IP地址列表。 | 1600| callback | AsyncCallback\<void> | 是 | 回调函数。当为当前应用程序添加自定义host和对应的ip地址的映射成功，error为undefined，否则为错误对象。 | 1601 1602**错误码：** 1603 1604以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1605 1606| 错误码ID | 错误信息 | 1607| ------- | --------------------------------- | 1608| 201 | Permission denied. | 1609| 401 | Parameter error. | 1610| 2100001 | Invalid parameter value. | 1611| 2100002 | Failed to connect to the service. | 1612| 2100003 | System internal error. | 1613 1614**示例：** 1615 1616```ts 1617import { connection } from '@kit.NetworkKit'; 1618import { BusinessError } from '@kit.BasicServicesKit'; 1619 1620connection.addCustomDnsRule("xxxx", ["xx.xx.xx.xx","xx.xx.xx.xx"], (error: BusinessError, data: void) => { 1621 if (error) { 1622 console.error(`Failed to get add custom dns rule. Code:${error.code}, message:${error.message}`); 1623 return; 1624 } 1625 console.info("Succeeded to get data: " + JSON.stringify(data)); 1626}) 1627``` 1628 1629## connection.addCustomDnsRule<sup>11+</sup> 1630 1631addCustomDnsRule(host: string, ip: Array\<string\>): Promise\<void\> 1632 1633为当前应用程序添加自定义host和对应的IP地址的映射，使用Promise方式作为异步方法。 1634 1635**需要权限**：ohos.permission.INTERNET 1636 1637**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1638 1639**系统能力**：SystemCapability.Communication.NetManager.Core 1640 1641**参数：** 1642 1643| 参数名 | 类型 | 必填 | 说明 | 1644| ------ | -------------- | ---- | -------------------------- | 1645| host | string | 是 | 需要自定义解析的主机名。 | 1646| ip | Array\<string> | 是 | 主机名所映射的IP地址列表。 | 1647 1648**返回值：** 1649 1650| 类型 | 说明 | 1651| ---------------------- | ----------------------- | 1652| Promise\<Array\<void>> | 无返回值的Promise对象。 | 1653 1654**错误码：** 1655 1656以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1657 1658| 错误码ID | 错误信息 | 1659| ------- | --------------------------------- | 1660| 201 | Permission denied. | 1661| 401 | Parameter error. | 1662| 2100001 | Invalid parameter value. | 1663| 2100002 | Failed to connect to the service. | 1664| 2100003 | System internal error. | 1665 1666**示例：** 1667 1668```ts 1669import { connection } from '@kit.NetworkKit'; 1670import { BusinessError } from '@kit.BasicServicesKit'; 1671 1672connection.addCustomDnsRule("xxxx", ["xx.xx.xx.xx","xx.xx.xx.xx"]).then(() => { 1673 console.info("success"); 1674}).catch((error: BusinessError) => { 1675 console.error(JSON.stringify(error)); 1676}) 1677``` 1678 1679## connection.removeCustomDnsRule<sup>11+</sup> 1680 1681removeCustomDnsRule(host: string, callback: AsyncCallback\<void\>): void 1682 1683删除当前应用程序中对应host的自定义DNS规则，使用callback方式作为异步方法。 1684 1685**需要权限**：ohos.permission.INTERNET 1686 1687**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1688 1689**系统能力**：SystemCapability.Communication.NetManager.Core 1690 1691**参数：** 1692 1693| 参数名 | 类型 | 必填 | 说明 | 1694| -------- | -------------------- | ---- | ------------------------------------------------------------ | 1695| host | string | 是 | 需要删除自定义DNS规则的主机名。 | 1696| callback | AsyncCallback\<void> | 是 | 回调函数。当删除当前应用程序中对应host的自定义DNS规则成功，error为undefined，否则为错误对象。 | 1697 1698**错误码：** 1699 1700以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1701 1702| 错误码ID | 错误信息 | 1703| ------- | ----------------------------- | 1704| 201 | Permission denied. | 1705| 401 | Parameter error. | 1706| 2100001 | Invalid parameter value. | 1707| 2100002 | Failed to connect to the service. | 1708| 2100003 | System internal error. | 1709 1710**示例：** 1711 1712```ts 1713import { connection } from '@kit.NetworkKit'; 1714import { BusinessError } from '@kit.BasicServicesKit'; 1715 1716connection.removeCustomDnsRule("xxxx", (error: BusinessError, data: void) => { 1717 if (error) { 1718 console.error(`Failed to remove custom dns rule. Code:${error.code}, message:${error.message}`); 1719 return; 1720 } 1721 console.info("Succeeded to get data: " + JSON.stringify(data)); 1722}) 1723``` 1724 1725## connection.removeCustomDnsRule<sup>11+</sup> 1726 1727removeCustomDnsRule(host: string): Promise\<void\> 1728 1729删除当前应用程序中对应host的自定义DNS规则，使用Promise方式作为异步方法。 1730 1731**需要权限**：ohos.permission.INTERNET 1732 1733**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1734 1735**系统能力**：SystemCapability.Communication.NetManager.Core 1736 1737**参数：** 1738 1739| 参数名 | 类型 | 必填 | 说明 | 1740| ------ | ------ | ---- | ------------------------------- | 1741| host | string | 是 | 需要删除自定义DNS规则的主机名。 | 1742 1743**返回值：** 1744 1745| 类型 | 说明 | 1746| ---------------------- | ----------------------- | 1747| Promise\<Array\<void>> | 无返回值的Promise对象。 | 1748 1749**错误码：** 1750 1751以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1752 1753| 错误码ID | 错误信息 | 1754| ------- | --------------------------------- | 1755| 201 | Permission denied. | 1756| 401 | Parameter error. | 1757| 2100001 | Invalid parameter value. | 1758| 2100002 | Failed to connect to the service. | 1759| 2100003 | System internal error. | 1760 1761**示例：** 1762 1763```ts 1764import { connection } from '@kit.NetworkKit'; 1765import { BusinessError } from '@kit.BasicServicesKit'; 1766 1767connection.removeCustomDnsRule("xxxx").then(() => { 1768 console.log("success"); 1769}).catch((error: BusinessError) => { 1770 console.log(JSON.stringify(error)); 1771}) 1772``` 1773 1774## connection.clearCustomDnsRules<sup>11+</sup> 1775 1776clearCustomDnsRules(callback: AsyncCallback\<void\>): void 1777 1778删除当前应用程序的所有的自定义DNS规则，使用callback方式作为异步方法。 1779 1780**需要权限**：ohos.permission.INTERNET 1781 1782**系统能力**：SystemCapability.Communication.NetManager.Core 1783 1784**参数：** 1785 1786| 参数名 | 类型 | 必填 | 说明 | 1787| -------- | -------------------- | ---- | ------------------------------------------------------------ | 1788| callback | AsyncCallback\<void> | 是 | 回调函数。当删除当前应用程序的所有的自定义DNS规则成功，error为undefined，否则为错误对象。 | 1789 1790**错误码：** 1791 1792以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1793 1794| 错误码ID| 错误信息 | 1795| ------- | --------------------------------- | 1796| 201 | Permission denied. | 1797| 401 | Parameter error. | 1798| 2100001 | Invalid parameter value. | 1799| 2100002 | Failed to connect to the service. | 1800| 2100003 | System internal error. | 1801 1802**示例：** 1803 1804```ts 1805import { connection } from '@kit.NetworkKit'; 1806import { BusinessError } from '@kit.BasicServicesKit'; 1807 1808connection.clearCustomDnsRules((error: BusinessError, data: void) => { 1809 if (error) { 1810 console.error(`Failed to clear custom dns rules. Code:${error.code}, message:${error.message}`); 1811 return; 1812 } 1813 console.info("Succeeded to get data: " + JSON.stringify(data)); 1814}) 1815``` 1816 1817## connection.clearCustomDnsRules<sup>11+</sup> 1818 1819clearCustomDnsRules(): Promise\<void\> 1820 1821删除当前应用程序的所有的自定义DNS规则，使用Promise方式作为异步方法。 1822 1823**需要权限**：ohos.permission.INTERNET 1824 1825**系统能力**：SystemCapability.Communication.NetManager.Core 1826 1827**返回值：** 1828 1829| 类型 | 说明 | 1830| ---------------------- | ----------------------- | 1831| Promise\<void\> | 无返回值的Promise对象。 | 1832 1833**错误码：** 1834 1835以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1836 1837| 错误码ID | 错误信息 | 1838| ------- | --------------------------------- | 1839| 201 | Permission denied. | 1840| 2100001 | Invalid parameter value. | 1841| 2100002 | Failed to connect to the service. | 1842| 2100003 | System internal error. | 1843 1844**示例：** 1845 1846```ts 1847import { connection } from '@kit.NetworkKit'; 1848import { BusinessError } from '@kit.BasicServicesKit'; 1849 1850connection.clearCustomDnsRules().then(() => { 1851 console.log("success"); 1852}).catch((error: BusinessError) => { 1853 console.log(JSON.stringify(error)); 1854}) 1855``` 1856 1857## connection.setPacUrl<sup>15+</sup> 1858 1859setPacUrl(pacUrl: string): void 1860 1861设置系统级代理自动配置（PAC）脚本地址。 1862 1863**需要权限**：ohos.permission.SET_PAC_URL 1864 1865**系统能力**：SystemCapability.Communication.NetManager.Core 1866 1867**参数：** 1868 1869| 参数名 | 类型 | 必填 | 说明 | 1870| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 1871| pacUrl | string | 是 | 需要设置的PAC脚本地址，该接口不会对脚本地址进行校验。 | 1872 1873**错误码：** 1874 1875以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1876 1877| 错误码ID | 错误信息 | 1878| ------- | --------------------------------- | 1879| 201 | Permission denied. | 1880| 401 | Parameter error. | 1881| 2100002 | Failed to connect to the service. | 1882| 2100003 | System internal error. | 1883 1884**示例：** 1885 1886```ts 1887import { connection } from '@kit.NetworkKit'; 1888 1889let pacUrl = "xxx"; 1890connection.setPacUrl(pacUrl); 1891``` 1892 1893## connection.getPacUrl<sup>15+</sup> 1894 1895getPacUrl(): string 1896 1897获取系统级代理自动配置（PAC）脚本地址。 1898 1899**系统能力**：SystemCapability.Communication.NetManager.Core 1900 1901**返回值：** 1902 1903| 类型 | 说明 | 1904| ---------------------- | ----------------------- | 1905| string | 返回PAC脚本地址。不存在时，抛出2100003错误码。 | 1906 1907**错误码：** 1908 1909以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1910 1911| 错误码ID | 错误信息 | 1912| ------- | --------------------------------- | 1913| 2100002 | Failed to connect to the service. | 1914| 2100003 | System internal error. | 1915 1916**示例：** 1917 1918```ts 1919import { connection } from '@kit.NetworkKit'; 1920 1921let pacUrl = connection.getPacUrl(); 1922``` 1923 1924 1925## NetConnection 1926 1927网络连接的句柄。 1928 1929> **说明：** 1930> 设备从无网络到有网络会触发netAvailable事件、netCapabilitiesChange事件和netConnectionPropertiesChange事件； 1931> 设备从有网络到无网络状态会触发netLost事件； 1932> 设备从WiFi到蜂窝会触发netLost事件（WiFi丢失）之后触发 netAvailable事件（蜂窝可用）； 1933 1934### register 1935 1936register(callback: AsyncCallback\<void>): void 1937 1938订阅指定网络状态变化的通知。 1939 1940**需要权限**：ohos.permission.GET_NETWORK_INFO 1941 1942**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1943 1944**系统能力**：SystemCapability.Communication.NetManager.Core 1945 1946**参数：** 1947 1948| 参数名 | 类型 | 必填 | 说明 | 1949| -------- | -------------------- | ---- | ------------------------------------------------------------ | 1950| callback | AsyncCallback\<void> | 是 | 回调函数。当订阅指定网络状态变化的通知成功，error为undefined，否则为错误对象。 | 1951 1952**错误码：** 1953 1954以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1955 1956| 错误码ID | 错误信息 | 1957| ------- | ---------------------------------------------------- | 1958| 201 | Permission denied. | 1959| 401 | Parameter error. | 1960| 2100002 | Failed to connect to the service. | 1961| 2100003 | System internal error. | 1962| 2101008 | The callback already exists. | 1963| 2101022 | The number of requests exceeded the maximum allowed. | 1964 1965**示例：** 1966 1967```ts 1968import { connection } from '@kit.NetworkKit'; 1969import { BusinessError } from '@kit.BasicServicesKit'; 1970 1971let netCon: connection.NetConnection = connection.createNetConnection(); 1972netCon.register((error: BusinessError) => { 1973 console.log(JSON.stringify(error)); 1974}); 1975``` 1976 1977### unregister 1978 1979unregister(callback: AsyncCallback\<void>): void 1980 1981取消订阅默认网络状态变化的通知。可在业务逻辑处理结束时取消订阅，但不应该放在事件回调函数中调用。 1982 1983**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1984 1985**系统能力**：SystemCapability.Communication.NetManager.Core 1986 1987**参数：** 1988 1989| 参数名 | 类型 | 必填 | 说明 | 1990| -------- | -------------------- | ---- | ------------------------------------------------------------ | 1991| callback | AsyncCallback\<void> | 是 | 回调函数。当取消订阅指定网络状态变化的通知成功，error为undefined，否则为错误对象。 | 1992 1993**错误码：** 1994 1995以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 1996 1997| 错误码ID | 错误信息 | 1998| ------- | --------------------------------- | 1999| 401 | Parameter error. | 2000| 2100002 | Failed to connect to the service. | 2001| 2100003 | System internal error. | 2002| 2101007 | The callback does not exist. | 2003 2004**示例：** 2005 2006```ts 2007import { connection } from '@kit.NetworkKit'; 2008import { BusinessError } from '@kit.BasicServicesKit'; 2009 2010let netCon: connection.NetConnection = connection.createNetConnection(); 2011netCon.unregister((error: BusinessError) => { 2012 console.log(JSON.stringify(error)); 2013}); 2014``` 2015 2016### on('netAvailable') 2017 2018on(type: 'netAvailable', callback: Callback\<NetHandle>): void 2019 2020订阅网络可用事件。此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 2021 2022**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2023 2024**系统能力**：SystemCapability.Communication.NetManager.Core 2025 2026**参数：** 2027 2028| 参数名 | 类型 | 必填 | 说明 | 2029| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ | 2030| type | string | 是 | 订阅事件，固定为'netAvailable'。<br>netAvailable：数据网络可用事件。 | 2031| callback | Callback\<[NetHandle](#nethandle)> | 是 | 回调函数，返回数据网络句柄。| 2032 2033**示例：** 2034 2035```ts 2036import { connection } from '@kit.NetworkKit'; 2037import { BusinessError } from '@kit.BasicServicesKit'; 2038 2039// 创建NetConnection对象 2040let netCon: connection.NetConnection = connection.createNetConnection(); 2041 2042// 先使用register接口注册订阅事件 2043netCon.register((error: BusinessError) => { 2044 console.log(JSON.stringify(error)); 2045}); 2046 2047// 订阅网络可用事件。调用register后，才能接收到此事件通知 2048netCon.on('netAvailable', (data: connection.NetHandle) => { 2049 console.info("Succeeded to get data: " + JSON.stringify(data)); 2050}); 2051 2052// 使用unregister接口取消订阅 2053netCon.unregister((error: BusinessError) => { 2054 console.log(JSON.stringify(error)); 2055}); 2056``` 2057 2058### on('netBlockStatusChange') 2059 2060on(type: 'netBlockStatusChange', callback: Callback\<NetBlockStatusInfo>): void 2061 2062订阅网络阻塞状态事件。此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 2063 2064**系统能力**：SystemCapability.Communication.NetManager.Core 2065 2066**参数：** 2067 2068| 参数名 | 类型 | 必填 | 说明 | 2069| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2070| type | string | 是 | 订阅事件，固定为'netBlockStatusChange'。<br/>netBlockStatusChange：网络阻塞状态事件。 | 2071| callback | Callback<[NetBlockStatusInfo](#netblockstatusinfo11)> | 是 | 回调函数，获取网络阻塞状态信息。| 2072 2073**示例：** 2074 2075```ts 2076import { connection } from '@kit.NetworkKit'; 2077import { BusinessError } from '@kit.BasicServicesKit'; 2078 2079// 创建NetConnection对象 2080let netCon: connection.NetConnection = connection.createNetConnection(); 2081 2082// 先使用register接口注册订阅事件 2083netCon.register((error: BusinessError) => { 2084 console.log(JSON.stringify(error)); 2085}); 2086 2087// 订阅网络阻塞状态事件。调用register后，才能接收到此事件通知 2088netCon.on('netBlockStatusChange', (data: connection.NetBlockStatusInfo) => { 2089 console.info("Succeeded to get data: " + JSON.stringify(data)); 2090}); 2091 2092// 使用unregister接口取消订阅 2093netCon.unregister((error: BusinessError) => { 2094 console.log(JSON.stringify(error)); 2095}); 2096``` 2097 2098### on('netCapabilitiesChange') 2099 2100on(type: 'netCapabilitiesChange', callback: Callback\<NetCapabilityInfo\>): void 2101 2102订阅网络能力变化事件。此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 2103 2104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2105 2106**系统能力**：SystemCapability.Communication.NetManager.Core 2107 2108**参数：** 2109 2110| 参数名 | 类型 | 必填 | 说明 | 2111| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2112| type | string | 是 | 订阅事件，固定为'netCapabilitiesChange'。<br/>netCapabilitiesChange：网络能力变化事件。 | 2113| callback | Callback<[NetCapabilityInfo](#netcapabilityinfo10)> | 是 | 回调函数，返回数据网络句柄(netHandle)和网络的能力信息(netCap)。| 2114 2115**示例：** 2116 2117```ts 2118import { connection } from '@kit.NetworkKit'; 2119import { BusinessError } from '@kit.BasicServicesKit'; 2120 2121// 创建NetConnection对象 2122let netCon: connection.NetConnection = connection.createNetConnection(); 2123 2124// 先使用register接口注册订阅事件 2125netCon.register((error: BusinessError) => { 2126 console.log(JSON.stringify(error)); 2127}); 2128 2129// 订阅网络能力变化事件。调用register后，才能接收到此事件通知 2130netCon.on('netCapabilitiesChange', (data: connection.NetCapabilityInfo) => { 2131 console.info("Succeeded to get data: " + JSON.stringify(data)); 2132}); 2133 2134// 使用unregister接口取消订阅 2135netCon.unregister((error: BusinessError) => { 2136 console.log(JSON.stringify(error)); 2137}); 2138``` 2139 2140### on('netConnectionPropertiesChange') 2141 2142on(type: 'netConnectionPropertiesChange', callback: Callback\<NetConnectionPropertyInfo\>): void 2143 2144订阅网络连接信息变化事件。此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 2145 2146**系统能力**：SystemCapability.Communication.NetManager.Core 2147 2148**参数：** 2149 2150| 参数名 | 类型 | 必填 | 说明 | 2151| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2152| type | string | 是 | 订阅事件，固定为'netConnectionPropertiesChange'。<br/>netConnectionPropertiesChange：网络连接信息变化事件。 | 2153| callback | Callback<[NetConnectionPropertyInfo](#netconnectionpropertyinfo11)> | 是 | 回调函数，获取网络连接属性信息。| 2154 2155**示例：** 2156 2157```ts 2158import { connection } from '@kit.NetworkKit'; 2159import { BusinessError } from '@kit.BasicServicesKit'; 2160 2161// 创建NetConnection对象 2162let netCon: connection.NetConnection = connection.createNetConnection(); 2163 2164// 先使用register接口注册订阅事件 2165netCon.register((error: BusinessError) => { 2166 console.log(JSON.stringify(error)); 2167}); 2168 2169// 订阅网络连接信息变化事件。调用register后，才能接收到此事件通知 2170netCon.on('netConnectionPropertiesChange', (data: connection.NetConnectionPropertyInfo) => { 2171 console.info("Succeeded to get data: " + JSON.stringify(data)); 2172}); 2173 2174// 使用unregister接口取消订阅 2175netCon.unregister((error: BusinessError) => { 2176 console.log(JSON.stringify(error)); 2177}); 2178``` 2179 2180### on('netLost') 2181 2182on(type: 'netLost', callback: Callback\<NetHandle>): void 2183 2184订阅网络丢失事件。此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 2185 2186**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2187 2188**系统能力**：SystemCapability.Communication.NetManager.Core 2189 2190**参数：** 2191 2192| 参数名 | 类型 | 必填 | 说明 | 2193| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ | 2194| type | string | 是 | 订阅事件，固定为'netLost'。<br/>netLost：网络严重中断或正常断开事件。 | 2195| callback | Callback\<[NetHandle](#nethandle)> | 是 | 回调函数，数据网络句柄(netHandle)。| 2196 2197**示例：** 2198 2199```ts 2200import { connection } from '@kit.NetworkKit'; 2201import { BusinessError } from '@kit.BasicServicesKit'; 2202 2203// 创建NetConnection对象 2204let netCon: connection.NetConnection = connection.createNetConnection(); 2205 2206// 先使用register接口注册订阅事件 2207netCon.register((error: BusinessError) => { 2208 console.log(JSON.stringify(error)); 2209}); 2210 2211// 订阅网络丢失事件。调用register后，才能接收到此事件通知 2212netCon.on('netLost', (data: connection.NetHandle) => { 2213 console.info("Succeeded to get data: " + JSON.stringify(data)); 2214}); 2215 2216// 使用unregister接口取消订阅 2217netCon.unregister((error: BusinessError) => { 2218 console.log(JSON.stringify(error)); 2219}); 2220``` 2221 2222### on('netUnavailable') 2223 2224on(type: 'netUnavailable', callback: Callback\<void>): void 2225 2226订阅网络不可用事件。此接口调用之前需要先调用register接口，使用unregister取消订阅默认网络状态变化的通知。 2227 2228**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2229 2230**系统能力**：SystemCapability.Communication.NetManager.Core 2231 2232**参数：** 2233 2234| 参数名 | 类型 | 必填 | 说明 | 2235| -------- | --------------- | ---- | ------------------------------------------------------------ | 2236| type | string | 是 | 订阅事件，固定为'netUnavailable'。<br/>netUnavailable：网络不可用事件。 | 2237| callback | Callback\<void> | 是 | 回调函数，无返回结果。| 2238 2239**示例：** 2240 2241```ts 2242import { connection } from '@kit.NetworkKit'; 2243import { BusinessError } from '@kit.BasicServicesKit'; 2244 2245// 创建NetConnection对象 2246let netCon: connection.NetConnection = connection.createNetConnection(); 2247 2248// 先使用register接口注册订阅事件 2249netCon.register((error: BusinessError) => { 2250 console.log(JSON.stringify(error)); 2251}); 2252 2253// 订阅网络不可用事件。调用register后，才能接收到此事件通知 2254netCon.on('netUnavailable', () => { 2255 console.info("Succeeded to get unavailable net event"); 2256}); 2257 2258// 使用unregister接口取消订阅 2259netCon.unregister((error: BusinessError) => { 2260 console.log(JSON.stringify(error)); 2261}); 2262``` 2263 2264## NetHandle 2265 2266数据网络的句柄。 2267 2268在调用NetHandle的方法之前，需要先获取NetHandle对象。 2269 2270**系统能力**：SystemCapability.Communication.NetManager.Core 2271 2272### 属性 2273 2274| 名称 | 类型 | 必填 | 说明 | 2275| ------ | ------ | --- |------------------------- | 2276| netId | number | 是 | 网络ID，取值为0代表没有默认网络，其余取值必须大于等于100。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2277 2278### bindSocket<sup>9+</sup> 2279 2280bindSocket(socketParam: TCPSocket \| UDPSocket, callback: AsyncCallback\<void>): void 2281 2282将TCPSocket或UDPSocket绑定到当前网络，使用callback方式作为异步方法。 2283 2284**系统能力**：SystemCapability.Communication.NetManager.Core 2285 2286**参数：** 2287 2288| 参数名 | 类型 | 必填 | 说明 | 2289| ----------- | ------------------------ | ---- | -------------------------------| 2290| socketParam | [TCPSocket](js-apis-socket.md#tcpsocket) \| [UDPSocket](js-apis-socket.md#udpsocket) | 是 | 待绑定的TCPSocket或UDPSocket对象。| 2291| callback | AsyncCallback\<void> | 是 | 回调函数。当TCPSocket或UDPSocket成功绑定到当前网络，error为undefined，否则为错误对象。 | 2292 2293**错误码：** 2294 2295以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 2296 2297| 错误码ID | 错误信息 | 2298| ------- | --------------------------------- | 2299| 401 | Parameter error. | 2300| 2100001 | Invalid parameter value. | 2301| 2100002 | Failed to connect to the service. | 2302| 2100003 | System internal error. | 2303 2304**示例：** 2305 2306```ts 2307import { connection, socket } from '@kit.NetworkKit'; 2308import { BusinessError } from '@kit.BasicServicesKit'; 2309 2310interface Data { 2311 message: ArrayBuffer, 2312 remoteInfo: socket.SocketRemoteInfo 2313} 2314 2315 connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 2316 if (netHandle.netId == 0) { 2317 // 当前没有已连接的网络时，获取的netHandler的netid为0,属于异常情况，需要额外处理 2318 } 2319 let tcp : socket.TCPSocket = socket.constructTCPSocketInstance(); 2320 let udp : socket.UDPSocket = socket.constructUDPSocketInstance(); 2321 let socketType = "TCPSocket"; 2322 if (socketType == "TCPSocket") { 2323 tcp.bind({address:"192.168.xxx.xxx", 2324 port:8080, 2325 family:1} as socket.NetAddress, (error: Error) => { 2326 if (error) { 2327 console.log('bind fail'); 2328 return; 2329 } 2330 netHandle.bindSocket(tcp, (error: BusinessError, data: void) => { 2331 if (error) { 2332 console.error(`Failed to bind socket. Code:${error.code}, message:${error.message}`); 2333 return; 2334 } else { 2335 console.info(JSON.stringify(data)); 2336 } 2337 }); 2338 }); 2339 } else { 2340 let callback: (value: Data) => void = (value: Data) => { 2341 console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo); 2342 }; 2343 udp.bind({address:"192.168.xxx.xxx", 2344 port:8080, 2345 family:1} as socket.NetAddress, (error: BusinessError) => { 2346 if (error) { 2347 console.error(`Failed to bind. Code:${error.code}, message:${error.message}`); 2348 return; 2349 } 2350 udp.on('message', (data: Data) => { 2351 console.info("Succeeded to get data: " + JSON.stringify(data)); 2352 }); 2353 netHandle.bindSocket(udp, (error: BusinessError, data: void) => { 2354 if (error) { 2355 console.error(`Failed to bind socket. Code:${error.code}, message:${error.message}`); 2356 return; 2357 } else { 2358 console.info(JSON.stringify(data)); 2359 } 2360 }); 2361 }); 2362 } 2363}) 2364``` 2365 2366### bindSocket<sup>9+</sup> 2367 2368bindSocket(socketParam: TCPSocket \| UDPSocket): Promise\<void\> 2369 2370将TCPSocket或UDPSockett绑定到当前网络，使用Promise方式作为异步方法。 2371 2372**系统能力**：SystemCapability.Communication.NetManager.Core 2373 2374**参数：** 2375 2376| 参数名 | 类型 | 必填 | 说明 | 2377| --------------- | --------------------- | ---- | ------------------------------ | 2378| socketParam | [TCPSocket](js-apis-socket.md#tcpsocket) \| [UDPSocket](js-apis-socket.md#udpsocket) | 是 | 待绑定的TCPSocket或UDPSocket对象。| 2379 2380**返回值：** 2381 2382| 类型 | 说明 | 2383| -------------- | ---------------------- | 2384| Promise\<void> | 无返回值的Promise对象。 | 2385 2386**错误码：** 2387 2388以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 2389 2390| 错误码ID | 错误信息 | 2391| ------- | --------------------------------- | 2392| 401 | Parameter error. | 2393| 2100001 | Invalid parameter value. | 2394| 2100002 | Failed to connect to the service. | 2395| 2100003 | System internal error. | 2396 2397**示例：** 2398 2399```ts 2400import { connection, socket } from '@kit.NetworkKit'; 2401import { BusinessError } from '@kit.BasicServicesKit'; 2402 2403interface Data { 2404 message: ArrayBuffer, 2405 remoteInfo: socket.SocketRemoteInfo 2406} 2407 2408connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 2409 if (netHandle.netId == 0) { 2410 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 2411 return; 2412 } 2413 let tcp : socket.TCPSocket = socket.constructTCPSocketInstance(); 2414 let udp : socket.UDPSocket = socket.constructUDPSocketInstance(); 2415 let socketType = "TCPSocket"; 2416 if (socketType == "TCPSocket") { 2417 tcp.bind({address:"192.168.xxx.xxx", 2418 port:8080, 2419 family:1} as socket.NetAddress, (error: Error) => { 2420 if (error) { 2421 console.log('bind fail'); 2422 return; 2423 } 2424 netHandle.bindSocket(tcp).then(() => { 2425 console.info("bind socket success"); 2426 }).catch((error: BusinessError) => { 2427 console.error(`Failed to bind socket. Code:${error.code}, message:${error.message}`); 2428 }); 2429 }); 2430 } else { 2431 let callback: (value: Data) => void = (value: Data) => { 2432 console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo); 2433 } 2434 udp.bind({address:"192.168.xxx.xxx", 2435 port:8080, 2436 family:1} as socket.NetAddress, (error: BusinessError) => { 2437 if (error) { 2438 console.error(`Failed to bind. Code:${error.code}, message:${error.message}`); 2439 return; 2440 } 2441 udp.on('message', (data: Data) => { 2442 console.info("Succeeded to get data: " + JSON.stringify(data)); 2443 }); 2444 netHandle.bindSocket(udp).then(() => { 2445 console.info("bind socket success"); 2446 }).catch((error: BusinessError) => { 2447 console.error(`Failed to bind socket. Code:${error.code}, message:${error.message}`); 2448 }); 2449 }); 2450 } 2451}); 2452``` 2453 2454### getAddressesByName 2455 2456getAddressesByName(host: string, callback: AsyncCallback\<Array\<NetAddress>\>\): void 2457 2458使用对应网络解析主机名以获取所有IP地址，使用callback方式作为异步方法。 2459 2460**需要权限**：ohos.permission.INTERNET 2461 2462**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 2463 2464**系统能力**：SystemCapability.Communication.NetManager.Core 2465 2466**参数：** 2467 2468| 参数名 | 类型 | 必填 | 说明 | 2469| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 2470| host | string | 是 | 需要解析的主机名。 | 2471| callback | AsyncCallback\<Array\<[NetAddress](#netaddress)>> | 是 | 回调函数。当使用对应网络解析主机名成功获取所有IP地址，error为undefined，data为获取到的所有IP地址；否则为错误对象。 | 2472 2473**错误码：** 2474 2475以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 2476 2477| 错误码ID | 错误信息 | 2478| ------- | --------------------------------- | 2479| 201 | Permission denied. | 2480| 401 | Parameter error. | 2481| 2100001 | Invalid parameter value. | 2482| 2100002 | Failed to connect to the service. | 2483| 2100003 | System internal error. | 2484 2485**示例：** 2486 2487```ts 2488import { connection } from '@kit.NetworkKit'; 2489import { BusinessError } from '@kit.BasicServicesKit'; 2490 2491connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 2492 if (netHandle.netId == 0) { 2493 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 2494 return; 2495 } 2496 let host = "xxxx"; 2497 netHandle.getAddressesByName(host, (error: BusinessError, data: connection.NetAddress[]) => { 2498 if (error) { 2499 console.error(`Failed to get addresses. Code:${error.code}, message:${error.message}`); 2500 return; 2501 } 2502 console.info("Succeeded to get data: " + JSON.stringify(data)); 2503 }); 2504}); 2505``` 2506 2507### getAddressesByName 2508 2509getAddressesByName(host: string): Promise\<Array\<NetAddress>> 2510 2511使用对应网络解析主机名以获取所有IP地址，使用Promise方式作为异步方法。 2512 2513**需要权限**：ohos.permission.INTERNET 2514 2515**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 2516 2517**系统能力**：SystemCapability.Communication.NetManager.Core 2518 2519**参数：** 2520 2521| 参数名 | 类型 | 必填 | 说明 | 2522| ------ | ------ | ---- | ------------------ | 2523| host | string | 是 | 需要解析的主机名。 | 2524 2525**返回值：** 2526 2527| 类型 | 说明 | 2528| ------------------------------------------- | ----------------------------- | 2529| Promise\<Array\<[NetAddress](#netaddress)>> | 以Promise形式返回所有IP地址。 | 2530 2531**错误码：** 2532 2533以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 2534 2535| 错误码ID | 错误信息 | 2536| ------- | --------------------------------- | 2537| 201 | Permission denied. | 2538| 401 | Parameter error. | 2539| 2100001 | Invalid parameter value. | 2540| 2100002 | Failed to connect to the service. | 2541| 2100003 | System internal error. | 2542 2543**示例：** 2544 2545```ts 2546import { connection } from '@kit.NetworkKit'; 2547 2548connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 2549 if (netHandle.netId == 0) { 2550 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 2551 return; 2552 } 2553 let host = "xxxx"; 2554 netHandle.getAddressesByName(host).then((data: connection.NetAddress[]) => { 2555 console.info("Succeeded to get data: " + JSON.stringify(data)); 2556 }); 2557}); 2558``` 2559 2560### getAddressByName 2561 2562getAddressByName(host: string, callback: AsyncCallback\<NetAddress>): void 2563 2564使用对应网络解析主机名以获取第一个IP地址，使用callback方式作为异步方法。 2565 2566**需要权限**：ohos.permission.INTERNET 2567 2568**系统能力**：SystemCapability.Communication.NetManager.Core 2569 2570**参数：** 2571 2572| 参数名 | 类型 | 必填 | 说明 | 2573| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 2574| host | string | 是 | 需要解析的主机名。 | 2575| callback | AsyncCallback\<[NetAddress](#netaddress)> | 是 | 回调函数。当使用对应网络解析主机名获取第一个IP地址成功，error为undefined，data为获取的第一个IP地址；否则为错误对象。 | 2576 2577**错误码：** 2578 2579以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 2580 2581| 错误码ID | 错误信息 | 2582| ------- | --------------------------------- | 2583| 201 | Permission denied. | 2584| 401 | Parameter error. | 2585| 2100001 | Invalid parameter value. | 2586| 2100002 | Failed to connect to the service. | 2587| 2100003 | System internal error. | 2588 2589**示例：** 2590 2591```ts 2592import { connection } from '@kit.NetworkKit'; 2593import { BusinessError } from '@kit.BasicServicesKit'; 2594 2595connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 2596 if (netHandle.netId == 0) { 2597 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 2598 return; 2599 } 2600 let host = "xxxx"; 2601 netHandle.getAddressByName(host, (error: BusinessError, data: connection.NetAddress) => { 2602 if (error) { 2603 console.error(`Failed to get address. Code:${error.code}, message:${error.message}`); 2604 return; 2605 } 2606 console.info("Succeeded to get data: " + JSON.stringify(data)); 2607 }); 2608}); 2609``` 2610 2611### getAddressByName 2612 2613getAddressByName(host: string): Promise\<NetAddress> 2614 2615使用对应网络解析主机名以获取第一个IP地址，使用Promise方式作为异步方法。 2616 2617**需要权限**：ohos.permission.INTERNET 2618 2619**系统能力**：SystemCapability.Communication.NetManager.Core 2620 2621**参数：** 2622 2623| 参数名 | 类型 | 必填 | 说明 | 2624| ------ | ------ | ---- | ------------------ | 2625| host | string | 是 | 需要解析的主机名。 | 2626 2627**返回值：** 2628 2629| 类型 | 说明 | 2630| ----------------------------------- | ------------------------------- | 2631| Promise\<[NetAddress](#netaddress)> | 以Promise形式返回第一个IP地址。 | 2632 2633**错误码：** 2634 2635以下错误码的详细介绍请参见[网络连接管理错误码](errorcode-net-connection.md)。 2636 2637| 错误码ID | 错误信息 | 2638| ------- | --------------------------------- | 2639| 201 | Permission denied. | 2640| 401 | Parameter error. | 2641| 2100001 | Invalid parameter value. | 2642| 2100002 | Failed to connect to the service. | 2643| 2100003 | System internal error. | 2644 2645**示例：** 2646 2647```ts 2648import { connection } from '@kit.NetworkKit'; 2649 2650connection.getDefaultNet().then((netHandle: connection.NetHandle) => { 2651 if (netHandle.netId == 0) { 2652 // 当前没有已连接的网络时，获取的netHandler的netid为0，属于异常场景，此处可以实际情况自行添加一些处理机制。 2653 return; 2654 } 2655 let host = "xxxx"; 2656 netHandle.getAddressByName(host).then((data: connection.NetAddress) => { 2657 console.info("Succeeded to get data: " + JSON.stringify(data)); 2658 }); 2659}); 2660``` 2661 2662## NetCap 2663 2664网络具体能力。 2665 2666**系统能力**：SystemCapability.Communication.NetManager.Core 2667 2668| 名称 | 值 | 说明 | 2669| ------------------------ | ---- | ---------------------- | 2670| NET_CAPABILITY_MMS | 0 | 表示网络可以访问运营商的MMSC（Multimedia Message Service，多媒体短信服务）发送和接收彩信。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2671| NET_CAPABILITY_NOT_METERED | 11 | 表示网络流量未被计费。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2672| NET_CAPABILITY_INTERNET | 12 | 表示该网络应具有访问Internet的能力，该能力由网络提供者设置，但该网络访问Internet的连通性并未被网络管理成功验证。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2673| NET_CAPABILITY_NOT_VPN | 15 | 表示网络不使用VPN（Virtual Private Network，虚拟专用网络）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2674| NET_CAPABILITY_VALIDATED | 16 | 表示网络管理通过该网络与华为云地址成功建立连接，该能力由网络管理模块设置。<br>请注意，网络管理可能会与华为云地址建立连接失败，导致网络能力不具备此标记位，但不完全代表该网络无法访问互联网。另外，对于新完成连接的网络，由于网络正在进行连通性验证，此值可能无法反映真实的验证结果。对此，您可以通过NET_CAPABILITY_CHECKING_CONNECTIVITY<sup>12+</sup>检查网络是否正在检测连通性。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2675| NET_CAPABILITY_PORTAL<sup>12+</sup> | 17 | 表示系统发现该网络存在强制网络门户，需要用户登陆认证，该能力由网络管理模块设置。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2676| NET_CAPABILITY_CHECKING_CONNECTIVITY<sup>12+</sup> | 31 | 表示网络管理正在检验当前网络的连通性，此值会在网络连接时设置，直到连通性检测结束后不再设置，当此值存在时，NET_CAPABILITY_VALIDATED的值可能不准确。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2677 2678## NetBearType 2679 2680网络类型。 2681 2682**系统能力**：SystemCapability.Communication.NetManager.Core 2683 2684| 名称 | 值 | 说明 | 2685| ----------------------- | ---- | ---------- | 2686| BEARER_CELLULAR | 0 | 蜂窝网络。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2687| BEARER_WIFI | 1 | Wi-Fi网络。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2688| BEARER_BLUETOOTH<sup>12+</sup> | 2 | 蓝牙网络。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2689| BEARER_ETHERNET | 3 | 以太网网络。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2690| BEARER_VPN<sup>12+</sup>| 4 | VPN网络。 | 2691 2692## HttpProxy<sup>10+</sup> 2693 2694网络代理配置信息 2695 2696**系统能力**：SystemCapability.Communication.NetManager.Core 2697 2698| 名称 | 类型 | 必填 | 说明 | 2699| ------ | ------ | --- |------------------------- | 2700| host | string | 是 | 代理服务器主机名。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 2701| port | number | 是 | 主机端口。取值范围[0,65535]。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2702| exclusionList | Array\<string\> | 是 | 不使用代理的主机名列表，主机名支持域名、IP地址以及通配符形式，详细匹配规则如下：<br/>1、域名匹配规则：<br/>（1）完全匹配：代理服务器主机名只要与列表中的任意一个主机名完全相同，就可以匹配。<br/>（2）包含匹配：代理服务器主机名只要包含列表中的任意一个主机名，就可以匹配。<br/>例如，如果在主机名列表中设置了 “ample.com”，则 “ample.com”、“www.ample.com”、“ample.com:80”都会被匹配，而 “www.example.com”、“ample.com.org”则不会被匹配。<br/>2、IP地址匹配规则：代理服务器主机名只要与列表中的任意一个IP地址完全相同，就可以匹配。<br/>3、域名跟IP地址可以同时添加到列表中进行匹配。<br/>4、单个“\*”是唯一有效的通配符，当列表中只有通配符时，将与所有代理服务器主机名匹配，表示禁用代理。通配符只能单独添加，不可以与其他域名、IP地址一起添加到列表中，否则通配符将不生效。<br/>5、匹配规则不区分主机名大小写。<br/>6、匹配主机名时，不考虑http和https等协议前缀。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2703| username<sup>12+</sup> | string | 否 | 使用代理的用户名。| 2704| password<sup>12+</sup> | string | 否 | 使用代理的用户密码。| 2705 2706## NetSpecifier 2707 2708提供承载数据网络能力的实例。 2709 2710**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2711 2712**系统能力**：SystemCapability.Communication.NetManager.Core 2713 2714| 名称 | 类型 | 必填 | 说明 | 2715| ----------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 2716| netCapabilities | [NetCapabilities](#netcapabilities) | 是 | 存储数据网络的传输能力和承载类型。 | 2717| bearerPrivateIdentifier | string | 否 | 网络标识符，蜂窝网络的标识符是"slot0"（对应SIM卡1）、"slot1"（对应SIM卡2）。从API12开始可以通过传递注册的WLAN热点信息表示应用希望激活的指定的WLAN网络。 | 2718 2719**示例：** 2720 2721```ts 2722import { connection } from '@kit.NetworkKit'; 2723import { wifiManager } from '@kit.ConnectivityKit'; 2724import { BusinessError } from '@kit.BasicServicesKit'; 2725 2726let config: wifiManager.WifiDeviceConfig = { 2727 ssid: "TEST", 2728 preSharedKey: "**********", 2729 securityType: wifiManager.WifiSecurityType.WIFI_SEC_TYPE_PSK 2730}; 2731// 通过wifiManager.addCandidateConfig获取注册WLAN的networkId 2732let networkId: number = await wifiManager.addCandidateConfig(config); 2733let netConnectionWlan = connection.createNetConnection({ 2734 netCapabilities: { 2735 bearerTypes: [connection.NetBearType.BEARER_WIFI] 2736 }, 2737 bearerPrivateIdentifier: `${networkId}` 2738}); 2739netConnectionWlan.register((error: BusinessError) => { 2740 console.log(JSON.stringify(error)); 2741}); 2742``` 2743 2744## NetCapabilityInfo<sup>10+</sup> 2745 2746提供承载数据网络能力的实例。 2747 2748**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2749 2750**系统能力**：SystemCapability.Communication.NetManager.Core 2751 2752| 名称 | 类型 | 必填 | 说明 | 2753| ----------------------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 2754| netHandle | [NetHandle](#nethandle) | 是 | 数据网络句柄。 | 2755| netCap | [NetCapabilities](#netcapabilities) | 是 | 存储数据网络的传输能力和承载类型。 | 2756 2757## NetCapabilities 2758 2759网络的能力集。 2760 2761**系统能力**：SystemCapability.Communication.NetManager.Core 2762 2763| 名称 | 类型 | 必填 | 说明 | 2764| --------------------- | ---------------------------------- | --- | ------------------------ | 2765| linkUpBandwidthKbps | number | 否 | 上行（设备到网络）带宽，单位(kb/s)，0表示无法评估当前网络带宽。| 2766| linkDownBandwidthKbps | number | 否 | 下行（网络到设备）带宽，单位(kb/s)，0表示无法评估当前网络带宽。| 2767| networkCap | Array\<[NetCap](#netcap)> | 否 | 网络具体能力。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2768| bearerTypes | Array\<[NetBearType](#netbeartype)> | 是 | 网络类型。数组里面只包含了一种具体的网络类型。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2769 2770## NetConnectionPropertyInfo<sup>11+</sup> 2771 2772网络连接信息 2773 2774**系统能力**：SystemCapability.Communication.NetManager.Core 2775 2776### 属性 2777 2778| 名称 | 类型 | 必填 | 说明 | 2779| -------------------- | --------------------------------------------------- | ---- |----------------------- | 2780| netHandle | [NetHandle](#nethandle) | 是 |数据网络句柄(netHandle)。| 2781| connectionProperties | [ConnectionProperties](#connectionproperties) | 是 |网络连接属性。 | 2782 2783## NetBlockStatusInfo<sup>11+</sup> 2784 2785获取网络状态信息。 2786 2787**系统能力**：SystemCapability.Communication.NetManager.Core 2788 2789### 属性 2790 2791| 名称 | 类型 | 必填 | 说明 | 2792| -------------------- | ------------------------------------- | --- |--------------------------- | 2793| netHandle | [NetHandle](#nethandle) | 是 |数据网络句柄(netHandle)。 | 2794| blocked | boolean | 是 |true：标识当前网络是堵塞状态；false：标识当前网络不是堵塞状态。 | 2795 2796## ConnectionProperties 2797 2798网络连接信息。 2799 2800**系统能力**：SystemCapability.Communication.NetManager.Core 2801 2802| 名称 | 类型 | 必填 | 说明 | 2803| ------------- | ----------------------------------- | ----|--------------------------------------- | 2804| interfaceName | string | 是 |网卡名称。 | 2805| domains | string | 是 |域名。 | 2806| linkAddresses | Array\<[LinkAddress](#linkaddress)> | 是 |链路信息。 | 2807| routes | Array\<[RouteInfo](#routeinfo)> | 是 |路由信息。 | 2808| dnses | Array\<[NetAddress](#netaddress)> | 是 |网络地址，参考[NetAddress](#netaddress)。 | 2809| mtu | number | 是 |最大传输单元。 | 2810 2811## RouteInfo 2812 2813网络路由信息。 2814 2815**系统能力**：SystemCapability.Communication.NetManager.Core 2816 2817| 名称 | 类型 | 必填 | 说明 | 2818| -------------- | --------------------------- | --- |-------------- | 2819| interface | string | 是 |网卡名称。 | 2820| destination | [LinkAddress](#linkaddress) | 是 |目的地址。 | 2821| gateway | [NetAddress](#netaddress) | 是 |网关地址。 | 2822| hasGateway | boolean | 是 |true：有网关；false：无网关。 | 2823| isDefaultRoute | boolean | 是 |true：默认路由；false：非默认路由。 | 2824 2825## LinkAddress 2826 2827网络链路信息。 2828 2829**系统能力**：SystemCapability.Communication.NetManager.Core 2830 2831| 名称 | 类型 | 必填 | 说明 | 2832| ------------ | ------------------------- |---- |-------------------- | 2833| address | [NetAddress](#netaddress) | 是 | 链路地址。 | 2834| prefixLength | number | 是 |链路地址前缀的长度。 | 2835 2836## NetAddress 2837 2838网络地址。 2839 2840**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2841 2842**系统能力**：SystemCapability.Communication.NetManager.Core 2843 2844| 名称 | 类型 |必填| 说明 | 2845| ------- | ------ | -- |---------------------------- | 2846| address | string | 是 |地址。 | 2847| family | number | 否 |IPv4 = 1，IPv6 = 2，默认IPv4。| 2848| port | number | 否 |端口，取值范围\[0, 65535]，默认值为0。 | 2849 2850## HttpRequest 2851 2852type HttpRequest = http.HttpRequest 2853 2854获取一个HTTP请求。 2855 2856**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2857 2858**系统能力**：SystemCapability.Communication.NetStack 2859 2860| 类型 | 说明 | 2861| ---------------- | --------------------------- | 2862| http.HttpRequest | 定义HTTP请求任务。在调用HttpRequest提供的API之前。 | 2863 2864## TCPSocket 2865 2866type TCPSocket = socket.TCPSocket 2867 2868获取一个TCPSocket对象。 2869 2870**原子化服务API：** 从API version 10开始，该接口支持在原子化服务中使用。 2871 2872**系统能力**：SystemCapability.Communication.NetStack 2873 2874| 类型 | 说明 | 2875| ---------------- | --------------------------- | 2876| socket.TCPSocket | 定义一个TCPSocket连接。 | 2877 2878## UDPSocket 2879 2880type UDPSocket = socket.UDPSocket 2881 2882获取一个UDPSocket对象。 2883 2884**原子化服务API：** 从API version 10开始，该接口支持在原子化服务中使用。 2885 2886**系统能力**：SystemCapability.Communication.NetStack 2887 2888| 类型 | 说明 | 2889| ---------------- | --------------------------- | 2890| socket.UDPSocket | 定义UDPSocket连接。 | 2891