• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.bluetooth.socket (Bluetooth socket Module)
2
3The **socket** module provides APIs for operating and managing Bluetooth sockets.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9
10
11## Modules to Import
12
13```js
14import socket from '@ohos.bluetooth.socket';
15import { BusinessError } from '@ohos.base';
16```
17
18## socket.sppListen<a name="sppListen"></a>
19
20sppListen(name: string, options: SppOptions, callback: AsyncCallback&lt;number&gt;): void
21
22Creates a Serial Port Profile (SPP) listening socket for the server.
23
24**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
25
26**System capability**: SystemCapability.Communication.Bluetooth.Core
27
28**Parameters**
29
30| Name     | Type                         | Mandatory  | Description                     |
31| -------- | --------------------------- | ---- | ----------------------- |
32| name     | string                      | Yes   | Name of the service.                 |
33| option   | [SppOptions](#sppoptions)     | Yes   | SPP listening configuration.             |
34| callback | AsyncCallback&lt;number&gt; | Yes   | Callback invoked to return the server socket ID.|
35
36**Error codes**
37
38For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md).
39
40| ID| Error Message|
41| -------- | ---------------------------- |
42|2900001 | Service stopped.                         |
43|2900003 | Bluetooth switch is off.                 |
44|2900004 | Profile is not supported.                |
45|2900099 | Operation failed.                        |
46
47**Example**
48
49```js
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
72Accepts a connection request from the client over a socket of the server.
73
74**System capability**: SystemCapability.Communication.Bluetooth.Core
75
76**Parameters**
77
78| Name         | Type                         | Mandatory  | Description                     |
79| ------------ | --------------------------- | ---- | ----------------------- |
80| serverSocket | number                      | Yes   | Server socket ID.          |
81| callback     | AsyncCallback&lt;number&gt; | Yes   | Callback invoked to return the client socket ID.|
82
83**Error codes**
84
85For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md).
86
87| ID| Error Message|
88| -------- | ---------------------------- |
89|2900001 | Service stopped.                         |
90|2900003 | Bluetooth switch is off.                 |
91|2900004 | Profile is not supported.                |
92|2900099 | Operation failed.                        |
93
94**Example**
95
96```js
97let serverNumber = -1;
98function serverSocket(code: BusinessError, number: number) {
99  console.log('bluetooth error code: ' + code.code);
100  if (code.code == 0) {
101    console.log('bluetooth serverSocket Number: ' + number);
102    serverNumber = number;
103  }
104}
105let clientNumber = -1;
106function acceptClientSocket(code: BusinessError, number: number) {
107  console.log('bluetooth error code: ' + code.code);
108  if (code.code == 0) {
109    console.log('bluetooth clientSocket Number: ' + number);
110    // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the server.
111    clientNumber = number;
112  }
113}
114try {
115    socket.sppAccept(serverNumber, acceptClientSocket);
116} catch (err) {
117    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
118}
119```
120
121
122## socket.sppConnect<a name="sppConnect"></a>
123
124sppConnect(deviceId: string, options: SppOptions, callback: AsyncCallback&lt;number&gt;): void
125
126Initiates an SPP connection to a remote device from the client.
127
128**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
129
130**System capability**: SystemCapability.Communication.Bluetooth.Core
131
132**Parameters**
133
134| Name     | Type                         | Mandatory  | Description                            |
135| -------- | --------------------------- | ---- | ------------------------------ |
136| deviceId | string                      | Yes   | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
137| option   | [SppOptions](#sppoptions)     | Yes   | SPP listening configuration for the connection.  |
138| callback | AsyncCallback&lt;number&gt; | Yes   | Callback invoked to return the client socket ID.       |
139
140**Error codes**
141
142For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md).
143
144| ID| Error Message|
145| -------- | ---------------------------- |
146|2900001 | Service stopped.                         |
147|2900003 | Bluetooth switch is off.                 |
148|2900004 | Profile is not supported.                |
149|2900099 | Operation failed.                        |
150
151**Example**
152
153```js
154
155let clientNumber = -1;
156function clientSocket(code: BusinessError, number: number) {
157  if (code.code != 0) {
158    return;
159  }
160  console.log('bluetooth serverSocket Number: ' + number);
161  // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client.
162  clientNumber = number;
163}
164let sppOption:socket.SppOptions = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0};
165try {
166    socket.sppConnect('XX:XX:XX:XX:XX:XX', sppOption, clientSocket);
167} catch (err) {
168    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
169}
170```
171
172
173## socket.sppCloseServerSocket<a name="sppCloseServerSocket"></a>
174
175sppCloseServerSocket(socket: number): void
176
177Closes an SPP listening socket of the server.
178
179**System capability**: SystemCapability.Communication.Bluetooth.Core
180
181**Parameters**
182
183| Name   | Type    | Mandatory  | Description             |
184| ------ | ------ | ---- | --------------- |
185| socket | number | Yes   | Server socket ID, which is obtained by **sppListen()**.|
186
187**Error codes**
188
189For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md).
190
191| ID| Error Message|
192| -------- | ---------------------------- |
193|2900001 | Service stopped.                         |
194|2900099 | Operation failed.                        |
195
196**Example**
197
198```js
199let serverNumber = -1;
200function serverSocket(code: BusinessError, number: number) {
201  console.log('bluetooth error code: ' + code.code);
202  if (code.code == 0) {
203    console.log('bluetooth serverSocket Number: ' + number);
204    serverNumber = number;
205  }
206}
207try {
208    socket.sppCloseServerSocket(serverNumber);
209} catch (err) {
210    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
211}
212```
213
214
215## socket.sppCloseClientSocket<a name="sppCloseClientSocket"></a>
216
217sppCloseClientSocket(socket: number): void
218
219Closes an SPP listening socket of the client.
220
221**System capability**: SystemCapability.Communication.Bluetooth.Core
222
223**Parameters**
224
225| Name   | Type    | Mandatory  | Description      |
226| ------ | ------ | ---- | ------------- |
227| socket | number | Yes   | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.|
228
229**Error codes**
230
231For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md).
232
233| ID| Error Message|
234| -------- | ---------------------------- |
235|2900001 | Service stopped.                         |
236|2900099 | Operation failed.                        |
237
238**Example**
239
240```js
241let clientNumber = -1;
242function clientSocket(code: BusinessError, number: number) {
243  if (code.code != 0) {
244    return;
245  }
246  console.log('bluetooth serverSocket Number: ' + number);
247  // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client.
248  clientNumber = number;
249}
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<a name="sppWrite"></a>
259
260sppWrite(clientSocket: number, data: ArrayBuffer): void
261
262Writes data to the remote device through a socket.
263
264**System capability**: SystemCapability.Communication.Bluetooth.Core
265
266**Parameters**
267
268| Name         | Type         | Mandatory  | Description           |
269| ------------ | ----------- | ---- | ------------- |
270| clientSocket | number      | Yes   | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.|
271| data         | ArrayBuffer | Yes   | Data to write.       |
272
273**Error codes**
274
275For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md).
276
277| ID| Error Message|
278| -------- | ---------------------------- |
279|2901054 | IO error.                                |
280|2900099 | Operation failed.                        |
281
282**Example**
283
284```js
285let clientNumber = -1;
286function clientSocket(code: BusinessError, number: number) {
287  if (code.code != 0) {
288    return;
289  }
290  console.log('bluetooth serverSocket Number: ' + number);
291  // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client.
292  clientNumber = number;
293}
294let arrayBuffer = new ArrayBuffer(8);
295let data = new Uint8Array(arrayBuffer);
296data[0] = 123;
297try {
298    socket.sppWrite(clientNumber, arrayBuffer);
299} catch (err) {
300    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
301}
302```
303
304
305## socket.on('sppRead')
306
307on(type: 'sppRead', clientSocket: number, callback: Callback&lt;ArrayBuffer&gt;): void
308
309Subscribes to SPP read request events.
310
311**System capability**: SystemCapability.Communication.Bluetooth.Core
312
313**Parameters**
314
315| Name         | Type                         | Mandatory  | Description                        |
316| ------------ | --------------------------- | ---- | -------------------------- |
317| type         | string                      | Yes   | Event type. The value is **sppRead**, which indicates an SPP read request event. |
318| clientSocket | number                      | Yes   | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.         |
319| callback     | Callback&lt;ArrayBuffer&gt; | Yes   | Callback invoked to return the data read.         |
320
321**Error codes**
322
323For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md).
324
325| ID| Error Message|
326| -------- | ---------------------------- |
327|2901054 | IO error.                                |
328|2900099 | Operation failed.                        |
329
330**Example**
331
332```js
333let clientNumber = -1;
334function clientSocket(code: BusinessError, number: number) {
335  if (code.code != 0) {
336    return;
337  }
338  console.log('bluetooth serverSocket Number: ' + number);
339  // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client.
340  clientNumber = number;
341}
342function dataRead(dataBuffer: ArrayBuffer) {
343  let data = new Uint8Array(dataBuffer);
344  console.log('bluetooth data is: ' + data[0]);
345}
346try {
347    socket.on('sppRead', clientNumber, dataRead);
348} catch (err) {
349    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
350}
351```
352
353
354## socket.off('sppRead')
355
356off(type: 'sppRead', clientSocket: number, callback?: Callback&lt;ArrayBuffer&gt;): void
357
358Unsubscribes from SPP read request events.
359
360**System capability**: SystemCapability.Communication.Bluetooth.Core
361
362**Parameters**
363
364| Name         | Type                         | Mandatory  | Description                                      |
365| ------------ | --------------------------- | ---- | ---------------------------------------- |
366| type         | string                      | Yes   | Event type. The value is **sppRead**, which indicates an SPP read request event.    |
367| clientSocket | number                      | Yes   | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.                       |
368| callback     | Callback&lt;ArrayBuffer&gt; | No   | Callback for the SPP read request event. If this parameter is not set, this API unsubscribes from all callbacks corresponding to **type**. |
369
370**Example**
371
372```js
373let clientNumber = -1;
374function clientSocket(code: BusinessError, number: number) {
375  if (code.code != 0) {
376    return;
377  }
378  console.log('bluetooth serverSocket Number: ' + number);
379  // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client.
380  clientNumber = number;
381}
382try {
383    socket.off('sppRead', clientNumber);
384} catch (err) {
385    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
386}
387```
388
389
390## SppOptions<a name="SppOptions"></a>
391
392Defines the SPP configuration.
393
394**System capability**: SystemCapability.Communication.Bluetooth.Core
395
396| Name    | Type               | Readable  | Writable  | Description         |
397| ------ | ------------------- | ---- | ---- | ----------- |
398| uuid   | string              | Yes   | Yes   | UUID of the SPP.|
399| secure | boolean             | Yes   | Yes   | Whether it is a secure channel.   |
400| type   | [SppType](#SppType)            | Yes   | Yes   | Type of the SPP link.   |
401
402
403## SppType<a name="SppType"></a>
404
405Enumerates the SPP link types.
406
407**System capability**: SystemCapability.Communication.Bluetooth.Core
408
409| Name        | Value | Description           |
410| ---------- | ---- | ------------- |
411| SPP_RFCOMM | 0    | Radio frequency communication (RFCOMM) link.|
412