1# Socket连接 2 3> **说明：** 4> 5>本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 6> 7 8## 导入模块 9 10``` 11import socket from '@ohos.net.socket'; 12``` 13 14## socket.constructUDPSocketInstance 15 16constructUDPSocketInstance\(\): UDPSocket 17 18创建一个UDPSocket对象。 19 20**系统能力**：SystemCapability.Communication.NetStack 21 22**返回值：** 23 24| 类型 | 说明 | 25| :--------------------------------- | :---------------------- | 26| [UDPSocket](#udpsocket) | 返回一个UDPSocket对象。 | 27 28 29**示例：** 30 31``` 32let udp = socket.constructUDPSocketInstance(); 33``` 34 35 36## UDPSocket 37 38UDPSocket连接。在调用UDPSocket的方法前，需要先通过[socket.constructUDPSocketInstance](#socketconstructudpsocketinstance)创建UDPSocket对象。 39 40### bind 41 42bind\(address: NetAddress, callback: AsyncCallback<void\>\): void 43 44绑定IP地址和端口，端口可以指定或由系统随机分配。使用callback方式作为异步方法。 45 46**需要权限**：ohos.permission.INTERNET 47 48**系统能力**：SystemCapability.Communication.NetStack 49 50**参数：** 51 52| 参数名 | 类型 | 必填 | 说明 | 53| -------- | ---------------------------------- | ---- | ------------------------------------------------------ | 54| address | [NetAddress](#netaddress) | 是 | 目标地址信息，参考[NetAddress](#netaddress)。 | 55| callback | AsyncCallback\<void\> | 是 | 回调函数。 | 56 57**示例：** 58 59``` 60let udp = socket.constructUDPSocketInstance(); 61udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => { 62 if (err) { 63 console.log('bind fail'); 64 return; 65 } 66 console.log('bind success'); 67}) 68``` 69 70 71### bind 72 73bind\(address: NetAddress\): Promise<void\> 74 75绑定IP地址和端口，端口可以指定或由系统随机分配。使用Promise方式作为异步方法。 76 77**需要权限**：ohos.permission.INTERNET 78 79**系统能力**：SystemCapability.Communication.NetStack 80 81**参数：** 82 83| 参数名 | 类型 | 必填 | 说明 | 84| ------- | ---------------------------------- | ---- | ------------------------------------------------------ | 85| address | [NetAddress](#netaddress) | 是 | 目标地址信息，参考[NetAddress](#netaddress)。 | 86 87 88**返回值：** 89 90| 类型 | 说明 | 91| :-------------- | :----------------------------------------- | 92| Promise\<void\> | 以Promise形式异步返回UDPSocket绑定的结果。 | 93 94**示例：** 95 96``` 97let udp = socket.constructUDPSocketInstance(); 98let promise = udp.bind({address: '192.168.xx.xxx', port: 8080, family: 1}); 99promise .then(() => { 100 console.log('bind success'); 101}).catch(err => { 102 console.log('bind fail'); 103}); 104``` 105 106 107### send 108 109send\(options: UDPSendOptions, callback: AsyncCallback<void\>\): void 110 111通过UDPSocket连接发送数据。使用callback方式作为异步方法。 112 113发送数据前，需要先调用[UDPSocket.bind()](#bind)绑定IP地址和端口。 114 115**需要权限**：ohos.permission.INTERNET 116 117**系统能力**：SystemCapability.Communication.NetStack 118 119**参数：** 120 121| 参数名 | 类型 | 必填 | 说明 | 122| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 123| options | [UDPSendOptions](#udpsendoptions) | 是 | UDPSocket发送参数，参考[UDPSendOptions](#udpsendoptions)。 | 124| callback | AsyncCallback\<void\> | 是 | 回调函数。 | 125 126**示例：** 127 128``` 129let udp = socket.constructUDPSocketInstance(); 130udp.send({ 131 data:'Hello, server!', 132 address: { 133 address:'192.168.xx.xxx', 134 port:xxxx, 135 family:1 136 } 137}, err=> { 138 if (err) { 139 console.log('send fail'); 140 return; 141 } 142 console.log('send success'); 143}) 144``` 145 146 147### send 148 149send\(options: UDPSendOptions\): Promise<void\> 150 151通过UDPSocket连接发送数据。使用Promise方式作为异步方法。 152 153发送数据前，需要先调用[UDPSocket.bind()](#bind)绑定IP地址和端口。 154 155**需要权限**：ohos.permission.INTERNET 156 157**系统能力**：SystemCapability.Communication.NetStack 158 159**参数：** 160 161| 参数名 | 类型 | 必填 | 说明 | 162| ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 163| options | [UDPSendOptions](#udpsendoptions) | 是 | UDPSocket发送参数，参考[UDPSendOptions](#udpsendoptions)。 | 164 165**返回值：** 166 167| 类型 | 说明 | 168| :-------------- | :--------------------------------------------- | 169| Promise\<void\> | 以Promise形式返回UDPSocket连接发送数据的结果。 | 170 171**示例：** 172 173``` 174let udp = socket.constructUDPSocketInstance(); 175let promise = udp.send({ 176 data:'Hello, server!', 177 address: { 178 address:'192.168.xx.xxx', 179 port:xxxx, 180 family:1 181 } 182}); 183promise.then(() => { 184 console.log('send success'); 185}).catch(err => { 186 console.log('send fail'); 187}); 188``` 189 190 191### close 192 193close\(callback: AsyncCallback<void\>\): void 194 195关闭UDPSocket连接。使用callback方式作为异步方法。 196 197**需要权限**：ohos.permission.INTERNET 198 199**系统能力**：SystemCapability.Communication.NetStack 200 201**参数：** 202 203| 参数名 | 类型 | 必填 | 说明 | 204| -------- | --------------------- | ---- | ---------- | 205| callback | AsyncCallback\<void\> | 是 | 回调函数。 | 206 207**示例：** 208 209``` 210let udp = socket.constructUDPSocketInstance(); 211udp.close(err => { 212 if (err) { 213 console.log('close fail'); 214 return; 215 } 216 console.log('close success'); 217}) 218``` 219 220 221### close 222 223close\(\): Promise<void\> 224 225关闭UDPSocket连接。使用Promise方式作为异步方法。 226 227**需要权限**：ohos.permission.INTERNET 228 229**系统能力**：SystemCapability.Communication.NetStack 230 231**返回值：** 232 233| 类型 | 说明 | 234| :-------------- | :----------------------------------------- | 235| Promise\<void\> | 以Promise形式返回关闭UDPSocket连接的结果。 | 236 237**示例：** 238 239``` 240let udp = socket.constructUDPSocketInstance(); 241let promise = udp.close(); 242promise.then(() => { 243 console.log('close success'); 244}).catch(err => { 245 console.log('close fail'); 246}); 247``` 248 249 250### getState 251 252getState\(callback: AsyncCallback<SocketStateBase\>\): void 253 254获取UDPSocket状态。使用callback方式作为异步方法。 255 256> **说明：** 257>[bind](#bind)方法调用成功后，才可调用此方法。 258 259**需要权限**：ohos.permission.INTERNET 260 261**系统能力**：SystemCapability.Communication.NetStack 262 263**参数：** 264 265| 参数名 | 类型 | 必填 | 说明 | 266| -------- | ------------------------------------------------------ | ---- | ---------- | 267| callback | AsyncCallback<[SocketStateBase](#socketstatebase)> | 是 | 回调函数。 | 268 269**示例：** 270 271``` 272let udp = socket.constructUDPSocketInstance(); 273udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => { 274 if (err) { 275 console.log('bind fail'); 276 return; 277 } 278 console.log('bind success'); 279 udp.getState((err, data) => { 280 if (err) { 281 console.log('getState fail'); 282 return; 283 } 284 console.log('getState success:' + JSON.stringify(data)); 285 }) 286}) 287``` 288 289 290### getState 291 292getState\(\): Promise<SocketStateBase\> 293 294获取UDPSocket状态。使用Promise方式作为异步方法。 295 296> **说明：** 297>[bind](#bind)方法调用成功后，才可调用此方法。 298 299**需要权限**：ohos.permission.INTERNET 300 301**系统能力**：SystemCapability.Communication.NetStack 302 303**返回值：** 304 305| 类型 | 说明 | 306| :----------------------------------------------- | :----------------------------------------- | 307| Promise<[SocketStateBase](#socketstatebase)> | 以Promise形式返回获取UDPSocket状态的结果。 | 308 309**示例：** 310 311``` 312let udp = socket.constructUDPSocketInstance(); 313udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => { 314 if (err) { 315 console.log('bind fail'); 316 return; 317 } 318 console.log('bind success'); 319 let promise = udp.getState({}); 320 promise.then(data => { 321 console.log('getState success:' + JSON.stringify(data)); 322 }).catch(err => { 323 console.log('getState fail'); 324 }); 325}) 326``` 327 328 329### setExtraOptions 330 331setExtraOptions\(options: UDPExtraOptions, callback: AsyncCallback<void\>\): void 332 333设置UDPSocket连接的其他属性。使用callback方式作为异步方法。 334 335> **说明：** 336>[bind](#bind)方法调用成功后，才可调用此方法。 337 338**需要权限**：ohos.permission.INTERNET 339 340**系统能力**：SystemCapability.Communication.NetStack 341 342**参数：** 343 344| 参数名 | 类型 | 必填 | 说明 | 345| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 346| options | [UDPExtraOptions](#udpextraoptions) | 是 | UDPSocket连接的其他属性，参考[UDPExtraOptions](#udpextraoptions)。 | 347| callback | AsyncCallback\<void\> | 是 | 回调函数。 | 348 349 350**示例：** 351 352``` 353let udp = socket.constructUDPSocketInstance(); 354udp.bind({address:'192.168.xx.xxx', port:xxxx, family:1}, err=> { 355 if (err) { 356 console.log('bind fail'); 357 return; 358 } 359 console.log('bind success'); 360 udp.setExtraOptions({ 361 receiveBufferSize:1000, 362 sendBufferSize:1000, 363 reuseAddress:false, 364 socketTimeout:6000, 365 broadcast:true 366 }, err=> { 367 if (err) { 368 console.log('setExtraOptions fail'); 369 return; 370 } 371 console.log('setExtraOptions success'); 372 }) 373}) 374``` 375 376 377### setExtraOptions 378 379setExtraOptions\(options: UDPExtraOptions\): Promise<void\> 380 381设置UDPSocket连接的其他属性。使用Promise方式作为异步方法。 382 383> **说明：** 384>[bind](#bind)方法调用成功后，才可调用此方法。 385 386**需要权限**：ohos.permission.INTERNET 387 388**系统能力**：SystemCapability.Communication.NetStack 389 390**参数：** 391 392| 参数名 | 类型 | 必填 | 说明 | 393| ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 394| options | [UDPExtraOptions](#udpextraoptions) | 是 | UDPSocket连接的其他属性，参考[UDPExtraOptions](#udpextraoptions)。 | 395 396**返回值：** 397 398| 类型 | 说明 | 399| :-------------- | :--------------------------------------------------- | 400| Promise\<void\> | 以Promise形式返回设置UDPSocket连接的其他属性的结果。 | 401 402**示例：** 403 404``` 405let udp = socket.constructUDPSocketInstance(); 406let promise = udp.bind({address:'192.168.xx.xxx', port:xxxx, family:1}); 407promise.then(() => { 408 console.log('bind success'); 409 let promise1 = udp.setExtraOptions({ 410 receiveBufferSize:1000, 411 sendBufferSize:1000, 412 reuseAddress:false, 413 socketTimeout:6000, 414 broadcast:true 415 }); 416 promise1.then(() => { 417 console.log('setExtraOptions success'); 418 }).catch(err => { 419 console.log('setExtraOptions fail'); 420 }); 421}).catch(err => { 422 console.log('bind fail'); 423}); 424``` 425 426 427### on\('message'\) 428 429on\(type: 'message', callback: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void 430 431订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。 432 433**系统能力**：SystemCapability.Communication.NetStack 434 435**参数：** 436 437| 参数名 | 类型 | 必填 | 说明 | 438| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | 439| type | string | 是 | 订阅的事件类型。'message'：接收消息事件。 | 440| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | 是 | 回调函数。 | 441 442**示例：** 443 444``` 445let udp = socket.constructUDPSocketInstance(); 446udp.on('message', value => { 447 console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo); 448}); 449``` 450 451 452### off\('message'\) 453 454off\(type: 'message', callback?: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void 455 456取消订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。 457 458> **说明：** 459>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 460 461**系统能力**：SystemCapability.Communication.NetStack 462 463**参数：** 464 465| 参数名 | 类型 | 必填 | 说明 | 466| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | 467| type | string | 是 | 订阅的事件类型。'message'：接收消息事件。 | 468| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | 否 | 回调函数。 | 469 470**示例：** 471 472``` 473let udp = socket.constructUDPSocketInstance(); 474let callback = value =>{ 475 console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo); 476} 477udp.on('message', callback); 478// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 479udp.off('message', callback); 480udp.off('message'); 481``` 482 483 484### on\('listening' | 'close'\) 485 486on\(type: 'listening' | 'close', callback: Callback<void\>\): void 487 488订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。 489 490**系统能力**：SystemCapability.Communication.NetStack 491 492**参数：** 493 494| 参数名 | 类型 | 必填 | 说明 | 495| -------- | ---------------- | ---- | ------------------------------------------------------------ | 496| type | string | 是 | 订阅的事件类型。<br />- 'listening'：数据包消息事件。<br />- 'close'：关闭事件。 | 497| callback | Callback\<void\> | 是 | 回调函数。 | 498 499**示例：** 500 501``` 502let udp = socket.constructUDPSocketInstance(); 503udp.on('listening', () => { 504 console.log("on listening success"); 505}); 506udp.on('close', () => { 507 console.log("on close success" ); 508}); 509``` 510 511 512### off\('listening' | 'close'\) 513 514off\(type: 'listening' | 'close', callback?: Callback<void\>\): void 515 516取消订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。 517 518> **说明：** 519>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 520 521**系统能力**：SystemCapability.Communication.NetStack 522 523**参数：** 524 525| 参数名 | 类型 | 必填 | 说明 | 526| -------- | ---------------- | ---- | ------------------------------------------------------------ | 527| type | string | 是 | 订阅事件类型。<br />- 'listening'：数据包消息事件。<br />- 'close'：关闭事件。 | 528| callback | Callback\<void\> | 否 | 回调函数。 | 529 530**示例：** 531 532``` 533let udp = socket.constructUDPSocketInstance(); 534let callback1 = () =>{ 535 console.log("on listening, success"); 536} 537udp.on('listening', callback1); 538// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 539udp.off('listening', callback1); 540udp.off('listening'); 541let callback2 = () =>{ 542 console.log("on close, success"); 543} 544udp.on('close', callback2); 545// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 546udp.off('close', callback2); 547udp.off('close'); 548``` 549 550 551### on\('error'\) 552 553on\(type: 'error', callback: ErrorCallback\): void 554 555订阅UDPSocket连接的error事件。使用callback方式作为异步方法。 556 557**系统能力**：SystemCapability.Communication.NetStack 558 559**参数：** 560 561| 参数名 | 类型 | 必填 | 说明 | 562| -------- | ------------- | ---- | ------------------------------------ | 563| type | string | 是 | 订阅的事件类型。'error'：error事件。 | 564| callback | ErrorCallback | 是 | 回调函数。 | 565 566 567**示例：** 568 569``` 570let udp = socket.constructUDPSocketInstance(); 571udp.on('error', err => { 572 console.log("on error, err:" + JSON.stringify(err)) 573}); 574``` 575 576 577### off\('error'\) 578 579off\(type: 'error', callback?: ErrorCallback\): void 580 581取消订阅UDPSocket连接的error事件。使用callback方式作为异步方法。 582 583> **说明：** 584>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 585 586**系统能力**：SystemCapability.Communication.NetStack 587 588**参数：** 589 590| 参数名 | 类型 | 必填 | 说明 | 591| -------- | ------------- | ---- | ------------------------------------ | 592| type | string | 是 | 订阅的事件类型。'error'：error事件。 | 593| callback | ErrorCallback | 否 | 回调函数。 | 594 595**示例：** 596 597``` 598let udp = socket.constructUDPSocketInstance(); 599let callback = err =>{ 600 console.log("on error, err:" + JSON.stringify(err)); 601} 602udp.on('error', callback); 603// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 604udp.off('error', callback); 605udp.off('error'); 606``` 607 608 609## NetAddress 610 611目标地址信息。 612 613**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 614 615| 参数名 | 类型 | 必填 | 说明 | 616| ------- | ------ | ---- | ------------------------------------------------------------ | 617| address | string | 是 | 本地绑定的ip地址。 | 618| port | number | 否 | 端口号 ，范围0~65535。如果不指定系统随机分配端口。 | 619| family | number | 否 | 网络协议类型，可选类型：<br />- 1：IPv4<br />- 2：IPv6<br />默认为1。 | 620 621## UDPSendOptions 622 623UDPSocket发送参数。 624 625**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 626 627| 参数名 | 类型 | 必填 | 说明 | 628| ------- | ---------------------------------- | ---- | -------------- | 629| data | string | 是 | 发送的数据。 | 630| address | [NetAddress](#netaddress) | 是 | 目标地址信息。 | 631 632## UDPExtraOptions 633 634UDPSocket连接的其他属性。 635 636**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 637 638| 参数名 | 类型 | 必填 | 说明 | 639| ----------------- | ------- | ---- | -------------------------------- | 640| broadcast | boolean | 否 | 是否可以发送广播。默认为false。 | 641| receiveBufferSize | number | 否 | 接收缓冲区大小（单位：Byte）。 | 642| sendBufferSize | number | 否 | 发送缓冲区大小（单位：Byte）。 | 643| reuseAddress | boolean | 否 | 是否重用地址。默认为false。 | 644| socketTimeout | number | 否 | 套接字超时时间，单位毫秒（ms）。 | 645 646## SocketStateBase 647 648Socket的状态信息。 649 650**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 651 652| 参数名 | 类型 | 必填 | 说明 | 653| ----------- | ------- | ---- | ---------- | 654| isBound | boolean | 是 | 是否绑定。 | 655| isClose | boolean | 是 | 是否关闭。 | 656| isConnected | boolean | 是 | 是否连接。 | 657 658## SocketRemoteInfo 659 660Socket的连接信息。 661 662**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 663 664| 参数名 | 类型 | 必填 | 说明 | 665| ------- | ------ | ---- | ------------------------------------------------------------ | 666| address | string | 是 | 本地绑定的ip地址。 | 667| family | string | 是 | 网络协议类型，可选类型：<br />- IPv4<br />- IPv6<br />默认为IPv4。 | 668| port | number | 是 | 端口号，范围0~65535。 | 669| size | number | 是 | 服务器响应信息的字节长度。 | 670 671## socket.constructTCPSocketInstance 672 673constructTCPSocketInstance\(\): TCPSocket 674 675创建一个TCPSocket对象。 676 677**系统能力**：SystemCapability.Communication.NetStack 678 679**返回值：** 680 681 | 类型 | 说明 | 682 | :--------------------------------- | :---------------------- | 683 | [TCPSocket](#tcpsocket) | 返回一个TCPSocket对象。 | 684 685**示例：** 686 687``` 688let tcp = socket.constructTCPSocketInstance(); 689``` 690 691 692## TCPSocket 693 694TCPSocket连接。在调用TCPSocket的方法前，需要先通过[socket.constructTCPSocketInstance](#socketconstructtcpsocketinstance)创建TCPSocket对象。 695 696### bind 697 698bind\(address: NetAddress, callback: AsyncCallback<void\>\): void 699 700绑定IP地址和端口，端口可以指定或由系统随机分配。使用callback方法作为异步方法。 701 702**需要权限**：ohos.permission.INTERNET 703 704**系统能力**：SystemCapability.Communication.NetStack 705 706**参数：** 707 708| 参数名 | 类型 | 必填 | 说明 | 709| -------- | ---------------------------------- | ---- | ------------------------------------------------------ | 710| address | [NetAddress](#netaddress) | 是 | 目标地址信息，参考[NetAddress](#netaddress)。 | 711| callback | AsyncCallback\<void\> | 是 | 回调函数。 | 712 713 714**示例：** 715 716``` 717let tcp = socket.constructTCPSocketInstance(); 718tcp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => { 719 if (err) { 720 console.log('bind fail'); 721 return; 722 } 723 console.log('bind success'); 724}) 725``` 726 727 728### bind 729 730bind\(address: NetAddress\): Promise<void\> 731 732绑定IP地址和端口，端口可以指定或由系统随机分配。使用Promise方法作为异步方法。 733 734**需要权限**：ohos.permission.INTERNET 735 736**系统能力**：SystemCapability.Communication.NetStack 737 738**参数：** 739 740| 参数名 | 类型 | 必填 | 说明 | 741| ------- | ---------------------------------- | ---- | ------------------------------------------------------ | 742| address | [NetAddress](#netaddress) | 是 | 目标地址信息，参考[NetAddress](#netaddress)。 | 743 744**返回值：** 745 746| 类型 | 说明 | 747| :-------------- | :------------------------------------------------------- | 748| Promise\<void\> | 以Promise形式返回TCPSocket绑定本机的IP地址和端口的结果。 | 749 750**示例：** 751 752``` 753let tcp = socket.constructTCPSocketInstance(); 754let promise = tcp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}); 755promise.then(() => { 756 console.log('bind success'); 757}).catch(err => { 758 console.log('bind fail'); 759}); 760``` 761 762 763### connect 764 765connect\(options: TCPConnectOptions, callback: AsyncCallback<void\>\): void 766 767连接到指定的IP地址和端口。使用callback方法作为异步方法。 768 769**需要权限**：ohos.permission.INTERNET 770 771**系统能力**：SystemCapability.Communication.NetStack 772 773**参数：** 774 775| 参数名 | 类型 | 必填 | 说明 | 776| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 777| options | [TCPConnectOptions](#tcpconnectoptions) | 是 | TCPSocket连接的参数，参考[TCPConnectOptions](#tcpconnectoptions)。 | 778| callback | AsyncCallback\<void\> | 是 | 回调函数。 | 779 780**示例：** 781 782``` 783let tcp = socket.constructTCPSocketInstance(); 784tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}, err => { 785 if (err) { 786 console.log('connect fail'); 787 return; 788 } 789 console.log('connect success'); 790}) 791``` 792 793 794### connect 795 796connect\(options: TCPConnectOptions\): Promise<void\> 797 798连接到指定的IP地址和端口。使用promise方法作为异步方法。 799 800**需要权限**：ohos.permission.INTERNET 801 802**系统能力**：SystemCapability.Communication.NetStack 803 804**参数：** 805 806| 参数名 | 类型 | 必填 | 说明 | 807| ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 808| options | [TCPConnectOptions](#tcpconnectoptions) | 是 | TCPSocket连接的参数，参考[TCPConnectOptions](#tcpconnectoptions)。 | 809 810**返回值：** 811 812| 类型 | 说明 | 813| :-------------- | :--------------------------------------------------------- | 814| Promise\<void\> | 以Promise形式返回TCPSocket连接到指定的IP地址和端口的结果。 | 815 816**示例：** 817 818``` 819let tcp = socket.constructTCPSocketInstance(); 820let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); 821promise.then(() => { 822 console.log('connect success') 823}).catch(err => { 824 console.log('connect fail'); 825}); 826``` 827 828 829### send 830 831send\(options: TCPSendOptions, callback: AsyncCallback<void\>\): void 832 833通过TCPSocket连接发送数据。使用callback方式作为异步方法。 834 835> **说明：** 836>[connect](#connect)方法调用成功后，才可调用此方法。 837 838**需要权限**：ohos.permission.INTERNET 839 840**系统能力**：SystemCapability.Communication.NetStack 841 842**参数：** 843 844| 参数名 | 类型 | 必填 | 说明 | 845| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 846| options | [TCPSendOptions](#tcpsendoptions) | 是 | TCPSocket发送请求的参数，参考[TCPSendOptions](#tcpsendoptions)。 | 847| callback | AsyncCallback\<void\> | 是 | 回调函数。 | 848 849**示例：** 850 851``` 852let tcp = socket.constructTCPSocketInstance(); 853let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); 854promise.then(() => { 855 console.log('connect success'); 856 tcp.send({ 857 data:'Hello, server!' 858 },err => { 859 if (err) { 860 console.log('send fail'); 861 return; 862 } 863 console.log('send success'); 864 }) 865}).catch(err => { 866 console.log('connect fail'); 867}); 868``` 869 870 871### send 872 873send\(options: TCPSendOptions\): Promise<void\> 874 875通过TCPSocket连接发送数据。使用Promise方式作为异步方法。 876 877> **说明：** 878>[connect](#connect)方法调用成功后，才可调用此方法。 879 880**需要权限**：ohos.permission.INTERNET 881 882**系统能力**：SystemCapability.Communication.NetStack 883 884**参数：** 885 886| 参数名 | 类型 | 必填 | 说明 | 887| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 888| options | [TCPSendOptions](#tcpsendoptions) | 是 | TCPSocket发送请求的参数，参考[TCPSendOptions](#tcpsendoptions)。 | 889 890**返回值：** 891 892| 类型 | 说明 | 893| :-------------- | :------------------------------------------------- | 894| Promise\<void\> | 以Promise形式返回通过TCPSocket连接发送数据的结果。 | 895 896**示例：** 897 898``` 899let tcp = socket.constructTCPSocketInstance(); 900let promise1 = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); 901promise1.then(() => { 902 console.log('connect success'); 903 let promise2 = tcp.send({ 904 data:'Hello, server!' 905 }); 906 promise2.then(() => { 907 console.log('send success'); 908 }).catch(err => { 909 console.log('send fail'); 910 }); 911}).catch(err => { 912 console.log('connect fail'); 913}); 914``` 915 916 917### close 918 919close\(callback: AsyncCallback<void\>\): void 920 921关闭TCPSocket连接。使用callback方式作为异步方法。 922 923**需要权限**：ohos.permission.INTERNET 924 925**系统能力**：SystemCapability.Communication.NetStack 926 927**参数：** 928 929| 参数名 | 类型 | 必填 | 说明 | 930| -------- | --------------------- | ---- | ---------- | 931| callback | AsyncCallback\<void\> | 是 | 回调函数。 | 932 933 934**示例：** 935 936``` 937let tcp = socket.constructTCPSocketInstance(); 938tcp.close(err => { 939 if (err) { 940 console.log('close fail'); 941 return; 942 } 943 console.log('close success'); 944}) 945``` 946 947 948### close 949 950close\(\): Promise<void\> 951 952关闭TCPSocket连接。使用Promise方式作为异步方法。 953 954**需要权限**：ohos.permission.INTERNET 955 956**系统能力**：SystemCapability.Communication.NetStack 957 958**返回值：** 959 960| 类型 | 说明 | 961| :-------------- | :----------------------------------------- | 962| Promise\<void\> | 以Promise形式返回关闭TCPSocket连接的结果。 | 963 964**示例：** 965 966``` 967let tcp = socket.constructTCPSocketInstance(); 968let promise = tcp.close(); 969promise.then(() => { 970 console.log('close success'); 971}).catch(err => { 972 console.log('close fail'); 973}); 974``` 975 976 977### getRemoteAddress 978 979getRemoteAddress\(callback: AsyncCallback<NetAddress\>\): void 980 981获取对端Socket地址。使用callback方式作为异步方法。 982 983> **说明：** 984>[connect](#connect)方法调用成功后，才可调用此方法。 985 986**需要权限**：ohos.permission.INTERNET 987 988**系统能力**：SystemCapability.Communication.NetStack 989 990**参数：** 991 992| 参数名 | 类型 | 必填 | 说明 | 993| -------- | ------------------------------------------------- | ---- | ---------- | 994| callback | AsyncCallback<[NetAddress](#netaddress)> | 是 | 回调函数。 | 995 996**示例：** 997 998``` 999let tcp = socket.constructTCPSocketInstance(); 1000let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); 1001promise.then(() => { 1002 console.log('connect success'); 1003 tcp.getRemoteAddress((err, data) => { 1004 if (err) { 1005 console.log('getRemoteAddressfail'); 1006 return; 1007 } 1008 console.log('getRemoteAddresssuccess:' + JSON.stringify(data)); 1009 }) 1010}).catch(err => { 1011 console.log('connect fail'); 1012}); 1013``` 1014 1015 1016### getRemoteAddress 1017 1018getRemoteAddress\(\): Promise<NetAddress\> 1019 1020获取对端Socket地址。使用Promise方式作为异步方法。 1021 1022> **说明：** 1023>[connect](#connect)方法调用成功后，才可调用此方法。 1024 1025**需要权限**：ohos.permission.INTERNET 1026 1027**系统能力**：SystemCapability.Communication.NetStack 1028 1029**返回值：** 1030 1031| 类型 | 说明 | 1032| :------------------------------------------ | :------------------------------------------ | 1033| Promise<[NetAddress](#netaddress)> | 以Promise形式返回获取对端socket地址的结果。 | 1034 1035**示例：** 1036 1037``` 1038let tcp = socket.constructTCPSocketInstance(); 1039let promise1 = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); 1040promise1.then(() => { 1041 console.log('connect success'); 1042 let promise2 = tcp.getRemoteAddress(); 1043 promise2.then(() => { 1044 console.log('getRemoteAddress success:' + JSON.stringify(data)); 1045 }).catch(err => { 1046 console.log('getRemoteAddressfail'); 1047 }); 1048}).catch(err => { 1049 console.log('connect fail'); 1050}); 1051``` 1052 1053 1054### getState 1055 1056getState\(callback: AsyncCallback<SocketStateBase\>\): void 1057 1058获取TCPSocket状态。使用callback方式作为异步方法。 1059 1060> **说明：** 1061>[bind](#bind)或[connect](#connect)方法调用成功后，才可调用此方法。 1062 1063**需要权限**：ohos.permission.INTERNET 1064 1065**系统能力**：SystemCapability.Communication.NetStack 1066 1067**参数：** 1068 1069| 参数名 | 类型 | 必填 | 说明 | 1070| -------- | ------------------------------------------------------ | ---- | ---------- | 1071| callback | AsyncCallback<[SocketStateBase](#socketstatebase)> | 是 | 回调函数。 | 1072 1073 1074**示例：** 1075 1076``` 1077let tcp = socket.constructTCPSocketInstance(); 1078let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); 1079promise.then(() => { 1080 console.log('connect success'); 1081 tcp.getState((err, data) => { 1082 if (err) { 1083 console.log('getState fail'); 1084 return; 1085 } 1086 console.log('getState success:' + JSON.stringify(data)); 1087 }); 1088}).catch(err => { 1089 console.log('connect fail'); 1090}); 1091``` 1092 1093 1094### getState 1095 1096getState\(\): Promise<SocketStateBase\> 1097 1098获取TCPSocket状态。使用Promise方式作为异步方法。 1099 1100> **说明：** 1101>[bind](#bind)或[connect](#connect)方法调用成功后，才可调用此方法。 1102 1103**需要权限**：ohos.permission.INTERNET 1104 1105**系统能力**：SystemCapability.Communication.NetStack 1106 1107**返回值：** 1108 1109| 类型 | 说明 | 1110| :----------------------------------------------- | :----------------------------------------- | 1111| Promise<[SocketStateBase](#socketstatebase)> | 以Promise形式返回获取TCPSocket状态的结果。 | 1112 1113 1114**示例：** 1115 1116``` 1117let tcp = socket.constructTCPSocketInstance(); 1118let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); 1119promise.then(() => { 1120 console.log('connect success'); 1121 let promise1 = tcp.getState(); 1122 promise1.then(() => { 1123 console.log('getState success:' + JSON.stringify(data)); 1124 }).catch(err => { 1125 console.log('getState fail'); 1126 }); 1127}).catch(err => { 1128 console.log('connect fail'); 1129}); 1130``` 1131 1132 1133### setExtraOptions 1134 1135setExtraOptions\(options: TCPExtraOptions, callback: AsyncCallback<void\>\): void 1136 1137设置TCPSocket连接的其他属性。使用callback方式作为异步方法。 1138 1139> **说明：** 1140>[bind](#bind)或[connect](#connect)方法调用成功后，才可调用此方法。 1141 1142**需要权限**：ohos.permission.INTERNET 1143 1144**系统能力**：SystemCapability.Communication.NetStack 1145 1146**参数：** 1147 1148| 参数名 | 类型 | 必填 | 说明 | 1149| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1150| options | [TCPExtraOptions](#tcpextraoptions) | 是 | TCPSocket连接的其他属性，参考[TCPExtraOptions](#tcpextraoptions)。 | 1151| callback | AsyncCallback\<void\> | 是 | 回调函数。 | 1152 1153**示例：** 1154 1155``` 1156let tcp = socket.constructTCPSocketInstance(); 1157let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); 1158promise.then(() => { 1159 console.log('connect success'); 1160 tcp.setExtraOptions({ 1161 keepAlive: true, 1162 OOBInline: true, 1163 TCPNoDelay: true, 1164 socketLinger: { on:true, linger:10 }, 1165 receiveBufferSize: 1000, 1166 sendBufferSize: 1000, 1167 reuseAddress: true, 1168 socketTimeout: 3000, 1169 },err => { 1170 if (err) { 1171 console.log('setExtraOptions fail'); 1172 return; 1173 } 1174 console.log('setExtraOptions success'); 1175 }); 1176}).catch(err => { 1177 console.log('connect fail'); 1178}); 1179``` 1180 1181 1182### setExtraOptions 1183 1184setExtraOptions\(options: TCPExtraOptions\): Promise<void\> 1185 1186设置TCPSocket连接的其他属性，使用Promise方式作为异步方法。 1187 1188> **说明：** 1189>[bind](#bind)或[connect](#connect)方法调用成功后，才可调用此方法。 1190 1191**需要权限**：ohos.permission.INTERNET 1192 1193**系统能力**：SystemCapability.Communication.NetStack 1194 1195**参数：** 1196 1197| 参数名 | 类型 | 必填 | 说明 | 1198| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1199| options | [TCPExtraOptions](#tcpextraoptions) | 是 | TCPSocket连接的其他属性，参考[TCPExtraOptions](#tcpextraoptions)。 | 1200 1201**返回值：** 1202 1203| 类型 | 说明 | 1204| :-------------- | :--------------------------------------------------- | 1205| Promise\<void\> | 以Promise形式返回设置TCPSocket连接的其他属性的结果。 | 1206 1207 1208**示例：** 1209 1210``` 1211let tcp = socket.constructTCPSocketInstance(); 1212let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}); 1213promise.then(() => { 1214 console.log('connect success'); 1215 let promise1 = tcp.setExtraOptions({ 1216 keepAlive: true, 1217 OOBInline: true, 1218 TCPNoDelay: true, 1219 socketLinger: { on:true, linger:10 }, 1220 receiveBufferSize: 1000, 1221 sendBufferSize: 1000, 1222 reuseAddress: true, 1223 socketTimeout: 3000, 1224 }); 1225 promise1.then(() => { 1226 console.log('setExtraOptions success'); 1227 }).catch(err => { 1228 console.log('setExtraOptions fail'); 1229 }); 1230}).catch(err => { 1231 console.log('connect fail'); 1232}); 1233``` 1234 1235 1236### on\('message'\) 1237 1238on\(type: 'message', callback: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void 1239 1240订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。 1241 1242**系统能力**：SystemCapability.Communication.NetStack 1243 1244**参数：** 1245 1246| 参数名 | 类型 | 必填 | 说明 | 1247| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | 1248| type | string | 是 | 订阅的事件类型。'message'：接收消息事件。 | 1249| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | 是 | 回调函数。 | 1250 1251**示例：** 1252 1253``` 1254let tcp = socket.constructTCPSocketInstance(); 1255tcp.on('message', value => { 1256 console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo) 1257}); 1258``` 1259 1260 1261### off\('message'\) 1262 1263off\(type: 'message', callback?: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void 1264 1265取消订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。 1266 1267> **说明：** 1268>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1269 1270**系统能力**：SystemCapability.Communication.NetStack 1271 1272**参数：** 1273 1274| 参数名 | 类型 | 必填 | 说明 | 1275| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | 1276| type | string | 是 | 订阅的事件类型。'message'：接收消息事件。 | 1277| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | 否 | 回调函数。 | 1278 1279**示例：** 1280 1281``` 1282let tcp = socket.constructTCPSocketInstance(); 1283let callback = value =>{ 1284 console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo); 1285} 1286tcp.on('message', callback); 1287// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1288tcp.off('message', callback); 1289tcp.off('message'); 1290``` 1291 1292 1293### on\('connect' | 'close'\) 1294 1295on\(type: 'connect' | 'close', callback: Callback<void\>\): void 1296 1297订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。 1298 1299**系统能力**：SystemCapability.Communication.NetStack 1300 1301**参数：** 1302 1303| 参数名 | 类型 | 必填 | 说明 | 1304| -------- | ---------------- | ---- | ------------------------------------------------------------ | 1305| type | string | 是 | 订阅的事件类型。<br />- 'connect'：连接事件。<br />- 'close'：关闭事件。 | 1306| callback | Callback\<void\> | 是 | 回调函数。 | 1307 1308 1309**示例：** 1310 1311``` 1312let tcp = socket.constructTCPSocketInstance(); 1313tcp.on('connect', () => { 1314 console.log("on connect success") 1315}); 1316tcp.on('close', data => { 1317 console.log("on close success") 1318}); 1319``` 1320 1321 1322### off\('connect' | 'close'\) 1323 1324off\(type: 'connect' | 'close', callback?: Callback<void\>\): void 1325 1326取消订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。 1327 1328> **说明：** 1329>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1330 1331**系统能力**：SystemCapability.Communication.NetStack 1332 1333**参数：** 1334 1335| 参数名 | 类型 | 必填 | 说明 | 1336| -------- | ---------------- | ---- | ------------------------------------------------------------ | 1337| type | string | 是 | 订阅的事件类型。<br />- 'connect'：连接事件。<br />- 'close'：关闭事件。 | 1338| callback | Callback\<void\> | 否 | 回调函数。 | 1339 1340**示例：** 1341 1342``` 1343let tcp = socket.constructTCPSocketInstance(); 1344let callback1 = () =>{ 1345 console.log("on connect success"); 1346} 1347tcp.on('connect', callback1); 1348// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1349tcp.off('connect', callback1); 1350tcp.off('connect'); 1351let callback2 = () =>{ 1352 console.log("on close success"); 1353} 1354tcp.on('close', callback2); 1355// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1356tcp.off('close', callback2); 1357tcp.off('close'); 1358``` 1359 1360 1361### on\('error'\) 1362 1363on\(type: 'error', callback: ErrorCallback\): void 1364 1365订阅TCPSocket连接的error事件。使用callback方式作为异步方法。 1366 1367**系统能力**：SystemCapability.Communication.NetStack 1368 1369**参数：** 1370 1371| 参数名 | 类型 | 必填 | 说明 | 1372| -------- | ------------- | ---- | ------------------------------------ | 1373| type | string | 是 | 订阅的事件类型。'error'：error事件。 | 1374| callback | ErrorCallback | 是 | 回调函数。 | 1375 1376**示例：** 1377 1378``` 1379let tcp = socket.constructTCPSocketInstance(); 1380tcp.on('error', err => { 1381 console.log("on error, err:" + JSON.stringify(err)) 1382}); 1383``` 1384 1385 1386### off\('error'\) 1387 1388off\(type: 'error', callback?: ErrorCallback\): void 1389 1390取消订阅TCPSocket连接的error事件。使用callback方式作为异步方法。 1391 1392> **说明：** 1393>可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1394 1395**系统能力**：SystemCapability.Communication.NetStack 1396 1397**参数：** 1398 1399| 参数名 | 类型 | 必填 | 说明 | 1400| -------- | ------------- | ---- | ------------------------------------ | 1401| type | string | 是 | 订阅的事件类型。'error'：error事件。 | 1402| callback | ErrorCallback | 否 | 回调函数。 | 1403 1404**示例：** 1405 1406``` 1407let tcp = socket.constructTCPSocketInstance(); 1408let callback = err =>{ 1409 console.log("on error, err:" + JSON.stringify(err)); 1410} 1411tcp.on('error', callback); 1412// 可以指定传入on中的callback取消一个订阅，也可以不指定callback清空所有订阅。 1413tcp.off('error', callback); 1414tcp.off('error'); 1415``` 1416 1417 1418## TCPConnectOptions 1419 1420TCPSocket连接的参数。 1421 1422**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 1423 1424| 参数名 | 类型 | 必填 | 说明 | 1425| ------- | ---------------------------------- | ---- | -------------------------- | 1426| address | [NetAddress](#netaddress) | 是 | 绑定的地址以及端口。 | 1427| timeout | number | 否 | 超时时间，单位毫秒（ms）。 | 1428 1429## TCPSendOptions 1430 1431TCPSocket发送请求的参数。 1432 1433**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 1434 1435| 参数名 | 类型 | 必填 | 说明 | 1436| -------- | ------ | ---- | ------------------------------------------------------------ | 1437| data | string | 是 | 发送的数据。 | 1438| encoding | string | 否 | 字符编码(UTF-8，UTF-16BE，UTF-16LE，UTF-16，US-AECII，ISO-8859-1)，默认为UTF-8。 | 1439 1440## TCPExtraOptions 1441 1442TCPSocket连接的其他属性。 1443 1444**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.NetStack。 1445 1446| 参数名 | 类型 | 必填 | 说明 | 1447| ----------------- | ------- | ---- | ------------------------------------------------------------ | 1448| keepAlive | boolean | 否 | 是否保持连接。默认为false。 | 1449| OOBInline | boolean | 否 | 是否为OOB内联。默认为false。 | 1450| TCPNoDelay | boolean | 否 | TCPSocket连接是否无时延。默认为false。 | 1451| socketLinger | Object | 是 | socket是否继续逗留。<br />- on：是否逗留（true：逗留；false：不逗留）。<br />- linger：逗留时长，单位毫秒（ms），取值范围为0~65535。<br />当入参on设置为true时，才需要设置。 | 1452| receiveBufferSize | number | 否 | 接收缓冲区大小（单位：Byte）。 | 1453| sendBufferSize | number | 否 | 发送缓冲区大小（单位：Byte）。 | 1454| reuseAddress | boolean | 否 | 是否重用地址。默认为false。 | 1455| socketTimeout | number | 否 | 套接字超时时间，单位毫秒（ms）。 | 1456
