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