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