js-apis-socket.md 85.2 KB
Newer Older
1
# @ohos.net.socket (Socket连接)
C
clevercong 已提交
2

3
> **说明:** 
C
clevercong 已提交
4
>
5
> 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
C
clevercong 已提交
6

C
clevercong 已提交
7
## 导入模块
C
clevercong 已提交
8

Z
zengyawen 已提交
9
```js
C
clevercong 已提交
10 11 12
import socket from '@ohos.net.socket';
```

C
clevercong 已提交
13
## socket.constructUDPSocketInstance
C
clevercong 已提交
14 15 16 17 18

constructUDPSocketInstance\(\): UDPSocket

创建一个UDPSocket对象。

C
clevercong 已提交
19
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
20

C
clevercong 已提交
21
**返回值:**
C
clevercong 已提交
22

C
clevercong 已提交
23 24
| 类型                               | 说明                    |
| :--------------------------------- | :---------------------- |
C
clevercong 已提交
25
| [UDPSocket](#udpsocket) | 返回一个UDPSocket对象。 |
C
clevercong 已提交
26 27


C
clevercong 已提交
28
**示例:**
C
clevercong 已提交
29

Z
zengyawen 已提交
30
```js
C
clevercong 已提交
31 32
let udp = socket.constructUDPSocketInstance();
```
C
clevercong 已提交
33 34


C
clevercong 已提交
35
## UDPSocket
C
clevercong 已提交
36

C
clevercong 已提交
37
UDPSocket连接。在调用UDPSocket的方法前,需要先通过[socket.constructUDPSocketInstance](#socketconstructudpsocketinstance)创建UDPSocket对象。
C
clevercong 已提交
38

C
clevercong 已提交
39
### bind
C
clevercong 已提交
40 41 42 43 44

bind\(address: NetAddress, callback: AsyncCallback<void\>\): void

绑定IP地址和端口,端口可以指定或由系统随机分配。使用callback方式作为异步方法。

C
clevercong 已提交
45 46
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
47
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
48

C
clevercong 已提交
49
**参数:**
C
clevercong 已提交
50

C
clevercong 已提交
51 52
| 参数名   | 类型                               | 必填 | 说明                                                   |
| -------- | ---------------------------------- | ---- | ------------------------------------------------------ |
C
clevercong 已提交
53
| address  | [NetAddress](#netaddress) | 是   | 目标地址信息,参考[NetAddress](#netaddress)。 |
C
clevercong 已提交
54
| callback | AsyncCallback\<void\>              | 是   | 回调函数。                                             |
C
clevercong 已提交
55

Y
Yangys 已提交
56 57 58 59 60 61 62
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
63
**示例:**
C
clevercong 已提交
64

Z
zengyawen 已提交
65
```js
C
clevercong 已提交
66 67 68 69 70 71 72 73 74
let udp = socket.constructUDPSocketInstance();
udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => {
  if (err) {
	console.log('bind fail');
	return;
  }
  console.log('bind success');
})
```
C
clevercong 已提交
75 76


C
clevercong 已提交
77
### bind
C
clevercong 已提交
78 79 80 81 82

bind\(address: NetAddress\): Promise<void\>

绑定IP地址和端口,端口可以指定或由系统随机分配。使用Promise方式作为异步方法。

C
clevercong 已提交
83 84
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
85
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
86

C
clevercong 已提交
87
**参数:**
C
clevercong 已提交
88

C
clevercong 已提交
89 90
| 参数名  | 类型                               | 必填 | 说明                                                   |
| ------- | ---------------------------------- | ---- | ------------------------------------------------------ |
C
clevercong 已提交
91
| address | [NetAddress](#netaddress) | 是   | 目标地址信息,参考[NetAddress](#netaddress)。 |
C
clevercong 已提交
92

Y
Yangys 已提交
93 94 95 96 97 98
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |
C
clevercong 已提交
99

C
clevercong 已提交
100
**返回值:**
C
clevercong 已提交
101

C
clevercong 已提交
102 103 104
| 类型            | 说明                                       |
| :-------------- | :----------------------------------------- |
| Promise\<void\> | 以Promise形式异步返回UDPSocket绑定的结果。 |
C
clevercong 已提交
105

C
clevercong 已提交
106
**示例:**
C
clevercong 已提交
107

Z
zengyawen 已提交
108
```js
C
clevercong 已提交
109 110 111 112 113 114 115 116
let udp = socket.constructUDPSocketInstance();
let promise = udp.bind({address: '192.168.xx.xxx', port: 8080, family: 1});
promise .then(() => {
  console.log('bind success');
}).catch(err => {
  console.log('bind fail');
});
```
C
clevercong 已提交
117 118


C
clevercong 已提交
119
### send
C
clevercong 已提交
120 121 122 123 124

send\(options: UDPSendOptions, callback: AsyncCallback<void\>\): void

通过UDPSocket连接发送数据。使用callback方式作为异步方法。

125 126
发送数据前,需要先调用[UDPSocket.bind()](#bind)绑定IP地址和端口。

C
clevercong 已提交
127 128
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
129
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
130

C
clevercong 已提交
131 132 133 134
**参数:**

| 参数名   | 类型                                     | 必填 | 说明                                                         |
| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
135
| options  | [UDPSendOptions](#udpsendoptions) | 是   | UDPSocket发送参数,参考[UDPSendOptions](#udpsendoptions)。 |
C
clevercong 已提交
136 137
| callback | AsyncCallback\<void\>                    | 是   | 回调函数。                                                   |

Y
Yangys 已提交
138 139 140 141 142 143 144
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
145 146
**示例:**

Z
zengyawen 已提交
147
```js
C
clevercong 已提交
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
let udp = socket.constructUDPSocketInstance();
udp.send({
  data:'Hello, server!',
  address: {
	address:'192.168.xx.xxx',
	port:xxxx,
	family:1
  }
}, err=> {
	if (err) {
	  console.log('send fail');
	  return;
	}
	console.log('send success');
})
```
C
clevercong 已提交
164 165


C
clevercong 已提交
166
### send
C
clevercong 已提交
167 168 169 170 171

send\(options: UDPSendOptions\): Promise<void\>

通过UDPSocket连接发送数据。使用Promise方式作为异步方法。

172 173
发送数据前,需要先调用[UDPSocket.bind()](#bind)绑定IP地址和端口。

C
clevercong 已提交
174 175
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
176
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
177

C
clevercong 已提交
178
**参数:**
C
clevercong 已提交
179

C
clevercong 已提交
180 181
| 参数名  | 类型                                     | 必填 | 说明                                                         |
| ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
182
| options | [UDPSendOptions](#udpsendoptions) | 是   | UDPSocket发送参数,参考[UDPSendOptions](#udpsendoptions)。 |
C
clevercong 已提交
183

Y
Yangys 已提交
184 185 186 187 188 189 190
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
191
**返回值:**
C
clevercong 已提交
192

C
clevercong 已提交
193 194 195
| 类型            | 说明                                           |
| :-------------- | :--------------------------------------------- |
| Promise\<void\> | 以Promise形式返回UDPSocket连接发送数据的结果。 |
C
clevercong 已提交
196

C
clevercong 已提交
197
**示例:**
C
clevercong 已提交
198

Z
zengyawen 已提交
199
```js
C
clevercong 已提交
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
let udp = socket.constructUDPSocketInstance();
let promise = udp.send({
  data:'Hello, server!',
  address: {
	address:'192.168.xx.xxx',
	port:xxxx,
	family:1
  }
});
promise.then(() => {
  console.log('send success');
}).catch(err => {
  console.log('send fail');
});
```
C
clevercong 已提交
215 216


C
clevercong 已提交
217
### close
C
clevercong 已提交
218 219 220 221 222

close\(callback: AsyncCallback<void\>\): void

关闭UDPSocket连接。使用callback方式作为异步方法。

C
clevercong 已提交
223 224
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
225
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
226

C
clevercong 已提交
227
**参数:**
C
clevercong 已提交
228

C
clevercong 已提交
229 230 231
| 参数名   | 类型                  | 必填 | 说明       |
| -------- | --------------------- | ---- | ---------- |
| callback | AsyncCallback\<void\> | 是   | 回调函数。 |
C
clevercong 已提交
232

C
clevercong 已提交
233
**示例:**
C
clevercong 已提交
234

Z
zengyawen 已提交
235
```js
C
clevercong 已提交
236 237 238 239 240 241 242 243 244
let udp = socket.constructUDPSocketInstance();
udp.close(err => {
  if (err) {
	console.log('close fail');
	return;
  }
  console.log('close success');
})
```
C
clevercong 已提交
245 246


C
clevercong 已提交
247
### close
C
clevercong 已提交
248 249 250 251 252

close\(\): Promise<void\>

关闭UDPSocket连接。使用Promise方式作为异步方法。

C
clevercong 已提交
253 254
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
255
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
256

C
clevercong 已提交
257
**返回值:**
C
clevercong 已提交
258

C
clevercong 已提交
259 260 261
| 类型            | 说明                                       |
| :-------------- | :----------------------------------------- |
| Promise\<void\> | 以Promise形式返回关闭UDPSocket连接的结果。 |
C
clevercong 已提交
262

C
clevercong 已提交
263
**示例:**
C
clevercong 已提交
264

Z
zengyawen 已提交
265
```js
C
clevercong 已提交
266 267 268 269 270 271 272 273
let udp = socket.constructUDPSocketInstance();
let promise = udp.close();
promise.then(() => {
  console.log('close success');
}).catch(err => {
  console.log('close fail');
});
```
C
clevercong 已提交
274 275


C
clevercong 已提交
276
### getState
C
clevercong 已提交
277 278 279 280 281 282

getState\(callback: AsyncCallback<SocketStateBase\>\): void

获取UDPSocket状态。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
283 284 285
>[bind](#bind)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
286

C
clevercong 已提交
287
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
288

C
clevercong 已提交
289 290 291 292
**参数:**

| 参数名   | 类型                                                   | 必填 | 说明       |
| -------- | ------------------------------------------------------ | ---- | ---------- |
C
clevercong 已提交
293
| callback | AsyncCallback<[SocketStateBase](#socketstatebase)> | 是   | 回调函数。 |
C
clevercong 已提交
294

Y
Yangys 已提交
295 296 297 298 299 300
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 201     | Permission denied.      |

C
clevercong 已提交
301 302
**示例:**

Z
zengyawen 已提交
303
```js
C
clevercong 已提交
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
let udp = socket.constructUDPSocketInstance();
udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => {
  if (err) {
	console.log('bind fail');
	return;
  }
  console.log('bind success');
  udp.getState((err, data) => {
	if (err) {
	  console.log('getState fail');
	  return;
	}
	console.log('getState success:' + JSON.stringify(data));
  })
})
```
C
clevercong 已提交
320 321


C
clevercong 已提交
322
### getState
C
clevercong 已提交
323 324 325 326 327 328

getState\(\): Promise<SocketStateBase\>

获取UDPSocket状态。使用Promise方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
329 330 331
>[bind](#bind)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
332

C
clevercong 已提交
333
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
334

C
clevercong 已提交
335
**返回值:**
C
clevercong 已提交
336

C
clevercong 已提交
337 338
| 类型                                             | 说明                                       |
| :----------------------------------------------- | :----------------------------------------- |
C
clevercong 已提交
339
| Promise<[SocketStateBase](#socketstatebase)> | 以Promise形式返回获取UDPSocket状态的结果。 |
C
clevercong 已提交
340

C
clevercong 已提交
341
**示例:**
C
clevercong 已提交
342

Z
zengyawen 已提交
343
```js
C
clevercong 已提交
344 345 346 347 348 349 350
let udp = socket.constructUDPSocketInstance();
udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => {
  if (err) {
	console.log('bind fail');
	return;
  }
  console.log('bind success');
Z
zhuwenchao 已提交
351
  let promise = udp.getState();
C
clevercong 已提交
352 353 354 355 356 357 358
  promise.then(data => {
	console.log('getState success:' + JSON.stringify(data));
  }).catch(err => {
	console.log('getState fail');
  });
})
```
C
clevercong 已提交
359 360


C
clevercong 已提交
361
### setExtraOptions
C
clevercong 已提交
362 363 364 365 366 367

setExtraOptions\(options: UDPExtraOptions, callback: AsyncCallback<void\>\): void

设置UDPSocket连接的其他属性。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
368 369 370
>[bind](#bind)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
371

C
clevercong 已提交
372
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
373

C
clevercong 已提交
374 375 376 377
**参数:**

| 参数名   | 类型                                     | 必填 | 说明                                                         |
| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
378
| options  | [UDPExtraOptions](#udpextraoptions) | 是   | UDPSocket连接的其他属性,参考[UDPExtraOptions](#udpextraoptions)。 |
C
clevercong 已提交
379 380
| callback | AsyncCallback\<void\>                    | 是   | 回调函数。                                                   |

Y
Yangys 已提交
381 382 383 384 385 386
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |
C
clevercong 已提交
387 388 389

**示例:**

Z
zengyawen 已提交
390
```js
C
clevercong 已提交
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412
let udp = socket.constructUDPSocketInstance();
udp.bind({address:'192.168.xx.xxx', port:xxxx, family:1}, err=> {
  if (err) {
	console.log('bind fail');
	return;
  }
  console.log('bind success');
  udp.setExtraOptions({
	receiveBufferSize:1000,
	sendBufferSize:1000,
	reuseAddress:false,
	socketTimeout:6000,
	broadcast:true
  }, err=> {
	if (err) {
	  console.log('setExtraOptions fail');
	  return;
	}
	console.log('setExtraOptions success');
  })
})
```
C
clevercong 已提交
413 414


C
clevercong 已提交
415
### setExtraOptions
C
clevercong 已提交
416 417 418 419 420 421

setExtraOptions\(options: UDPExtraOptions\): Promise<void\>

设置UDPSocket连接的其他属性。使用Promise方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
422 423 424
>[bind](#bind)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
425

C
clevercong 已提交
426
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
427

C
clevercong 已提交
428 429 430 431
**参数:**

| 参数名  | 类型                                     | 必填 | 说明                                                         |
| ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
432
| options | [UDPExtraOptions](#udpextraoptions) | 是   | UDPSocket连接的其他属性,参考[UDPExtraOptions](#udpextraoptions)。 |
C
clevercong 已提交
433 434 435 436 437 438 439

**返回值:**

| 类型            | 说明                                                 |
| :-------------- | :--------------------------------------------------- |
| Promise\<void\> | 以Promise形式返回设置UDPSocket连接的其他属性的结果。 |

Y
Yangys 已提交
440 441 442 443 444 445 446
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
447 448
**示例:**

Z
zengyawen 已提交
449
```js
C
clevercong 已提交
450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469
let udp = socket.constructUDPSocketInstance();
let promise = udp.bind({address:'192.168.xx.xxx', port:xxxx, family:1});
promise.then(() => {
  console.log('bind success');
  let promise1 = udp.setExtraOptions({
	receiveBufferSize:1000,
	sendBufferSize:1000,
	reuseAddress:false,
	socketTimeout:6000,
	broadcast:true
  });
  promise1.then(() => {
	console.log('setExtraOptions success');
  }).catch(err => {
	console.log('setExtraOptions fail');
  });
}).catch(err => {
  console.log('bind fail');
});
```
C
clevercong 已提交
470 471


C
clevercong 已提交
472
### on\('message'\)
C
clevercong 已提交
473 474 475 476 477

on\(type: 'message', callback: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void

订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。

C
clevercong 已提交
478
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
479

C
clevercong 已提交
480
**参数:**
C
clevercong 已提交
481

C
clevercong 已提交
482 483 484
| 参数名   | 类型                                                         | 必填 | 说明                                      |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- |
| type     | string                                                       | 是   | 订阅的事件类型。'message':接收消息事件。 |
C
clevercong 已提交
485
| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | 是   | 回调函数。                                |
C
clevercong 已提交
486

C
clevercong 已提交
487
**示例:**
C
clevercong 已提交
488

Z
zengyawen 已提交
489
```js
C
clevercong 已提交
490 491
let udp = socket.constructUDPSocketInstance();
udp.on('message', value => {
C
clevercong 已提交
492
	console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo);
C
clevercong 已提交
493 494
});
```
C
clevercong 已提交
495 496


C
clevercong 已提交
497
### off\('message'\)
C
clevercong 已提交
498 499 500 501 502 503 504 505

off\(type: 'message', callback?: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void

取消订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
506
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
507

C
clevercong 已提交
508
**参数:**
C
clevercong 已提交
509

C
clevercong 已提交
510 511 512
| 参数名   | 类型                                                         | 必填 | 说明                                      |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- |
| type     | string                                                       | 是   | 订阅的事件类型。'message':接收消息事件。 |
C
clevercong 已提交
513
| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | 否   | 回调函数。                                |
C
clevercong 已提交
514

C
clevercong 已提交
515
**示例:**
C
clevercong 已提交
516

Z
zengyawen 已提交
517
```js
C
clevercong 已提交
518 519
let udp = socket.constructUDPSocketInstance();
let callback = value =>{
C
clevercong 已提交
520
	console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo);
C
clevercong 已提交
521 522 523 524 525 526
}
udp.on('message', callback);
// 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
udp.off('message', callback);
udp.off('message');
```
C
clevercong 已提交
527 528


C
clevercong 已提交
529
### on\('listening' | 'close'\)
C
clevercong 已提交
530 531 532 533 534

on\(type: 'listening' | 'close', callback: Callback<void\>\): void

订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。

C
clevercong 已提交
535
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
536

C
clevercong 已提交
537
**参数:**
C
clevercong 已提交
538

C
clevercong 已提交
539 540 541 542
| 参数名   | 类型             | 必填 | 说明                                                         |
| -------- | ---------------- | ---- | ------------------------------------------------------------ |
| type     | string           | 是   | 订阅的事件类型。<br />- 'listening':数据包消息事件。<br />- 'close':关闭事件。 |
| callback | Callback\<void\> | 是   | 回调函数。                                                   |
C
clevercong 已提交
543

C
clevercong 已提交
544
**示例:**
C
clevercong 已提交
545

Z
zengyawen 已提交
546
```js
C
clevercong 已提交
547 548
let udp = socket.constructUDPSocketInstance();
udp.on('listening', () => {
C
clevercong 已提交
549
	console.log("on listening success");
C
clevercong 已提交
550 551 552 553 554
});
udp.on('close', () => {
	console.log("on close success" );
});
```
C
clevercong 已提交
555 556


C
clevercong 已提交
557
### off\('listening' | 'close'\)
C
clevercong 已提交
558 559 560 561 562 563 564 565

off\(type: 'listening' | 'close', callback?: Callback<void\>\): void

取消订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
566
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
567

C
clevercong 已提交
568 569 570 571 572 573 574 575 576
**参数:**

| 参数名   | 类型             | 必填 | 说明                                                         |
| -------- | ---------------- | ---- | ------------------------------------------------------------ |
| type     | string           | 是   | 订阅事件类型。<br />- 'listening':数据包消息事件。<br />- 'close':关闭事件。 |
| callback | Callback\<void\> | 否   | 回调函数。                                                   |

**示例:**

Z
zengyawen 已提交
577
```js
C
clevercong 已提交
578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593
let udp = socket.constructUDPSocketInstance();
let callback1 = () =>{
	console.log("on listening, success");
}
udp.on('listening', callback1);
// 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
udp.off('listening', callback1);
udp.off('listening');
let callback2 = () =>{
	console.log("on close, success");
}
udp.on('close', callback2);
// 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
udp.off('close', callback2);
udp.off('close');
```
C
clevercong 已提交
594 595


C
clevercong 已提交
596
### on\('error'\)
C
clevercong 已提交
597 598 599 600 601

on\(type: 'error', callback: ErrorCallback\): void

订阅UDPSocket连接的error事件。使用callback方式作为异步方法。

C
clevercong 已提交
602
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
603

C
clevercong 已提交
604
**参数:**
C
clevercong 已提交
605

C
clevercong 已提交
606 607 608 609
| 参数名   | 类型          | 必填 | 说明                                 |
| -------- | ------------- | ---- | ------------------------------------ |
| type     | string        | 是   | 订阅的事件类型。'error':error事件。 |
| callback | ErrorCallback | 是   | 回调函数。                           |
C
clevercong 已提交
610

C
clevercong 已提交
611
**示例:**
C
clevercong 已提交
612

Z
zengyawen 已提交
613
```js
Z
zengyawen 已提交
614
let udp = socket.constructUDPSocketInstance();
C
clevercong 已提交
615 616 617 618
udp.on('error', err => {
	console.log("on error, err:" + JSON.stringify(err))
});
```
C
clevercong 已提交
619 620


C
clevercong 已提交
621
### off\('error'\)
C
clevercong 已提交
622 623 624 625 626 627 628 629

off\(type: 'error', callback?: ErrorCallback\): void

取消订阅UDPSocket连接的error事件。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
630
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
631

C
clevercong 已提交
632
**参数:**
C
clevercong 已提交
633

C
clevercong 已提交
634 635 636 637
| 参数名   | 类型          | 必填 | 说明                                 |
| -------- | ------------- | ---- | ------------------------------------ |
| type     | string        | 是   | 订阅的事件类型。'error':error事件。 |
| callback | ErrorCallback | 否   | 回调函数。                           |
C
clevercong 已提交
638

C
clevercong 已提交
639
**示例:**
C
clevercong 已提交
640

Z
zengyawen 已提交
641
```js
Z
zengyawen 已提交
642
let udp = socket.constructUDPSocketInstance();
C
clevercong 已提交
643 644 645 646 647 648 649 650
let callback = err =>{
	console.log("on error, err:" + JSON.stringify(err));
}
udp.on('error', callback);
// 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
udp.off('error', callback);
udp.off('error');
```
C
clevercong 已提交
651 652


C
clevercong 已提交
653
## NetAddress
C
clevercong 已提交
654 655 656

目标地址信息。

C
clevercong 已提交
657 658
**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

L
liyufan 已提交
659
| 名称  | 类型   | 必填 | 说明                                                         |
C
clevercong 已提交
660 661 662 663 664
| ------- | ------ | ---- | ------------------------------------------------------------ |
| address | string | 是   | 本地绑定的ip地址。                                           |
| port    | number | 否   | 端口号 ,范围0~65535。如果不指定系统随机分配端口。           |
| family  | number | 否   | 网络协议类型,可选类型:<br />- 1:IPv4<br />- 2:IPv6<br />默认为1。 |

C
clevercong 已提交
665
## UDPSendOptions
C
clevercong 已提交
666 667 668

UDPSocket发送参数。

C
clevercong 已提交
669 670
**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

L
liyufan 已提交
671
| 名称  | 类型                               | 必填 | 说明           |
C
clevercong 已提交
672
| ------- | ---------------------------------- | ---- | -------------- |
Z
zhuwenchao 已提交
673
| data    | string \| ArrayBuffer<sup>7+</sup>                          | 是   | 发送的数据。   |
C
clevercong 已提交
674
| address | [NetAddress](#netaddress) | 是   | 目标地址信息。 |
C
clevercong 已提交
675

C
clevercong 已提交
676
## UDPExtraOptions
C
clevercong 已提交
677 678 679

UDPSocket连接的其他属性。

C
clevercong 已提交
680 681
**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

L
liyufan 已提交
682
| 名称            | 类型    | 必填 | 说明                             |
C
clevercong 已提交
683 684 685 686 687 688 689
| ----------------- | ------- | ---- | -------------------------------- |
| broadcast         | boolean | 否   | 是否可以发送广播。默认为false。  |
| receiveBufferSize | number  | 否   | 接收缓冲区大小(单位:Byte)。   |
| sendBufferSize    | number  | 否   | 发送缓冲区大小(单位:Byte)。   |
| reuseAddress      | boolean | 否   | 是否重用地址。默认为false。      |
| socketTimeout     | number  | 否   | 套接字超时时间,单位毫秒(ms)。 |

C
clevercong 已提交
690
## SocketStateBase
C
clevercong 已提交
691 692 693

Socket的状态信息。

C
clevercong 已提交
694 695
**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

L
liyufan 已提交
696
| 名称      | 类型    | 必填 | 说明       |
C
clevercong 已提交
697 698 699 700 701
| ----------- | ------- | ---- | ---------- |
| isBound     | boolean | 是   | 是否绑定。 |
| isClose     | boolean | 是   | 是否关闭。 |
| isConnected | boolean | 是   | 是否连接。 |

C
clevercong 已提交
702
## SocketRemoteInfo
C
clevercong 已提交
703 704 705

Socket的连接信息。

C
clevercong 已提交
706 707
**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

L
liyufan 已提交
708
| 名称  | 类型   | 必填 | 说明                                                         |
C
clevercong 已提交
709 710 711 712 713 714
| ------- | ------ | ---- | ------------------------------------------------------------ |
| address | string | 是   | 本地绑定的ip地址。                                           |
| family  | string | 是   | 网络协议类型,可选类型:<br />- IPv4<br />- IPv6<br />默认为IPv4。 |
| port    | number | 是   | 端口号,范围0~65535。                                        |
| size    | number | 是   | 服务器响应信息的字节长度。                                   |

Y
Yangys 已提交
715
## UDP 错误码说明
Y
Yangys 已提交
716

Y
Yangys 已提交
717
UDP 其余错误码映射形式为:2301000 + 内核错误码。
Y
Yangys 已提交
718

Y
Yangys 已提交
719
错误码的详细介绍参见[Socket错误码](../errorcodes/errorcode-net-socket.md)
Y
Yangys 已提交
720

C
clevercong 已提交
721
## socket.constructTCPSocketInstance
C
clevercong 已提交
722 723 724 725 726

constructTCPSocketInstance\(\): TCPSocket

创建一个TCPSocket对象。

C
clevercong 已提交
727
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
728

C
clevercong 已提交
729
**返回值:**
C
clevercong 已提交
730 731 732

  | 类型                               | 说明                    |
  | :--------------------------------- | :---------------------- |
C
clevercong 已提交
733
  | [TCPSocket](#tcpsocket) | 返回一个TCPSocket对象。 |
C
clevercong 已提交
734

C
clevercong 已提交
735
**示例:**
C
clevercong 已提交
736

Z
zengyawen 已提交
737
```js
C
clevercong 已提交
738 739
let tcp = socket.constructTCPSocketInstance();
```
C
clevercong 已提交
740 741


C
clevercong 已提交
742
## TCPSocket
C
clevercong 已提交
743

C
clevercong 已提交
744
TCPSocket连接。在调用TCPSocket的方法前,需要先通过[socket.constructTCPSocketInstance](#socketconstructtcpsocketinstance)创建TCPSocket对象。
C
clevercong 已提交
745

C
clevercong 已提交
746
### bind
C
clevercong 已提交
747 748 749 750 751

bind\(address: NetAddress, callback: AsyncCallback<void\>\): void

绑定IP地址和端口,端口可以指定或由系统随机分配。使用callback方法作为异步方法。

C
clevercong 已提交
752 753
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
754
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
755

C
clevercong 已提交
756
**参数:**
C
clevercong 已提交
757

C
clevercong 已提交
758 759
| 参数名   | 类型                               | 必填 | 说明                                                   |
| -------- | ---------------------------------- | ---- | ------------------------------------------------------ |
C
clevercong 已提交
760
| address  | [NetAddress](#netaddress) | 是   | 目标地址信息,参考[NetAddress](#netaddress)。 |
C
clevercong 已提交
761
| callback | AsyncCallback\<void\>              | 是   | 回调函数。                                             |
C
clevercong 已提交
762

Y
Yangys 已提交
763 764 765 766 767 768
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |
C
clevercong 已提交
769

C
clevercong 已提交
770
**示例:**
C
clevercong 已提交
771

Z
zengyawen 已提交
772
```js
C
clevercong 已提交
773 774 775 776 777 778 779 780 781
let tcp = socket.constructTCPSocketInstance();
tcp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => {
  if (err) {
	console.log('bind fail');
	return;
  }
  console.log('bind success');
})
```
C
clevercong 已提交
782 783


C
clevercong 已提交
784
### bind
C
clevercong 已提交
785

C
clevercong 已提交
786
bind\(address: NetAddress\): Promise<void\>
C
clevercong 已提交
787 788 789

绑定IP地址和端口,端口可以指定或由系统随机分配。使用Promise方法作为异步方法。

C
clevercong 已提交
790 791
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
792
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
793

C
clevercong 已提交
794
**参数:**
C
clevercong 已提交
795

C
clevercong 已提交
796 797
| 参数名  | 类型                               | 必填 | 说明                                                   |
| ------- | ---------------------------------- | ---- | ------------------------------------------------------ |
C
clevercong 已提交
798
| address | [NetAddress](#netaddress) | 是   | 目标地址信息,参考[NetAddress](#netaddress)。 |
C
clevercong 已提交
799

C
clevercong 已提交
800
**返回值:**
C
clevercong 已提交
801

C
clevercong 已提交
802 803 804
| 类型            | 说明                                                     |
| :-------------- | :------------------------------------------------------- |
| Promise\<void\> | 以Promise形式返回TCPSocket绑定本机的IP地址和端口的结果。 |
C
clevercong 已提交
805

Y
Yangys 已提交
806 807 808 809 810 811 812
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
813
**示例:**
C
clevercong 已提交
814

Z
zengyawen 已提交
815
```js
C
clevercong 已提交
816 817 818 819 820 821 822 823
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1});
promise.then(() => {
  console.log('bind success');
}).catch(err => {
  console.log('bind fail');
});
```
C
clevercong 已提交
824 825


C
clevercong 已提交
826
### connect
C
clevercong 已提交
827 828 829 830 831

connect\(options: TCPConnectOptions, callback: AsyncCallback<void\>\): void

连接到指定的IP地址和端口。使用callback方法作为异步方法。

C
clevercong 已提交
832 833
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
834
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
835

C
clevercong 已提交
836
**参数:**
C
clevercong 已提交
837

C
clevercong 已提交
838 839
| 参数名   | 类型                                     | 必填 | 说明                                                         |
| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
840
| options  | [TCPConnectOptions](#tcpconnectoptions) | 是   | TCPSocket连接的参数,参考[TCPConnectOptions](#tcpconnectoptions)。 |
C
clevercong 已提交
841
| callback | AsyncCallback\<void\>                    | 是   | 回调函数。                                                   |
C
clevercong 已提交
842

Y
Yangys 已提交
843 844 845 846 847 848 849
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
850
**示例:**
C
clevercong 已提交
851

Z
zengyawen 已提交
852
```js
C
clevercong 已提交
853 854 855 856 857 858 859 860 861
let tcp = socket.constructTCPSocketInstance();
tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000}, err => {
  if (err) {
	console.log('connect fail');
	return;
  }
  console.log('connect success');
})
```
C
clevercong 已提交
862 863


C
clevercong 已提交
864
### connect
C
clevercong 已提交
865 866 867 868 869

connect\(options: TCPConnectOptions\): Promise<void\>

连接到指定的IP地址和端口。使用promise方法作为异步方法。

C
clevercong 已提交
870 871
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
872
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
873

C
clevercong 已提交
874
**参数:**
C
clevercong 已提交
875

C
clevercong 已提交
876 877
| 参数名  | 类型                                     | 必填 | 说明                                                         |
| ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
878
| options | [TCPConnectOptions](#tcpconnectoptions) | 是   | TCPSocket连接的参数,参考[TCPConnectOptions](#tcpconnectoptions)。 |
C
clevercong 已提交
879

C
clevercong 已提交
880
**返回值:**
C
clevercong 已提交
881

C
clevercong 已提交
882 883 884
| 类型            | 说明                                                       |
| :-------------- | :--------------------------------------------------------- |
| Promise\<void\> | 以Promise形式返回TCPSocket连接到指定的IP地址和端口的结果。 |
C
clevercong 已提交
885

Y
Yangys 已提交
886 887 888 889 890 891 892
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
893
**示例:**
C
clevercong 已提交
894

Z
zengyawen 已提交
895
```js
C
clevercong 已提交
896 897 898 899 900 901 902 903
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000});
promise.then(() => {
  console.log('connect success')
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
904 905


C
clevercong 已提交
906
### send
C
clevercong 已提交
907 908 909 910 911 912

send\(options: TCPSendOptions, callback: AsyncCallback<void\>\): void

通过TCPSocket连接发送数据。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
913 914 915
>[connect](#connect)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
916

C
clevercong 已提交
917
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
918

C
clevercong 已提交
919 920 921 922
**参数:**

| 参数名   | 类型                                    | 必填 | 说明                                                         |
| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
923
| options  | [TCPSendOptions](#tcpsendoptions) | 是   | TCPSocket发送请求的参数,参考[TCPSendOptions](#tcpsendoptions)。 |
C
clevercong 已提交
924 925
| callback | AsyncCallback\<void\>                   | 是   | 回调函数。                                                   |

Y
Yangys 已提交
926 927 928 929 930 931 932
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
933 934
**示例:**

Z
zengyawen 已提交
935
```js
C
clevercong 已提交
936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000});
promise.then(() => {
  console.log('connect success');
  tcp.send({
	data:'Hello, server!'
  },err => {
	if (err) {
	  console.log('send fail');
	  return;
	}
	console.log('send success');
  })
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
953 954


C
clevercong 已提交
955
### send
C
clevercong 已提交
956 957 958 959 960 961

send\(options: TCPSendOptions\): Promise<void\>

通过TCPSocket连接发送数据。使用Promise方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
962 963 964
>[connect](#connect)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
965

C
clevercong 已提交
966
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
967

C
clevercong 已提交
968 969 970 971
**参数:**

| 参数名  | 类型                                    | 必填 | 说明                                                         |
| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
972
| options | [TCPSendOptions](#tcpsendoptions) | 是   | TCPSocket发送请求的参数,参考[TCPSendOptions](#tcpsendoptions)。 |
C
clevercong 已提交
973 974 975 976 977 978 979

**返回值:**

| 类型            | 说明                                               |
| :-------------- | :------------------------------------------------- |
| Promise\<void\> | 以Promise形式返回通过TCPSocket连接发送数据的结果。 |

Y
Yangys 已提交
980 981 982 983 984 985 986
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
987 988
**示例:**

Z
zengyawen 已提交
989
```js
C
clevercong 已提交
990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005
let tcp = socket.constructTCPSocketInstance();
let promise1 = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000});
promise1.then(() => {
  console.log('connect success');
  let promise2 = tcp.send({
	data:'Hello, server!'
  });
  promise2.then(() => {
	console.log('send success');
  }).catch(err => {
	console.log('send fail');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1006 1007


C
clevercong 已提交
1008
### close
C
clevercong 已提交
1009 1010 1011 1012 1013

close\(callback: AsyncCallback<void\>\): void

关闭TCPSocket连接。使用callback方式作为异步方法。

C
clevercong 已提交
1014 1015
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
1016
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1017

C
clevercong 已提交
1018
**参数:**
C
clevercong 已提交
1019

C
clevercong 已提交
1020 1021 1022
| 参数名   | 类型                  | 必填 | 说明       |
| -------- | --------------------- | ---- | ---------- |
| callback | AsyncCallback\<void\> | 是   | 回调函数。 |
C
clevercong 已提交
1023

Y
Yangys 已提交
1024 1025 1026 1027 1028
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 201     | Permission denied.      |
C
clevercong 已提交
1029

C
clevercong 已提交
1030
**示例:**
C
clevercong 已提交
1031

Z
zengyawen 已提交
1032
```js
C
clevercong 已提交
1033 1034 1035 1036 1037 1038 1039 1040 1041
let tcp = socket.constructTCPSocketInstance();
tcp.close(err => {
  if (err) {
	console.log('close fail');
	return;
  }
  console.log('close success');
})
```
C
clevercong 已提交
1042 1043


C
clevercong 已提交
1044
### close
C
clevercong 已提交
1045 1046 1047 1048 1049

close\(\): Promise<void\>

关闭TCPSocket连接。使用Promise方式作为异步方法。

C
clevercong 已提交
1050 1051
**需要权限**:ohos.permission.INTERNET

C
clevercong 已提交
1052
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1053

C
clevercong 已提交
1054
**返回值:**
C
clevercong 已提交
1055

C
clevercong 已提交
1056 1057 1058
| 类型            | 说明                                       |
| :-------------- | :----------------------------------------- |
| Promise\<void\> | 以Promise形式返回关闭TCPSocket连接的结果。 |
C
clevercong 已提交
1059

Y
Yangys 已提交
1060 1061 1062 1063 1064 1065
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 201     | Permission denied.      |

C
clevercong 已提交
1066
**示例:**
C
clevercong 已提交
1067

Z
zengyawen 已提交
1068
```js
C
clevercong 已提交
1069 1070 1071 1072 1073 1074 1075 1076
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.close();
promise.then(() => {
  console.log('close success');
}).catch(err => {
  console.log('close fail');
});
```
C
clevercong 已提交
1077 1078


C
clevercong 已提交
1079
### getRemoteAddress
C
clevercong 已提交
1080 1081 1082 1083 1084 1085

getRemoteAddress\(callback: AsyncCallback<NetAddress\>\): void

获取对端Socket地址。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
1086 1087 1088
>[connect](#connect)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
1089

C
clevercong 已提交
1090
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1091

C
clevercong 已提交
1092
**参数:**
C
clevercong 已提交
1093

C
clevercong 已提交
1094 1095
| 参数名   | 类型                                              | 必填 | 说明       |
| -------- | ------------------------------------------------- | ---- | ---------- |
C
clevercong 已提交
1096
| callback | AsyncCallback<[NetAddress](#netaddress)> | 是   | 回调函数。 |
C
clevercong 已提交
1097

Y
Yangys 已提交
1098 1099 1100 1101 1102 1103
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 201     | Permission denied.      |

C
clevercong 已提交
1104
**示例:**
C
clevercong 已提交
1105

Z
zengyawen 已提交
1106
```js
C
clevercong 已提交
1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000});
promise.then(() => {
  console.log('connect success');
  tcp.getRemoteAddress((err, data) => {
	if (err) {
	  console.log('getRemoteAddressfail');
	  return;
	}
	console.log('getRemoteAddresssuccess:' + JSON.stringify(data));
  })
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1122 1123


C
clevercong 已提交
1124
### getRemoteAddress
C
clevercong 已提交
1125 1126 1127 1128 1129 1130

getRemoteAddress\(\): Promise<NetAddress\>

获取对端Socket地址。使用Promise方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
1131 1132 1133
>[connect](#connect)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
1134

C
clevercong 已提交
1135
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1136

C
clevercong 已提交
1137
**返回值:**
C
clevercong 已提交
1138

C
clevercong 已提交
1139 1140
| 类型                                        | 说明                                        |
| :------------------------------------------ | :------------------------------------------ |
C
clevercong 已提交
1141
| Promise<[NetAddress](#netaddress)> | 以Promise形式返回获取对端socket地址的结果。 |
C
clevercong 已提交
1142

Y
Yangys 已提交
1143 1144 1145 1146 1147 1148
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 201     | Permission denied.      |

C
clevercong 已提交
1149
**示例:**
C
clevercong 已提交
1150

Z
zengyawen 已提交
1151
```js
C
clevercong 已提交
1152 1153 1154 1155 1156 1157
let tcp = socket.constructTCPSocketInstance();
let promise1 = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000});
promise1.then(() => {
  console.log('connect success');
  let promise2 = tcp.getRemoteAddress();
  promise2.then(() => {
F
fuchao 已提交
1158
	console.log('getRemoteAddress success');
C
clevercong 已提交
1159 1160 1161 1162 1163 1164 1165
  }).catch(err => {
	console.log('getRemoteAddressfail');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1166 1167


C
clevercong 已提交
1168
### getState
C
clevercong 已提交
1169 1170 1171 1172 1173 1174

getState\(callback: AsyncCallback<SocketStateBase\>\): void

获取TCPSocket状态。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
1175 1176 1177
>[bind](#bind)或[connect](#connect)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
1178

C
clevercong 已提交
1179
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1180

C
clevercong 已提交
1181
**参数:**
C
clevercong 已提交
1182

C
clevercong 已提交
1183 1184
| 参数名   | 类型                                                   | 必填 | 说明       |
| -------- | ------------------------------------------------------ | ---- | ---------- |
C
clevercong 已提交
1185
| callback | AsyncCallback<[SocketStateBase](#socketstatebase)> | 是   | 回调函数。 |
C
clevercong 已提交
1186

Y
Yangys 已提交
1187 1188 1189 1190 1191
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 201     | Permission denied.      |
C
clevercong 已提交
1192

C
clevercong 已提交
1193
**示例:**
C
clevercong 已提交
1194

Z
zengyawen 已提交
1195
```js
C
clevercong 已提交
1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000});
promise.then(() => {
  console.log('connect success');
  tcp.getState((err, data) => {
	if (err) {
	  console.log('getState fail');
	  return;
	}
	console.log('getState success:' + JSON.stringify(data));
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1211 1212


C
clevercong 已提交
1213
### getState
C
clevercong 已提交
1214 1215 1216 1217 1218 1219

getState\(\): Promise<SocketStateBase\>

获取TCPSocket状态。使用Promise方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
1220 1221 1222
>[bind](#bind)或[connect](#connect)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
1223

C
clevercong 已提交
1224
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1225

C
clevercong 已提交
1226
**返回值:**
C
clevercong 已提交
1227

C
clevercong 已提交
1228 1229
| 类型                                             | 说明                                       |
| :----------------------------------------------- | :----------------------------------------- |
C
clevercong 已提交
1230
| Promise<[SocketStateBase](#socketstatebase)> | 以Promise形式返回获取TCPSocket状态的结果。 |
C
clevercong 已提交
1231

Y
Yangys 已提交
1232 1233 1234 1235 1236
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 201     | Permission denied.      |
C
clevercong 已提交
1237

C
clevercong 已提交
1238
**示例:**
C
clevercong 已提交
1239

Z
zengyawen 已提交
1240
```js
C
clevercong 已提交
1241 1242 1243 1244 1245 1246
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000});
promise.then(() => {
  console.log('connect success');
  let promise1 = tcp.getState();
  promise1.then(() => {
F
fuchao 已提交
1247
	console.log('getState success');
C
clevercong 已提交
1248 1249 1250 1251 1252 1253 1254
  }).catch(err => {
	console.log('getState fail');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1255 1256


C
clevercong 已提交
1257
### setExtraOptions
C
clevercong 已提交
1258 1259 1260 1261 1262 1263

setExtraOptions\(options: TCPExtraOptions, callback: AsyncCallback<void\>\): void

设置TCPSocket连接的其他属性。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
1264 1265 1266
>[bind](#bind)或[connect](#connect)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
1267

C
clevercong 已提交
1268
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1269

C
clevercong 已提交
1270 1271 1272 1273
**参数:**

| 参数名   | 类型                                      | 必填 | 说明                                                         |
| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
1274
| options  | [TCPExtraOptions](#tcpextraoptions) | 是   | TCPSocket连接的其他属性,参考[TCPExtraOptions](#tcpextraoptions)。 |
C
clevercong 已提交
1275 1276
| callback | AsyncCallback\<void\>                     | 是   | 回调函数。                                                   |

Y
Yangys 已提交
1277 1278 1279 1280 1281 1282 1283
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |

C
clevercong 已提交
1284 1285
**示例:**

Z
zengyawen 已提交
1286
```js
C
clevercong 已提交
1287 1288 1289 1290 1291 1292 1293 1294
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000});
promise.then(() => {
  console.log('connect success');
  tcp.setExtraOptions({
	keepAlive: true,
	OOBInline: true,
	TCPNoDelay: true,
C
clevercong 已提交
1295
	socketLinger: { on:true, linger:10 },
C
clevercong 已提交
1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310
	receiveBufferSize: 1000,
	sendBufferSize: 1000,
	reuseAddress: true,
	socketTimeout: 3000,
  },err => {
	if (err) {
	  console.log('setExtraOptions fail');
	  return;
	}
	console.log('setExtraOptions success');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1311 1312


C
clevercong 已提交
1313
### setExtraOptions
C
clevercong 已提交
1314 1315 1316 1317 1318 1319

setExtraOptions\(options: TCPExtraOptions\): Promise<void\>

设置TCPSocket连接的其他属性,使用Promise方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
C
clevercong 已提交
1320 1321 1322
>[bind](#bind)或[connect](#connect)方法调用成功后,才可调用此方法。

**需要权限**:ohos.permission.INTERNET
C
clevercong 已提交
1323

C
clevercong 已提交
1324
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1325

C
clevercong 已提交
1326 1327 1328 1329
**参数:**

| 参数名  | 类型                                      | 必填 | 说明                                                         |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
1330
| options | [TCPExtraOptions](#tcpextraoptions) | 是   | TCPSocket连接的其他属性,参考[TCPExtraOptions](#tcpextraoptions)。 |
C
clevercong 已提交
1331 1332 1333 1334 1335 1336 1337

**返回值:**

| 类型            | 说明                                                 |
| :-------------- | :--------------------------------------------------- |
| Promise\<void\> | 以Promise形式返回设置TCPSocket连接的其他属性的结果。 |

Y
Yangys 已提交
1338 1339 1340 1341 1342 1343
**错误码:**

| 错误码ID | 错误信息                 |
| ------- | ----------------------- |
| 401     | Parameter error.        |
| 201     | Permission denied.      |
C
clevercong 已提交
1344 1345 1346

**示例:**

Z
zengyawen 已提交
1347
```js
C
clevercong 已提交
1348 1349 1350 1351 1352 1353 1354 1355
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.connect({ address: {address: '192.168.xx.xxx', port: xxxx, family: 1} , timeout: 6000});
promise.then(() => {
  console.log('connect success');
  let promise1 = tcp.setExtraOptions({
	keepAlive: true,
	OOBInline: true,
	TCPNoDelay: true,
C
clevercong 已提交
1356
	socketLinger: { on:true, linger:10 },
C
clevercong 已提交
1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370
	receiveBufferSize: 1000,
	sendBufferSize: 1000,
	reuseAddress: true,
	socketTimeout: 3000,
  });
  promise1.then(() => {
	console.log('setExtraOptions success');
  }).catch(err => {
	console.log('setExtraOptions fail');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1371 1372


C
clevercong 已提交
1373
### on\('message'\)
C
clevercong 已提交
1374 1375 1376 1377 1378

on\(type: 'message', callback: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void

订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。

C
clevercong 已提交
1379
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1380

C
clevercong 已提交
1381
**参数:**
C
clevercong 已提交
1382

C
clevercong 已提交
1383 1384 1385
| 参数名   | 类型                                                         | 必填 | 说明                                      |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- |
| type     | string                                                       | 是   | 订阅的事件类型。'message':接收消息事件。 |
C
clevercong 已提交
1386
| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | 是   | 回调函数。                                |
C
clevercong 已提交
1387

C
clevercong 已提交
1388
**示例:**
C
clevercong 已提交
1389

Z
zengyawen 已提交
1390
```js
C
clevercong 已提交
1391 1392 1393 1394 1395
let tcp = socket.constructTCPSocketInstance();
tcp.on('message', value => {
	console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo)
});
```
C
clevercong 已提交
1396 1397


C
clevercong 已提交
1398
### off\('message'\)
C
clevercong 已提交
1399 1400 1401 1402 1403 1404 1405 1406

off\(type: 'message', callback?: Callback<\{message: ArrayBuffer, remoteInfo: SocketRemoteInfo\}\>\): void

取消订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
1407
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1408

C
clevercong 已提交
1409
**参数:**
C
clevercong 已提交
1410

C
clevercong 已提交
1411 1412 1413
| 参数名   | 类型                                                         | 必填 | 说明                                      |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- |
| type     | string                                                       | 是   | 订阅的事件类型。'message':接收消息事件。 |
C
clevercong 已提交
1414
| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | 否   | 回调函数。                                |
C
clevercong 已提交
1415

C
clevercong 已提交
1416
**示例:**
C
clevercong 已提交
1417

Z
zengyawen 已提交
1418
```js
C
clevercong 已提交
1419 1420 1421 1422 1423 1424 1425 1426 1427
let tcp = socket.constructTCPSocketInstance();
let callback = value =>{
	console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo);
}
tcp.on('message', callback);
// 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
tcp.off('message', callback);
tcp.off('message');
```
C
clevercong 已提交
1428 1429


C
clevercong 已提交
1430
### on\('connect' | 'close'\)
C
clevercong 已提交
1431 1432 1433 1434 1435

on\(type: 'connect' | 'close', callback: Callback<void\>\): void

订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。

C
clevercong 已提交
1436
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1437

C
clevercong 已提交
1438
**参数:**
C
clevercong 已提交
1439

C
clevercong 已提交
1440 1441 1442 1443
| 参数名   | 类型             | 必填 | 说明                                                         |
| -------- | ---------------- | ---- | ------------------------------------------------------------ |
| type     | string           | 是   | 订阅的事件类型。<br />- 'connect':连接事件。<br />- 'close':关闭事件。 |
| callback | Callback\<void\> | 是   | 回调函数。                                                   |
C
clevercong 已提交
1444

C
clevercong 已提交
1445
**示例:**
C
clevercong 已提交
1446

Z
zengyawen 已提交
1447
```js
C
clevercong 已提交
1448 1449 1450 1451 1452 1453 1454 1455
let tcp = socket.constructTCPSocketInstance();
tcp.on('connect', () => {
	console.log("on connect success")
});
tcp.on('close', data => {
	console.log("on close success")
});
```
C
clevercong 已提交
1456 1457


C
clevercong 已提交
1458
### off\('connect' | 'close'\)
C
clevercong 已提交
1459

C
clevercong 已提交
1460
off\(type: 'connect' | 'close', callback?: Callback<void\>\): void
C
clevercong 已提交
1461 1462 1463 1464 1465 1466

取消订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
1467
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1468

C
clevercong 已提交
1469 1470 1471 1472 1473 1474 1475 1476 1477
**参数:**

| 参数名   | 类型             | 必填 | 说明                                                         |
| -------- | ---------------- | ---- | ------------------------------------------------------------ |
| type     | string           | 是   | 订阅的事件类型。<br />- 'connect':连接事件。<br />- 'close':关闭事件。 |
| callback | Callback\<void\> | 否   | 回调函数。                                                   |

**示例:**

Z
zengyawen 已提交
1478
```js
C
clevercong 已提交
1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494
let tcp = socket.constructTCPSocketInstance();
let callback1 = () =>{
	console.log("on connect success");
}
tcp.on('connect', callback1);
// 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
tcp.off('connect', callback1);
tcp.off('connect');
let callback2 = () =>{
	console.log("on close success");
}
tcp.on('close', callback2);
// 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
tcp.off('close', callback2);
tcp.off('close');
```
C
clevercong 已提交
1495 1496


C
clevercong 已提交
1497
### on\('error'\)
C
clevercong 已提交
1498 1499 1500 1501 1502

on\(type: 'error', callback: ErrorCallback\): void

订阅TCPSocket连接的error事件。使用callback方式作为异步方法。

C
clevercong 已提交
1503
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1504

C
clevercong 已提交
1505
**参数:**
C
clevercong 已提交
1506

C
clevercong 已提交
1507 1508 1509 1510
| 参数名   | 类型          | 必填 | 说明                                 |
| -------- | ------------- | ---- | ------------------------------------ |
| type     | string        | 是   | 订阅的事件类型。'error':error事件。 |
| callback | ErrorCallback | 是   | 回调函数。                           |
C
clevercong 已提交
1511

C
clevercong 已提交
1512
**示例:**
C
clevercong 已提交
1513

Z
zengyawen 已提交
1514
```js
C
clevercong 已提交
1515 1516 1517 1518 1519
let tcp = socket.constructTCPSocketInstance();
tcp.on('error', err => {
	console.log("on error, err:" + JSON.stringify(err))
});
```
C
clevercong 已提交
1520 1521


C
clevercong 已提交
1522
### off\('error'\)
C
clevercong 已提交
1523 1524 1525 1526 1527 1528 1529 1530

off\(type: 'error', callback?: ErrorCallback\): void

取消订阅TCPSocket连接的error事件。使用callback方式作为异步方法。

>![](public_sys-resources/icon-note.gif) **说明:** 
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
1531
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1532

C
clevercong 已提交
1533 1534 1535 1536 1537 1538 1539 1540 1541
**参数:**

| 参数名   | 类型          | 必填 | 说明                                 |
| -------- | ------------- | ---- | ------------------------------------ |
| type     | string        | 是   | 订阅的事件类型。'error':error事件。 |
| callback | ErrorCallback | 否   | 回调函数。                           |

**示例:**

Z
zengyawen 已提交
1542
```js
C
clevercong 已提交
1543 1544 1545 1546 1547 1548 1549 1550 1551
let tcp = socket.constructTCPSocketInstance();
let callback = err =>{
	console.log("on error, err:" + JSON.stringify(err));
}
tcp.on('error', callback);
// 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
tcp.off('error', callback);
tcp.off('error');
```
C
clevercong 已提交
1552 1553


C
clevercong 已提交
1554
## TCPConnectOptions
C
clevercong 已提交
1555 1556 1557

TCPSocket连接的参数。

C
clevercong 已提交
1558 1559
**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

L
liyufan 已提交
1560
| 名称  | 类型                               | 必填 | 说明                       |
C
clevercong 已提交
1561
| ------- | ---------------------------------- | ---- | -------------------------- |
C
clevercong 已提交
1562
| address | [NetAddress](#netaddress) | 是   | 绑定的地址以及端口。       |
C
clevercong 已提交
1563 1564
| timeout | number                             | 否   | 超时时间,单位毫秒(ms)。 |

C
clevercong 已提交
1565
## TCPSendOptions
C
clevercong 已提交
1566 1567 1568

TCPSocket发送请求的参数。

C
clevercong 已提交
1569 1570
**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

L
liyufan 已提交
1571
| 名称   | 类型   | 必填 | 说明                                                         |
C
clevercong 已提交
1572
| -------- | ------ | ---- | ------------------------------------------------------------ |
Z
zhuwenchao 已提交
1573
| data     | string\| ArrayBuffer<sup>7+</sup>  | 是   | 发送的数据。                                                 |
C
clevercong 已提交
1574 1575
| encoding | string | 否   | 字符编码(UTF-8,UTF-16BE,UTF-16LE,UTF-16,US-AECII,ISO-8859-1),默认为UTF-8。 |

C
clevercong 已提交
1576
## TCPExtraOptions
C
clevercong 已提交
1577 1578 1579

TCPSocket连接的其他属性。

C
clevercong 已提交
1580 1581
**系统能力**:以下各项对应的系统能力均为SystemCapability.Communication.NetStack。

L
liyufan 已提交
1582
| 名称            | 类型    | 必填 | 说明                                                         |
C
clevercong 已提交
1583 1584 1585 1586 1587 1588 1589 1590 1591
| ----------------- | ------- | ---- | ------------------------------------------------------------ |
| keepAlive         | boolean | 否   | 是否保持连接。默认为false。                                  |
| OOBInline         | boolean | 否   | 是否为OOB内联。默认为false。                                 |
| TCPNoDelay        | boolean | 否   | TCPSocket连接是否无时延。默认为false。                       |
| socketLinger      | Object  | 是   | socket是否继续逗留。<br />- on:是否逗留(true:逗留;false:不逗留)。<br />- linger:逗留时长,单位毫秒(ms),取值范围为0~65535。<br />当入参on设置为true时,才需要设置。 |
| receiveBufferSize | number  | 否   | 接收缓冲区大小(单位:Byte)。                               |
| sendBufferSize    | number  | 否   | 发送缓冲区大小(单位:Byte)。                               |
| reuseAddress      | boolean | 否   | 是否重用地址。默认为false。                                  |
| socketTimeout     | number  | 否   | 套接字超时时间,单位毫秒(ms)。                             |
L
liyufan 已提交
1592

Y
Yangys 已提交
1593
## TCP 错误码说明
Y
Yangys 已提交
1594

Y
Yangys 已提交
1595
TCP 其余错误码映射形式为:2301000 + 内核错误码。
Y
Yangys 已提交
1596

Y
Yangys 已提交
1597
错误码的详细介绍参见[Socket错误码](../errorcodes/errorcode-net-socket.md)
Y
Yangys 已提交
1598

L
liyufan 已提交
1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642
## socket.constructTLSSocketInstance<sup>9+</sup>

constructTLSSocketInstance(): TLSSocket

创建并返回一个TLSSocket对象。

**系统能力**:SystemCapability.Communication.NetStack

**返回值:**

| 类型                               | 说明                    |
| :--------------------------------- | :---------------------- |
| [TLSSocket](#tlssocket9) | 返回一个TLSSocket对象。 |

**示例:**

```js
let tls = socket.constructTLSSocketInstance();
```

## TLSSocket<sup>9+</sup>

TLSSocket连接。在调用TLSSocket的方法前,需要先通过[socket.constructTLSSocketInstance](#socketconstructtlssocketinstance9)创建TLSSocket对象。

### bind<sup>9+</sup>

bind\(address: NetAddress, callback: AsyncCallback<void\>\): void

绑定IP地址和端口。使用callback方法作为异步方法。

**需要权限**:ohos.permission.INTERNET

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                               | 必填 | 说明                                                   |
| -------- | ---------------------------------- | ---- | ------------------------------------------------------ |
| address  | [NetAddress](#netaddress) | 是   | 目标地址信息,参考[NetAddress](#netaddress)。 |
| callback | AsyncCallback\<void\>              | 是   | 回调函数。成功返回TLSSocket绑定本机的IP地址和端口的结果。 失败返回错误码,错误信息。|

**错误码:**

| 错误码ID | 错误信息                 |
L
liyufan 已提交
1643
| ------- | ----------------------- |
L
liyufan 已提交
1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674
| 401     | Parameter error.        |
| 201     | Permission denied.      |
| 2303198 | Address already in use. |
| 2300002 | System internal error.  |

**示例:**

```js
tls.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => {
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});
```

### bind<sup>9+</sup>

bind\(address: NetAddress\): Promise<void\>

绑定IP地址和端口。使用Promise方法作为异步方法。

**需要权限**:ohos.permission.INTERNET

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名  | 类型                               | 必填 | 说明                                                   |
| ------- | ---------------------------------- | ---- | ------------------------------------------------------ |
L
liyufan 已提交
1675
| address | [NetAddress](#netaddress)          | 是   | 目标地址信息,参考[NetAddress](#netaddress)。 |
L
liyufan 已提交
1676 1677 1678 1679 1680 1681 1682 1683 1684 1685

**返回值:**

| 类型            | 说明                                                     |
| :-------------- | :------------------------------------------------------- |
| Promise\<void\> | 以Promise形式返回TLSSocket绑定本机的IP地址和端口的结果。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                 |
L
liyufan 已提交
1686
| ------- | ----------------------- |
L
liyufan 已提交
1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719
| 401     | Parameter error.        |
| 201     | Permission denied.      |
| 2303198 | Address already in use. |
| 2300002 | System internal error.  |

**示例:**

```js
let promise = tls.bind({address: '192.168.xx.xxx', port: xxxx, family: 1});
promise.then(() => {
  console.log('bind success');
}).catch(err => {
  console.log('bind fail');
});
```

### getState<sup>9+</sup>

getState\(callback: AsyncCallback<SocketStateBase\>\): void

在TLSSocket的bind成功之后,获取TLSSocket状态。使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                                                   | 必填 | 说明       |
| -------- | ------------------------------------------------------ | ---- | ---------- |
| callback | AsyncCallback\<[SocketStateBase](#socketstatebase)> | 是   | 回调函数。成功返回TLSSocket状态,失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
1720
| ------- | ------------------------------ |
L
liyufan 已提交
1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error.         |

**示例:**

```js
let promise = tls.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => {
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});
tls.getState((err, data) => {
  if (err) {
    console.log('getState fail');
    return;
  }
  console.log('getState success:' + JSON.stringify(data));
});
```

### getState<sup>9+</sup>

getState\(\): Promise<SocketStateBase\>

在TLSSocket的bind成功之后,获取TLSSocket状态。使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**返回值:**

| 类型                                             | 说明                                       |
| :----------------------------------------------- | :----------------------------------------- |
| Promise\<[SocketStateBase](#socketstatebase)> | 以Promise形式返回获取TLSSocket状态的结果。失败返回错误码,错误信息。|

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
1760
| ------- | ------------------------------ |
L
liyufan 已提交
1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error.         |

**示例:**

```js
tls.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => {
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});
let promise = tls.getState();
promise.then(() => {
  console.log('getState success');
}).catch(err => {
  console.log('getState fail');
});
```

### setExtraOptions<sup>9+</sup>

setExtraOptions\(options: TCPExtraOptions, callback: AsyncCallback<void\>\): void

在TLSSocket的bind成功之后,设置TCPSocket连接的其他属性。使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                                      | 必填 | 说明                                                         |
| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| options  | [TCPExtraOptions](#tcpextraoptions) | 是   | TCPSocket连接的其他属性,参考[TCPExtraOptions](#tcpextraoptions)。 |
| callback | AsyncCallback\<void\>                     | 是   | 回调函数。成功返回设置TCPSocket连接的其他属性的结果,失败返回错误码,错误信息。|

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
1800
| ------- | -----------------------------  |
L
liyufan 已提交
1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856
| 401     | Parameter error.               |
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error.         |

**示例:**

```js
tls.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => {
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});

tls.setExtraOptions({
  keepAlive: true,
  OOBInline: true,
  TCPNoDelay: true,
  socketLinger: { on:true, linger:10 },
  receiveBufferSize: 1000,
  sendBufferSize: 1000,
  reuseAddress: true,
  socketTimeout: 3000,
},err => {
  if (err) {
    console.log('setExtraOptions fail');
    return;
  }
  console.log('setExtraOptions success');
});
```

### setExtraOptions<sup>9+</sup>

setExtraOptions\(options: TCPExtraOptions\): Promise<void\>

在TLSSocket的bind成功之后,设置TCPSocket连接的其他属性,使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名  | 类型                                      | 必填 | 说明                                                         |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| options | [TCPExtraOptions](#tcpextraoptions) | 是   | TCPSocket连接的其他属性,参考[TCPExtraOptions](#tcpextraoptions)。 |

**返回值:**

| 类型            | 说明                                                 |
| :-------------- | :--------------------------------------------------- |
| Promise\<void\> | 以Promise形式返回设置TCPSocket连接的其他属性的结果。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
1857
| ------- | ------------------------------ |
L
liyufan 已提交
1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906
| 401     | Parameter error.               |
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error.         |

**示例:**

```js
tls.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => {
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});
let promise = tls.setExtraOptions({
  keepAlive: true,
  OOBInline: true,
  TCPNoDelay: true,
  socketLinger: { on:true, linger:10 },
  receiveBufferSize: 1000,
  sendBufferSize: 1000,
  reuseAddress: true,
  socketTimeout: 3000,
});
promise.then(() => {
  console.log('setExtraOptions success');
}).catch(err => {
  console.log('setExtraOptions fail');
});
```

### connect<sup>9+</sup>

connect(options: TLSConnectOptions, callback: AsyncCallback\<void>): void

在TLSSocket上bind成功之后,进行通信连接,并创建和初始化TLS会话,实现建立连接过程,启动与服务器的TLS/SSL握手,实现数据传输功能,使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                                   | 必填 | 说明 |
| -------- | ---------------------------------------| ----| --------------- |
| options  | [TLSConnectOptions](#tlsconnectoptions9) | 是   | TLSSocket连接所需要的参数。|
| callback | AsyncCallback\<void>                  | 是   | 回调函数,成功无返回,失败返回错误码,错误信息。|

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
1907
| ------- | -------------------------------------------- |
L
liyufan 已提交
1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926
| 401     | Parameter error.                             |
| 2303104 | Interrupted system call.                     |
| 2303109 | Bad file number.                             |
| 2303111 | Resource temporarily unavailable try again.  |
| 2303188 | Socket operation on non-socket.              |
| 2303191 | Protocol wrong type for socket.              |
| 2303198 | Address already in use.                      |
| 2303199 | Cannot assign requested address.             |
| 2303210 | Connection timed out.                        |
| 2303501 | SSL is null.                                 |
| 2303502 | Error in tls reading.                        |
| 2303503 | Error in tls writing                         |
| 2303505 | Error occurred in the tls system call.       |
| 2303506 | Error clearing tls connection.               |
| 2300002 | System internal error.                       |

**示例:**

```js
Y
YOUR_NAME 已提交
1927
let tlsTwoWay = socket.constructTLSSocketInstance(); // Two way authentication
Z
zhanghaifeng 已提交
1928
tlsTwoWay.bind({address: '192.168.xxx.xxx', port: 8080, family: 1}, err => {
L
liyufan 已提交
1929 1930 1931 1932 1933 1934 1935 1936 1937 1938
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});
let options = {
  ALPNProtocols: ["spdy/1", "http/1.1"],
  address: {
    address: "192.168.xx.xxx",
Z
zhanghaifeng 已提交
1939
    port: 8080,
L
liyufan 已提交
1940 1941 1942 1943 1944 1945
    family: 1,
  },
  secureOptions: {
    key: "xxxx",
    cert: "xxxx",
    ca: ["xxxx"],
Z
zhanghaifeng 已提交
1946
    password: "xxxx",
Y
YOUR_NAME 已提交
1947
    protocols: [socket.Protocol.TLSv12],
L
liyufan 已提交
1948
    useRemoteCipherPrefer: true,
Y
YOUR_NAME 已提交
1949 1950
    signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
    cipherSuite: "AES256-SHA256",
L
liyufan 已提交
1951 1952
  },
};
Y
YOUR_NAME 已提交
1953
tlsTwoWay.connect(options, (err, data) => {
Z
zhanghaifeng 已提交
1954 1955
  console.error("connect callback error"+err);
  console.log(JSON.stringify(data));
L
liyufan 已提交
1956 1957 1958
});

let tlsOneWay = socket.constructTLSSocketInstance(); // One way authentication
Z
zhanghaifeng 已提交
1959
  tlsOneWay.bind({address: '192.168.xxx.xxx', port: 8080, family: 1}, err => {
L
liyufan 已提交
1960 1961 1962 1963 1964 1965 1966 1967 1968
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});
let oneWayOptions = {
  address: {
    address: "192.168.xxx.xxx",
Z
zhanghaifeng 已提交
1969
    port: 8080,
L
liyufan 已提交
1970 1971 1972 1973
    family: 1,
  },
  secureOptions: {
    ca: ["xxxx","xxxx"],
Y
YOUR_NAME 已提交
1974
    cipherSuite: "AES256-SHA256",
L
liyufan 已提交
1975 1976
  },
};
Y
YOUR_NAME 已提交
1977
tlsOneWay.connect(oneWayOptions, (err, data) => {
Z
zhanghaifeng 已提交
1978 1979
  console.error("connect callback error"+err);
  console.log(JSON.stringify(data));
L
liyufan 已提交
1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005
});
```

### connect<sup>9+</sup>

connect(options: TLSConnectOptions): Promise\<void>

在TLSSocket上bind成功之后,进行通信连接,并创建和初始化TLS会话,实现建立连接过程,启动与服务器的TLS/SSL握手,实现数据传输功能,该连接包括两种认证方式,单向认证与双向认证,使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                                   | 必填 | 说明 |
| -------- | --------------------------------------| ----| --------------- |
| options  | [TLSConnectOptions](#tlsconnectoptions9) | 是   | 连接所需要的参数。|

**返回值:**

| 类型                                        | 说明                          |
| ------------------------------------------- | ----------------------------- |
| Promise\<void>                              | 以Promise形式返回,成功无返回,失败返回错误码,错误信息。|

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2006
| ------- | -------------------------------------------- |
L
liyufan 已提交
2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025
| 401     | Parameter error.                             |
| 2303104 | Interrupted system call.                     |
| 2303109 | Bad file number.                             |
| 2303111 | Resource temporarily unavailable try again.  |
| 2303188 | Socket operation on non-socket.              |
| 2303191 | Protocol wrong type for socket.              |
| 2303198 | Address already in use.                      |
| 2303199 | Cannot assign requested address.             |
| 2303210 | Connection timed out.                        |
| 2303501 | SSL is null.                                 |
| 2303502 | Error in tls reading.                        |
| 2303503 | Error in tls writing                         |
| 2303505 | Error occurred in the tls system call.       |
| 2303506 | Error clearing tls connection.               |
| 2300002 | System internal error.                       |

**示例:**

```js
Y
YOUR_NAME 已提交
2026
let tlsTwoWay = socket.constructTLSSocketInstance(); // Two way authentication
Z
zhanghaifeng 已提交
2027
tlsTwoWay.bind({address: '192.168.xxx.xxx', port: 8080, family: 1}, err => {
L
liyufan 已提交
2028 2029 2030 2031 2032 2033 2034 2035 2036 2037
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});
let options = {
  ALPNProtocols: ["spdy/1", "http/1.1"],
  address: {
    address: "xxxx",
Z
zhanghaifeng 已提交
2038
    port: 8080,
L
liyufan 已提交
2039 2040 2041 2042 2043 2044
    family: 1,
  },
  secureOptions: {
    key: "xxxx",
    cert: "xxxx",
    ca: ["xxxx"],
Z
zhanghaifeng 已提交
2045
    password: "xxxx",
Y
YOUR_NAME 已提交
2046
    protocols: [socket.Protocol.TLSv12],
L
liyufan 已提交
2047
    useRemoteCipherPrefer: true,
Y
YOUR_NAME 已提交
2048 2049
    signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
    cipherSuite: "AES256-SHA256",
L
liyufan 已提交
2050 2051
  },
};
Y
YOUR_NAME 已提交
2052
tlsTwoWay.connect(options).then(data => {
Z
zhanghaifeng 已提交
2053
  console.log(JSON.stringify(data));
L
liyufan 已提交
2054 2055 2056 2057 2058
}).catch(err => {
  console.error(err);
});

let tlsOneWay = socket.constructTLSSocketInstance(); // One way authentication
Z
zhanghaifeng 已提交
2059
tlsOneWay.bind({address: '192.168.xxx.xxx', port: 8080, family: 1}, err => {
L
liyufan 已提交
2060 2061 2062 2063 2064 2065 2066 2067 2068
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});
let oneWayOptions = {
  address: {
    address: "192.168.xxx.xxx",
Z
zhanghaifeng 已提交
2069
    port: 8080,
L
liyufan 已提交
2070 2071 2072 2073
    family: 1,
  },
  secureOptions: {
    ca: ["xxxx","xxxx"],
Y
YOUR_NAME 已提交
2074
    cipherSuite: "AES256-SHA256",
L
liyufan 已提交
2075 2076 2077
  },
};
tlsOneWay.connect(oneWayOptions).then(data => {
Z
zhanghaifeng 已提交
2078
  console.log(JSON.stringify(data));
L
liyufan 已提交
2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100
}).catch(err => {
  console.error(err);
});
```

### getRemoteAddress<sup>9+</sup>

getRemoteAddress\(callback: AsyncCallback<NetAddress\>\): void

在TLSSocket通信连接成功之后,获取对端Socket地址。使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                                              | 必填 | 说明       |
| -------- | ------------------------------------------------- | ---- | ---------- |
| callback | AsyncCallback\<[NetAddress](#netaddress)> | 是   | 回调函数。成功返回对端的socket地址,失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
Y
YOUR_NAME 已提交
2101
| ------- | -----------------------------  |
L
liyufan 已提交
2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error.         |

**示例:**

```js
tls.getRemoteAddress((err, data) => {
  if (err) {
    console.log('getRemoteAddress fail');
    return;
  }
  console.log('getRemoteAddress success:' + JSON.stringify(data));
});
```

### getRemoteAddress<sup>9+</sup>

getRemoteAddress\(\): Promise\<NetAddress>

在TLSSocket通信连接成功之后,获取对端Socket地址。使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**返回值:**

| 类型                                        | 说明                                        |
| :------------------------------------------ | :------------------------------------------ |
| Promise\<[NetAddress](#netaddress)> | 以Promise形式返回获取对端socket地址的结果。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
Y
YOUR_NAME 已提交
2134
| ------- | ------------------------------ |
L
liyufan 已提交
2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error.         |

**示例:**

```js
let promise = tls.getRemoteAddress();
promise.then(() => {
  console.log('getRemoteAddress success');
}).catch(err => {
  console.log('getRemoteAddress fail');
});
```

### getCertificate<sup>9+</sup>

getCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata9)>): void

在TLSSocket通信连接成功之后,获取本地的数字证书,该接口只适用于双向认证时,使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                                   | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback\<[X509CertRawData](#x509certrawdata9)>    | 是   | 回调函数,成功返回本地的证书,失败返回错误码,错误信息。|

**错误码:**

| 错误码ID | 错误信息                        |
Y
YOUR_NAME 已提交
2166
| ------- | ------------------------------ |
L
liyufan 已提交
2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199
| 2303501 | SSL is null.                   |
| 2303504 | Error looking up x509.         |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getCertificate((err, data) => {
  if (err) {
    console.log("getCertificate callback error = " + err);
  } else {
    console.log("getCertificate callback = " + data);
  }
});
```

### getCertificate<sup>9+</sup>

getCertificate():Promise\<[X509CertRawData](#x509certrawdata9)>

在TLSSocket通信连接之后,获取本地的数字证书,该接口只适用于双向认证时,使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**返回值:**

| 类型            | 说明                  |
| -------------- | -------------------- |
| Promise\<[X509CertRawData](#x509certrawdata9)> | 以Promise形式返回本地的数字证书的结果。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
Y
YOUR_NAME 已提交
2200
| ------- | ------------------------------ |
L
liyufan 已提交
2201 2202 2203 2204 2205 2206 2207 2208
| 2303501 | SSL is null.                   |
| 2303504 | Error looking up x509.         |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getCertificate().then(data => {
Y
YOUR_NAME 已提交
2209
  console.log(data);
L
liyufan 已提交
2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231
}).catch(err => {
  console.error(err);
});
```

### getRemoteCertificate<sup>9+</sup>

getRemoteCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata9)>): void

在TLSSocket通信连接成功之后,获取服务端的数字证书,使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名    | 类型                                    | 必填  | 说明           |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback\<[X509CertRawData](#x509certrawdata9)>  | 是   | 回调函数,返回服务端的证书。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2232
| ------- | ------------------------------ |
L
liyufan 已提交
2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264
| 2303501 | SSL is null.                   |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getRemoteCertificate((err, data) => {
  if (err) {
    console.log("getRemoteCertificate callback error = " + err);
  } else {
    console.log("getRemoteCertificate callback = " + data);
  }
});
```

### getRemoteCertificate<sup>9+</sup>

getRemoteCertificate():Promise\<[X509CertRawData](#x509certrawdata9)>

在TLSSocket通信连接成功之后,获取服务端的数字证书,使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**返回值:**

| 类型            | 说明                  |
| -------------- | -------------------- |
| Promise\<[X509CertRawData](#x509certrawdata9)> | 以Promise形式返回服务端的数字证书的结果。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2265
| ------- | ------------------------------ |
L
liyufan 已提交
2266 2267 2268 2269 2270 2271 2272
| 2303501 | SSL is null.                   |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getRemoteCertificate().then(data => {
Y
YOUR_NAME 已提交
2273
  console.log(data);
L
liyufan 已提交
2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295
}).catch(err => {
  console.error(err);
});
```

### getProtocol<sup>9+</sup>

getProtocol(callback: AsyncCallback\<string>): void

在TLSSocket通信连接成功之后,获取通信的协议版本,使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                                       | 必填 | 说明           |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback\<string>                  | 是   | 回调函数,返回通信的协议。失败返回错误码,错误信息。|

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2296
| ------- | -----------------------------  |
L
liyufan 已提交
2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329
| 2303501 | SSL is null.                   |
| 2303505 | Error occurred in the tls system call. |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getProtocol((err, data) => {
  if (err) {
    console.log("getProtocol callback error = " + err);
  } else {
    console.log("getProtocol callback = " + data);
  }
});
```

### getProtocol<sup>9+</sup>

getProtocol():Promise\<string>

在TLSSocket通信连接成功之后,获取通信的协议版本,使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**返回值:**

| 类型            | 说明                  |
| -------------- | -------------------- |
| Promise\<string> | 以Promise形式返回通信的协议。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2330
| ------- | ------------------------------ |
L
liyufan 已提交
2331 2332 2333 2334 2335 2336 2337 2338
| 2303501 | SSL is null.                   |
| 2303505 | Error occurred in the tls system call. |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getProtocol().then(data => {
Y
YOUR_NAME 已提交
2339
  console.log(data);
L
liyufan 已提交
2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361
}).catch(err => {
  console.error(err);
});
```

### getCipherSuite<sup>9+</sup>

getCipherSuite(callback: AsyncCallback\<Array\<string>>): void

在TLSSocket通信连接成功之后,获取通信双方协商后的加密套件,使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                                     | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback\<Array\<string>>          | 是   | 回调函数,返回通信双方支持的加密套件。 失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2362
| ------- | ------------------------------ |
L
liyufan 已提交
2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396
| 2303501 | SSL is null.                   |
| 2303502 | Error in tls reading.          |
| 2303505 | Error occurred in the tls system call. |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getCipherSuite((err, data) => {
  if (err) {
    console.log("getCipherSuite callback error = " + err);
  } else {
    console.log("getCipherSuite callback = " + data);
  }
});
```

### getCipherSuite<sup>9+</sup>

getCipherSuite(): Promise\<Array\<string>>

在TLSSocket通信连接成功之后,获取通信双方协商后的加密套件,使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**返回值:**

| 类型                    | 说明                  |
| ---------------------- | --------------------- |
| Promise\<Array\<string>> | 以Promise形式返回通信双方支持的加密套件。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2397
| ------- | ------------------------------ |
L
liyufan 已提交
2398 2399 2400 2401 2402 2403 2404 2405 2406
| 2303501 | SSL is null.                   |
| 2303502 | Error in tls reading.          |
| 2303505 | Error occurred in the tls system call. |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getCipherSuite().then(data => {
Z
zhanghaifeng 已提交
2407
  console.log('getCipherSuite success:' + JSON.stringify(data));
L
liyufan 已提交
2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429
}).catch(err => {
  console.error(err);
});
```

### getSignatureAlgorithms<sup>9+</sup>

getSignatureAlgorithms(callback: AsyncCallback\<Array\<string>>): void

在TLSSocket通信连接成功之后,获取通信双方协商后签名算法,该接口只适配双向认证模式下,使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名   | 类型                                   | 必填 | 说明            |
| -------- | -------------------------------------| ---- | ---------------|
| callback | AsyncCallback\<Array\<string>>         | 是   | 回调函数,返回双方支持的签名算法。  |

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2430
| ------- | ------------------------------ |
L
liyufan 已提交
2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462
| 2303501 | SSL is null.                   |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getSignatureAlgorithms((err, data) => {
  if (err) {
    console.log("getSignatureAlgorithms callback error = " + err);
  } else {
    console.log("getSignatureAlgorithms callback = " + data);
  }
});
```

### getSignatureAlgorithms<sup>9+</sup>

getSignatureAlgorithms(): Promise\<Array\<string>>

在TLSSocket通信连接成功之后,获取通信双方协商后的签名算法,该接口只适配双向认证模式下,使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**返回值:**

| 类型                    | 说明                  |
| ---------------------- | -------------------- |
| Promise\<Array\<string>> | 以Promise形式返回获取到的双方支持的签名算法。 |

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2463
| ------- | ------------------------------ |
L
liyufan 已提交
2464 2465 2466 2467 2468 2469 2470
| 2303501 | SSL is null.                   |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getSignatureAlgorithms().then(data => {
Z
zhanghaifeng 已提交
2471
  console.log("getSignatureAlgorithms success" + data);
L
liyufan 已提交
2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494
}).catch(err => {
  console.error(err);
});
```

### send<sup>9+</sup>

send(data: string, callback: AsyncCallback\<void>): void

在TLSSocket通信连接成功之后,向服务端发送消息,使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名    | 类型                          | 必填 | 说明            |
| -------- | -----------------------------| ---- | ---------------|
|   data   | string                       | 是   | 发送的数据内容。   |
| callback | AsyncCallback\<void>         | 是   | 回调函数,返回TLSSocket发送数据的结果。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2495
| ------- | -------------------------------------------- |
L
liyufan 已提交
2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531
| 401     | Parameter error.                             |
| 2303501 | SSL is null.                                 |
| 2303503 | Error in tls writing                         |
| 2303505 | Error occurred in the tls system call.       |
| 2303506 | Error clearing tls connection.               |
| 2300002 | System internal error.                       |

**示例:**

```js
tls.send("xxxx", (err) => {
  if (err) {
    console.log("send callback error = " + err);
  } else {
    console.log("send success");
  }
});
```

### send<sup>9+</sup>

send(data: string): Promise\<void>

在TLSSocket通信连接成功之后,向服务端发送消息,使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名    | 类型                          | 必填 | 说明            |
| -------- | -----------------------------| ---- | ---------------|
|   data   | string                       | 是   | 发送的数据内容。   |

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2532
| ------- | -------------------------------------------- |
L
liyufan 已提交
2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572
| 401     | Parameter error.                             |
| 2303501 | SSL is null.                                 |
| 2303503 | Error in tls writing                         |
| 2303505 | Error occurred in the tls system call.       |
| 2303506 | Error clearing tls connection.               |
| 2300002 | System internal error.                       |

**返回值:**

| 类型           | 说明                  |
| -------------- | -------------------- |
| Promise\<void> | 以Promise形式返回,返回TLSSocket发送数据的结果。失败返回错误码,错误信息。 |

**示例:**

```js
tls.send("xxxx").then(() =>{
  console.log("send success");
}).catch(err => {
  console.error(err);
});
```

### close<sup>9+</sup>

close(callback: AsyncCallback\<void>): void

在TLSSocket通信连接成功之后,断开连接,使用callback方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**参数:**

| 参数名    | 类型                          | 必填 | 说明            |
| -------- | -----------------------------| ---- | ---------------|
| callback | AsyncCallback\<void>         | 是   | 回调函数,成功返回TLSSocket关闭连接的结果。 失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2573
| ------- | -------------------------------------------- |
L
liyufan 已提交
2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607
| 2303501 | SSL is null.                                 |
| 2303505 | Error occurred in the tls system call.       |
| 2303506 | Error clearing tls connection.               |
| 2300002 | System internal error.                       |

**示例:**

```js
tls.close((err) => {
  if (err) {
    console.log("close callback error = " + err);
  } else {
    console.log("close success");
  }
});
```

### close<sup>9+</sup>

close(): Promise\<void>

在TLSSocket通信连接成功之后,断开连接,使用Promise方式作为异步方法。

**系统能力**:SystemCapability.Communication.NetStack

**返回值:**

| 类型           | 说明                  |
| -------------- | -------------------- |
| Promise\<void> | 以Promise形式返回,返回TLSSocket关闭连接的结果。失败返回错误码,错误信息。 |

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2608
| ------- | -------------------------------------------- |
L
liyufan 已提交
2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629
| 2303501 | SSL is null.                                 |
| 2303505 | Error occurred in the tls system call.       |
| 2303506 | Error clearing tls connection.               |
| 2300002 | System internal error.                       |

**示例:**

```js
tls.close().then(() =>{
  console.log("close success");
}).catch(err => {
  console.error(err);
});
```

## TLSConnectOptions<sup>9+</sup>

TLS连接的操作。

**系统能力**:SystemCapability.Communication.NetStack

L
liyufan 已提交
2630 2631 2632 2633
| 名称          | 类型                                     | 必填 | 说明            |
| -------------- | ------------------------------------- | ---  |-------------- |
| address        | [NetAddress](#netaddress)             | 是  |  网关地址。       |
| secureOptions  | [TLSSecureOptions](#tlssecureoptions9) | 是 | TLS安全相关操作。|
Y
YOUR_NAME 已提交
2634
| ALPNProtocols  | Array\<string>                         | 否 | ALPN协议。      |
L
liyufan 已提交
2635 2636 2637 2638 2639 2640 2641

## TLSSecureOptions<sup>9+</sup>

TLS安全相关操作,其中ca证书为必选参数,其他参数为可选参数。当本地证书cert和私钥key不为空时,开启双向验证模式。cert和key其中一项为空时,开启单向验证模式。

**系统能力**:SystemCapability.Communication.NetStack

L
liyufan 已提交
2642 2643 2644 2645 2646
| 名称                 | 类型                                                    | 必填 | 说明                                |
| --------------------- | ------------------------------------------------------ | --- |----------------------------------- |
| ca                    | string \| Array\<string>                               | 是 | 服务端的ca证书,用于认证校验服务端的数字证书。|
| cert                  | string                                                  | 否 | 本地客户端的数字证书。                 |
| key                   | string                                                  | 否 | 本地数字证书的私钥。                   |
Z
zhanghaifeng 已提交
2647
| password                | string                                                  | 否 | 读取私钥的密码。                      |
L
liyufan 已提交
2648 2649 2650 2651
| protocols             | [Protocol](#protocol9) \|Array\<[Protocol](#protocol9)> | 否 | TLS的协议版本。                  |
| useRemoteCipherPrefer | boolean                                                 | 否 | 优先使用对等方的密码套件。          |
| signatureAlgorithms   | string                                                 | 否 | 通信过程中的签名算法。               |
| cipherSuite           | string                                                 | 否 | 通信过程中的加密套件。               |
L
liyufan 已提交
2652 2653 2654 2655 2656 2657 2658

## Protocol<sup>9+</sup>

TLS通信的协议版本。

**系统能力**:SystemCapability.Communication.NetStack

L
liyufan 已提交
2659 2660 2661 2662
| 名称      |    值    | 说明                |
| --------- | --------- |------------------ |
| TLSv12    | "TLSv1.2" | 使用TLSv1.2协议通信。 |
| TLSv13    | "TLSv1.3" | 使用TLSv1.3协议通信。 |
L
liyufan 已提交
2663 2664 2665 2666 2667 2668 2669

## X509CertRawData<sup>9+</sup>

存储证书的数据。

**系统能力**:SystemCapability.Communication.NetStack

L
liyufan 已提交
2670 2671
| 类型                                                                   | 说明                   |
| --------------------------------------------------------------------- | --------------------- |
Z
zhanghaifeng 已提交
2672
|[cryptoFramework.EncodingBlob](js-apis-cryptoFramework.md#datablob) | 存储证书的数据和编码格式 |