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