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

Y
Yangys 已提交
3 4
本模块提供利用Socket进行数据传输的能力,支持TCPSocket、UDPSocket、WebSocket和TLSSocket。

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

C
clevercong 已提交
9
## 导入模块
C
clevercong 已提交
10

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

C
clevercong 已提交
15
## socket.constructUDPSocketInstance
C
clevercong 已提交
16

Y
Yangys 已提交
17
constructUDPSocketInstance(): UDPSocket
C
clevercong 已提交
18 19 20

创建一个UDPSocket对象。

C
clevercong 已提交
21
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
22

C
clevercong 已提交
23
**返回值:**
C
clevercong 已提交
24

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


C
clevercong 已提交
30
**示例:**
C
clevercong 已提交
31

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


C
clevercong 已提交
37
## UDPSocket
C
clevercong 已提交
38

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

C
clevercong 已提交
41
### bind
C
clevercong 已提交
42

Y
Yangys 已提交
43
bind(address: NetAddress, callback: AsyncCallback\<void\>): void
C
clevercong 已提交
44 45 46

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

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

C
clevercong 已提交
49
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
50

C
clevercong 已提交
51
**参数:**
C
clevercong 已提交
52

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

Y
Yangys 已提交
58 59 60 61 62 63 64
**错误码:**

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

C
clevercong 已提交
65
**示例:**
C
clevercong 已提交
66

Z
zengyawen 已提交
67
```js
C
clevercong 已提交
68 69 70 71 72 73 74 75 76
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 已提交
77 78


C
clevercong 已提交
79
### bind
C
clevercong 已提交
80

Y
Yangys 已提交
81
bind(address: NetAddress): Promise\<void\>
C
clevercong 已提交
82 83 84

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

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

C
clevercong 已提交
87
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
88

C
clevercong 已提交
89
**参数:**
C
clevercong 已提交
90

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

Y
Yangys 已提交
95 96 97 98 99 100
**错误码:**

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

C
clevercong 已提交
102
**返回值:**
C
clevercong 已提交
103

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

C
clevercong 已提交
108
**示例:**
C
clevercong 已提交
109

Z
zengyawen 已提交
110
```js
C
clevercong 已提交
111 112 113 114 115 116 117 118
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 已提交
119 120


C
clevercong 已提交
121
### send
C
clevercong 已提交
122

Y
Yangys 已提交
123
send(options: UDPSendOptions, callback: AsyncCallback\<void\>): void
C
clevercong 已提交
124 125 126

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

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

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

C
clevercong 已提交
131
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
132

C
clevercong 已提交
133 134 135 136
**参数:**

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

Y
Yangys 已提交
140 141 142 143 144 145 146
**错误码:**

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

C
clevercong 已提交
147 148
**示例:**

Z
zengyawen 已提交
149
```js
C
clevercong 已提交
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
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 已提交
166 167


C
clevercong 已提交
168
### send
C
clevercong 已提交
169

Y
Yangys 已提交
170
send(options: UDPSendOptions): Promise\<void\>
C
clevercong 已提交
171 172 173

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

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

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

C
clevercong 已提交
178
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
179

C
clevercong 已提交
180
**参数:**
C
clevercong 已提交
181

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

Y
Yangys 已提交
186 187 188 189 190 191 192
**错误码:**

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

C
clevercong 已提交
193
**返回值:**
C
clevercong 已提交
194

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

C
clevercong 已提交
199
**示例:**
C
clevercong 已提交
200

Z
zengyawen 已提交
201
```js
C
clevercong 已提交
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216
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 已提交
217 218


C
clevercong 已提交
219
### close
C
clevercong 已提交
220

Y
Yangys 已提交
221
close(callback: AsyncCallback\<void\>): void
C
clevercong 已提交
222 223 224

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

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

C
clevercong 已提交
227
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
228

C
clevercong 已提交
229
**参数:**
C
clevercong 已提交
230

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

C
clevercong 已提交
235
**示例:**
C
clevercong 已提交
236

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


C
clevercong 已提交
249
### close
C
clevercong 已提交
250

Y
Yangys 已提交
251
close(): Promise\<void\>
C
clevercong 已提交
252 253 254

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

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

C
clevercong 已提交
257
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
258

C
clevercong 已提交
259
**返回值:**
C
clevercong 已提交
260

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

C
clevercong 已提交
265
**示例:**
C
clevercong 已提交
266

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


C
clevercong 已提交
278
### getState
C
clevercong 已提交
279

Y
Yangys 已提交
280
getState(callback: AsyncCallback\<SocketStateBase\>): void
C
clevercong 已提交
281 282 283

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

Y
Yangys 已提交
284
>**说明:** 
Y
Yangys 已提交
285
>bind方法调用成功后,才可调用此方法。
C
clevercong 已提交
286 287

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

C
clevercong 已提交
289
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
290

C
clevercong 已提交
291 292 293 294
**参数:**

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

Y
Yangys 已提交
297 298 299 300 301 302
**错误码:**

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

C
clevercong 已提交
303 304
**示例:**

Z
zengyawen 已提交
305
```js
C
clevercong 已提交
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321
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 已提交
322 323


C
clevercong 已提交
324
### getState
C
clevercong 已提交
325

Y
Yangys 已提交
326
getState(): Promise\<SocketStateBase\>
C
clevercong 已提交
327 328 329

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

Y
Yangys 已提交
330
>**说明:** 
Y
Yangys 已提交
331
>bind方法调用成功后,才可调用此方法。
C
clevercong 已提交
332 333

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

C
clevercong 已提交
335
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
336

C
clevercong 已提交
337
**返回值:**
C
clevercong 已提交
338

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

C
clevercong 已提交
343
**示例:**
C
clevercong 已提交
344

Z
zengyawen 已提交
345
```js
C
clevercong 已提交
346 347 348 349 350 351 352
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 已提交
353
  let promise = udp.getState();
C
clevercong 已提交
354 355 356 357 358 359 360
  promise.then(data => {
	console.log('getState success:' + JSON.stringify(data));
  }).catch(err => {
	console.log('getState fail');
  });
})
```
C
clevercong 已提交
361 362


C
clevercong 已提交
363
### setExtraOptions
C
clevercong 已提交
364

Y
Yangys 已提交
365
setExtraOptions(options: UDPExtraOptions, callback: AsyncCallback\<void\>): void
C
clevercong 已提交
366 367 368

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

Y
Yangys 已提交
369
>**说明:** 
Y
Yangys 已提交
370
>bind方法调用成功后,才可调用此方法。
C
clevercong 已提交
371 372

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

C
clevercong 已提交
374
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
375

C
clevercong 已提交
376 377 378 379
**参数:**

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

Y
Yangys 已提交
383 384 385 386 387 388
**错误码:**

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

**示例:**

Z
zengyawen 已提交
392
```js
C
clevercong 已提交
393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414
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 已提交
415 416


C
clevercong 已提交
417
### setExtraOptions
C
clevercong 已提交
418

Y
Yangys 已提交
419
setExtraOptions(options: UDPExtraOptions): Promise\<void\>
C
clevercong 已提交
420 421 422

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

Y
Yangys 已提交
423
>**说明:** 
Y
Yangys 已提交
424
>bind方法调用成功后,才可调用此方法。
C
clevercong 已提交
425 426

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

C
clevercong 已提交
428
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
429

C
clevercong 已提交
430 431 432 433
**参数:**

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

**返回值:**

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

Y
Yangys 已提交
442 443 444 445 446 447 448
**错误码:**

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

C
clevercong 已提交
449 450
**示例:**

Z
zengyawen 已提交
451
```js
C
clevercong 已提交
452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471
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 已提交
472 473


Y
Yangys 已提交
474
### on('message')
C
clevercong 已提交
475

Y
Yangys 已提交
476
on(type: 'message', callback: Callback\<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void
C
clevercong 已提交
477 478 479

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

C
clevercong 已提交
480
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
481

C
clevercong 已提交
482
**参数:**
C
clevercong 已提交
483

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

C
clevercong 已提交
489
**示例:**
C
clevercong 已提交
490

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


Y
Yangys 已提交
499
### off('message')
C
clevercong 已提交
500

Y
Yangys 已提交
501
off(type: 'message', callback?: Callback\<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void
C
clevercong 已提交
502 503 504

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

Y
Yangys 已提交
505
>**说明:** 
C
clevercong 已提交
506 507
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
508
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
509

C
clevercong 已提交
510
**参数:**
C
clevercong 已提交
511

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

C
clevercong 已提交
517
**示例:**
C
clevercong 已提交
518

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


Y
Yangys 已提交
531
### on('listening' | 'close')
C
clevercong 已提交
532

Y
Yangys 已提交
533
on(type: 'listening' | 'close', callback: Callback\<void\>): void
C
clevercong 已提交
534 535 536

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

C
clevercong 已提交
537
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
538

C
clevercong 已提交
539
**参数:**
C
clevercong 已提交
540

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

C
clevercong 已提交
546
**示例:**
C
clevercong 已提交
547

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


Y
Yangys 已提交
559
### off('listening' | 'close')
C
clevercong 已提交
560

Y
Yangys 已提交
561
off(type: 'listening' | 'close', callback?: Callback\<void\>): void
C
clevercong 已提交
562 563 564

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

Y
Yangys 已提交
565
>**说明:** 
C
clevercong 已提交
566 567
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
568
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
569

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

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

**示例:**

Z
zengyawen 已提交
579
```js
C
clevercong 已提交
580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595
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 已提交
596 597


Y
Yangys 已提交
598
### on('error')
C
clevercong 已提交
599

Y
Yangys 已提交
600
on(type: 'error', callback: ErrorCallback): void
C
clevercong 已提交
601 602 603

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

C
clevercong 已提交
604
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
605

C
clevercong 已提交
606
**参数:**
C
clevercong 已提交
607

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

C
clevercong 已提交
613
**示例:**
C
clevercong 已提交
614

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


Y
Yangys 已提交
623
### off('error')
C
clevercong 已提交
624

Y
Yangys 已提交
625
off(type: 'error', callback?: ErrorCallback): void
C
clevercong 已提交
626 627 628

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

Y
Yangys 已提交
629
>**说明:** 
C
clevercong 已提交
630 631
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
632
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
633

C
clevercong 已提交
634
**参数:**
C
clevercong 已提交
635

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

C
clevercong 已提交
641
**示例:**
C
clevercong 已提交
642

Z
zengyawen 已提交
643
```js
Z
zengyawen 已提交
644
let udp = socket.constructUDPSocketInstance();
C
clevercong 已提交
645 646 647 648 649 650 651 652
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 已提交
653 654


C
clevercong 已提交
655
## NetAddress
C
clevercong 已提交
656 657 658

目标地址信息。

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

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

C
clevercong 已提交
667
## UDPSendOptions
C
clevercong 已提交
668 669 670

UDPSocket发送参数。

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

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

C
clevercong 已提交
678
## UDPExtraOptions
C
clevercong 已提交
679 680 681

UDPSocket连接的其他属性。

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

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

C
clevercong 已提交
692
## SocketStateBase
C
clevercong 已提交
693 694 695

Socket的状态信息。

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

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

C
clevercong 已提交
704
## SocketRemoteInfo
C
clevercong 已提交
705 706 707

Socket的连接信息。

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

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

Y
Yangys 已提交
717
## UDP 错误码说明
Y
Yangys 已提交
718

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

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

C
clevercong 已提交
723
## socket.constructTCPSocketInstance
C
clevercong 已提交
724

Y
Yangys 已提交
725
constructTCPSocketInstance(): TCPSocket
C
clevercong 已提交
726 727 728

创建一个TCPSocket对象。

C
clevercong 已提交
729
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
730

C
clevercong 已提交
731
**返回值:**
C
clevercong 已提交
732 733 734

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

C
clevercong 已提交
737
**示例:**
C
clevercong 已提交
738

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


C
clevercong 已提交
744
## TCPSocket
C
clevercong 已提交
745

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

C
clevercong 已提交
748
### bind
C
clevercong 已提交
749

Y
Yangys 已提交
750
bind(address: NetAddress, callback: AsyncCallback\<void\>): void
C
clevercong 已提交
751 752 753

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

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

C
clevercong 已提交
756
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
757

C
clevercong 已提交
758
**参数:**
C
clevercong 已提交
759

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

Y
Yangys 已提交
765 766 767 768 769 770
**错误码:**

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

C
clevercong 已提交
772
**示例:**
C
clevercong 已提交
773

Z
zengyawen 已提交
774
```js
C
clevercong 已提交
775 776 777 778 779 780 781 782 783
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 已提交
784 785


C
clevercong 已提交
786
### bind
C
clevercong 已提交
787

Y
Yangys 已提交
788
bind(address: NetAddress): Promise\<void\>
C
clevercong 已提交
789 790 791

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

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

C
clevercong 已提交
794
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
795

C
clevercong 已提交
796
**参数:**
C
clevercong 已提交
797

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

C
clevercong 已提交
802
**返回值:**
C
clevercong 已提交
803

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

Y
Yangys 已提交
808 809 810 811 812 813 814
**错误码:**

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

C
clevercong 已提交
815
**示例:**
C
clevercong 已提交
816

Z
zengyawen 已提交
817
```js
C
clevercong 已提交
818 819 820 821 822 823 824 825
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 已提交
826 827


C
clevercong 已提交
828
### connect
C
clevercong 已提交
829

Y
Yangys 已提交
830
connect(options: TCPConnectOptions, callback: AsyncCallback\<void\>): void
C
clevercong 已提交
831 832 833

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

Y
Yangys 已提交
834
>**说明:** 
Y
Yangys 已提交
835 836
>bind方法调用成功后,才可调用此方法。

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

C
clevercong 已提交
839
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
840

C
clevercong 已提交
841
**参数:**
C
clevercong 已提交
842

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

Y
Yangys 已提交
848 849 850 851 852 853 854
**错误码:**

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

C
clevercong 已提交
855
**示例:**
C
clevercong 已提交
856

Z
zengyawen 已提交
857
```js
C
clevercong 已提交
858 859 860 861 862 863 864 865 866
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 已提交
867 868


C
clevercong 已提交
869
### connect
C
clevercong 已提交
870

Y
Yangys 已提交
871
connect(options: TCPConnectOptions): Promise\<void\>
C
clevercong 已提交
872 873 874

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

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

C
clevercong 已提交
877
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
878

C
clevercong 已提交
879
**参数:**
C
clevercong 已提交
880

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

C
clevercong 已提交
885
**返回值:**
C
clevercong 已提交
886

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

Y
Yangys 已提交
891 892 893 894 895 896 897
**错误码:**

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

C
clevercong 已提交
898
**示例:**
C
clevercong 已提交
899

Z
zengyawen 已提交
900
```js
C
clevercong 已提交
901 902 903 904 905 906 907 908
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 已提交
909 910


C
clevercong 已提交
911
### send
C
clevercong 已提交
912

Y
Yangys 已提交
913
send(options: TCPSendOptions, callback: AsyncCallback\<void\>): void
C
clevercong 已提交
914 915 916

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

Y
Yangys 已提交
917
>**说明:** 
Y
Yangys 已提交
918
>connect方法调用成功后,才可调用此方法。
C
clevercong 已提交
919 920

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

C
clevercong 已提交
922
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
923

C
clevercong 已提交
924 925 926 927
**参数:**

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

Y
Yangys 已提交
931 932 933 934 935 936 937
**错误码:**

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

C
clevercong 已提交
938 939
**示例:**

Z
zengyawen 已提交
940
```js
C
clevercong 已提交
941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957
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 已提交
958 959


C
clevercong 已提交
960
### send
C
clevercong 已提交
961

Y
Yangys 已提交
962
send(options: TCPSendOptions): Promise\<void\>
C
clevercong 已提交
963 964 965

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

Y
Yangys 已提交
966
>**说明:** 
Y
Yangys 已提交
967
>connect方法调用成功后,才可调用此方法。
C
clevercong 已提交
968 969

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

C
clevercong 已提交
971
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
972

C
clevercong 已提交
973 974 975 976
**参数:**

| 参数名  | 类型                                    | 必填 | 说明                                                         |
| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
977
| options | [TCPSendOptions](#tcpsendoptions) | 是   | TCPSocket发送请求的参数,参考[TCPSendOptions](#tcpsendoptions)。 |
C
clevercong 已提交
978 979 980 981 982 983 984

**返回值:**

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

Y
Yangys 已提交
985 986 987 988 989 990 991
**错误码:**

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

C
clevercong 已提交
992 993
**示例:**

Z
zengyawen 已提交
994
```js
C
clevercong 已提交
995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010
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 已提交
1011 1012


C
clevercong 已提交
1013
### close
C
clevercong 已提交
1014

Y
Yangys 已提交
1015
close(callback: AsyncCallback\<void\>): void
C
clevercong 已提交
1016 1017 1018

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

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

C
clevercong 已提交
1021
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1022

C
clevercong 已提交
1023
**参数:**
C
clevercong 已提交
1024

C
clevercong 已提交
1025 1026 1027
| 参数名   | 类型                  | 必填 | 说明       |
| -------- | --------------------- | ---- | ---------- |
| callback | AsyncCallback\<void\> | 是   | 回调函数。 |
C
clevercong 已提交
1028

Y
Yangys 已提交
1029 1030 1031 1032 1033
**错误码:**

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

C
clevercong 已提交
1035
**示例:**
C
clevercong 已提交
1036

Z
zengyawen 已提交
1037
```js
C
clevercong 已提交
1038 1039 1040 1041 1042 1043 1044 1045 1046
let tcp = socket.constructTCPSocketInstance();
tcp.close(err => {
  if (err) {
	console.log('close fail');
	return;
  }
  console.log('close success');
})
```
C
clevercong 已提交
1047 1048


C
clevercong 已提交
1049
### close
C
clevercong 已提交
1050

Y
Yangys 已提交
1051
close(): Promise\<void\>
C
clevercong 已提交
1052 1053 1054

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

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

C
clevercong 已提交
1057
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1058

C
clevercong 已提交
1059
**返回值:**
C
clevercong 已提交
1060

C
clevercong 已提交
1061 1062 1063
| 类型            | 说明                                       |
| :-------------- | :----------------------------------------- |
| Promise\<void\> | 以Promise形式返回关闭TCPSocket连接的结果。 |
C
clevercong 已提交
1064

Y
Yangys 已提交
1065 1066 1067 1068 1069 1070
**错误码:**

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

C
clevercong 已提交
1071
**示例:**
C
clevercong 已提交
1072

Z
zengyawen 已提交
1073
```js
C
clevercong 已提交
1074 1075 1076 1077 1078 1079 1080 1081
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.close();
promise.then(() => {
  console.log('close success');
}).catch(err => {
  console.log('close fail');
});
```
C
clevercong 已提交
1082 1083


C
clevercong 已提交
1084
### getRemoteAddress
C
clevercong 已提交
1085

Y
Yangys 已提交
1086
getRemoteAddress(callback: AsyncCallback\<NetAddress\>): void
C
clevercong 已提交
1087 1088 1089

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

Y
Yangys 已提交
1090
>**说明:** 
Y
Yangys 已提交
1091
>connect方法调用成功后,才可调用此方法。
C
clevercong 已提交
1092 1093

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

C
clevercong 已提交
1095
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1096

C
clevercong 已提交
1097
**参数:**
C
clevercong 已提交
1098

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

Y
Yangys 已提交
1103 1104 1105 1106 1107 1108
**错误码:**

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

C
clevercong 已提交
1109
**示例:**
C
clevercong 已提交
1110

Z
zengyawen 已提交
1111
```js
C
clevercong 已提交
1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126
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 已提交
1127 1128


C
clevercong 已提交
1129
### getRemoteAddress
C
clevercong 已提交
1130

Y
Yangys 已提交
1131
getRemoteAddress(): Promise\<NetAddress\>
C
clevercong 已提交
1132 1133 1134

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

Y
Yangys 已提交
1135
>**说明:** 
Y
Yangys 已提交
1136
>connect方法调用成功后,才可调用此方法。
C
clevercong 已提交
1137 1138

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

C
clevercong 已提交
1140
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1141

C
clevercong 已提交
1142
**返回值:**
C
clevercong 已提交
1143

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

Y
Yangys 已提交
1148 1149 1150 1151 1152 1153
**错误码:**

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

C
clevercong 已提交
1154
**示例:**
C
clevercong 已提交
1155

Z
zengyawen 已提交
1156
```js
C
clevercong 已提交
1157 1158 1159 1160 1161 1162
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 已提交
1163
	console.log('getRemoteAddress success');
C
clevercong 已提交
1164 1165 1166 1167 1168 1169 1170
  }).catch(err => {
	console.log('getRemoteAddressfail');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1171 1172


C
clevercong 已提交
1173
### getState
C
clevercong 已提交
1174

Y
Yangys 已提交
1175
getState(callback: AsyncCallback\<SocketStateBase\>): void
C
clevercong 已提交
1176 1177 1178

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

Y
Yangys 已提交
1179
>**说明:** 
Y
Yangys 已提交
1180
>bind或connect方法调用成功后,才可调用此方法。
C
clevercong 已提交
1181 1182

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

C
clevercong 已提交
1184
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1185

C
clevercong 已提交
1186
**参数:**
C
clevercong 已提交
1187

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

Y
Yangys 已提交
1192 1193 1194 1195 1196
**错误码:**

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

C
clevercong 已提交
1198
**示例:**
C
clevercong 已提交
1199

Z
zengyawen 已提交
1200
```js
C
clevercong 已提交
1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215
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 已提交
1216 1217


C
clevercong 已提交
1218
### getState
C
clevercong 已提交
1219

Y
Yangys 已提交
1220
getState(): Promise\<SocketStateBase\>
C
clevercong 已提交
1221 1222 1223

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

Y
Yangys 已提交
1224
>**说明:** 
Y
Yangys 已提交
1225
>bind或connect方法调用成功后,才可调用此方法。
C
clevercong 已提交
1226 1227

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

C
clevercong 已提交
1229
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1230

C
clevercong 已提交
1231
**返回值:**
C
clevercong 已提交
1232

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

Y
Yangys 已提交
1237 1238 1239 1240 1241
**错误码:**

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

C
clevercong 已提交
1243
**示例:**
C
clevercong 已提交
1244

Z
zengyawen 已提交
1245
```js
C
clevercong 已提交
1246 1247 1248 1249 1250 1251
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 已提交
1252
	console.log('getState success');
C
clevercong 已提交
1253 1254 1255 1256 1257 1258 1259
  }).catch(err => {
	console.log('getState fail');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1260 1261


C
clevercong 已提交
1262
### setExtraOptions
C
clevercong 已提交
1263

Y
Yangys 已提交
1264
setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback\<void\>): void
C
clevercong 已提交
1265 1266 1267

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

Y
Yangys 已提交
1268
>**说明:** 
Y
Yangys 已提交
1269
>bind或connect方法调用成功后,才可调用此方法。
C
clevercong 已提交
1270 1271

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

C
clevercong 已提交
1273
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1274

C
clevercong 已提交
1275 1276 1277 1278
**参数:**

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

Y
Yangys 已提交
1282 1283 1284 1285 1286 1287 1288
**错误码:**

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

C
clevercong 已提交
1289 1290
**示例:**

Z
zengyawen 已提交
1291
```js
C
clevercong 已提交
1292 1293 1294 1295 1296 1297 1298 1299
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 已提交
1300
	socketLinger: { on:true, linger:10 },
C
clevercong 已提交
1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315
	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 已提交
1316 1317


C
clevercong 已提交
1318
### setExtraOptions
C
clevercong 已提交
1319

Y
Yangys 已提交
1320
setExtraOptions(options: TCPExtraOptions): Promise\<void\>
C
clevercong 已提交
1321 1322 1323

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

Y
Yangys 已提交
1324
>**说明:** 
Y
Yangys 已提交
1325
>bind或connect方法调用成功后,才可调用此方法。
C
clevercong 已提交
1326 1327

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

C
clevercong 已提交
1329
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1330

C
clevercong 已提交
1331 1332 1333 1334
**参数:**

| 参数名  | 类型                                      | 必填 | 说明                                                         |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
1335
| options | [TCPExtraOptions](#tcpextraoptions) | 是   | TCPSocket连接的其他属性,参考[TCPExtraOptions](#tcpextraoptions)。 |
C
clevercong 已提交
1336 1337 1338 1339 1340 1341 1342

**返回值:**

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

Y
Yangys 已提交
1343 1344 1345 1346 1347 1348
**错误码:**

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

**示例:**

Z
zengyawen 已提交
1352
```js
C
clevercong 已提交
1353 1354 1355 1356 1357 1358 1359 1360
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 已提交
1361
	socketLinger: { on:true, linger:10 },
C
clevercong 已提交
1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375
	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 已提交
1376 1377


Y
Yangys 已提交
1378
### on('message')
C
clevercong 已提交
1379

Y
Yangys 已提交
1380
on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void
C
clevercong 已提交
1381 1382 1383

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

C
clevercong 已提交
1384
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1385

C
clevercong 已提交
1386
**参数:**
C
clevercong 已提交
1387

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

C
clevercong 已提交
1393
**示例:**
C
clevercong 已提交
1394

Z
zengyawen 已提交
1395
```js
C
clevercong 已提交
1396 1397 1398 1399 1400
let tcp = socket.constructTCPSocketInstance();
tcp.on('message', value => {
	console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo)
});
```
C
clevercong 已提交
1401 1402


Y
Yangys 已提交
1403
### off('message')
C
clevercong 已提交
1404

Y
Yangys 已提交
1405
off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void
C
clevercong 已提交
1406 1407 1408

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

Y
Yangys 已提交
1409
>**说明:** 
C
clevercong 已提交
1410 1411
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
1412
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1413

C
clevercong 已提交
1414
**参数:**
C
clevercong 已提交
1415

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

C
clevercong 已提交
1421
**示例:**
C
clevercong 已提交
1422

Z
zengyawen 已提交
1423
```js
C
clevercong 已提交
1424 1425 1426 1427 1428 1429 1430 1431 1432
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 已提交
1433 1434


Y
Yangys 已提交
1435
### on('connect' | 'close')
C
clevercong 已提交
1436

Y
Yangys 已提交
1437
on(type: 'connect' | 'close', callback: Callback\<void\>): void
C
clevercong 已提交
1438 1439 1440

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

C
clevercong 已提交
1441
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1442

C
clevercong 已提交
1443
**参数:**
C
clevercong 已提交
1444

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

C
clevercong 已提交
1450
**示例:**
C
clevercong 已提交
1451

Z
zengyawen 已提交
1452
```js
C
clevercong 已提交
1453 1454 1455 1456 1457 1458 1459 1460
let tcp = socket.constructTCPSocketInstance();
tcp.on('connect', () => {
	console.log("on connect success")
});
tcp.on('close', data => {
	console.log("on close success")
});
```
C
clevercong 已提交
1461 1462


Y
Yangys 已提交
1463
### off('connect' | 'close')
C
clevercong 已提交
1464

Y
Yangys 已提交
1465
off(type: 'connect' | 'close', callback?: Callback\<void\>): void
C
clevercong 已提交
1466 1467 1468

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

Y
Yangys 已提交
1469
>**说明:** 
C
clevercong 已提交
1470 1471
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
1472
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1473

C
clevercong 已提交
1474 1475 1476 1477 1478 1479 1480 1481 1482
**参数:**

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

**示例:**

Z
zengyawen 已提交
1483
```js
C
clevercong 已提交
1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499
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 已提交
1500 1501


Y
Yangys 已提交
1502
### on('error')
C
clevercong 已提交
1503

Y
Yangys 已提交
1504
on(type: 'error', callback: ErrorCallback): void
C
clevercong 已提交
1505 1506 1507

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

C
clevercong 已提交
1508
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1509

C
clevercong 已提交
1510
**参数:**
C
clevercong 已提交
1511

C
clevercong 已提交
1512 1513 1514 1515
| 参数名   | 类型          | 必填 | 说明                                 |
| -------- | ------------- | ---- | ------------------------------------ |
| type     | string        | 是   | 订阅的事件类型。'error':error事件。 |
| callback | ErrorCallback | 是   | 回调函数。                           |
C
clevercong 已提交
1516

C
clevercong 已提交
1517
**示例:**
C
clevercong 已提交
1518

Z
zengyawen 已提交
1519
```js
C
clevercong 已提交
1520 1521 1522 1523 1524
let tcp = socket.constructTCPSocketInstance();
tcp.on('error', err => {
	console.log("on error, err:" + JSON.stringify(err))
});
```
C
clevercong 已提交
1525 1526


Y
Yangys 已提交
1527
### off('error')
C
clevercong 已提交
1528

Y
Yangys 已提交
1529
off(type: 'error', callback?: ErrorCallback): void
C
clevercong 已提交
1530 1531 1532

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

Y
Yangys 已提交
1533
>**说明:** 
C
clevercong 已提交
1534 1535
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。

C
clevercong 已提交
1536
**系统能力**:SystemCapability.Communication.NetStack
C
clevercong 已提交
1537

C
clevercong 已提交
1538 1539 1540 1541 1542 1543 1544 1545 1546
**参数:**

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

**示例:**

Z
zengyawen 已提交
1547
```js
C
clevercong 已提交
1548 1549 1550 1551 1552 1553 1554 1555 1556
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 已提交
1557 1558


C
clevercong 已提交
1559
## TCPConnectOptions
C
clevercong 已提交
1560 1561 1562

TCPSocket连接的参数。

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

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

C
clevercong 已提交
1570
## TCPSendOptions
C
clevercong 已提交
1571 1572 1573

TCPSocket发送请求的参数。

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

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

C
clevercong 已提交
1581
## TCPExtraOptions
C
clevercong 已提交
1582 1583 1584

TCPSocket连接的其他属性。

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

L
liyufan 已提交
1587
| 名称            | 类型    | 必填 | 说明                                                         |
C
clevercong 已提交
1588 1589 1590 1591 1592 1593 1594 1595 1596
| ----------------- | ------- | ---- | ------------------------------------------------------------ |
| 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 已提交
1597

Y
Yangys 已提交
1598
## TCP 错误码说明
Y
Yangys 已提交
1599

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

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

L
liyufan 已提交
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
## 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>

Y
Yangys 已提交
1630
bind(address: NetAddress, callback: AsyncCallback\<void\>): void
L
liyufan 已提交
1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647

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

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

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

**参数:**

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

**错误码:**

| 错误码ID | 错误信息                 |
L
liyufan 已提交
1648
| ------- | ----------------------- |
L
liyufan 已提交
1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667
| 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>

Y
Yangys 已提交
1668
bind(address: NetAddress): Promise\<void\>
L
liyufan 已提交
1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679

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

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

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

**参数:**

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

**返回值:**

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

**错误码:**

| 错误码ID | 错误信息                 |
L
liyufan 已提交
1691
| ------- | ----------------------- |
L
liyufan 已提交
1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709
| 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>

Y
Yangys 已提交
1710
getState(callback: AsyncCallback\<SocketStateBase\>): void
L
liyufan 已提交
1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724

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

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

**参数:**

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

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
1725
| ------- | ------------------------------ |
L
liyufan 已提交
1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749
| 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>

Y
Yangys 已提交
1750
getState(): Promise\<SocketStateBase\>
L
liyufan 已提交
1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764

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

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

**返回值:**

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

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
1765
| ------- | ------------------------------ |
L
liyufan 已提交
1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788
| 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>

Y
Yangys 已提交
1789
setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback\<void\>): void
L
liyufan 已提交
1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804

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

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

**参数:**

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

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
1805
| ------- | -----------------------------  |
L
liyufan 已提交
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
| 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>

Y
Yangys 已提交
1841
setExtraOptions(options: TCPExtraOptions): Promise\<void\>
L
liyufan 已提交
1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861

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

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

**参数:**

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

**返回值:**

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

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
1862
| ------- | ------------------------------ |
L
liyufan 已提交
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
| 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>

Y
Yangys 已提交
1896
connect(options: TLSConnectOptions, callback: AsyncCallback\<void\>): void
L
liyufan 已提交
1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911

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

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

**参数:**

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

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
1912
| ------- | -------------------------------------------- |
L
liyufan 已提交
1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931
| 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 已提交
1932
let tlsTwoWay = socket.constructTLSSocketInstance(); // Two way authentication
Z
zhanghaifeng 已提交
1933
tlsTwoWay.bind({address: '192.168.xxx.xxx', port: 8080, family: 1}, err => {
L
liyufan 已提交
1934 1935 1936 1937 1938 1939 1940 1941 1942 1943
  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 已提交
1944
    port: 8080,
L
liyufan 已提交
1945 1946 1947 1948 1949 1950
    family: 1,
  },
  secureOptions: {
    key: "xxxx",
    cert: "xxxx",
    ca: ["xxxx"],
Z
zhanghaifeng 已提交
1951
    password: "xxxx",
Y
YOUR_NAME 已提交
1952
    protocols: [socket.Protocol.TLSv12],
L
liyufan 已提交
1953
    useRemoteCipherPrefer: true,
Y
YOUR_NAME 已提交
1954 1955
    signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
    cipherSuite: "AES256-SHA256",
L
liyufan 已提交
1956 1957
  },
};
Y
YOUR_NAME 已提交
1958
tlsTwoWay.connect(options, (err, data) => {
Z
zhanghaifeng 已提交
1959 1960
  console.error("connect callback error"+err);
  console.log(JSON.stringify(data));
L
liyufan 已提交
1961 1962 1963
});

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

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

Y
Yangys 已提交
1990
connect(options: TLSConnectOptions): Promise\<void\>
L
liyufan 已提交
1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005

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

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

**参数:**

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

**返回值:**

| 类型                                        | 说明                          |
| ------------------------------------------- | ----------------------------- |
Y
Yangys 已提交
2006
| Promise\<void\>                              | 以Promise形式返回,成功无返回,失败返回错误码,错误信息。|
L
liyufan 已提交
2007 2008 2009 2010

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2011
| ------- | -------------------------------------------- |
L
liyufan 已提交
2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030
| 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 已提交
2031
let tlsTwoWay = socket.constructTLSSocketInstance(); // Two way authentication
Z
zhanghaifeng 已提交
2032
tlsTwoWay.bind({address: '192.168.xxx.xxx', port: 8080, family: 1}, err => {
L
liyufan 已提交
2033 2034 2035 2036 2037 2038 2039 2040 2041 2042
  if (err) {
    console.log('bind fail');
    return;
  }
  console.log('bind success');
});
let options = {
  ALPNProtocols: ["spdy/1", "http/1.1"],
  address: {
    address: "xxxx",
Z
zhanghaifeng 已提交
2043
    port: 8080,
L
liyufan 已提交
2044 2045 2046 2047 2048 2049
    family: 1,
  },
  secureOptions: {
    key: "xxxx",
    cert: "xxxx",
    ca: ["xxxx"],
Z
zhanghaifeng 已提交
2050
    password: "xxxx",
Y
YOUR_NAME 已提交
2051
    protocols: [socket.Protocol.TLSv12],
L
liyufan 已提交
2052
    useRemoteCipherPrefer: true,
Y
YOUR_NAME 已提交
2053 2054
    signatureAlgorithms: "rsa_pss_rsae_sha256:ECDSA+SHA256",
    cipherSuite: "AES256-SHA256",
L
liyufan 已提交
2055 2056
  },
};
Y
YOUR_NAME 已提交
2057
tlsTwoWay.connect(options).then(data => {
Z
zhanghaifeng 已提交
2058
  console.log(JSON.stringify(data));
L
liyufan 已提交
2059 2060 2061 2062 2063
}).catch(err => {
  console.error(err);
});

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

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

Y
Yangys 已提交
2091
getRemoteAddress(callback: AsyncCallback\<NetAddress\>): void
L
liyufan 已提交
2092 2093 2094 2095 2096 2097 2098 2099 2100

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

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

**参数:**

| 参数名   | 类型                                              | 必填 | 说明       |
| -------- | ------------------------------------------------- | ---- | ---------- |
Y
Yangys 已提交
2101
| callback | AsyncCallback\<[NetAddress](#netaddress)\> | 是   | 回调函数。成功返回对端的socket地址,失败返回错误码,错误信息。 |
L
liyufan 已提交
2102 2103 2104 2105

**错误码:**

| 错误码ID | 错误信息                        |
Y
YOUR_NAME 已提交
2106
| ------- | -----------------------------  |
L
liyufan 已提交
2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123
| 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>

Y
Yangys 已提交
2124
getRemoteAddress(): Promise\<NetAddress\>
L
liyufan 已提交
2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138

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

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

**返回值:**

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

**错误码:**

| 错误码ID | 错误信息                        |
Y
YOUR_NAME 已提交
2139
| ------- | ------------------------------ |
L
liyufan 已提交
2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155
| 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>

Y
Yangys 已提交
2156
getCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata9)\>): void
L
liyufan 已提交
2157 2158 2159 2160 2161 2162 2163 2164 2165

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

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

**参数:**

| 参数名   | 类型                                   | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
Y
Yangys 已提交
2166
| callback | AsyncCallback\<[X509CertRawData](#x509certrawdata9)\>    | 是   | 回调函数,成功返回本地的证书,失败返回错误码,错误信息。|
L
liyufan 已提交
2167 2168 2169 2170

**错误码:**

| 错误码ID | 错误信息                        |
Y
YOUR_NAME 已提交
2171
| ------- | ------------------------------ |
L
liyufan 已提交
2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189
| 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>

Y
Yangys 已提交
2190
getCertificate():Promise\<[X509CertRawData](#x509certrawdata9)\>
L
liyufan 已提交
2191 2192 2193 2194 2195 2196 2197 2198 2199

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

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

**返回值:**

| 类型            | 说明                  |
| -------------- | -------------------- |
Y
Yangys 已提交
2200
| Promise\<[X509CertRawData](#x509certrawdata9)\> | 以Promise形式返回本地的数字证书的结果。失败返回错误码,错误信息。 |
L
liyufan 已提交
2201 2202 2203 2204

**错误码:**

| 错误码ID | 错误信息                        |
Y
YOUR_NAME 已提交
2205
| ------- | ------------------------------ |
L
liyufan 已提交
2206 2207 2208 2209 2210 2211 2212 2213
| 2303501 | SSL is null.                   |
| 2303504 | Error looking up x509.         |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getCertificate().then(data => {
Y
YOUR_NAME 已提交
2214
  console.log(data);
L
liyufan 已提交
2215 2216 2217 2218 2219 2220 2221
}).catch(err => {
  console.error(err);
});
```

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

Y
Yangys 已提交
2222
getRemoteCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata9)\>): void
L
liyufan 已提交
2223 2224 2225 2226 2227 2228 2229 2230 2231

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

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

**参数:**

| 参数名    | 类型                                    | 必填  | 说明           |
| -------- | ----------------------------------------| ---- | ---------------|
Y
Yangys 已提交
2232
| callback | AsyncCallback\<[X509CertRawData](#x509certrawdata9)\>  | 是   | 回调函数,返回服务端的证书。失败返回错误码,错误信息。 |
L
liyufan 已提交
2233 2234 2235 2236

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2237
| ------- | ------------------------------ |
L
liyufan 已提交
2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254
| 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>

Y
Yangys 已提交
2255
getRemoteCertificate():Promise\<[X509CertRawData](#x509certrawdata9)\>
L
liyufan 已提交
2256 2257 2258 2259 2260 2261 2262 2263 2264

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

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

**返回值:**

| 类型            | 说明                  |
| -------------- | -------------------- |
Y
Yangys 已提交
2265
| Promise\<[X509CertRawData](#x509certrawdata9)\> | 以Promise形式返回服务端的数字证书的结果。失败返回错误码,错误信息。 |
L
liyufan 已提交
2266 2267 2268 2269

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2270
| ------- | ------------------------------ |
L
liyufan 已提交
2271 2272 2273 2274 2275 2276 2277
| 2303501 | SSL is null.                   |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getRemoteCertificate().then(data => {
Y
YOUR_NAME 已提交
2278
  console.log(data);
L
liyufan 已提交
2279 2280 2281 2282 2283 2284 2285
}).catch(err => {
  console.error(err);
});
```

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

Y
Yangys 已提交
2286
getProtocol(callback: AsyncCallback\<string\>): void
L
liyufan 已提交
2287 2288 2289 2290 2291 2292 2293 2294 2295

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

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

**参数:**

| 参数名   | 类型                                       | 必填 | 说明           |
| -------- | ----------------------------------------| ---- | ---------------|
Y
Yangys 已提交
2296
| callback | AsyncCallback\<string\>                  | 是   | 回调函数,返回通信的协议。失败返回错误码,错误信息。|
L
liyufan 已提交
2297 2298 2299 2300

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2301
| ------- | -----------------------------  |
L
liyufan 已提交
2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319
| 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>

Y
Yangys 已提交
2320
getProtocol():Promise\<string\>
L
liyufan 已提交
2321 2322 2323 2324 2325 2326 2327 2328 2329

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

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

**返回值:**

| 类型            | 说明                  |
| -------------- | -------------------- |
Y
Yangys 已提交
2330
| Promise\<string\> | 以Promise形式返回通信的协议。失败返回错误码,错误信息。 |
L
liyufan 已提交
2331 2332 2333 2334

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2335
| ------- | ------------------------------ |
L
liyufan 已提交
2336 2337 2338 2339 2340 2341 2342 2343
| 2303501 | SSL is null.                   |
| 2303505 | Error occurred in the tls system call. |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getProtocol().then(data => {
Y
YOUR_NAME 已提交
2344
  console.log(data);
L
liyufan 已提交
2345 2346 2347 2348 2349 2350 2351
}).catch(err => {
  console.error(err);
});
```

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

Y
Yangys 已提交
2352
getCipherSuite(callback: AsyncCallback\<Array\<string\>\>): void
L
liyufan 已提交
2353 2354 2355 2356 2357 2358 2359 2360 2361

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

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

**参数:**

| 参数名   | 类型                                     | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
Y
Yangys 已提交
2362
| callback | AsyncCallback\<Array\<string\>\>          | 是   | 回调函数,返回通信双方支持的加密套件。 失败返回错误码,错误信息。 |
L
liyufan 已提交
2363 2364 2365 2366

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2367
| ------- | ------------------------------ |
L
liyufan 已提交
2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386
| 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>

Y
Yangys 已提交
2387
getCipherSuite(): Promise\<Array\<string\>\>
L
liyufan 已提交
2388 2389 2390 2391 2392 2393 2394 2395 2396

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

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

**返回值:**

| 类型                    | 说明                  |
| ---------------------- | --------------------- |
Y
Yangys 已提交
2397
| Promise\<Array\<string\>\> | 以Promise形式返回通信双方支持的加密套件。失败返回错误码,错误信息。 |
L
liyufan 已提交
2398 2399 2400 2401

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2402
| ------- | ------------------------------ |
L
liyufan 已提交
2403 2404 2405 2406 2407 2408 2409 2410 2411
| 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 已提交
2412
  console.log('getCipherSuite success:' + JSON.stringify(data));
L
liyufan 已提交
2413 2414 2415 2416 2417 2418 2419
}).catch(err => {
  console.error(err);
});
```

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

Y
Yangys 已提交
2420
getSignatureAlgorithms(callback: AsyncCallback\<Array\<string\>\>): void
L
liyufan 已提交
2421 2422 2423 2424 2425 2426 2427 2428 2429

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

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

**参数:**

| 参数名   | 类型                                   | 必填 | 说明            |
| -------- | -------------------------------------| ---- | ---------------|
Y
Yangys 已提交
2430
| callback | AsyncCallback\<Array\<string\>\>         | 是   | 回调函数,返回双方支持的签名算法。  |
L
liyufan 已提交
2431 2432 2433 2434

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2435
| ------- | ------------------------------ |
L
liyufan 已提交
2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452
| 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>

Y
Yangys 已提交
2453
getSignatureAlgorithms(): Promise\<Array\<string\>\>
L
liyufan 已提交
2454 2455 2456 2457 2458 2459 2460 2461 2462

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

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

**返回值:**

| 类型                    | 说明                  |
| ---------------------- | -------------------- |
Y
Yangys 已提交
2463
| Promise\<Array\<string\>\> | 以Promise形式返回获取到的双方支持的签名算法。 |
L
liyufan 已提交
2464 2465 2466 2467

**错误码:**

| 错误码ID | 错误信息                        |
L
liyufan 已提交
2468
| ------- | ------------------------------ |
L
liyufan 已提交
2469 2470 2471 2472 2473 2474 2475
| 2303501 | SSL is null.                   |
| 2300002 | System internal error.         |

**示例:**

```js
tls.getSignatureAlgorithms().then(data => {
Z
zhanghaifeng 已提交
2476
  console.log("getSignatureAlgorithms success" + data);
L
liyufan 已提交
2477 2478 2479 2480 2481 2482 2483
}).catch(err => {
  console.error(err);
});
```

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

Y
Yangys 已提交
2484
send(data: string, callback: AsyncCallback\<void\>): void
L
liyufan 已提交
2485 2486 2487 2488 2489 2490 2491 2492 2493 2494

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

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

**参数:**

| 参数名    | 类型                          | 必填 | 说明            |
| -------- | -----------------------------| ---- | ---------------|
|   data   | string                       | 是   | 发送的数据内容。   |
Y
Yangys 已提交
2495
| callback | AsyncCallback\<void\>         | 是   | 回调函数,返回TLSSocket发送数据的结果。失败返回错误码,错误信息。 |
L
liyufan 已提交
2496 2497 2498 2499

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2500
| ------- | -------------------------------------------- |
L
liyufan 已提交
2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521
| 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>

Y
Yangys 已提交
2522
send(data: string): Promise\<void\>
L
liyufan 已提交
2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536

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

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

**参数:**

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

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2537
| ------- | -------------------------------------------- |
L
liyufan 已提交
2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548
| 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.                       |

**返回值:**

| 类型           | 说明                  |
| -------------- | -------------------- |
Y
Yangys 已提交
2549
| Promise\<void\> | 以Promise形式返回,返回TLSSocket发送数据的结果。失败返回错误码,错误信息。 |
L
liyufan 已提交
2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562

**示例:**

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

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

Y
Yangys 已提交
2563
close(callback: AsyncCallback\<void\>): void
L
liyufan 已提交
2564 2565 2566 2567 2568 2569 2570 2571 2572

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

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

**参数:**

| 参数名    | 类型                          | 必填 | 说明            |
| -------- | -----------------------------| ---- | ---------------|
Y
Yangys 已提交
2573
| callback | AsyncCallback\<void\>         | 是   | 回调函数,成功返回TLSSocket关闭连接的结果。 失败返回错误码,错误信息。 |
L
liyufan 已提交
2574 2575 2576 2577

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2578
| ------- | -------------------------------------------- |
L
liyufan 已提交
2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597
| 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>

Y
Yangys 已提交
2598
close(): Promise\<void\>
L
liyufan 已提交
2599 2600 2601 2602 2603 2604 2605 2606 2607

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

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

**返回值:**

| 类型           | 说明                  |
| -------------- | -------------------- |
Y
Yangys 已提交
2608
| Promise\<void\> | 以Promise形式返回,返回TLSSocket关闭连接的结果。失败返回错误码,错误信息。 |
L
liyufan 已提交
2609 2610 2611 2612

**错误码:**

| 错误码ID | 错误信息                                      |
L
liyufan 已提交
2613
| ------- | -------------------------------------------- |
L
liyufan 已提交
2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634
| 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 已提交
2635 2636 2637 2638
| 名称          | 类型                                     | 必填 | 说明            |
| -------------- | ------------------------------------- | ---  |-------------- |
| address        | [NetAddress](#netaddress)             | 是  |  网关地址。       |
| secureOptions  | [TLSSecureOptions](#tlssecureoptions9) | 是 | TLS安全相关操作。|
Y
Yangys 已提交
2639
| ALPNProtocols  | Array\<string\>                         | 否 | ALPN协议。      |
L
liyufan 已提交
2640 2641 2642 2643 2644 2645 2646

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

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

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

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

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

TLS通信的协议版本。

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

L
liyufan 已提交
2664 2665 2666 2667
| 名称      |    值    | 说明                |
| --------- | --------- |------------------ |
| TLSv12    | "TLSv1.2" | 使用TLSv1.2协议通信。 |
| TLSv13    | "TLSv1.3" | 使用TLSv1.3协议通信。 |
L
liyufan 已提交
2668 2669 2670 2671 2672 2673 2674

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

存储证书的数据。

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

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