js-apis-socket.md 43.7 KB
Newer Older
C
clevercong 已提交
1
# Socket连接
C
clevercong 已提交
2 3 4 5 6 7 8

>![](public_sys-resources/icon-note.gif) **说明:** 
>
>本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
>
>本模块所有接口需要设备具有系统能力:SystemCapability.Communication.NetStack

C
clevercong 已提交
9
## 导入模块
C
clevercong 已提交
10 11 12 13 14

```
import socket from '@ohos.net.socket';
```

C
clevercong 已提交
15
## 权限列表
C
clevercong 已提交
16 17 18

ohos.permission.INTERNET

C
clevercong 已提交
19
## socket.constructUDPSocketInstance
C
clevercong 已提交
20 21 22 23 24

constructUDPSocketInstance\(\): UDPSocket

创建一个UDPSocket对象。

C
clevercong 已提交
25
**返回值:**
C
clevercong 已提交
26

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


C
clevercong 已提交
32
**示例:**
C
clevercong 已提交
33

C
clevercong 已提交
34 35 36
```
let udp = socket.constructUDPSocketInstance();
```
C
clevercong 已提交
37 38


C
clevercong 已提交
39
## UDPSocket
C
clevercong 已提交
40

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

C
clevercong 已提交
43
### bind
C
clevercong 已提交
44 45 46 47 48

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

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

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

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

C
clevercong 已提交
58
**示例:**
C
clevercong 已提交
59

C
clevercong 已提交
60 61 62 63 64 65 66 67 68 69
```
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 已提交
70 71


C
clevercong 已提交
72
### bind
C
clevercong 已提交
73 74 75 76 77

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

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

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

C
clevercong 已提交
80
**参数:**
C
clevercong 已提交
81

C
clevercong 已提交
82 83
| 参数名  | 类型                               | 必填 | 说明                                                   |
| ------- | ---------------------------------- | ---- | ------------------------------------------------------ |
C
clevercong 已提交
84
| address | [NetAddress](#netaddress) | 是   | 目标地址信息,参考[NetAddress](#netaddress)。 |
C
clevercong 已提交
85 86


C
clevercong 已提交
87
**返回值:**
C
clevercong 已提交
88

C
clevercong 已提交
89 90 91
| 类型            | 说明                                       |
| :-------------- | :----------------------------------------- |
| Promise\<void\> | 以Promise形式异步返回UDPSocket绑定的结果。 |
C
clevercong 已提交
92

C
clevercong 已提交
93
**示例:**
C
clevercong 已提交
94

C
clevercong 已提交
95 96 97 98 99 100 101 102 103
```
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 已提交
104 105


C
clevercong 已提交
106
### send
C
clevercong 已提交
107 108 109 110 111

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

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

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

C
clevercong 已提交
114 115 116 117
**参数:**

| 参数名   | 类型                                     | 必填 | 说明                                                         |
| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
118
| options  | [UDPSendOptions](#udpsendoptions) | 是   | UDPSocket发送参数,参考[UDPSendOptions](#udpsendoptions)。 |
C
clevercong 已提交
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
| callback | AsyncCallback\<void\>                    | 是   | 回调函数。                                                   |

**示例:**

```
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 已提交
140 141


C
clevercong 已提交
142
### send
C
clevercong 已提交
143 144 145 146 147

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

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

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

C
clevercong 已提交
150
**参数:**
C
clevercong 已提交
151

C
clevercong 已提交
152 153
| 参数名  | 类型                                     | 必填 | 说明                                                         |
| ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
154
| options | [UDPSendOptions](#udpsendoptions) | 是   | UDPSocket发送参数,参考[UDPSendOptions](#udpsendoptions)。 |
C
clevercong 已提交
155

C
clevercong 已提交
156
**返回值:**
C
clevercong 已提交
157

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

C
clevercong 已提交
162
**示例:**
C
clevercong 已提交
163

C
clevercong 已提交
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
```
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 已提交
180 181


C
clevercong 已提交
182
### close
C
clevercong 已提交
183 184 185 186 187

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

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

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

C
clevercong 已提交
190
**参数:**
C
clevercong 已提交
191

C
clevercong 已提交
192 193 194
| 参数名   | 类型                  | 必填 | 说明       |
| -------- | --------------------- | ---- | ---------- |
| callback | AsyncCallback\<void\> | 是   | 回调函数。 |
C
clevercong 已提交
195

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

C
clevercong 已提交
198 199 200 201 202 203 204 205 206 207
```
let udp = socket.constructUDPSocketInstance();
udp.close(err => {
  if (err) {
	console.log('close fail');
	return;
  }
  console.log('close success');
})
```
C
clevercong 已提交
208 209


C
clevercong 已提交
210
### close
C
clevercong 已提交
211 212 213 214 215

close\(\): Promise<void\>

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

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

C
clevercong 已提交
218
**返回值:**
C
clevercong 已提交
219

C
clevercong 已提交
220 221 222
| 类型            | 说明                                       |
| :-------------- | :----------------------------------------- |
| Promise\<void\> | 以Promise形式返回关闭UDPSocket连接的结果。 |
C
clevercong 已提交
223

C
clevercong 已提交
224
**示例:**
C
clevercong 已提交
225

C
clevercong 已提交
226 227 228 229 230 231 232 233 234
```
let udp = socket.constructUDPSocketInstance();
let promise = udp.close();
promise.then(() => {
  console.log('close success');
}).catch(err => {
  console.log('close fail');
});
```
C
clevercong 已提交
235 236


C
clevercong 已提交
237
### getState
C
clevercong 已提交
238 239 240 241 242 243

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

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

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

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

C
clevercong 已提交
248 249 250 251
**参数:**

| 参数名   | 类型                                                   | 必填 | 说明       |
| -------- | ------------------------------------------------------ | ---- | ---------- |
C
clevercong 已提交
252
| callback | AsyncCallback<[SocketStateBase](#socketstatebase)> | 是   | 回调函数。 |
C
clevercong 已提交
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272

**示例:**

```
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 已提交
273 274


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

getState\(\): Promise<SocketStateBase\>

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

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

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

C
clevercong 已提交
286
**返回值:**
C
clevercong 已提交
287

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

C
clevercong 已提交
292
**示例:**
C
clevercong 已提交
293

C
clevercong 已提交
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309
```
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');
  let promise = udp.getState({});
  promise.then(data => {
	console.log('getState success:' + JSON.stringify(data));
  }).catch(err => {
	console.log('getState fail');
  });
})
```
C
clevercong 已提交
310 311


C
clevercong 已提交
312
### setExtraOptions
C
clevercong 已提交
313 314 315 316 317 318

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

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

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

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

C
clevercong 已提交
323 324 325 326
**参数:**

| 参数名   | 类型                                     | 必填 | 说明                                                         |
| -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
327
| options  | [UDPExtraOptions](#udpextraoptions) | 是   | UDPSocket连接的其他属性,参考[UDPExtraOptions](#udpextraoptions)。 |
C
clevercong 已提交
328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355
| callback | AsyncCallback\<void\>                    | 是   | 回调函数。                                                   |


**示例:**

```
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 已提交
356 357


C
clevercong 已提交
358
### setExtraOptions
C
clevercong 已提交
359 360 361 362 363 364

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

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

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

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

C
clevercong 已提交
369 370 371 372
**参数:**

| 参数名  | 类型                                     | 必填 | 说明                                                         |
| ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
373
| options | [UDPExtraOptions](#udpextraoptions) | 是   | UDPSocket连接的其他属性,参考[UDPExtraOptions](#udpextraoptions)。 |
C
clevercong 已提交
374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403

**返回值:**

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

**示例:**

```
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 已提交
404 405


C
clevercong 已提交
406
### on\('message'\)
C
clevercong 已提交
407 408 409 410 411

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

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

C
clevercong 已提交
412
**参数:**
C
clevercong 已提交
413

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

C
clevercong 已提交
419
**示例:**
C
clevercong 已提交
420

C
clevercong 已提交
421 422 423 424 425 426
```
let udp = socket.constructUDPSocketInstance();
udp.on('message', value => {
	console.log("on message, message:" + value.message) + ", remoteInfo:" + value.remoteInfo);
});
```
C
clevercong 已提交
427 428


C
clevercong 已提交
429
### off\('message'\)
C
clevercong 已提交
430 431 432 433 434 435 436 437

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

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

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

C
clevercong 已提交
438
**参数:**
C
clevercong 已提交
439

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

C
clevercong 已提交
445
**示例:**
C
clevercong 已提交
446

C
clevercong 已提交
447 448 449 450 451 452 453 454 455 456
```
let udp = socket.constructUDPSocketInstance();
let callback = value =>{
	console.log("on message, message:" + value.message) + ", remoteInfo:" + value.remoteInfo);
}
udp.on('message', callback);
// 可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
udp.off('message', callback);
udp.off('message');
```
C
clevercong 已提交
457 458


C
clevercong 已提交
459
### on\('listening' | 'close'\)
C
clevercong 已提交
460 461 462 463 464

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

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

C
clevercong 已提交
465
**参数:**
C
clevercong 已提交
466

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

C
clevercong 已提交
472
**示例:**
C
clevercong 已提交
473

C
clevercong 已提交
474 475 476 477 478 479 480 481 482
```
let udp = socket.constructUDPSocketInstance();
udp.on('listening', () => {
	console.log("on listening success"));
});
udp.on('close', () => {
	console.log("on close success" );
});
```
C
clevercong 已提交
483 484


C
clevercong 已提交
485
### off\('listening' | 'close'\)
C
clevercong 已提交
486 487 488 489 490 491 492 493

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

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

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

C
clevercong 已提交
494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519
**参数:**

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

**示例:**

```
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 已提交
520 521


C
clevercong 已提交
522
### on\('error'\)
C
clevercong 已提交
523 524 525 526 527

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

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

C
clevercong 已提交
528
**参数:**
C
clevercong 已提交
529

C
clevercong 已提交
530 531 532 533
| 参数名   | 类型          | 必填 | 说明                                 |
| -------- | ------------- | ---- | ------------------------------------ |
| type     | string        | 是   | 订阅的事件类型。'error':error事件。 |
| callback | ErrorCallback | 是   | 回调函数。                           |
C
clevercong 已提交
534 535


C
clevercong 已提交
536
**示例:**
C
clevercong 已提交
537

C
clevercong 已提交
538 539 540 541 542 543
```
let udp = socket.constructUDPSocketInstance()
udp.on('error', err => {
	console.log("on error, err:" + JSON.stringify(err))
});
```
C
clevercong 已提交
544 545


C
clevercong 已提交
546
### off\('error'\)
C
clevercong 已提交
547 548 549 550 551 552 553 554

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

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

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

C
clevercong 已提交
555
**参数:**
C
clevercong 已提交
556

C
clevercong 已提交
557 558 559 560
| 参数名   | 类型          | 必填 | 说明                                 |
| -------- | ------------- | ---- | ------------------------------------ |
| type     | string        | 是   | 订阅的事件类型。'error':error事件。 |
| callback | ErrorCallback | 否   | 回调函数。                           |
C
clevercong 已提交
561

C
clevercong 已提交
562
**示例:**
C
clevercong 已提交
563

C
clevercong 已提交
564 565 566 567 568 569 570 571 572 573
```
let udp = socket.constructUDPSocketInstance()
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 已提交
574 575


C
clevercong 已提交
576
## NetAddress
C
clevercong 已提交
577 578 579 580 581 582 583 584 585

目标地址信息。

| 参数名  | 类型   | 必填 | 说明                                                         |
| ------- | ------ | ---- | ------------------------------------------------------------ |
| address | string | 是   | 本地绑定的ip地址。                                           |
| port    | number | 否   | 端口号 ,范围0~65535。如果不指定系统随机分配端口。           |
| family  | number | 否   | 网络协议类型,可选类型:<br />- 1:IPv4<br />- 2:IPv6<br />默认为1。 |

C
clevercong 已提交
586
## UDPSendOptions
C
clevercong 已提交
587 588 589 590 591 592

UDPSocket发送参数。

| 参数名  | 类型                               | 必填 | 说明           |
| ------- | ---------------------------------- | ---- | -------------- |
| data    | string                             | 是   | 发送的数据。   |
C
clevercong 已提交
593
| address | [NetAddress](#netaddress) | 是   | 目标地址信息。 |
C
clevercong 已提交
594

C
clevercong 已提交
595
## UDPExtraOptions
C
clevercong 已提交
596 597 598 599 600 601 602 603 604 605 606

UDPSocket连接的其他属性。

| 参数名            | 类型    | 必填 | 说明                             |
| ----------------- | ------- | ---- | -------------------------------- |
| broadcast         | boolean | 否   | 是否可以发送广播。默认为false。  |
| receiveBufferSize | number  | 否   | 接收缓冲区大小(单位:Byte)。   |
| sendBufferSize    | number  | 否   | 发送缓冲区大小(单位:Byte)。   |
| reuseAddress      | boolean | 否   | 是否重用地址。默认为false。      |
| socketTimeout     | number  | 否   | 套接字超时时间,单位毫秒(ms)。 |

C
clevercong 已提交
607
## SocketStateBase
C
clevercong 已提交
608 609 610 611 612 613 614 615 616

Socket的状态信息。

| 参数名      | 类型    | 必填 | 说明       |
| ----------- | ------- | ---- | ---------- |
| isBound     | boolean | 是   | 是否绑定。 |
| isClose     | boolean | 是   | 是否关闭。 |
| isConnected | boolean | 是   | 是否连接。 |

C
clevercong 已提交
617
## SocketRemoteInfo
C
clevercong 已提交
618 619 620 621 622 623 624 625 626 627

Socket的连接信息。

| 参数名  | 类型   | 必填 | 说明                                                         |
| ------- | ------ | ---- | ------------------------------------------------------------ |
| address | string | 是   | 本地绑定的ip地址。                                           |
| family  | string | 是   | 网络协议类型,可选类型:<br />- IPv4<br />- IPv6<br />默认为IPv4。 |
| port    | number | 是   | 端口号,范围0~65535。                                        |
| size    | number | 是   | 服务器响应信息的字节长度。                                   |

C
clevercong 已提交
628
## socket.constructTCPSocketInstance
C
clevercong 已提交
629 630 631 632 633

constructTCPSocketInstance\(\): TCPSocket

创建一个TCPSocket对象。

C
clevercong 已提交
634
**返回值:**
C
clevercong 已提交
635 636 637

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

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

C
clevercong 已提交
642 643 644
```
let tcp = socket.constructTCPSocketInstance();
```
C
clevercong 已提交
645 646


C
clevercong 已提交
647
## TCPSocket
C
clevercong 已提交
648

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

C
clevercong 已提交
651
### bind
C
clevercong 已提交
652 653 654 655 656

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

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

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

C
clevercong 已提交
659
**参数:**
C
clevercong 已提交
660

C
clevercong 已提交
661 662
| 参数名   | 类型                               | 必填 | 说明                                                   |
| -------- | ---------------------------------- | ---- | ------------------------------------------------------ |
C
clevercong 已提交
663
| address  | [NetAddress](#netaddress) | 是   | 目标地址信息,参考[NetAddress](#netaddress)。 |
C
clevercong 已提交
664
| callback | AsyncCallback\<void\>              | 是   | 回调函数。                                             |
C
clevercong 已提交
665 666


C
clevercong 已提交
667
**示例:**
C
clevercong 已提交
668

C
clevercong 已提交
669 670 671 672 673 674 675 676 677 678
```
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 已提交
679 680


C
clevercong 已提交
681
### bind
C
clevercong 已提交
682 683 684 685 686

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

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

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

C
clevercong 已提交
689
**参数:**
C
clevercong 已提交
690

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

C
clevercong 已提交
695
**返回值:**
C
clevercong 已提交
696

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

C
clevercong 已提交
701
**示例:**
C
clevercong 已提交
702

C
clevercong 已提交
703 704 705 706 707 708 709 710 711
```
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 已提交
712 713


C
clevercong 已提交
714
### connect
C
clevercong 已提交
715 716 717 718 719

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

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

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

C
clevercong 已提交
722
**参数:**
C
clevercong 已提交
723

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

C
clevercong 已提交
729
**示例:**
C
clevercong 已提交
730

C
clevercong 已提交
731 732 733 734 735 736 737 738 739 740
```
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 已提交
741 742


C
clevercong 已提交
743
### connect
C
clevercong 已提交
744 745 746 747 748

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

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

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

C
clevercong 已提交
751
**参数:**
C
clevercong 已提交
752

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

C
clevercong 已提交
757
**返回值:**
C
clevercong 已提交
758

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

C
clevercong 已提交
763
**示例:**
C
clevercong 已提交
764

C
clevercong 已提交
765 766 767 768 769 770 771 772 773
```
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 已提交
774 775


C
clevercong 已提交
776
### send
C
clevercong 已提交
777 778 779 780 781 782

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

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

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

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

C
clevercong 已提交
787 788 789 790
**参数:**

| 参数名   | 类型                                    | 必填 | 说明                                                         |
| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
791
| options  | [TCPSendOptions](#tcpsendoptions) | 是   | TCPSocket发送请求的参数,参考[TCPSendOptions](#tcpsendoptions)。 |
C
clevercong 已提交
792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813
| callback | AsyncCallback\<void\>                   | 是   | 回调函数。                                                   |

**示例:**

```
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 已提交
814 815


C
clevercong 已提交
816
### send
C
clevercong 已提交
817 818 819 820 821 822

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

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

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

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

C
clevercong 已提交
827 828 829 830
**参数:**

| 参数名  | 类型                                    | 必填 | 说明                                                         |
| ------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
831
| options | [TCPSendOptions](#tcpsendoptions) | 是   | TCPSocket发送请求的参数,参考[TCPSendOptions](#tcpsendoptions)。 |
C
clevercong 已提交
832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857

**返回值:**

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

**示例:**

```
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 已提交
858 859


C
clevercong 已提交
860
### close
C
clevercong 已提交
861 862 863 864 865

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

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

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

C
clevercong 已提交
868
**参数:**
C
clevercong 已提交
869

C
clevercong 已提交
870 871 872
| 参数名   | 类型                  | 必填 | 说明       |
| -------- | --------------------- | ---- | ---------- |
| callback | AsyncCallback\<void\> | 是   | 回调函数。 |
C
clevercong 已提交
873 874


C
clevercong 已提交
875
**示例:**
C
clevercong 已提交
876

C
clevercong 已提交
877 878 879 880 881 882 883 884 885 886
```
let tcp = socket.constructTCPSocketInstance();
tcp.close(err => {
  if (err) {
	console.log('close fail');
	return;
  }
  console.log('close success');
})
```
C
clevercong 已提交
887 888


C
clevercong 已提交
889
### close
C
clevercong 已提交
890 891 892 893 894

close\(\): Promise<void\>

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

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

C
clevercong 已提交
897
**返回值:**
C
clevercong 已提交
898

C
clevercong 已提交
899 900 901
| 类型            | 说明                                       |
| :-------------- | :----------------------------------------- |
| Promise\<void\> | 以Promise形式返回关闭TCPSocket连接的结果。 |
C
clevercong 已提交
902

C
clevercong 已提交
903
**示例:**
C
clevercong 已提交
904

C
clevercong 已提交
905 906 907 908 909 910 911 912 913
```
let tcp = socket.constructTCPSocketInstance();
let promise = tcp.close();
promise.then(() => {
  console.log('close success');
}).catch(err => {
  console.log('close fail');
});
```
C
clevercong 已提交
914 915


C
clevercong 已提交
916
### getRemoteAddress
C
clevercong 已提交
917 918 919 920 921 922

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

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

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

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

C
clevercong 已提交
927
**参数:**
C
clevercong 已提交
928

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

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

C
clevercong 已提交
935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950
```
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 已提交
951 952


C
clevercong 已提交
953
### getRemoteAddress
C
clevercong 已提交
954 955 956 957 958 959

getRemoteAddress\(\): Promise<NetAddress\>

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

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

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

C
clevercong 已提交
964
**返回值:**
C
clevercong 已提交
965

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

C
clevercong 已提交
970
**示例:**
C
clevercong 已提交
971

C
clevercong 已提交
972 973 974 975 976 977 978 979 980 981 982 983 984 985 986
```
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(() => {
	console.log('getRemoteAddress success:' + JSON.stringify(data));
  }).catch(err => {
	console.log('getRemoteAddressfail');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
987 988


C
clevercong 已提交
989
### getState
C
clevercong 已提交
990 991 992 993 994 995

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

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

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

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

C
clevercong 已提交
1000
**参数:**
C
clevercong 已提交
1001

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


C
clevercong 已提交
1007
**示例:**
C
clevercong 已提交
1008

C
clevercong 已提交
1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024
```
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 已提交
1025 1026


C
clevercong 已提交
1027
### getState
C
clevercong 已提交
1028 1029 1030 1031 1032 1033

getState\(\): Promise<SocketStateBase\>

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

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

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

C
clevercong 已提交
1038
**返回值:**
C
clevercong 已提交
1039

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


C
clevercong 已提交
1045
**示例:**
C
clevercong 已提交
1046

C
clevercong 已提交
1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061
```
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(() => {
	console.log('getState success:' + JSON.stringify(data));
  }).catch(err => {
	console.log('getState fail');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1062 1063


C
clevercong 已提交
1064
### setExtraOptions
C
clevercong 已提交
1065 1066 1067 1068 1069 1070

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

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

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

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

C
clevercong 已提交
1075 1076 1077 1078
**参数:**

| 参数名   | 类型                                      | 必填 | 说明                                                         |
| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
1079
| options  | [TCPExtraOptions](#tcpextraoptions) | 是   | TCPSocket连接的其他属性,参考[TCPExtraOptions](#tcpextraoptions)。 |
C
clevercong 已提交
1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108
| callback | AsyncCallback\<void\>                     | 是   | 回调函数。                                                   |

**示例:**

```
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,
	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');
  });
}).catch(err => {
  console.log('connect fail');
});
```
C
clevercong 已提交
1109 1110


C
clevercong 已提交
1111
### setExtraOptions
C
clevercong 已提交
1112 1113 1114 1115 1116 1117

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

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

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

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

C
clevercong 已提交
1122 1123 1124 1125
**参数:**

| 参数名  | 类型                                      | 必填 | 说明                                                         |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
C
clevercong 已提交
1126
| options | [TCPExtraOptions](#tcpextraoptions) | 是   | TCPSocket连接的其他属性,参考[TCPExtraOptions](#tcpextraoptions)。 |
C
clevercong 已提交
1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160

**返回值:**

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


**示例:**

```
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,
	socketLinger: { on:true, linger:10 }
	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 已提交
1161 1162


C
clevercong 已提交
1163
### on\('message'\)
C
clevercong 已提交
1164 1165 1166 1167 1168

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

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

C
clevercong 已提交
1169
**参数:**
C
clevercong 已提交
1170

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

C
clevercong 已提交
1176
**示例:**
C
clevercong 已提交
1177

C
clevercong 已提交
1178 1179 1180 1181 1182 1183
```
let tcp = socket.constructTCPSocketInstance();
tcp.on('message', value => {
	console.log("on message, message:" + value.message + ", remoteInfo:" + value.remoteInfo)
});
```
C
clevercong 已提交
1184 1185


C
clevercong 已提交
1186
### off\('message'\)
C
clevercong 已提交
1187 1188 1189 1190 1191 1192 1193 1194

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

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

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

C
clevercong 已提交
1195
**参数:**
C
clevercong 已提交
1196

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

C
clevercong 已提交
1202
**示例:**
C
clevercong 已提交
1203

C
clevercong 已提交
1204 1205 1206 1207 1208 1209 1210 1211 1212 1213
```
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 已提交
1214 1215


C
clevercong 已提交
1216
### on\('connect' | 'close'\)
C
clevercong 已提交
1217 1218 1219 1220 1221

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

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

C
clevercong 已提交
1222
**参数:**
C
clevercong 已提交
1223

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


C
clevercong 已提交
1230
**示例:**
C
clevercong 已提交
1231

C
clevercong 已提交
1232 1233 1234 1235 1236 1237 1238 1239 1240
```
let tcp = socket.constructTCPSocketInstance();
tcp.on('connect', () => {
	console.log("on connect success")
});
tcp.on('close', data => {
	console.log("on close success")
});
```
C
clevercong 已提交
1241 1242


C
clevercong 已提交
1243
### off\('connect' | 'close'\)
C
clevercong 已提交
1244 1245 1246 1247 1248 1249 1250 1251

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

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

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

C
clevercong 已提交
1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277
**参数:**

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

**示例:**

```
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 已提交
1278 1279


C
clevercong 已提交
1280
### on\('error'\)
C
clevercong 已提交
1281 1282 1283 1284 1285

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

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

C
clevercong 已提交
1286
**参数:**
C
clevercong 已提交
1287

C
clevercong 已提交
1288 1289 1290 1291
| 参数名   | 类型          | 必填 | 说明                                 |
| -------- | ------------- | ---- | ------------------------------------ |
| type     | string        | 是   | 订阅的事件类型。'error':error事件。 |
| callback | ErrorCallback | 是   | 回调函数。                           |
C
clevercong 已提交
1292

C
clevercong 已提交
1293
**示例:**
C
clevercong 已提交
1294

C
clevercong 已提交
1295 1296 1297 1298 1299 1300
```
let tcp = socket.constructTCPSocketInstance();
tcp.on('error', err => {
	console.log("on error, err:" + JSON.stringify(err))
});
```
C
clevercong 已提交
1301 1302


C
clevercong 已提交
1303
### off\('error'\)
C
clevercong 已提交
1304 1305 1306 1307 1308 1309 1310 1311

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

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

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

C
clevercong 已提交
1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330
**参数:**

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

**示例:**

```
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 已提交
1331 1332


C
clevercong 已提交
1333
## TCPConnectOptions
C
clevercong 已提交
1334 1335 1336 1337 1338

TCPSocket连接的参数。

| 参数名  | 类型                               | 必填 | 说明                       |
| ------- | ---------------------------------- | ---- | -------------------------- |
C
clevercong 已提交
1339
| address | [NetAddress](#netaddress) | 是   | 绑定的地址以及端口。       |
C
clevercong 已提交
1340 1341
| timeout | number                             | 否   | 超时时间,单位毫秒(ms)。 |

C
clevercong 已提交
1342
## TCPSendOptions
C
clevercong 已提交
1343 1344 1345 1346 1347 1348 1349 1350

TCPSocket发送请求的参数。

| 参数名   | 类型   | 必填 | 说明                                                         |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| data     | string | 是   | 发送的数据。                                                 |
| encoding | string | 否   | 字符编码(UTF-8,UTF-16BE,UTF-16LE,UTF-16,US-AECII,ISO-8859-1),默认为UTF-8。 |

C
clevercong 已提交
1351
## TCPExtraOptions
C
clevercong 已提交
1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364

TCPSocket连接的其他属性。

| 参数名            | 类型    | 必填 | 说明                                                         |
| ----------------- | ------- | ---- | ------------------------------------------------------------ |
| 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)。                             |