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