1# @ohos.bluetooth.socket (蓝牙socket模块)
2
3socket模块提供了操作和管理蓝牙socket的方法。
4
5> **说明：**
6>
7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9
10
11## 导入模块
12
13```js
14import { socket } from '@kit.ConnectivityKit';
15```
16
17## socket.sppListen
18
19sppListen(name: string, options: SppOptions, callback: AsyncCallback<number>): void
20
21创建一个服务端监听Socket。使用Callback异步回调。
22
23**需要权限**：ohos.permission.ACCESS_BLUETOOTH
24
25**系统能力**：SystemCapability.Communication.Bluetooth.Core。
26
27**参数：**
28
29| 参数名      | 类型                          | 必填   | 说明                      |
30| -------- | --------------------------- | ---- | ----------------------- |
31| name     | string                      | 是    | 服务的名称。                  |
32| options   | [SppOptions](#sppoptions)     | 是    | spp监听配置参数。              |
33| callback | AsyncCallback<number> | 是    | 表示回调函数的入参，服务端Socket的id。 |
34
35**错误码**：
36
37以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
38
39| 错误码ID | 错误信息 |
40| -------- | ---------------------------- |
41|201 | Permission denied.                 |
42|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
43|801 | Capability not supported.          |
44|2900001 | Service stopped.                         |
45|2900003 | Bluetooth disabled.                 |
46|2900004 | Profile not supported.                |
47|2900099 | Operation failed.                        |
48
49**示例：**
50
51```js
52import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
53let serverNumber = -1;
54let serverSocket = (code: BusinessError, number: number) => {
55  if (code) {
56    console.error('sppListen error, code is ' + code);
57    return;
58  } else {
59    serverNumber = number;
60    console.info('sppListen success, serverNumber = ' + serverNumber);
61  }
62}
63
64let sppOption:socket.SppOptions = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0};
65try {
66    socket.sppListen('server1', sppOption, serverSocket);
67} catch (err) {
68    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
69}
70```
71
72
73## socket.sppAccept
74
75sppAccept(serverSocket: number, callback: AsyncCallback<number>): void
76
77服务端监听socket等待客户端连接。使用Callback异步回调。
78
79**系统能力**：SystemCapability.Communication.Bluetooth.Core。
80
81**参数：**
82
83| 参数名          | 类型                          | 必填   | 说明                      |
84| ------------ | --------------------------- | ---- | ----------------------- |
85| serverSocket | number                      | 是    | 服务端socket的id。           |
86| callback     | AsyncCallback<number> | 是    | 表示回调函数的入参，客户端socket的id。 |
87
88**错误码**：
89
90以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
91
92| 错误码ID | 错误信息 |
93| -------- | ---------------------------- |
94|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
95|801 | Capability not supported.          |
96|2900001 | Service stopped.                         |
97|2900003 | Bluetooth disabled.                 |
98|2900004 | Profile not supported.                |
99|2900099 | Operation failed.                        |
100
101**示例：**
102
103```js
104import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
105let clientNumber = -1;
106let serverNumber = -1;
107let acceptClientSocket = (code: BusinessError, number: number) => {
108  console.info('bluetooth error code: ' + code.code);
109  if (code) {
110    console.error('sppListen error, code is ' + code);
111    return;
112  } else {
113    clientNumber = number; // 获取的clientNumber用作客户端后续读/写操作socket的id。
114    console.info('sppListen success, serverNumber = ' + clientNumber);
115  }
116}
117try {
118    socket.sppAccept(serverNumber, acceptClientSocket); // serverNumber是sppListen回调中得到的serverNumber。
119} catch (err) {
120    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
121}
122```
123
124
125## socket.sppConnect
126
127sppConnect(deviceId: string, options: SppOptions, callback: AsyncCallback<number>): void
128
129客户端向远端设备发起spp连接。使用Callback异步回调。
130
131**需要权限**：ohos.permission.ACCESS_BLUETOOTH
132
133**系统能力**：SystemCapability.Communication.Bluetooth.Core。
134
135**参数：**
136
137| 参数名      | 类型                          | 必填   | 说明                             |
138| -------- | --------------------------- | ---- | ------------------------------ |
139| deviceId | string                      | 是    | 对端设备地址，例如："XX:XX:XX:XX:XX:XX"。 |
140| options   | [SppOptions](#sppoptions)     | 是    | spp客户端连接配置参数。                  |
141| callback | AsyncCallback<number> | 是    | 表示回调函数的入参，客户端socket的id。        |
142
143**错误码**：
144
145以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
146
147| 错误码ID | 错误信息 |
148| -------- | ---------------------------- |
149|201 | Permission denied.                 |
150|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
151|801 | Capability not supported.          |
152|2900001 | Service stopped.                         |
153|2900003 | Bluetooth disabled.                 |
154|2900004 | Profile not supported.                |
155|2900099 | Operation failed.                        |
156
157**示例：**
158
159```js
160import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
161
162let clientNumber = -1;
163let clientSocket = (code: BusinessError, number: number) => {
164  if (code) {
165    console.error('sppListen error, code is ' + code);
166    return;
167  } else {
168    console.info('bluetooth serverSocket Number: ' + number);
169    // 获取的clientNumber用作客户端后续读/写操作socket的id。
170    clientNumber = number;
171  }
172}
173let sppOption:socket.SppOptions = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0};
174try {
175    socket.sppConnect('XX:XX:XX:XX:XX:XX', sppOption, clientSocket);
176} catch (err) {
177    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
178}
179```
180
181
182## socket.sppCloseServerSocket
183
184sppCloseServerSocket(socket: number): void
185
186关闭服务端监听Socket，入参socket由sppListen接口返回。
187
188**系统能力**：SystemCapability.Communication.Bluetooth.Core。
189
190**参数：**
191
192| 参数名    | 类型     | 必填   | 说明              |
193| ------ | ------ | ---- | --------------- |
194| socket | number | 是    | 服务端监听socket的id。 |
195
196**错误码**：
197
198以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
199
200| 错误码ID | 错误信息 |
201| -------- | ---------------------------- |
202|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.             |
203|801 | Capability not supported.          |
204|2900001 | Service stopped.                         |
205|2900099 | Operation failed.                        |
206
207**示例：**
208
209```js
210import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
211let serverNumber = -1; // 此处serverNumber需赋值为调用sppListen接口后，回调中得到的serverNumber。
212try {
213    socket.sppCloseServerSocket(serverNumber);
214} catch (err) {
215    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
216}
217```
218
219
220## socket.sppCloseClientSocket
221
222sppCloseClientSocket(socket: number): void
223
224关闭客户端socket，入参socket由sppAccept或sppConnect接口获取。
225
226**系统能力**：SystemCapability.Communication.Bluetooth.Core。
227
228**参数：**
229
230| 参数名    | 类型     | 必填   | 说明       |
231| ------ | ------ | ---- | ------------- |
232| socket | number | 是    | 客户端socket的id。 |
233
234**错误码**：
235
236以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
237
238| 错误码ID | 错误信息 |
239| -------- | ---------------------------- |
240|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.              |
241|801 | Capability not supported.          |
242|2900001 | Service stopped.                         |
243|2900099 | Operation failed.                        |
244
245**示例：**
246
247```js
248import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
249let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
250try {
251    socket.sppCloseClientSocket(clientNumber);
252} catch (err) {
253    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
254}
255```
256
257
258## socket.sppWrite
259
260sppWrite(clientSocket: number, data: ArrayBuffer): void
261
262通过socket向远端发送数据，入参clientSocket由sppAccept或sppConnect接口获取 。
263
264**系统能力**：SystemCapability.Communication.Bluetooth.Core。
265
266**参数：**
267
268| 参数名          | 类型          | 必填   | 说明            |
269| ------------ | ----------- | ---- | ------------- |
270| clientSocket | number      | 是    | 客户端socket的id。 |
271| data         | ArrayBuffer | 是    | 写入的数据。        |
272
273**错误码**：
274
275以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
276
277| 错误码ID | 错误信息 |
278| -------- | ---------------------------- |
279|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.             |
280|801 | Capability not supported.          |
281|2901054 | IO error.                                |
282|2900099 | Operation failed.                        |
283
284**示例：**
285
286```js
287import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
288let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
289let arrayBuffer = new ArrayBuffer(8);
290let data = new Uint8Array(arrayBuffer);
291data[0] = 123;
292try {
293    socket.sppWrite(clientNumber, arrayBuffer);
294} catch (err) {
295    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
296}
297```
298
299
300## socket.on('sppRead')
301
302on(type: 'sppRead', clientSocket: number, callback: Callback<ArrayBuffer>): void
303
304订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。使用Callback异步回调。
305
306**系统能力**：SystemCapability.Communication.Bluetooth.Core。
307
308**参数：**
309
310| 参数名          | 类型                          | 必填   | 说明                         |
311| ------------ | --------------------------- | ---- | -------------------------- |
312| type         | string                      | 是    | 填写"sppRead"字符串，表示spp读请求事件。 |
313| clientSocket | number                      | 是    | 客户端socket的id。              |
314| callback     | Callback<ArrayBuffer> | 是    | 表示回调函数的入参，读取到的数据。          |
315
316**错误码**：
317
318以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
319
320| 错误码ID | 错误信息 |
321| -------- | ---------------------------- |
322|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.            |
323|801 | Capability not supported.          |
324|2901054 | IO error.                                |
325|2900099 | Operation failed.                        |
326
327**示例：**
328
329```js
330import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
331let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
332let dataRead = (dataBuffer: ArrayBuffer) => {
333    let data = new Uint8Array(dataBuffer);
334    console.info('bluetooth data is: ' + data[0]);
335}
336try {
337    socket.on('sppRead', clientNumber, dataRead);
338} catch (err) {
339    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
340}
341```
342
343
344## socket.off('sppRead')
345
346off(type: 'sppRead', clientSocket: number, callback?: Callback<ArrayBuffer>): void
347
348取消订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。
349
350**系统能力**：SystemCapability.Communication.Bluetooth.Core。
351
352**参数：**
353
354| 参数名          | 类型                          | 必填   | 说明                                       |
355| ------------ | --------------------------- | ---- | ---------------------------------------- |
356| type         | string                      | 是    | 填写"sppRead"字符串，表示spp读请求事件。               |
357| clientSocket | number                      | 是    | 客户端Socket的id。                            |
358| callback     | Callback<ArrayBuffer> | 否    | 表示取消订阅spp读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 |
359
360**错误码**：
361
362以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
363
364| 错误码ID | 错误信息 |
365| -------- | ---------------------------- |
366|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.              |
367|801 | Capability not supported.          |
368
369**示例：**
370
371```js
372import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
373let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
374try {
375    socket.off('sppRead', clientNumber);
376} catch (err) {
377    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
378}
379```
380
381
382## SppOptions
383
384描述spp的配置参数。
385
386**系统能力**：SystemCapability.Communication.Bluetooth.Core。
387
388| 名称     | 类型                | 可读   | 可写   | 说明          |
389| ------ | ------------------- | ---- | ---- | ----------- |
390| uuid   | string              | 是    | 是    | spp单据的uuid。 |
391| secure | boolean             | 是    | 是    | 是否是安全通道。true表示是安全通道，false表示非安全通道。    |
392| type   | [SppType](#spptype)            | 是    | 是    | Spp链路类型。    |
393
394
395## SppType
396
397枚举，Spp链路类型。
398
399**系统能力**：SystemCapability.Communication.Bluetooth.Core。
400
401| 名称         | 值  | 说明            |
402| ---------- | ---- | ------------- |
403| SPP_RFCOMM | 0    | 表示rfcomm链路类型。 |