• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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  if (code) {
109    console.error('sppListen error, code is ' + code);
110    return;
111  } else {
112    clientNumber = number; // 获取的clientNumber用作客户端后续读/写操作socket的id。
113    console.info('sppListen success, serverNumber = ' + clientNumber);
114  }
115}
116try {
117    socket.sppAccept(serverNumber, acceptClientSocket); // serverNumber是sppListen回调中得到的serverNumber。
118} catch (err) {
119    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
120}
121```
122
123
124## socket.sppConnect
125
126sppConnect(deviceId: string, options: SppOptions, callback: AsyncCallback<number>): void
127
128客户端向远端设备发起spp连接。使用Callback异步回调。
129
130**需要权限**：ohos.permission.ACCESS_BLUETOOTH
131
132**系统能力**：SystemCapability.Communication.Bluetooth.Core。
133
134**参数：**
135
136| 参数名      | 类型                          | 必填   | 说明                             |
137| -------- | --------------------------- | ---- | ------------------------------ |
138| deviceId | string                      | 是    | 对端设备地址，例如："XX:XX:XX:XX:XX:XX"。 |
139| options   | [SppOptions](#sppoptions)     | 是    | spp客户端连接配置参数。                  |
140| callback | AsyncCallback<number> | 是    | 表示回调函数的入参，客户端socket的id。        |
141
142**错误码**：
143
144以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
145
146| 错误码ID | 错误信息 |
147| -------- | ---------------------------- |
148|201 | Permission denied.                 |
149|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
150|801 | Capability not supported.          |
151|2900001 | Service stopped.                         |
152|2900003 | Bluetooth disabled.                 |
153|2900004 | Profile not supported.                |
154|2900099 | Operation failed.                        |
155
156**示例：**
157
158```js
159import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
160
161let clientSocket = (code: BusinessError, number: number) => {
162  if (code) {
163    console.error('sppListen error, code is ' + code);
164    return;
165  } else {
166    // 获取的number用作客户端后续读/写操作socket的id。
167    console.info('bluetooth serverSocket Number: ' + number);
168  }
169}
170let sppOption:socket.SppOptions = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0};
171try {
172    socket.sppConnect('XX:XX:XX:XX:XX:XX', sppOption, clientSocket);
173} catch (err) {
174    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
175}
176```
177
178
179## socket.getDeviceId<sup>17+</sup>
180
181getDeviceId(clientSocket: number): string
182
183通过clientSocket获取对端设备地址。服务端、客户端均可调用，传入非法clientSocket无法获取。
184
185**系统能力**：SystemCapability.Communication.Bluetooth.Core
186
187**参数：**
188
189| 参数名      | 类型                          | 必填   | 说明                             |
190| -------- | ------------------------------- | ---- | ------------------------------ |
191| clientSocket | number                      | 是    | 客户端Socket的id。 |
192
193**返回值：**
194
195| 类型                                       | 说明                         |
196| ---------------------------------------- | -------------------------- |
197| string | 返回对端设备地址，例如："XX:XX:XX:XX:XX:XX"。 |
198
199**错误码**：
200
201以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
202
203| 错误码ID | 错误信息 |
204| -------- | ---------------------------- |
205|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
206
207**示例：**
208
209```js
210import { socket } from '@kit.ConnectivityKit';
211import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
212// 服务端获取客户端设备地址。
213let clientSocket = -1; // clientSocket是sppAccept回调中得到的，调getDeviceId接口前需更新clientSocket。
214try {
215    let deviceAddr: string = socket.getDeviceId(clientSocket);
216} catch (err) {
217    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
218}
219
220// 客户端获取服务端设备地址。
221// clientSocket是sppConnect回调中得到的，调getDeviceId接口前需更新clientSocket。
222try {
223    let deviceAddr: string = socket.getDeviceId(clientSocket);
224} catch (err) {
225    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
226}
227```
228
229
230## socket.sppCloseServerSocket
231
232sppCloseServerSocket(socket: number): void
233
234关闭服务端监听Socket，入参socket由sppListen接口返回。
235
236**系统能力**：SystemCapability.Communication.Bluetooth.Core。
237
238**参数：**
239
240| 参数名    | 类型     | 必填   | 说明              |
241| ------ | ------ | ---- | --------------- |
242| socket | number | 是    | 服务端监听socket的id。 |
243
244**错误码**：
245
246以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
247
248| 错误码ID | 错误信息 |
249| -------- | ---------------------------- |
250|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.             |
251|801 | Capability not supported.          |
252|2900001 | Service stopped.                         |
253|2900099 | Operation failed.                        |
254
255**示例：**
256
257```js
258import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
259let serverNumber = -1; // 此处serverNumber需赋值为调用sppListen接口后，回调中得到的serverNumber。
260try {
261    socket.sppCloseServerSocket(serverNumber);
262} catch (err) {
263    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
264}
265```
266
267
268## socket.sppCloseClientSocket
269
270sppCloseClientSocket(socket: number): void
271
272关闭客户端socket，入参socket由sppAccept或sppConnect接口获取。
273
274**系统能力**：SystemCapability.Communication.Bluetooth.Core。
275
276**参数：**
277
278| 参数名    | 类型     | 必填   | 说明       |
279| ------ | ------ | ---- | ------------- |
280| socket | number | 是    | 客户端socket的id。 |
281
282**错误码**：
283
284以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
285
286| 错误码ID | 错误信息 |
287| -------- | ---------------------------- |
288|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.              |
289|801 | Capability not supported.          |
290|2900001 | Service stopped.                         |
291|2900099 | Operation failed.                        |
292
293**示例：**
294
295```js
296import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
297let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
298try {
299    socket.sppCloseClientSocket(clientNumber);
300} catch (err) {
301    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
302}
303```
304
305
306## socket.sppWrite
307
308sppWrite(clientSocket: number, data: ArrayBuffer): void
309
310通过socket向远端发送数据，入参clientSocket由sppAccept或sppConnect接口获取 。
311
312**系统能力**：SystemCapability.Communication.Bluetooth.Core。
313
314**参数：**
315
316| 参数名          | 类型          | 必填   | 说明            |
317| ------------ | ----------- | ---- | ------------- |
318| clientSocket | number      | 是    | 客户端socket的id。 |
319| data         | ArrayBuffer | 是    | 写入的数据。        |
320
321**错误码**：
322
323以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
324
325| 错误码ID | 错误信息 |
326| -------- | ---------------------------- |
327|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.             |
328|801 | Capability not supported.          |
329|2901054 | IO error.                                |
330|2900099 | Operation failed.                        |
331
332**示例：**
333
334```js
335import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
336let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
337let arrayBuffer = new ArrayBuffer(8);
338let data = new Uint8Array(arrayBuffer);
339data[0] = 123;
340try {
341    socket.sppWrite(clientNumber, arrayBuffer);
342} catch (err) {
343    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
344}
345```
346
347
348## socket.on('sppRead')
349
350on(type: 'sppRead', clientSocket: number, callback: Callback&lt;ArrayBuffer&gt;): void
351
352订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。使用Callback异步回调。
353
354**系统能力**：SystemCapability.Communication.Bluetooth.Core。
355
356**参数：**
357
358| 参数名          | 类型                          | 必填   | 说明                         |
359| ------------ | --------------------------- | ---- | -------------------------- |
360| type         | string                      | 是    | 填写"sppRead"字符串，表示spp读请求事件。 |
361| clientSocket | number                      | 是    | 客户端socket的id。              |
362| callback     | Callback&lt;ArrayBuffer&gt; | 是    | 表示回调函数的入参，读取到的数据。          |
363
364**错误码**：
365
366以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
367
368| 错误码ID | 错误信息 |
369| -------- | ---------------------------- |
370|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.            |
371|801 | Capability not supported.          |
372|2901054 | IO error.                                |
373|2900099 | Operation failed.                        |
374
375**示例：**
376
377```js
378import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
379let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
380let dataRead = (dataBuffer: ArrayBuffer) => {
381    let data = new Uint8Array(dataBuffer);
382    console.info('bluetooth data is: ' + data[0]);
383}
384try {
385    socket.on('sppRead', clientNumber, dataRead);
386} catch (err) {
387    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
388}
389```
390
391
392## socket.off('sppRead')
393
394off(type: 'sppRead', clientSocket: number, callback?: Callback&lt;ArrayBuffer&gt;): void
395
396取消订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。
397
398**系统能力**：SystemCapability.Communication.Bluetooth.Core。
399
400**参数：**
401
402| 参数名          | 类型                          | 必填   | 说明                                       |
403| ------------ | --------------------------- | ---- | ---------------------------------------- |
404| type         | string                      | 是    | 填写"sppRead"字符串，表示spp读请求事件。               |
405| clientSocket | number                      | 是    | 客户端Socket的id。                            |
406| callback     | Callback&lt;ArrayBuffer&gt; | 否    | 表示取消订阅spp读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 |
407
408**错误码**：
409
410以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
411
412| 错误码ID | 错误信息 |
413| -------- | ---------------------------- |
414|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.              |
415|801 | Capability not supported.          |
416
417**示例：**
418
419```js
420import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
421let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
422try {
423    socket.off('sppRead', clientNumber);
424} catch (err) {
425    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
426}
427```
428
429
430## socket.sppWriteAsync<sup>18+</sup>
431
432sppWriteAsync(clientSocket: number, data: ArrayBuffer): Promise&lt;void&gt;
433
434通过socket向远端发送数据的异步接口，该接口支持断开连接时SPP操作异常错误返回。
435
436**系统能力**：SystemCapability.Communication.Bluetooth.Core
437
438**参数：**
439
440| 参数名          | 类型                          | 必填   | 说明                                       |
441| ------------ | --------------------------- | ---- | ---------------------------------------- |
442| clientSocket | number                      | 是    | 客户端Socket的id。                            |
443| data         | ArrayBuffer                 | 是    | 写入的数据。 |
444
445**返回值：**
446
447| 类型                            | 说明         |
448| ----------------------------- | ---------- |
449| Promise&lt;void&gt; | 以Promise的形式返回结果。如果成功，err为undefined，否则为错误对象。 |
450
451**错误码**：
452
453以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
454
455| 错误码ID | 错误信息 |
456| -------- | ---------------------------- |
457|801 | Capability not supported.          |
458|2901054 | IO error. |
459|2900099 | Operation failed. |
460
461**示例：**
462
463```js
464import { socket } from '@kit.ConnectivityKit'
465import { AsyncCallback,BusinessError } from '@kit.BasicServicesKit';
466let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
467let arrayBuffer = new ArrayBuffer(8);
468let data = new Uint8Array(arrayBuffer);
469try {
470    await socket.sppWriteAsync(clientNumber, arrayBuffer);
471} catch (err) {
472    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
473}
474```
475
476
477## socket.sppReadAsync<sup>18+</sup>
478
479sppReadAsync(clientSocket: number): Promise&lt;ArrayBuffer&gt;
480
481通过socket读取对端所发送数据的异步接口，该接口支持断开连接时SPP操作异常错误返回。
482
483> **注意**：
484>
485> - 该接口不可与[socket.on('sppRead')](#socketonsppread)接口混用，同一路socket只能使用[socket.on('sppRead')](#socketonsppread)或者socket.sppReadAsync其中一个接口。
486>
487> - 该接口与[socket.on('sppRead')](#socketonsppread)使用方式不同，需要业务循环使用读取数据。
488
489**系统能力**：SystemCapability.Communication.Bluetooth.Core
490
491**参数：**
492
493| 参数名          | 类型                          | 必填   | 说明                                       |
494| ------------ | --------------------------- | ---- | ---------------------------------------- |
495| clientSocket | number                      | 是    | 客户端Socket的id。                            |
496
497**返回值：**
498
499| 类型                            | 说明         |
500| ----------------------------- | ---------- |
501| Promise&lt;ArrayBuffer&gt; | 以Promise的形式返回读取数据结果。如果成功，值在ArrayBuffer中返回，如果失败，返回对应错误码。 |
502
503**错误码**：
504
505以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
506
507| 错误码ID | 错误信息 |
508| -------- | ---------------------------- |
509|801 | Capability not supported.          |
510|2901054 | IO error. |
511|2900099 | Operation failed. |
512
513**示例：**
514
515```js
516import { socket } from '@kit.ConnectivityKit'
517import { AsyncCallback,BusinessError } from '@kit.BasicServicesKit';
518let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
519let buffer = new ArrayBuffer(1024);
520let data = new Uint8Array(arrayBuffer);
521let flag = 1;
522while (flag) {
523  try {
524    buffer = await socket.sppReadAsync(this.clientNumber);
525    if (buffer != null) {
526      console.info('sppRead success, data = ' + JSON.stringify(buffer));
527      printArrayBuffer(buffer);
528    } else {
529      console.error('sppRead error, data is null');
530    }
531  } catch (err) {
532    flag = 0;
533    console.error('startSppRead errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
534  }
535}
536```
537
538
539## SppOptions
540
541描述spp的配置参数。
542
543**系统能力**：SystemCapability.Communication.Bluetooth.Core。
544
545| 名称     | 类型                | 可读   | 可写   | 说明          |
546| ------ | ------------------- | ---- | ---- | ----------- |
547| uuid   | string              | 是    | 是    | spp单据的uuid。 |
548| secure | boolean             | 是    | 是    | 是否是安全通道。true表示是安全通道，false表示非安全通道。    |
549| type   | [SppType](#spptype)            | 是    | 是    | Spp链路类型。    |
550
551
552## SppType
553
554枚举，Spp链路类型。
555
556**系统能力**：SystemCapability.Communication.Bluetooth.Core。
557
558| 名称         | 值  | 说明            |
559| ---------- | ---- | ------------- |
560| SPP_RFCOMM | 0    | 表示rfcomm链路类型。 |
561