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 if (code) { 109 console.error('sppListen error, code is ' + code); 110 return; 111 } else { 112 clientNumber = number; // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. 113 console.info('sppListen success, serverNumber = ' + clientNumber); 114 } 115} 116try { 117 socket.sppAccept(serverNumber, acceptClientSocket); // serverNumber is the server number returned by the sppListen callback. 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 128Initiates an SPP connection to a remote device from the client. This API uses an asynchronous callback to return the result. 129 130**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 131 132**System capability**: SystemCapability.Communication.Bluetooth.Core 133 134**Parameters** 135 136| Name | Type | Mandatory | Description | 137| -------- | --------------------------- | ---- | ------------------------------ | 138| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 139| options | [SppOptions](#sppoptions) | Yes | SPP listening configuration for client. | 140| callback | AsyncCallback<number> | Yes | Callback used to return the client socket ID. | 141 142**Error codes** 143 144For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 145 146| ID| Error Message| 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**Example** 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 // The obtained number is used as the socket ID for subsequent read/write operations on the client. 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 183Obtains the address of the peer device over a client socket. This API is applicable both to the server and client. However, the API call fails if an invalid **clientSocket** is passed. 184 185**System capability**: SystemCapability.Communication.Bluetooth.Core 186 187**Parameters** 188 189| Name | Type | Mandatory | Description | 190| -------- | ------------------------------- | ---- | ------------------------------ | 191| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept** or **sppConnect**.| 192 193**Return value** 194 195| Type | Description | 196| ---------------------------------------- | -------------------------- | 197| string | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 198 199**Error codes** 200 201For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 202 203| ID| Error Message| 204| -------- | ---------------------------- | 205|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 206 207**Example** 208 209```js 210import { socket } from '@kit.ConnectivityKit'; 211import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 212// The server obtains the address of the client. 213let clientSocket = -1; // clientSocket is obtained from the sppAccept callback. Before calling getDeviceId, update the 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// The client obtains the address of the server. 221// clientSocket is obtained from the sppAccept callback. Before calling getDeviceId, update the 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 234Closes a listening socket of the server. 235 236**System capability**: SystemCapability.Communication.Bluetooth.Core 237 238**Parameters** 239 240| Name | Type | Mandatory | Description | 241| ------ | ------ | ---- | --------------- | 242| socket | number | Yes | Server socket ID, which is obtained by **sppListen()**.| 243 244**Error codes** 245 246For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 247 248| ID| Error Message| 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**Example** 256 257```js 258import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 259let serverNumber = -1; // Set serverNumber to the value of serverNumber returned by the sppListen callback. 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 272Closes a client socket. 273 274**System capability**: SystemCapability.Communication.Bluetooth.Core 275 276**Parameters** 277 278| Name | Type | Mandatory | Description | 279| ------ | ------ | ---- | ------------- | 280| socket | number | Yes | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.| 281 282**Error codes** 283 284For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 285 286| ID| Error Message| 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**Example** 294 295```js 296import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 297let clientNumber = -1; // clientNumber is obtained by sppAccept or 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 310Writes data to the remote device through a socket. 311 312**System capability**: SystemCapability.Communication.Bluetooth.Core 313 314**Parameters** 315 316| Name | Type | Mandatory | Description | 317| ------------ | ----------- | ---- | ------------- | 318| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**.| 319| data | ArrayBuffer | Yes | Data to write. | 320 321**Error codes** 322 323For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 324 325| ID| Error Message| 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**Example** 333 334```js 335import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 336let clientNumber = -1; // clientNumber is obtained by sppAccept or 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<ArrayBuffer>): void 351 352Subscribes to the SPP read request events. This API uses an asynchronous callback to return the result. 353 354**System capability**: SystemCapability.Communication.Bluetooth.Core 355 356**Parameters** 357 358| Name | Type | Mandatory | Description | 359| ------------ | --------------------------- | ---- | -------------------------- | 360| type | string | Yes | Event type. The value is **sppRead**, which indicates an SPP read request event.| 361| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept()** or **sppConnect()**. | 362| callback | Callback<ArrayBuffer> | Yes | Callback used to return the data read. | 363 364**Error codes** 365 366For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 367 368| ID| Error Message| 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**Example** 376 377```js 378import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 379let clientNumber = -1; // clientNumber is obtained by sppAccept or 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<ArrayBuffer>): void 395 396Unsubscribes from the SPP read request events. 397 398**System capability**: SystemCapability.Communication.Bluetooth.Core 399 400**Parameters** 401 402| Name | Type | Mandatory | Description | 403| ------------ | --------------------------- | ---- | ---------------------------------------- | 404| type | string | Yes | Event type. The value is **sppRead**, which indicates an SPP read request event. | 405| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept** or **sppConnect**. | 406| callback | Callback<ArrayBuffer> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| 407 408**Error codes** 409 410For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 411 412| ID| Error Message| 413| -------- | ---------------------------- | 414|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 415|801 | Capability not supported. | 416 417**Example** 418 419```js 420import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 421let clientNumber = -1; // clientNumber is obtained by sppAccept or 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<void> 433 434Writes data to the remote device through the socket. This API uses a promise to return the result. It supports returning of SPP operation errors, if any, when the connection is disconnected. 435 436**System capability**: SystemCapability.Communication.Bluetooth.Core 437 438**Parameters** 439 440| Name | Type | Mandatory | Description | 441| ------------ | --------------------------- | ---- | ---------------------------------------- | 442| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept** or **sppConnect**. | 443| data | ArrayBuffer | Yes | Data to write.| 444 445**Return value** 446 447| Type | Description | 448| ----------------------------- | ---------- | 449| Promise<void> | Promise used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 450 451**Error codes** 452 453For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 454 455| ID| Error Message| 456| -------- | ---------------------------- | 457|801 | Capability not supported. | 458|2901054 | IO error. | 459|2900099 | Operation failed. | 460 461**Example** 462 463```js 464import { socket } from '@kit.ConnectivityKit' 465import { AsyncCallback,BusinessError } from '@kit.BasicServicesKit'; 466let clientNumber = -1; // clientNumber is obtained by sppAccept or 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<ArrayBuffer> 480 481Reads data sent from the remote device through the socket. This API uses a promise to return the result. It supports returning of SPP operation errors, if any, when the connection is disconnected. 482 483> **NOTE** 484> 485> - This API cannot be used together with [socket.on('sppRead')](#socketonsppread). A socket can use either this API or [socket.on('sppRead')](#socketonsppread). 486> 487> - This API is used in a different way from [socket.on('sppRead')](#socketonsppread). It needs to be called cyclically to read data. 488 489**System capability**: SystemCapability.Communication.Bluetooth.Core 490 491**Parameters** 492 493| Name | Type | Mandatory | Description | 494| ------------ | --------------------------- | ---- | ---------------------------------------- | 495| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept** or **sppConnect**. | 496 497**Return value** 498 499| Type | Description | 500| ----------------------------- | ---------- | 501| Promise<ArrayBuffer> | Promise used to return the result. If the operation is successful, the result is returned in **ArrayBuffer**. If the operation fails, the corresponding error code is returned.| 502 503**Error codes** 504 505For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 506 507| ID| Error Message| 508| -------- | ---------------------------- | 509|801 | Capability not supported. | 510|2901054 | IO error. | 511|2900099 | Operation failed. | 512 513**Example** 514 515```js 516import { socket } from '@kit.ConnectivityKit' 517import { AsyncCallback,BusinessError } from '@kit.BasicServicesKit'; 518let clientNumber = -1; // clientNumber is obtained by sppAccept or 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 541Defines the SPP configuration parameters. 542 543**System capability**: SystemCapability.Communication.Bluetooth.Core 544 545| Name | Type | Readable | Writable | Description | 546| ------ | ------------------- | ---- | ---- | ----------- | 547| uuid | string | Yes | Yes | UUID of the SPP.| 548| 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. | 549| type | [SppType](#spptype) | Yes | Yes | Type of the SPP link. | 550 551 552## SppType 553 554Enumerates the SPP link types. 555 556**System capability**: SystemCapability.Communication.Bluetooth.Core 557 558| Name | Value | Description | 559| ---------- | ---- | ------------- | 560| SPP_RFCOMM | 0 | Radio frequency communication (RFCOMM) link.| 561