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