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 '@kit.ConnectivityKit';
15```
16
17## socket.sppListen
18
19sppListen(name: string, options: SppOptions, callback: AsyncCallback<number>): void
20
21Creates a Serial Port Profile (SPP) listening socket for the server. This API uses an asynchronous callback to return the result.
22
23**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
24
25**System capability**: SystemCapability.Communication.Bluetooth.Core
26
27**Parameters**
28
29| Name     | Type                         | Mandatory  | Description                     |
30| -------- | --------------------------- | ---- | ----------------------- |
31| name     | string                      | Yes   | Name of the service.                 |
32| options   | [SppOptions](#sppoptions)     | Yes   | SPP listening configuration.             |
33| callback | AsyncCallback<number> | Yes   | Callback used to return the server socket ID.|
34
35**Error codes**
36
37For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
38
39| ID| Error Message|
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**Example**
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
77Accepts a connection request from the client over a socket of the server. This API uses an asynchronous callback to return the result.
78
79**System capability**: SystemCapability.Communication.Bluetooth.Core
80
81**Parameters**
82
83| Name         | Type                         | Mandatory  | Description                     |
84| ------------ | --------------------------- | ---- | ----------------------- |
85| serverSocket | number                      | Yes   | Server socket ID.          |
86| callback     | AsyncCallback<number> | Yes   | Callback used to return the client socket ID.|
87
88**Error codes**
89
90For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
91
92| ID| Error Message|
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**Example**
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; // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client.
114    console.info('sppListen success, serverNumber = ' + clientNumber);
115  }
116}
117try {
118    socket.sppAccept(serverNumber, acceptClientSocket); // serverNumber is the server number returned by the sppListen callback.
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
129Initiates an SPP connection to a remote device from the client. This API uses an asynchronous callback to return the result.
130
131**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
132
133**System capability**: SystemCapability.Communication.Bluetooth.Core
134
135**Parameters**
136
137| Name     | Type                         | Mandatory  | Description                            |
138| -------- | --------------------------- | ---- | ------------------------------ |
139| deviceId | string                      | Yes   | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
140| options   | [SppOptions](#sppoptions)     | Yes   | SPP listening configuration for the connection.                 |
141| callback | AsyncCallback<number> | Yes   | Callback used to return the client socket ID.       |
142
143**Error codes**
144
145For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
146
147| ID| Error Message|
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**Example**
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    // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client.
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
186Closes an SPP listening socket of the server.
187
188**System capability**: SystemCapability.Communication.Bluetooth.Core
189
190**Parameters**
191
192| Name   | Type    | Mandatory  | Description             |
193| ------ | ------ | ---- | --------------- |
194| socket | number | Yes   | Server socket ID, which is obtained by **sppListen()**.|
195
196**Error codes**
197
198For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
199
200| ID| Error Message|
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**Example**
208
209```js
210import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
211let serverNumber = -1; // Set serverNumber to the value of serverNumber returned by the sppListen callback.
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
224Closes an SPP listening socket of the client.
225
226**System capability**: SystemCapability.Communication.Bluetooth.Core
227
228**Parameters**
229
230| Name   | Type    | Mandatory  | Description      |
231| ------ | ------ | ---- | ------------- |
232| socket | number | Yes   | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.|
233
234**Error codes**
235
236For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
237
238| ID| Error Message|
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**Example**
246
247```js
248import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
249let clientNumber = -1; // clientNumber is obtained by sppAccept or 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
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](errorcode-bluetoothManager.md).
276
277| ID| Error Message|
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**Example**
285
286```js
287import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
288let clientNumber = -1; // clientNumber is obtained by sppAccept or 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
304Subscribes to the SPP read request events. This API uses an asynchronous callback to return the result.
305
306**System capability**: SystemCapability.Communication.Bluetooth.Core
307
308**Parameters**
309
310| Name         | Type                         | Mandatory  | Description                        |
311| ------------ | --------------------------- | ---- | -------------------------- |
312| type         | string                      | Yes   | Event type. The value is **sppRead**, which indicates an SPP read request event.|
313| clientSocket | number                      | Yes   | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.             |
314| callback     | Callback<ArrayBuffer> | Yes   | Callback used to return the data read.         |
315
316**Error codes**
317
318For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
319
320| ID| Error Message|
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**Example**
328
329```js
330import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
331let clientNumber = -1; // clientNumber is obtained by sppAccept or 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
348Unsubscribes from SPP read request events.
349
350**System capability**: SystemCapability.Communication.Bluetooth.Core
351
352**Parameters**
353
354| Name         | Type                         | Mandatory  | Description                                      |
355| ------------ | --------------------------- | ---- | ---------------------------------------- |
356| type         | string                      | Yes   | Event type. The value is **sppRead**, which indicates an SPP read request event.              |
357| clientSocket | number                      | Yes   | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.                       |
358| callback     | Callback<ArrayBuffer> | No   | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.|
359
360**Error codes**
361
362For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
363
364| ID| Error Message|
365| -------- | ---------------------------- |
366|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.              |
367|801 | Capability not supported.          |
368
369**Example**
370
371```js
372import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
373let clientNumber = -1; // clientNumber is obtained by sppAccept or 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
384Defines the SPP configuration.
385
386**System capability**: SystemCapability.Communication.Bluetooth.Core
387
388| Name    | Type               | Readable  | Writable  | Description         |
389| ------ | ------------------- | ---- | ---- | ----------- |
390| uuid   | string              | Yes   | Yes   | UUID of the SPP.|
391| secure | boolean             | Yes   | Yes   | Whether it is a secure channel. The value **true** indicates a secure channel, and the value **false** indicates a non-secure channel.   |
392| type   | [SppType](#spptype)            | Yes   | Yes   | Type of the SPP link.   |
393
394
395## SppType
396
397Enumerates the SPP link types.
398
399**System capability**: SystemCapability.Communication.Bluetooth.Core
400
401| Name        | Value | Description           |
402| ---------- | ---- | ------------- |
403| SPP_RFCOMM | 0    | Radio frequency communication (RFCOMM) link.|
404