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'; 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. 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| option | [SppOptions](#sppoptions) | Yes | SPP listening configuration. | 33| callback | AsyncCallback<number> | Yes | Callback invoked to return the server socket ID.| 34 35**Error codes** 36 37For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 38 39| ID| Error Message| 40| -------- | ---------------------------- | 41|2900001 | Service stopped. | 42|2900003 | Bluetooth switch is off. | 43|2900004 | Profile is not supported. | 44|2900099 | Operation failed. | 45 46**Example** 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 69 70sppAccept(serverSocket: number, callback: AsyncCallback<number>): 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<number> | 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 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 // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the server. 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 124 125sppConnect(deviceId: string, options: SppOptions, callback: AsyncCallback<number>): void 126 127Initiates an SPP connection to a remote device from the client. 128 129**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 130 131**System capability**: SystemCapability.Communication.Bluetooth.Core 132 133**Parameters** 134 135| Name | Type | Mandatory | Description | 136| -------- | --------------------------- | ---- | ------------------------------ | 137| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 138| option | [SppOptions](#sppoptions) | Yes | SPP listening configuration for the connection. | 139| callback | AsyncCallback<number> | Yes | Callback invoked to return the client socket ID. | 140 141**Error codes** 142 143For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 144 145| ID| Error Message| 146| -------- | ---------------------------- | 147|2900001 | Service stopped. | 148|2900003 | Bluetooth switch is off. | 149|2900004 | Profile is not supported. | 150|2900099 | Operation failed. | 151 152**Example** 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 // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. 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 176 177sppCloseServerSocket(socket: number): void 178 179Closes an SPP listening socket of the server. 180 181**System capability**: SystemCapability.Communication.Bluetooth.Core 182 183**Parameters** 184 185| Name | Type | Mandatory | Description | 186| ------ | ------ | ---- | --------------- | 187| socket | number | Yes | Server socket ID, which is obtained by **sppListen()**.| 188 189**Error codes** 190 191For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 192 193| ID| Error Message| 194| -------- | ---------------------------- | 195|2900001 | Service stopped. | 196|2900099 | Operation failed. | 197 198**Example** 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 219 220sppCloseClientSocket(socket: number): void 221 222Closes an SPP listening socket of the client. 223 224**System capability**: SystemCapability.Communication.Bluetooth.Core 225 226**Parameters** 227 228| Name | Type | Mandatory | Description | 229| ------ | ------ | ---- | ------------- | 230| socket | number | Yes | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.| 231 232**Error codes** 233 234For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 235 236| ID| Error Message| 237| -------- | ---------------------------- | 238|2900001 | Service stopped. | 239|2900099 | Operation failed. | 240 241**Example** 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 // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. 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 263 264sppWrite(clientSocket: number, data: ArrayBuffer): void 265 266Writes data to the remote device through a socket. 267 268**System capability**: SystemCapability.Communication.Bluetooth.Core 269 270**Parameters** 271 272| Name | Type | Mandatory | Description | 273| ------------ | ----------- | ---- | ------------- | 274| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.| 275| data | ArrayBuffer | Yes | Data to write. | 276 277**Error codes** 278 279For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 280 281| ID| Error Message| 282| -------- | ---------------------------- | 283|2901054 | IO error. | 284|2900099 | Operation failed. | 285 286**Example** 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 // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. 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<ArrayBuffer>): void 313 314Subscribes to SPP read request events. 315 316**System capability**: SystemCapability.Communication.Bluetooth.Core 317 318**Parameters** 319 320| Name | Type | Mandatory | Description | 321| ------------ | --------------------------- | ---- | -------------------------- | 322| type | string | Yes | Event type. The value is **sppRead**, which indicates an SPP read request event. | 323| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**. | 324| callback | Callback<ArrayBuffer> | Yes | Callback invoked to return the data read. | 325 326**Error codes** 327 328For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 329 330| ID| Error Message| 331| -------- | ---------------------------- | 332|2901054 | IO error. | 333|2900099 | Operation failed. | 334 335**Example** 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 // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. 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<ArrayBuffer>): void 363 364Unsubscribes from SPP read request events. 365 366**System capability**: SystemCapability.Communication.Bluetooth.Core 367 368**Parameters** 369 370| Name | Type | Mandatory | Description | 371| ------------ | --------------------------- | ---- | ---------------------------------------- | 372| type | string | Yes | Event type. The value is **sppRead**, which indicates an SPP read request event. | 373| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**. | 374| callback | Callback<ArrayBuffer> | No | Callback for the SPP read request event. If this parameter is not set, this API unsubscribes from all callbacks corresponding to **type**. | 375 376**Example** 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 // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. 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 398 399Defines the SPP configuration. 400 401**System capability**: SystemCapability.Communication.Bluetooth.Core 402 403| Name | Type | Readable | Writable | Description | 404| ------ | ------------------- | ---- | ---- | ----------- | 405| uuid | string | Yes | Yes | UUID of the SPP.| 406| secure | boolean | Yes | Yes | Whether it is a secure channel. | 407| type | [SppType](#spptype) | Yes | Yes | Type of the SPP link. | 408 409 410## SppType 411 412Enumerates the SPP link types. 413 414**System capability**: SystemCapability.Communication.Bluetooth.Core 415 416| Name | Value | Description | 417| ---------- | ---- | ------------- | 418| SPP_RFCOMM | 0 | Radio frequency communication (RFCOMM) link.| 419