1# @ohos.bluetooth.ble (蓝牙ble模块) 2 3ble模块提供了对蓝牙操作和管理的方法。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10 11## 导入模块 12 13```js 14import { ble } from '@kit.ConnectivityKit'; 15``` 16 17 18## ProfileConnectionState 19 20type ProfileConnectionState = constant.ProfileConnectionState 21 22蓝牙设备的profile连接状态。 23 24**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 25 26**系统能力**：SystemCapability.Communication.Bluetooth.Core 27 28| 类型 | 说明 | 29| ------------------- | ------------------- | 30| [constant.ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 蓝牙设备的profile连接状态。 | 31 32 33## ble.createGattServer<a name="createGattServer"></a> 34 35createGattServer(): GattServer 36 37创建GattServer实例。 38 39**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 40 41**系统能力**：SystemCapability.Communication.Bluetooth.Core 42 43**返回值：** 44 45| 类型 | 说明 | 46| ----------------------------- | ---------- | 47| [GattServer](#gattserver) | 返回一个Gatt服务的实例。 | 48 49**示例：** 50 51```js 52let gattServer: ble.GattServer = ble.createGattServer(); 53console.info('gatt success'); 54``` 55 56 57## ble.createGattClientDevice<a name="createGattClientDevice"></a> 58 59createGattClientDevice(deviceId: string): GattClientDevice 60 61创建一个可使用的GattClientDevice实例。 62 63**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 64 65**系统能力**：SystemCapability.Communication.Bluetooth.Core 66 67**参数：** 68 69| 参数名 | 类型 | 必填 | 说明 | 70| -------- | ------ | ---- | ------------------------------------ | 71| deviceId | string | 是 | 对端设备地址， 例如："XX:XX:XX:XX:XX:XX"。 | 72 73**返回值：** 74 75| 类型 | 说明 | 76| ------------------------------------- | ------------------------------------ | 77| [GattClientDevice](#gattclientdevice) | client端类，使用client端方法之前需要创建该类的实例进行操作。 | 78 79**错误码**： 80 81以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 82 83| 错误码ID | 错误信息 | 84| -------- | ---------------------------- | 85|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 86|801 | Capability not supported. | 87 88**示例：** 89 90```js 91import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 92try { 93 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 94} catch (err) { 95 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 96} 97``` 98 99 100## ble.getConnectedBLEDevices<a name="getConnectedBLEDevices"></a> 101 102getConnectedBLEDevices(): Array<string> 103 104获取和当前设备连接的BLE设备。 105 106**需要权限**：ohos.permission.ACCESS_BLUETOOTH 107 108**系统能力**：SystemCapability.Communication.Bluetooth.Core 109 110**返回值：** 111 112| 类型 | 说明 | 113| ------------------- | ------------------- | 114| Array<string> | 返回当前设备作为Server端时连接BLE设备地址集合。<br>基于信息安全考虑，此处获取的设备地址为随机MAC地址。<br>- 配对成功后，该地址不会变更。<br>- 已配对设备取消配对后重新扫描或蓝牙服务下电时，该随机地址会变更。 | 115 116**错误码**： 117 118以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 119 120| 错误码ID | 错误信息 | 121| -------- | ---------------------------- | 122|201 | Permission denied. | 123|801 | Capability not supported. | 124|2900001 | Service stopped. | 125|2900003 | Bluetooth disabled. | 126|2900099 | Operation failed. | 127 128**示例：** 129 130```js 131import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 132try { 133 let result: Array<string> = ble.getConnectedBLEDevices(); 134} catch (err) { 135 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 136} 137``` 138 139 140## ble.startBLEScan<a name="startBLEScan"></a> 141 142startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void 143 144发起BLE扫描流程。 145 146**需要权限**：ohos.permission.ACCESS_BLUETOOTH 147 148**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 149 150**系统能力**：SystemCapability.Communication.Bluetooth.Core 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| ------- | -------------------------------------- | ---- | ----------------------------------- | 156| filters | Array<[ScanFilter](#scanfilter)> | 是 | 表示扫描结果过滤策略集合，符合过滤条件的设备发现会保留。如果不使用过滤的方式，该参数设置为null。 | 157| options | [ScanOptions](#scanoptions) | 否 | 表示扫描的参数配置，可选参数。 | 158 159**错误码**： 160 161以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 162 163| 错误码ID | 错误信息 | 164| -------- | ---------------------------- | 165|201 | Permission denied. | 166|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 167|801 | Capability not supported. | 168|2900001 | Service stopped. | 169|2900003 | Bluetooth disabled. | 170|2900099 | Operation failed. | 171 172**示例：** 173 174```js 175import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 176function onReceiveEvent(data: Array<ble.ScanResult>) { 177 console.info('BLE scan device find result = '+ JSON.stringify(data)); 178} 179try { 180 ble.on("BLEDeviceFind", onReceiveEvent); 181 let scanFilter: ble.ScanFilter = { 182 deviceId:"XX:XX:XX:XX:XX:XX", 183 name:"test", 184 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" 185 }; 186 let scanOptions: ble.ScanOptions = { 187 interval: 500, 188 dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER, 189 matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE 190 } 191 ble.startBLEScan([scanFilter],scanOptions); 192} catch (err) { 193 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 194} 195``` 196 197 198## ble.stopBLEScan<a name="stopBLEScan"></a> 199 200stopBLEScan(): void 201 202停止BLE扫描流程。 203 204**需要权限**：ohos.permission.ACCESS_BLUETOOTH 205 206**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 207 208**系统能力**：SystemCapability.Communication.Bluetooth.Core 209 210**错误码**： 211 212以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 213 214| 错误码ID | 错误信息 | 215| -------- | ---------------------------- | 216|201 | Permission denied. | 217|801 | Capability not supported. | 218|2900001 | Service stopped. | 219|2900003 | Bluetooth disabled. | 220|2900099 | Operation failed. | 221 222**示例：** 223 224```js 225import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 226try { 227 ble.stopBLEScan(); 228} catch (err) { 229 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 230} 231``` 232 233 234## ble.startAdvertising<a name="startAdvertising"></a> 235 236startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void 237 238开始发送BLE广播。 239 240**需要权限**：ohos.permission.ACCESS_BLUETOOTH 241 242**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 243 244**系统能力**：SystemCapability.Communication.Bluetooth.Core 245 246**参数：** 247 248| 参数名 | 类型 | 必填 | 说明 | 249| ----------- | ------------------------------------- | ---- | -------------- | 250| setting | [AdvertiseSetting](#advertisesetting) | 是 | BLE广播的相关参数。 | 251| advData | [AdvertiseData](#advertisedata) | 是 | BLE广播包内容。 | 252| advResponse | [AdvertiseData](#advertisedata) | 否 | BLE回复扫描请求回复响应。 | 253 254**错误码**： 255 256以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 257 258| 错误码ID | 错误信息 | 259| -------- | ---------------------------- | 260|201 | Permission denied. | 261|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 262|801 | Capability not supported. | 263|2900001 | Service stopped. | 264|2900003 | Bluetooth disabled. | 265|2900099 | Operation failed. | 266 267**示例：** 268 269```js 270import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 271let manufactureValueBuffer = new Uint8Array(4); 272manufactureValueBuffer[0] = 1; 273manufactureValueBuffer[1] = 2; 274manufactureValueBuffer[2] = 3; 275manufactureValueBuffer[3] = 4; 276 277let serviceValueBuffer = new Uint8Array(4); 278serviceValueBuffer[0] = 4; 279serviceValueBuffer[1] = 6; 280serviceValueBuffer[2] = 7; 281serviceValueBuffer[3] = 8; 282console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 283console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 284try { 285 let setting: ble.AdvertiseSetting = { 286 interval:150, 287 txPower:0, 288 connectable:true 289 }; 290 let manufactureDataUnit: ble.ManufactureData = { 291 manufactureId:4567, 292 manufactureValue:manufactureValueBuffer.buffer 293 }; 294 let serviceDataUnit: ble.ServiceData = { 295 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 296 serviceValue:serviceValueBuffer.buffer 297 }; 298 let advData: ble.AdvertiseData = { 299 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 300 manufactureData:[manufactureDataUnit], 301 serviceData:[serviceDataUnit] 302 }; 303 let advResponse: ble.AdvertiseData = { 304 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 305 manufactureData:[manufactureDataUnit], 306 serviceData:[serviceDataUnit] 307 }; 308 ble.startAdvertising(setting, advData ,advResponse); 309} catch (err) { 310 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 311} 312``` 313 314 315## ble.stopAdvertising<a name="stopAdvertising"></a> 316 317stopAdvertising(): void 318 319停止发送BLE广播。 320 321**需要权限**：ohos.permission.ACCESS_BLUETOOTH 322 323**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 324 325**系统能力**：SystemCapability.Communication.Bluetooth.Core 326 327**错误码**： 328 329以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 330 331| 错误码ID | 错误信息 | 332| -------- | ---------------------------- | 333|201 | Permission denied. | 334|801 | Capability not supported. | 335|2900001 | Service stopped. | 336|2900003 | Bluetooth disabled. | 337|2900099 | Operation failed. | 338 339**示例：** 340 341```js 342import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 343try { 344 ble.stopAdvertising(); 345} catch (err) { 346 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 347} 348``` 349 350 351## ble.startAdvertising<sup>11+</sup><a name="startAdvertising"></a> 352 353startAdvertising(advertisingParams: AdvertisingParams, callback: AsyncCallback<number>): void 354 355开始发送BLE广播。使用Callback异步回调。从API15开始，多次调用，可发起多路广播，每一路广播通过不同的ID管理。 356 357**需要权限**：ohos.permission.ACCESS_BLUETOOTH 358 359**系统能力**：SystemCapability.Communication.Bluetooth.Core 360 361**参数：** 362 363| 参数名 | 类型 | 必填 | 说明 | 364| ------------------- | --------------------------------------- | ----- | ------------------------------- | 365| advertisingParams | [AdvertisingParams](#advertisingparams11) | 是 | 启动BLE广播的相关参数。 | 366| callback | AsyncCallback<number> | 是 | 广播ID标识，通过注册回调函数获取。 | 367 368**错误码**： 369 370以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 371 372| 错误码ID | 错误信息 | 373| -------- | -------------------------------------- | 374|201 | Permission denied. | 375|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 376|801 | Capability not supported. | 377|2900001 | Service stopped. | 378|2900003 | Bluetooth disabled. | 379|2900099 | Operation failed. | 380 381**示例：** 382 383```js 384import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 385let manufactureValueBuffer = new Uint8Array(4); 386manufactureValueBuffer[0] = 1; 387manufactureValueBuffer[1] = 2; 388manufactureValueBuffer[2] = 3; 389manufactureValueBuffer[3] = 4; 390 391let serviceValueBuffer = new Uint8Array(4); 392serviceValueBuffer[0] = 4; 393serviceValueBuffer[1] = 6; 394serviceValueBuffer[2] = 7; 395serviceValueBuffer[3] = 8; 396console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 397console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 398try { 399 let setting: ble.AdvertiseSetting = { 400 interval:150, 401 txPower:0, 402 connectable:true, 403 }; 404 let manufactureDataUnit: ble.ManufactureData = { 405 manufactureId:4567, 406 manufactureValue:manufactureValueBuffer.buffer 407 }; 408 let serviceDataUnit: ble.ServiceData = { 409 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 410 serviceValue:serviceValueBuffer.buffer 411 }; 412 let advData: ble.AdvertiseData = { 413 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 414 manufactureData:[manufactureDataUnit], 415 serviceData:[serviceDataUnit] 416 }; 417 let advResponse: ble.AdvertiseData = { 418 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 419 manufactureData:[manufactureDataUnit], 420 serviceData:[serviceDataUnit] 421 }; 422 let advertisingParams: ble.AdvertisingParams = { 423 advertisingSettings: setting, 424 advertisingData: advData, 425 advertisingResponse: advResponse, 426 duration: 0 427 } 428 let advHandle = 0xFF; 429 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 430 if (err) { 431 return; 432 } else { 433 advHandle = outAdvHandle; 434 console.info("advHandle: " + advHandle); 435 } 436 }); 437} catch (err) { 438 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 439} 440``` 441 442 443## ble.startAdvertising<sup>11+</sup><a name="startAdvertising"></a> 444 445startAdvertising(advertisingParams: AdvertisingParams): Promise<number> 446 447开始发送BLE广播。使用Promise异步回调。从API15开始，多次调用，可发起多路广播，每一路广播通过不同的ID管理。 448 449**需要权限**：ohos.permission.ACCESS_BLUETOOTH 450 451**系统能力**：SystemCapability.Communication.Bluetooth.Core 452 453**参数：** 454 455| 参数名 | 类型 | 必填 | 说明 | 456| ------------------- | -------------------------------------- | ----- | ----------------------- | 457| advertisingParams | [AdvertisingParams](#advertisingparams11) | 是 | 启动BLE广播的相关参数。 | 458 459**返回值：** 460 461| 类型 | 说明 | 462| -------------------------- | ------------------------------- | 463| Promise<number> | 广播ID标识，通过promise形式获取。 | 464 465**错误码**： 466 467以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 468 469| 错误码ID | 错误信息 | 470| -------- | -------------------------------------- | 471|201 | Permission denied. | 472|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 473|801 | Capability not supported. | 474|2900001 | Service stopped. | 475|2900003 | Bluetooth disabled. | 476|2900099 | Operation failed. | 477 478**示例：** 479 480```js 481import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 482let manufactureValueBuffer = new Uint8Array(4); 483manufactureValueBuffer[0] = 1; 484manufactureValueBuffer[1] = 2; 485manufactureValueBuffer[2] = 3; 486manufactureValueBuffer[3] = 4; 487 488let serviceValueBuffer = new Uint8Array(4); 489serviceValueBuffer[0] = 4; 490serviceValueBuffer[1] = 6; 491serviceValueBuffer[2] = 7; 492serviceValueBuffer[3] = 8; 493console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 494console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 495try { 496 let setting: ble.AdvertiseSetting = { 497 interval:150, 498 txPower:0, 499 connectable:true 500 }; 501 let manufactureDataUnit: ble.ManufactureData = { 502 manufactureId:4567, 503 manufactureValue:manufactureValueBuffer.buffer 504 }; 505 let serviceDataUnit: ble.ServiceData = { 506 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 507 serviceValue:serviceValueBuffer.buffer 508 }; 509 let advData: ble.AdvertiseData = { 510 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 511 manufactureData:[manufactureDataUnit], 512 serviceData:[serviceDataUnit] 513 }; 514 let advResponse: ble.AdvertiseData = { 515 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 516 manufactureData:[manufactureDataUnit], 517 serviceData:[serviceDataUnit] 518 }; 519 let advertisingParams: ble.AdvertisingParams = { 520 advertisingSettings: setting, 521 advertisingData: advData, 522 advertisingResponse: advResponse, 523 duration: 0 524 } 525 let advHandle = 0xFF; 526 ble.startAdvertising(advertisingParams) 527 .then(outAdvHandle => { 528 advHandle = outAdvHandle; 529 }); 530} catch (err) { 531 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 532} 533``` 534 535 536## ble.enableAdvertising<sup>11+</sup><a name="enableAdvertising"></a> 537 538enableAdvertising(advertisingEnableParams: AdvertisingEnableParams, callback: AsyncCallback<void>): void 539 540临时启动BLE广播。使用Callback异步回调。 541 542**需要权限**：ohos.permission.ACCESS_BLUETOOTH 543 544**系统能力**：SystemCapability.Communication.Bluetooth.Core 545 546**参数：** 547 548| 参数名 | 类型 | 必填 | 说明 | 549| ------------------------- | --------------------------------------------------- | ----- | ------------------------------- | 550| advertisingEnableParams | [AdvertisingEnableParams](#advertisingenableparams11) | 是 | 临时启动BLE广播的相关参数。 | 551| callback | AsyncCallback<void> | 是 | 回调函数。 | 552 553**错误码**： 554 555以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 556 557| 错误码ID | 错误信息 | 558| ------- | -------------------------------------- | 559|201 | Permission denied. | 560|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 561|801 | Capability not supported. | 562|2900001 | Service stopped. | 563|2900003 | Bluetooth disabled. | 564|2900099 | Operation failed. | 565 566**示例：** 567 568```js 569import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 570let manufactureValueBuffer = new Uint8Array(4); 571manufactureValueBuffer[0] = 1; 572manufactureValueBuffer[1] = 2; 573manufactureValueBuffer[2] = 3; 574manufactureValueBuffer[3] = 4; 575 576let serviceValueBuffer = new Uint8Array(4); 577serviceValueBuffer[0] = 4; 578serviceValueBuffer[1] = 6; 579serviceValueBuffer[2] = 7; 580serviceValueBuffer[3] = 8; 581console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 582console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 583try { 584 let setting: ble.AdvertiseSetting = { 585 interval:150, 586 txPower:0, 587 connectable:true 588 }; 589 let manufactureDataUnit: ble.ManufactureData = { 590 manufactureId:4567, 591 manufactureValue:manufactureValueBuffer.buffer 592 }; 593 let serviceDataUnit: ble.ServiceData = { 594 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 595 serviceValue:serviceValueBuffer.buffer 596 }; 597 let advData: ble.AdvertiseData = { 598 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 599 manufactureData:[manufactureDataUnit], 600 serviceData:[serviceDataUnit] 601 }; 602 let advResponse: ble.AdvertiseData = { 603 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 604 manufactureData:[manufactureDataUnit], 605 serviceData:[serviceDataUnit] 606 }; 607 let advertisingParams: ble.AdvertisingParams = { 608 advertisingSettings: setting, 609 advertisingData: advData, 610 advertisingResponse: advResponse, 611 duration: 300 612 } 613 let advHandle = 0xFF; 614 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 615 if (err) { 616 return; 617 } else { 618 advHandle = outAdvHandle; 619 console.info("advHandle: " + advHandle); 620 } 621 }); 622 623 let advertisingEnableParams: ble.AdvertisingEnableParams = { 624 advertisingId: advHandle, 625 duration: 0 626 } 627 628 // after 3s, advertising disabled, then enable the advertising 629 ble.enableAdvertising(advertisingEnableParams, (err) => { 630 if (err) { 631 return; 632 } 633 }); 634} catch (err) { 635 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 636} 637``` 638 639 640## ble.enableAdvertising<sup>11+</sup><a name="enableAdvertising"></a> 641 642enableAdvertising(advertisingEnableParams: AdvertisingEnableParams): Promise<void> 643 644临时启动BLE广播。使用Promise异步回调。 645 646**需要权限**：ohos.permission.ACCESS_BLUETOOTH 647 648**系统能力**：SystemCapability.Communication.Bluetooth.Core 649 650**参数：** 651 652| 参数名 | 类型 | 必填 | 说明 | 653| ------------------------- | --------------------------------------------------- | ----- | ------------------------------- | 654| advertisingEnableParams | [AdvertisingEnableParams](#advertisingenableparams11) | 是 | 临时启动BLE广播的相关参数。 | 655 656**返回值：** 657 658| 类型 | 说明 | 659| -------------------------- | ------------ | 660| Promise<void> | 回调函数。 | 661 662**错误码**： 663 664以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 665 666| 错误码ID | 错误信息 | 667| ------- | -------------------------------------- | 668|201 | Permission denied. | 669|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 670|801 | Capability not supported. | 671|2900001 | Service stopped. | 672|2900003 | Bluetooth disabled. | 673|2900099 | Operation failed. | 674 675**示例：** 676 677```js 678import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 679let manufactureValueBuffer = new Uint8Array(4); 680manufactureValueBuffer[0] = 1; 681manufactureValueBuffer[1] = 2; 682manufactureValueBuffer[2] = 3; 683manufactureValueBuffer[3] = 4; 684 685let serviceValueBuffer = new Uint8Array(4); 686serviceValueBuffer[0] = 4; 687serviceValueBuffer[1] = 6; 688serviceValueBuffer[2] = 7; 689serviceValueBuffer[3] = 8; 690console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 691console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 692try { 693 let setting: ble.AdvertiseSetting = { 694 interval:150, 695 txPower:0, 696 connectable:true 697 }; 698 let manufactureDataUnit: ble.ManufactureData = { 699 manufactureId:4567, 700 manufactureValue:manufactureValueBuffer.buffer 701 }; 702 let serviceDataUnit: ble.ServiceData = { 703 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 704 serviceValue:serviceValueBuffer.buffer 705 }; 706 let advData: ble.AdvertiseData = { 707 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 708 manufactureData:[manufactureDataUnit], 709 serviceData:[serviceDataUnit] 710 }; 711 let advResponse: ble.AdvertiseData = { 712 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 713 manufactureData:[manufactureDataUnit], 714 serviceData:[serviceDataUnit] 715 }; 716 let advertisingParams: ble.AdvertisingParams = { 717 advertisingSettings: setting, 718 advertisingData: advData, 719 advertisingResponse: advResponse, 720 duration: 300 721 } 722 let advHandle = 0xFF; 723 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 724 if (err) { 725 return; 726 } else { 727 advHandle = outAdvHandle; 728 console.info("advHandle: " + advHandle); 729 } 730 }); 731 732 let advertisingEnableParams: ble.AdvertisingEnableParams = { 733 advertisingId: advHandle, 734 duration: 0 735 } 736 737 // after 3s, advertising disabled, then enable the advertising 738 ble.enableAdvertising(advertisingEnableParams) 739 .then(() => { 740 console.info("enable success"); 741 }); 742} catch (err) { 743 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 744} 745``` 746 747 748## ble.disableAdvertising<sup>11+</sup><a name="disableAdvertising"></a> 749 750disableAdvertising(advertisingDisableParams: AdvertisingDisableParams, callback: AsyncCallback<void>): void 751 752临时停止BLE广播。使用Callback异步回调。 753 754**需要权限**：ohos.permission.ACCESS_BLUETOOTH 755 756**系统能力**：SystemCapability.Communication.Bluetooth.Core 757 758**参数：** 759 760| 参数名 | 类型 | 必填 | 说明 | 761| ------------------------- | ----------------------------------------------------- | ----- | ------------------------------- | 762| advertisingDisableParams | [AdvertisingDisableParams](#advertisingdisableparams11) | 是 | 临时停止BLE广播的相关参数。 | 763| callback | AsyncCallback<void> | 是 | 回调函数。 | 764 765**错误码**： 766 767以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 768 769| 错误码ID | 错误信息 | 770| ------- | -------------------------------------- | 771|201 | Permission denied. | 772|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 773|801 | Capability not supported. | 774|2900001 | Service stopped. | 775|2900003 | Bluetooth disabled. | 776|2900099 | Operation failed. | 777 778**示例：** 779 780```js 781import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 782let manufactureValueBuffer = new Uint8Array(4); 783manufactureValueBuffer[0] = 1; 784manufactureValueBuffer[1] = 2; 785manufactureValueBuffer[2] = 3; 786manufactureValueBuffer[3] = 4; 787 788let serviceValueBuffer = new Uint8Array(4); 789serviceValueBuffer[0] = 4; 790serviceValueBuffer[1] = 6; 791serviceValueBuffer[2] = 7; 792serviceValueBuffer[3] = 8; 793console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 794console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 795try { 796 let setting: ble.AdvertiseSetting = { 797 interval:150, 798 txPower:0, 799 connectable:true 800 }; 801 let manufactureDataUnit: ble.ManufactureData = { 802 manufactureId:4567, 803 manufactureValue:manufactureValueBuffer.buffer 804 }; 805 let serviceDataUnit: ble.ServiceData = { 806 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 807 serviceValue:serviceValueBuffer.buffer 808 }; 809 let advData: ble.AdvertiseData = { 810 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 811 manufactureData:[manufactureDataUnit], 812 serviceData:[serviceDataUnit] 813 }; 814 let advResponse: ble.AdvertiseData = { 815 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 816 manufactureData:[manufactureDataUnit], 817 serviceData:[serviceDataUnit] 818 }; 819 let advertisingParams: ble.AdvertisingParams = { 820 advertisingSettings: setting, 821 advertisingData: advData, 822 advertisingResponse: advResponse, 823 duration: 0 824 } 825 let advHandle = 0xFF; 826 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 827 if (err) { 828 return; 829 } else { 830 advHandle = outAdvHandle; 831 console.info("advHandle: " + advHandle); 832 } 833 }); 834 835 let advertisingDisableParams: ble.AdvertisingDisableParams = { 836 advertisingId: advHandle 837 } 838 ble.disableAdvertising(advertisingDisableParams, (err) => { 839 if (err) { 840 return; 841 } 842 }); 843} catch (err) { 844 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 845} 846``` 847 848 849## ble.disableAdvertising<sup>11+</sup><a name="disableAdvertising"></a> 850 851disableAdvertising(advertisingDisableParams: AdvertisingDisableParams): Promise<void> 852 853临时停止BLE广播。使用Promise异步回调。 854 855**需要权限**：ohos.permission.ACCESS_BLUETOOTH 856 857**系统能力**：SystemCapability.Communication.Bluetooth.Core 858 859**参数：** 860 861| 参数名 | 类型 | 必填 | 说明 | 862| ------------------------- | ----------------------------------------------------- | ----- | ------------------------------- | 863| advertisingDisableParams | [AdvertisingDisableParams](#advertisingdisableparams11) | 是 | 临时停止BLE广播的相关参数。 | 864 865**返回值：** 866 867| 类型 | 说明 | 868| -------------------------- | ------------ | 869| Promise<void> | 回调函数。 | 870 871**错误码**： 872 873以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 874 875| 错误码ID | 错误信息 | 876| ------- | -------------------------------------- | 877|201 | Permission denied. | 878|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 879|801 | Capability not supported. | 880|2900001 | Service stopped. | 881|2900003 | Bluetooth disabled. | 882|2900099 | Operation failed. | 883 884**示例：** 885 886```js 887import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 888let manufactureValueBuffer = new Uint8Array(4); 889manufactureValueBuffer[0] = 1; 890manufactureValueBuffer[1] = 2; 891manufactureValueBuffer[2] = 3; 892manufactureValueBuffer[3] = 4; 893 894let serviceValueBuffer = new Uint8Array(4); 895serviceValueBuffer[0] = 4; 896serviceValueBuffer[1] = 6; 897serviceValueBuffer[2] = 7; 898serviceValueBuffer[3] = 8; 899console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 900console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 901try { 902 let setting: ble.AdvertiseSetting = { 903 interval:150, 904 txPower:0, 905 connectable:true 906 }; 907 let manufactureDataUnit: ble.ManufactureData = { 908 manufactureId:4567, 909 manufactureValue:manufactureValueBuffer.buffer 910 }; 911 let serviceDataUnit: ble.ServiceData = { 912 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 913 serviceValue:serviceValueBuffer.buffer 914 }; 915 let advData: ble.AdvertiseData = { 916 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 917 manufactureData:[manufactureDataUnit], 918 serviceData:[serviceDataUnit] 919 }; 920 let advResponse: ble.AdvertiseData = { 921 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 922 manufactureData:[manufactureDataUnit], 923 serviceData:[serviceDataUnit] 924 }; 925 let advertisingParams: ble.AdvertisingParams = { 926 advertisingSettings: setting, 927 advertisingData: advData, 928 advertisingResponse: advResponse, 929 duration: 0 930 } 931 let advHandle = 0xFF; 932 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 933 if (err) { 934 return; 935 } else { 936 advHandle = outAdvHandle; 937 console.info("advHandle: " + advHandle); 938 } 939 }); 940 941 let advertisingDisableParams: ble.AdvertisingDisableParams = { 942 advertisingId: advHandle 943 } 944 ble.disableAdvertising(advertisingDisableParams) 945 .then(() => { 946 console.info("enable success"); 947 }); 948} catch (err) { 949 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 950} 951``` 952 953## ble.stopAdvertising<sup>11+</sup><a name="stopAdvertising"></a> 954 955stopAdvertising(advertisingId: number, callback: AsyncCallback<void>): void 956 957停止发送BLE广播。使用Callback异步回调。 958 959**需要权限**：ohos.permission.ACCESS_BLUETOOTH 960 961**系统能力**：SystemCapability.Communication.Bluetooth.Core 962 963**参数：** 964 965| 参数名 | 类型 | 必填 | 说明 | 966| ------------------------- | ---------------------------- | ----- | --------------------------- | 967| advertisingId | number | 是 | 需要停止的广播ID标识。 | 968| callback | AsyncCallback<void> | 是 | 回调函数。 | 969 970**错误码**： 971 972以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 973 974| 错误码ID | 错误信息 | 975| -------- | ---------------------------- | 976|201 | Permission denied. | 977|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 978|801 | Capability not supported. | 979|2900001 | Service stopped. | 980|2900003 | Bluetooth disabled. | 981|2900099 | Operation failed. | 982 983**示例：** 984 985```js 986import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 987let manufactureValueBuffer = new Uint8Array(4); 988manufactureValueBuffer[0] = 1; 989manufactureValueBuffer[1] = 2; 990manufactureValueBuffer[2] = 3; 991manufactureValueBuffer[3] = 4; 992 993let serviceValueBuffer = new Uint8Array(4); 994serviceValueBuffer[0] = 4; 995serviceValueBuffer[1] = 6; 996serviceValueBuffer[2] = 7; 997serviceValueBuffer[3] = 8; 998console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 999console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 1000try { 1001 let setting: ble.AdvertiseSetting = { 1002 interval:150, 1003 txPower:0, 1004 connectable:true 1005 }; 1006 let manufactureDataUnit: ble.ManufactureData = { 1007 manufactureId:4567, 1008 manufactureValue:manufactureValueBuffer.buffer 1009 }; 1010 let serviceDataUnit: ble.ServiceData = { 1011 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 1012 serviceValue:serviceValueBuffer.buffer 1013 }; 1014 let advData: ble.AdvertiseData = { 1015 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1016 manufactureData:[manufactureDataUnit], 1017 serviceData:[serviceDataUnit] 1018 }; 1019 let advResponse: ble.AdvertiseData = { 1020 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1021 manufactureData:[manufactureDataUnit], 1022 serviceData:[serviceDataUnit] 1023 }; 1024 let advertisingParams: ble.AdvertisingParams = { 1025 advertisingSettings: setting, 1026 advertisingData: advData, 1027 advertisingResponse: advResponse, 1028 duration: 0 1029 } 1030 let advHandle = 0xFF; 1031 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 1032 if (err) { 1033 return; 1034 } else { 1035 advHandle = outAdvHandle; 1036 console.info("advHandle: " + advHandle); 1037 } 1038 }); 1039 1040 ble.stopAdvertising(advHandle, (err) => { 1041 if (err) { 1042 return; 1043 } 1044 }); 1045} catch (err) { 1046 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1047} 1048``` 1049 1050 1051## ble.stopAdvertising<sup>11+</sup><a name="stopAdvertising"></a> 1052 1053stopAdvertising(advertisingId: number): Promise<void> 1054 1055停止发送BLE广播。使用Promise异步回调。 1056 1057**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1058 1059**系统能力**：SystemCapability.Communication.Bluetooth.Core 1060 1061**参数：** 1062 1063| 参数名 | 类型 | 必填 | 说明 | 1064| ------------------------- | ---------------------------- | ----- | --------------------------- | 1065| advertisingId | number | 是 | 需要停止的广播ID标识。 | 1066 1067**返回值：** 1068 1069| 类型 | 说明 | 1070| -------------------------- | ------------ | 1071| Promise<void> | 回调函数。 | 1072 1073**错误码**： 1074 1075以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1076 1077| 错误码ID | 错误信息 | 1078| -------- | ---------------------------- | 1079|201 | Permission denied. | 1080|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1081|801 | Capability not supported. | 1082|2900001 | Service stopped. | 1083|2900003 | Bluetooth disabled. | 1084|2900099 | Operation failed. | 1085 1086**示例：** 1087 1088```js 1089import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1090let manufactureValueBuffer = new Uint8Array(4); 1091manufactureValueBuffer[0] = 1; 1092manufactureValueBuffer[1] = 2; 1093manufactureValueBuffer[2] = 3; 1094manufactureValueBuffer[3] = 4; 1095 1096let serviceValueBuffer = new Uint8Array(4); 1097serviceValueBuffer[0] = 4; 1098serviceValueBuffer[1] = 6; 1099serviceValueBuffer[2] = 7; 1100serviceValueBuffer[3] = 8; 1101console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 1102console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 1103try { 1104 let setting: ble.AdvertiseSetting = { 1105 interval:150, 1106 txPower:0, 1107 connectable:true 1108 }; 1109 let manufactureDataUnit: ble.ManufactureData = { 1110 manufactureId:4567, 1111 manufactureValue:manufactureValueBuffer.buffer 1112 }; 1113 let serviceDataUnit: ble.ServiceData = { 1114 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 1115 serviceValue:serviceValueBuffer.buffer 1116 }; 1117 let advData: ble.AdvertiseData = { 1118 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1119 manufactureData:[manufactureDataUnit], 1120 serviceData:[serviceDataUnit] 1121 }; 1122 let advResponse: ble.AdvertiseData = { 1123 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1124 manufactureData:[manufactureDataUnit], 1125 serviceData:[serviceDataUnit] 1126 }; 1127 let advertisingParams: ble.AdvertisingParams = { 1128 advertisingSettings: setting, 1129 advertisingData: advData, 1130 advertisingResponse: advResponse, 1131 duration: 0 1132 } 1133 let advHandle = 0xFF; 1134 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 1135 if (err) { 1136 return; 1137 } else { 1138 advHandle = outAdvHandle; 1139 console.info("advHandle: " + advHandle); 1140 } 1141 }); 1142 1143 ble.stopAdvertising(advHandle) 1144 .then(() => { 1145 console.info("enable success"); 1146 }); 1147} catch (err) { 1148 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1149} 1150``` 1151 1152 1153## ble.on('advertisingStateChange')<sup>11+</sup> 1154 1155on(type: 'advertisingStateChange', callback: Callback<AdvertisingStateChangeInfo>): void 1156 1157订阅BLE广播状态。使用Callback异步回调。 1158 1159**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1160 1161**系统能力**：SystemCapability.Communication.Bluetooth.Core 1162 1163**参数：** 1164 1165| 参数名 | 类型 | 必填 | 说明 | 1166| -------- | ------------------------------------------------------------------------- | ----- | ---------------------------------------------------------- | 1167| type | string | 是 | 填写"advertisingStateChange"字符串，表示广播状态事件。 | 1168| callback | Callback<[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)> | 是 | 表示回调函数的入参，广播状态。回调函数由用户创建通过该接口注册。 | 1169 1170**错误码**： 1171 1172以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1173 1174| 错误码ID | 错误信息 | 1175| -------- | ---------------------------- | 1176|201 | Permission denied. | 1177|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1178|801 | Capability not supported. | 1179|2900099 | Operation failed. | 1180 1181**示例：** 1182 1183```js 1184import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1185function onReceiveEvent(data: ble.AdvertisingStateChangeInfo) { 1186 console.info('bluetooth advertising state = ' + JSON.stringify(data)); 1187} 1188try { 1189 ble.on('advertisingStateChange', onReceiveEvent); 1190} catch (err) { 1191 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1192} 1193``` 1194 1195 1196## ble.off('advertisingStateChange')<sup>11+</sup> 1197 1198off(type: 'advertisingStateChange', callback?: Callback<AdvertisingStateChangeInfo>): void 1199 1200取消订阅BLE广播状态。 1201 1202**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1203 1204**系统能力**：SystemCapability.Communication.Bluetooth.Core 1205 1206**参数：** 1207 1208| 参数名 | 类型 | 必填 | 说明 | 1209| -------- | ------------------------------------------------------------------------- | ----- | ---------------------------------------------------------- | 1210| type | string | 是 | 填写"advertisingStateChange"字符串，表示广播状态事件。 | 1211| callback | Callback<[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)> | 否 | 表示取消订阅广播状态上报。不填该参数则取消订阅该type对应的所有回调。 | 1212 1213**错误码**： 1214 1215以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1216 1217| 错误码ID | 错误信息 | 1218| -------- | ---------------------------- | 1219|201 | Permission denied. | 1220|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1221|801 | Capability not supported. | 1222|2900099 | Operation failed. | 1223 1224**示例：** 1225 1226```js 1227import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1228function onReceiveEvent(data: ble.AdvertisingStateChangeInfo) { 1229 console.info('bluetooth advertising state = ' + JSON.stringify(data)); 1230} 1231try { 1232 ble.on('advertisingStateChange', onReceiveEvent); 1233 ble.off('advertisingStateChange', onReceiveEvent); 1234} catch (err) { 1235 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1236} 1237``` 1238 1239 1240## ble.on('BLEDeviceFind') 1241 1242on(type: 'BLEDeviceFind', callback: Callback<Array<ScanResult>>): void 1243 1244订阅BLE设备发现上报事件。使用Callback异步回调。 1245 1246**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1247 1248**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1249 1250**系统能力**：SystemCapability.Communication.Bluetooth.Core 1251 1252**参数：** 1253 1254| 参数名 | 类型 | 必填 | 说明 | 1255| -------- | ---------------------------------------- | ---- | ----------------------------------- | 1256| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 1257| callback | Callback<Array<[ScanResult](#scanresult)>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | 1258 1259**错误码**： 1260 1261以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1262 1263| 错误码ID | 错误信息 | 1264| -------- | ---------------------------- | 1265|201 | Permission denied. | 1266|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1267|801 | Capability not supported. | 1268|2900099 | Operation failed. | 1269 1270**示例：** 1271 1272```js 1273import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1274function onReceiveEvent(data: Array<ble.ScanResult>) { 1275 console.info('bluetooth device find = '+ JSON.stringify(data)); 1276} 1277try { 1278 ble.on('BLEDeviceFind', onReceiveEvent); 1279} catch (err) { 1280 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1281} 1282``` 1283 1284 1285## ble.off('BLEDeviceFind') 1286 1287off(type: 'BLEDeviceFind', callback?: Callback<Array<ScanResult>>): void 1288 1289取消订阅BLE设备发现上报事件。 1290 1291**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1292 1293**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1294 1295**系统能力**：SystemCapability.Communication.Bluetooth.Core 1296 1297**参数：** 1298 1299| 参数名 | 类型 | 必填 | 说明 | 1300| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1301| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 1302| callback | Callback<Array<[ScanResult](#scanresult)>> | 否 | 表示取消订阅BLE设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1303 1304**错误码**： 1305 1306以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1307 1308 1309| 错误码ID | 错误信息 | 1310| -------- | ---------------------------- | 1311|201 | Permission denied. | 1312|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1313|801 | Capability not supported. | 1314|2900099 | Operation failed. | 1315 1316**示例：** 1317 1318```js 1319import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1320function onReceiveEvent(data: Array<ble.ScanResult>) { 1321 console.info('bluetooth device find = '+ JSON.stringify(data)); 1322} 1323try { 1324 ble.on('BLEDeviceFind', onReceiveEvent); 1325 ble.off('BLEDeviceFind', onReceiveEvent); 1326} catch (err) { 1327 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1328} 1329``` 1330 1331 1332## GattServer 1333 1334server端类，使用server端方法之前需要创建该类的实例进行操作，通过createGattServer()方法构造此实例。 1335 1336 1337### addService 1338 1339addService(service: GattService): void 1340 1341server端添加服务。 1342 1343**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1344 1345**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1346 1347**系统能力**：SystemCapability.Communication.Bluetooth.Core 1348 1349**参数：** 1350 1351| 参数名 | 类型 | 必填 | 说明 | 1352| ------- | --------------------------- | ---- | ------------------------ | 1353| service | [GattService](#gattservice) | 是 | 服务端的service数据。BLE广播的相关参数 | 1354 1355**错误码**： 1356 1357以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1358 1359| 错误码ID | 错误信息 | 1360| -------- | ---------------------------- | 1361|201 | Permission denied. | 1362|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1363|801 | Capability not supported. | 1364|2900001 | Service stopped. | 1365|2900003 | Bluetooth disabled. | 1366|2900099 | Operation failed. | 1367 1368**示例：** 1369 1370```js 1371import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1372// 创建descriptors。 1373let descriptors: Array<ble.BLEDescriptor> = []; 1374let arrayBuffer = new ArrayBuffer(8); 1375let descV = new Uint8Array(arrayBuffer); 1376descV[0] = 11; 1377let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1378 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1379 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 1380descriptors[0] = descriptor; 1381 1382// 创建characteristics。 1383let characteristics: Array<ble.BLECharacteristic> = []; 1384let arrayBufferC = new ArrayBuffer(8); 1385let cccV = new Uint8Array(arrayBufferC); 1386cccV[0] = 1; 1387let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1388 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 1389characteristics[0] = characteristic; 1390 1391// 创建gattService。 1392let gattService: ble.GattService = {serviceUuid:'00001810-0000-1000-8000-00805F9B34FB', isPrimary: true, characteristics:characteristics, includeServices:[]}; 1393 1394try { 1395 let gattServer: ble.GattServer = ble.createGattServer(); 1396 gattServer.addService(gattService); 1397} catch (err) { 1398 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1399} 1400``` 1401 1402 1403### removeService 1404 1405removeService(serviceUuid: string): void 1406 1407删除已添加的服务。 1408 1409**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1410 1411**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1412 1413**系统能力**：SystemCapability.Communication.Bluetooth.Core 1414 1415**参数：** 1416 1417| 参数名 | 类型 | 必填 | 说明 | 1418| ----------- | ------ | ---- | ---------------------------------------- | 1419| serviceUuid | string | 是 | service的UUID。例如“00001810-0000-1000-8000-00805F9B34FB”。 | 1420 1421**错误码**： 1422 1423以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1424 1425| 错误码ID | 错误信息 | 1426| -------- | ---------------------------- | 1427|201 | Permission denied. | 1428|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1429|801 | Capability not supported. | 1430|2900001 | Service stopped. | 1431|2900003 | Bluetooth disabled. | 1432|2900004 | Profile not supported. | 1433|2900099 | Operation failed. | 1434 1435**示例：** 1436 1437```js 1438import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1439let server: ble.GattServer = ble.createGattServer(); 1440try { 1441 // 调用removeService接口前需要完成server端和client端的配对及连接。 1442 server.removeService('00001810-0000-1000-8000-00805F9B34FB'); 1443} catch (err) { 1444 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1445} 1446``` 1447 1448 1449### close 1450 1451close(): void 1452 1453关闭服务端功能，去掉server在协议栈的注册，调用该接口后[GattServer](#gattserver)实例将不能再使用。 1454 1455**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1456 1457**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1458 1459**系统能力**：SystemCapability.Communication.Bluetooth.Core 1460 1461**错误码**： 1462 1463以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1464 1465| 错误码ID | 错误信息 | 1466| -------- | ---------------------------- | 1467|201 | Permission denied. | 1468|801 | Capability not supported. | 1469|2900001 | Service stopped. | 1470|2900003 | Bluetooth disabled. | 1471|2900099 | Operation failed. | 1472 1473**示例：** 1474 1475```js 1476import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1477let server: ble.GattServer = ble.createGattServer(); 1478try { 1479 server.close(); 1480} catch (err) { 1481 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1482} 1483``` 1484 1485 1486### notifyCharacteristicChanged 1487 1488notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic, callback: AsyncCallback<void>): void 1489 1490server端特征值发生变化时，主动通知已连接的client设备。使用Callback异步回调。 1491 1492**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1493 1494**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1495 1496**系统能力**：SystemCapability.Communication.Bluetooth.Core 1497 1498**参数：** 1499 1500| 参数名 | 类型 | 必填 | 说明 | 1501| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | 1502| deviceId | string | 是 | 接收通知的client端设备地址。例如“XX:XX:XX:XX:XX:XX”。 | 1503| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | 是 | 通知的特征值数据。 | 1504| callback | AsyncCallback<void> | 是 | 回调函数。当通知成功，err为undefined，否则为错误对象。 | 1505 1506**错误码**： 1507 1508以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1509 1510| 错误码ID | 错误信息 | 1511| -------- | ---------------------------- | 1512|201 | Permission denied. | 1513|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1514|801 | Capability not supported. | 1515|2900001 | Service stopped. | 1516|2900003 | Bluetooth disabled. | 1517|2900099 | Operation failed. | 1518 1519**示例：** 1520 1521```js 1522import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1523let arrayBufferC = new ArrayBuffer(8); 1524let notifyCharacter: ble.NotifyCharacteristic = { 1525 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1526 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1527 characteristicValue: arrayBufferC, 1528 confirm: true 1529}; 1530try { 1531 let gattServer: ble.GattServer = ble.createGattServer(); 1532 gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter, (err: BusinessError) => { 1533 if (err) { 1534 console.info('notifyCharacteristicChanged callback failed'); 1535 } else { 1536 console.info('notifyCharacteristicChanged callback successful'); 1537 } 1538 }); 1539} catch (err) { 1540 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1541} 1542``` 1543 1544 1545### notifyCharacteristicChanged 1546 1547notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic): Promise<void> 1548 1549server端特征值发生变化时，主动通知已连接的client设备。使用Promise异步回调。 1550 1551**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1552 1553**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1554 1555**系统能力**：SystemCapability.Communication.Bluetooth.Core 1556 1557**参数：** 1558 1559| 参数名 | 类型 | 必填 | 说明 | 1560| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | 1561| deviceId | string | 是 | 接收通知的client端设备地址。例如“XX:XX:XX:XX:XX:XX”。 | 1562| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | 是 | 通知的特征值数据。 | 1563 1564**返回值：** 1565 1566| 类型 | 说明 | 1567| ------------------- | ------------- | 1568| Promise<void> | 返回promise对象。 | 1569 1570**错误码**： 1571 1572以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1573 1574| 错误码ID | 错误信息 | 1575| -------- | ---------------------------- | 1576|201 | Permission denied. | 1577|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1578|801 | Capability not supported. | 1579|2900001 | Service stopped. | 1580|2900003 | Bluetooth disabled. | 1581|2900099 | Operation failed. | 1582 1583**示例：** 1584 1585```js 1586import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1587let arrayBufferC = new ArrayBuffer(8); 1588let notifyCharacter: ble.NotifyCharacteristic = { 1589 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1590 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1591 characteristicValue: arrayBufferC, 1592 confirm: true 1593}; 1594try { 1595 let gattServer: ble.GattServer = ble.createGattServer(); 1596 gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter).then(() => { 1597 console.info('notifyCharacteristicChanged promise successful'); 1598 }); 1599} catch (err) { 1600 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1601} 1602``` 1603 1604 1605### sendResponse 1606 1607sendResponse(serverResponse: ServerResponse): void 1608 1609server端回复client端的读写请求。 1610 1611**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1612 1613**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1614 1615**系统能力**：SystemCapability.Communication.Bluetooth.Core 1616 1617**参数：** 1618 1619| 参数名 | 类型 | 必填 | 说明 | 1620| -------------- | --------------------------------- | ---- | --------------- | 1621| serverResponse | [ServerResponse](#serverresponse) | 是 | server端回复的响应数据。 | 1622 1623**错误码**： 1624 1625以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1626 1627| 错误码ID | 错误信息 | 1628| -------- | ---------------------------- | 1629|201 | Permission denied. | 1630|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1631|801 | Capability not supported. | 1632|2900001 | Service stopped. | 1633|2900003 | Bluetooth disabled. | 1634|2900099 | Operation failed. | 1635 1636**示例：** 1637 1638```js 1639import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1640/* send response */ 1641let arrayBufferCCC = new ArrayBuffer(8); 1642let cccValue = new Uint8Array(arrayBufferCCC); 1643cccValue[0] = 1123; 1644let serverResponse: ble.ServerResponse = { 1645 deviceId: 'XX:XX:XX:XX:XX:XX', 1646 transId: 0, 1647 status: 0, 1648 offset: 0, 1649 value: arrayBufferCCC 1650}; 1651try { 1652 let gattServer: ble.GattServer = ble.createGattServer(); 1653 gattServer.sendResponse(serverResponse); 1654} catch (err) { 1655 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1656} 1657``` 1658 1659 1660### on('characteristicRead') 1661 1662on(type: 'characteristicRead', callback: Callback<CharacteristicReadRequest>): void 1663 1664server端订阅特征值读请求事件。使用Callback异步回调。 1665 1666**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1667 1668**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1669 1670**系统能力**：SystemCapability.Communication.Bluetooth.Core 1671 1672**参数：** 1673 1674| 参数名 | 类型 | 必填 | 说明 | 1675| -------- | ---------------------------------------- | ---- | ------------------------------------- | 1676| type | string | 是 | 填写"characteristicRead"字符串，表示特征值读请求事件。 | 1677| callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | 是 | 表示回调函数的入参，client端发送的读请求数据。 | 1678 1679**错误码**： 1680 1681以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1682 1683| 错误码ID | 错误信息 | 1684| -------- | ---------------------------- | 1685|201 | Permission denied. | 1686|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1687|801 | Capability not supported. | 1688 1689**示例：** 1690 1691```js 1692import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1693let arrayBufferCCC = new ArrayBuffer(8); 1694let cccValue = new Uint8Array(arrayBufferCCC); 1695cccValue[0] = 1123; 1696let gattServer: ble.GattServer = ble.createGattServer(); 1697function ReadCharacteristicReq(characteristicReadRequest: ble.CharacteristicReadRequest) { 1698 let deviceId: string = characteristicReadRequest.deviceId; 1699 let transId: number = characteristicReadRequest.transId; 1700 let offset: number = characteristicReadRequest.offset; 1701 let characteristicUuid: string = characteristicReadRequest.characteristicUuid; 1702 1703 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; 1704 1705 try { 1706 gattServer.sendResponse(serverResponse); 1707 } catch (err) { 1708 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1709 } 1710} 1711gattServer.on('characteristicRead', ReadCharacteristicReq); 1712``` 1713 1714 1715### off('characteristicRead') 1716 1717off(type: 'characteristicRead', callback?: Callback<CharacteristicReadRequest>): void 1718 1719server端取消订阅特征值读请求事件。 1720 1721**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1722 1723**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1724 1725**系统能力**：SystemCapability.Communication.Bluetooth.Core 1726 1727**参数：** 1728 1729| 参数名 | 类型 | 必填 | 说明 | 1730| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1731| type | string | 是 | 填写"characteristicRead"字符串，表示特征值读请求事件。 | 1732| callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | 否 | 表示取消订阅特征值读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1733 1734**错误码**： 1735 1736以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1737 1738| 错误码ID | 错误信息 | 1739| -------- | ---------------------------- | 1740|201 | Permission denied. | 1741|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1742|801 | Capability not supported. | 1743 1744**示例：** 1745 1746```js 1747import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1748try { 1749 let gattServer: ble.GattServer = ble.createGattServer(); 1750 gattServer.off('characteristicRead'); 1751} catch (err) { 1752 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1753} 1754``` 1755 1756 1757### on('characteristicWrite') 1758 1759on(type: 'characteristicWrite', callback: Callback<CharacteristicWriteRequest>): void 1760 1761server端订阅特征值写请求事件。使用Callback异步回调。 1762 1763**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1764 1765**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1766 1767**系统能力**：SystemCapability.Communication.Bluetooth.Core 1768 1769**参数：** 1770 1771| 参数名 | 类型 | 必填 | 说明 | 1772| -------- | ---------------------------------------- | ---- | -------------------------------------- | 1773| type | string | 是 | 填写"characteristicWrite"字符串，表示特征值写请求事件。 | 1774| callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | 是 | 表示回调函数的入参，client端发送的写请求数据。 | 1775 1776**错误码**： 1777 1778以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1779 1780| 错误码ID | 错误信息 | 1781| -------- | ---------------------------- | 1782|201 | Permission denied. | 1783|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1784|801 | Capability not supported. | 1785 1786**示例：** 1787 1788```js 1789import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1790let arrayBufferCCC = new ArrayBuffer(8); 1791let cccValue = new Uint8Array(arrayBufferCCC); 1792let gattServer: ble.GattServer = ble.createGattServer(); 1793function WriteCharacteristicReq(characteristicWriteRequest: ble.CharacteristicWriteRequest) { 1794 let deviceId: string = characteristicWriteRequest.deviceId; 1795 let transId: number = characteristicWriteRequest.transId; 1796 let offset: number = characteristicWriteRequest.offset; 1797 let isPrepared: boolean = characteristicWriteRequest.isPrepared; 1798 let needRsp: boolean = characteristicWriteRequest.needRsp; 1799 let value: Uint8Array = new Uint8Array(characteristicWriteRequest.value); 1800 let characteristicUuid: string = characteristicWriteRequest.characteristicUuid; 1801 1802 cccValue[0] = value[0]; 1803 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; 1804 1805 try { 1806 gattServer.sendResponse(serverResponse); 1807 } catch (err) { 1808 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1809 } 1810} 1811gattServer.on('characteristicWrite', WriteCharacteristicReq); 1812``` 1813 1814 1815### off('characteristicWrite') 1816 1817off(type: 'characteristicWrite', callback?: Callback<CharacteristicWriteRequest>): void 1818 1819server端取消订阅特征值写请求事件。 1820 1821**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1822 1823**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1824 1825**系统能力**：SystemCapability.Communication.Bluetooth.Core 1826 1827**参数：** 1828 1829| 参数名 | 类型 | 必填 | 说明 | 1830| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1831| type | string | 是 | 填写"characteristicWrite"字符串，表示特征值写请求事件。 | 1832| callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | 否 | 表示取消订阅特征值写请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1833 1834**错误码**： 1835 1836以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1837 1838| 错误码ID | 错误信息 | 1839| -------- | ---------------------------- | 1840|201 | Permission denied. | 1841|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1842|801 | Capability not supported. | 1843 1844**示例：** 1845 1846```js 1847import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1848try { 1849 let gattServer: ble.GattServer = ble.createGattServer(); 1850 gattServer.off('characteristicWrite'); 1851} catch (err) { 1852 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1853} 1854``` 1855 1856 1857### on('descriptorRead') 1858 1859on(type: 'descriptorRead', callback: Callback<DescriptorReadRequest>): void 1860 1861server端订阅描述符读请求事件。使用Callback异步回调。 1862 1863**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1864 1865**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1866 1867**系统能力**：SystemCapability.Communication.Bluetooth.Core 1868 1869**参数：** 1870 1871| 参数名 | 类型 | 必填 | 说明 | 1872| -------- | ---------------------------------------- | ---- | --------------------------------- | 1873| type | string | 是 | 填写"descriptorRead"字符串，表示描述符读请求事件。 | 1874| callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | 是 | 表示回调函数的入参，client端发送的读请求数据。 | 1875 1876**错误码**： 1877 1878以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1879 1880| 错误码ID | 错误信息 | 1881| -------- | ---------------------------- | 1882|201 | Permission denied. | 1883|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1884|801 | Capability not supported. | 1885 1886**示例：** 1887 1888```js 1889import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1890let arrayBufferDesc = new ArrayBuffer(8); 1891let descValue = new Uint8Array(arrayBufferDesc); 1892descValue[0] = 1101; 1893let gattServer: ble.GattServer = ble.createGattServer(); 1894function ReadDescriptorReq(descriptorReadRequest: ble.DescriptorReadRequest) { 1895 let deviceId: string = descriptorReadRequest.deviceId; 1896 let transId: number = descriptorReadRequest.transId; 1897 let offset: number = descriptorReadRequest.offset; 1898 let descriptorUuid: string = descriptorReadRequest.descriptorUuid; 1899 1900 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; 1901 1902 try { 1903 gattServer.sendResponse(serverResponse); 1904 } catch (err) { 1905 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1906 } 1907} 1908gattServer.on('descriptorRead', ReadDescriptorReq); 1909``` 1910 1911 1912### off('descriptorRead') 1913 1914off(type: 'descriptorRead', callback?: Callback<DescriptorReadRequest>): void 1915 1916server端取消订阅描述符读请求事件。 1917 1918**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1919 1920**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1921 1922**系统能力**：SystemCapability.Communication.Bluetooth.Core 1923 1924**参数：** 1925 1926| 参数名 | 类型 | 必填 | 说明 | 1927| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1928| type | string | 是 | 填写"descriptorRead"字符串，表示描述符读请求事件。 | 1929| callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | 否 | 表示取消订阅描述符读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1930 1931**错误码**： 1932 1933以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1934 1935| 错误码ID | 错误信息 | 1936| -------- | ---------------------------- | 1937|201 | Permission denied. | 1938|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1939|801 | Capability not supported. | 1940 1941**示例：** 1942 1943```js 1944import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1945try { 1946 let gattServer: ble.GattServer = ble.createGattServer(); 1947 gattServer.off('descriptorRead'); 1948} catch (err) { 1949 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1950} 1951``` 1952 1953 1954### on('descriptorWrite') 1955 1956on(type: 'descriptorWrite', callback: Callback<DescriptorWriteRequest>): void 1957 1958server端订阅描述符写请求事件。使用Callback异步回调。 1959 1960**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1961 1962**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1963 1964**系统能力**：SystemCapability.Communication.Bluetooth.Core 1965 1966**参数：** 1967 1968| 参数名 | 类型 | 必填 | 说明 | 1969| -------- | ---------------------------------------- | ---- | ---------------------------------- | 1970| type | string | 是 | 填写"descriptorWrite"字符串，表示描述符写请求事件。 | 1971| callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | 是 | 表示回调函数的入参，client端发送的写请求数据。 | 1972 1973**错误码**： 1974 1975以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1976 1977| 错误码ID | 错误信息 | 1978| -------- | ---------------------------- | 1979|201 | Permission denied. | 1980|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1981|801 | Capability not supported. | 1982 1983**示例：** 1984 1985```js 1986import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1987let arrayBufferDesc = new ArrayBuffer(8); 1988let descValue = new Uint8Array(arrayBufferDesc); 1989let gattServer: ble.GattServer = ble.createGattServer(); 1990function WriteDescriptorReq(descriptorWriteRequest: ble.DescriptorWriteRequest) { 1991 let deviceId: string = descriptorWriteRequest.deviceId; 1992 let transId: number = descriptorWriteRequest.transId; 1993 let offset: number = descriptorWriteRequest.offset; 1994 let isPrepared: boolean = descriptorWriteRequest.isPrepared; 1995 let needRsp: boolean = descriptorWriteRequest.needRsp; 1996 let value: Uint8Array = new Uint8Array(descriptorWriteRequest.value); 1997 let descriptorUuid: string = descriptorWriteRequest.descriptorUuid; 1998 1999 descValue[0] = value[0]; 2000 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; 2001 2002 try { 2003 gattServer.sendResponse(serverResponse); 2004 } catch (err) { 2005 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2006 } 2007} 2008gattServer.on('descriptorWrite', WriteDescriptorReq); 2009``` 2010 2011 2012### off('descriptorWrite') 2013 2014off(type: 'descriptorWrite', callback?: Callback<DescriptorWriteRequest>): void 2015 2016server端取消订阅描述符写请求事件。 2017 2018**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2019 2020**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2021 2022**系统能力**：SystemCapability.Communication.Bluetooth.Core 2023 2024**参数：** 2025 2026| 参数名 | 类型 | 必填 | 说明 | 2027| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2028| type | string | 是 | 填写"descriptorWrite"字符串，表示描述符写请求事件。 | 2029| callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | 否 | 表示取消订阅描述符写请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 2030 2031**错误码**： 2032 2033以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2034 2035| 错误码ID | 错误信息 | 2036| -------- | ---------------------------- | 2037|201 | Permission denied. | 2038|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2039|801 | Capability not supported. | 2040 2041**示例：** 2042 2043```js 2044import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2045try { 2046let gattServer: ble.GattServer = ble.createGattServer(); 2047gattServer.off('descriptorWrite'); 2048} catch (err) { 2049 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 2050} 2051``` 2052 2053 2054### on('connectionStateChange') 2055 2056on(type: 'connectionStateChange', callback: Callback<BLEConnectionChangeState>): void 2057 2058server端订阅BLE连接状态变化事件。使用Callback异步回调。 2059 2060**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2061 2062**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2063 2064**系统能力**：SystemCapability.Communication.Bluetooth.Core 2065 2066**参数：** 2067 2068| 参数名 | 类型 | 必填 | 说明 | 2069| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2070| type | string | 是 | 填写"connectionStateChange"字符串，表示BLE连接状态变化事件。 | 2071| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 是 | 表示回调函数的入参，连接状态。 | 2072 2073**错误码**： 2074 2075以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2076 2077| 错误码ID | 错误信息 | 2078| -------- | ---------------------------- | 2079|201 | Permission denied. | 2080|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2081|801 | Capability not supported. | 2082 2083**示例：** 2084 2085```js 2086import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2087import { constant } from '@kit.ConnectivityKit'; 2088let Connected = (bleConnectionChangeState: ble.BLEConnectionChangeState) => { 2089 let deviceId: string = bleConnectionChangeState.deviceId; 2090 let status: constant.ProfileConnectionState = bleConnectionChangeState.state; 2091} 2092try { 2093 let gattServer: ble.GattServer = ble.createGattServer(); 2094 gattServer.on('connectionStateChange', Connected); 2095} catch (err) { 2096 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 2097} 2098``` 2099 2100 2101### off('connectionStateChange') 2102 2103off(type: 'connectionStateChange', callback?: Callback<BLEConnectionChangeState>): void 2104 2105server端取消订阅BLE连接状态变化事件。 2106 2107**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2108 2109**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2110 2111**系统能力**：SystemCapability.Communication.Bluetooth.Core 2112 2113**参数：** 2114 2115| 参数名 | 类型 | 必填 | 说明 | 2116| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2117| type | string | 是 | 填写"connectionStateChange"字符串，表示BLE连接状态变化事件。 | 2118| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 否 | 表示取消订阅BLE连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。 | 2119 2120**错误码**： 2121 2122以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2123 2124| 错误码ID | 错误信息 | 2125| -------- | ---------------------------- | 2126|201 | Permission denied. | 2127|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2128|801 | Capability not supported. | 2129 2130**示例：** 2131 2132```js 2133import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2134try { 2135 let gattServer: ble.GattServer = ble.createGattServer(); 2136 gattServer.off('connectionStateChange'); 2137} catch (err) { 2138 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 2139} 2140``` 2141 2142 2143### on('BLEMtuChange') 2144 2145on(type: 'BLEMtuChange', callback: Callback<number>): void 2146 2147server端订阅MTU状态变化事件。使用Callback异步回调。 2148 2149**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2150 2151**系统能力**：SystemCapability.Communication.Bluetooth.Core 2152 2153**参数：** 2154 2155| 参数名 | 类型 | 必填 | 说明 | 2156| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2157| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 2158| callback | Callback<number> | 是 | 返回MTU字节数的值，通过注册回调函数获取。 | 2159 2160**错误码**： 2161 2162以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2163 2164| 错误码ID | 错误信息 | 2165| -------- | ---------------------------- | 2166|201 | Permission denied. | 2167|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2168|801 | Capability not supported. | 2169 2170**示例：** 2171 2172```js 2173import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2174try { 2175 let gattServer: ble.GattServer = ble.createGattServer(); 2176 gattServer.on('BLEMtuChange', (mtu: number) => { 2177 console.info('BLEMtuChange, mtu: ' + mtu); 2178 }); 2179} catch (err) { 2180 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2181} 2182``` 2183 2184 2185### off('BLEMtuChange') 2186 2187off(type: 'BLEMtuChange', callback?: Callback<number>): void 2188 2189server端取消订阅MTU状态变化事件。 2190 2191**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2192 2193**系统能力**：SystemCapability.Communication.Bluetooth.Core 2194 2195**参数：** 2196 2197| 参数名 | 类型 | 必填 | 说明 | 2198| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2199| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 2200| callback | Callback<number> | 否 | 返回MTU字节数的值，通过注册回调函数获取。不填该参数则取消订阅该type对应的所有回调。 | 2201 2202**错误码**： 2203 2204以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2205 2206| 错误码ID | 错误信息 | 2207| -------- | ---------------------------- | 2208|201 | Permission denied. | 2209|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2210|801 | Capability not supported. | 2211 2212**示例：** 2213 2214```js 2215import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2216try { 2217 let gattServer: ble.GattServer = ble.createGattServer(); 2218 gattServer.off('BLEMtuChange'); 2219} catch (err) { 2220 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2221} 2222``` 2223 2224 2225## GattClientDevice 2226 2227client端类，使用client端方法之前需要创建该类的实例进行操作，通过createGattClientDevice(deviceId: string)方法构造此实例。 2228 2229 2230### connect 2231 2232connect(): void 2233 2234client端发起连接远端蓝牙低功耗设备。 2235 2236**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2237 2238**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2239 2240**系统能力**：SystemCapability.Communication.Bluetooth.Core 2241 2242**错误码**： 2243 2244以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2245 2246| 错误码ID | 错误信息 | 2247| -------- | ---------------------------- | 2248|201 | Permission denied. | 2249|801 | Capability not supported. | 2250|2900001 | Service stopped. | 2251|2900003 | Bluetooth disabled. | 2252|2900099 | Operation failed. | 2253 2254**示例：** 2255 2256```js 2257import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2258try { 2259 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2260 device.connect(); 2261} catch (err) { 2262 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2263} 2264``` 2265 2266 2267### disconnect 2268 2269disconnect(): void 2270 2271client端断开与远端蓝牙低功耗设备的连接。 2272 2273**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2274 2275**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2276 2277**系统能力**：SystemCapability.Communication.Bluetooth.Core 2278 2279**错误码**： 2280 2281以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2282 2283| 错误码ID | 错误信息 | 2284| -------- | ---------------------------- | 2285|201 | Permission denied. | 2286|801 | Capability not supported. | 2287|2900001 | Service stopped. | 2288|2900003 | Bluetooth disabled. | 2289|2900099 | Operation failed. | 2290 2291**示例：** 2292 2293```js 2294import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2295try { 2296 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2297 device.disconnect(); 2298} catch (err) { 2299 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2300} 2301``` 2302 2303 2304### close 2305 2306close(): void 2307 2308关闭客户端功能，注销client在协议栈的注册，调用该接口后[GattClientDevice](#gattclientdevice)实例将不能再使用。 2309 2310**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2311 2312**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2313 2314**系统能力**：SystemCapability.Communication.Bluetooth.Core 2315 2316**错误码**： 2317 2318以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2319 2320| 错误码ID | 错误信息 | 2321| -------- | ---------------------------- | 2322|201 | Permission denied. | 2323|801 | Capability not supported. | 2324|2900001 | Service stopped. | 2325|2900003 | Bluetooth disabled. | 2326|2900099 | Operation failed. | 2327 2328**示例：** 2329 2330```js 2331import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2332try { 2333 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2334 device.close(); 2335} catch (err) { 2336 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2337} 2338``` 2339 2340 2341### getDeviceName 2342 2343getDeviceName(callback: AsyncCallback<string>): void 2344 2345client获取远端蓝牙低功耗设备名。使用Callback异步回调。 2346 2347**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2348 2349**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2350 2351**系统能力**：SystemCapability.Communication.Bluetooth.Core 2352 2353**参数：** 2354 2355| 参数名 | 类型 | 必填 | 说明 | 2356| -------- | --------------------------- | ---- | ------------------------------- | 2357| callback | AsyncCallback<string> | 是 | client获取对端server设备名，通过注册回调函数获取。 | 2358 2359**错误码**： 2360 2361以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2362 2363| 错误码ID | 错误信息 | 2364| -------- | ---------------------------- | 2365|201 | Permission denied. | 2366|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 2367|801 | Capability not supported. | 2368|2900001 | Service stopped. | 2369|2900099 | Operation failed. | 2370 2371**示例：** 2372 2373```js 2374import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2375// callback 2376try { 2377 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 2378 gattClient.connect(); 2379 gattClient.getDeviceName((err: BusinessError, data: string)=> { 2380 console.info('device name err ' + JSON.stringify(err)); 2381 console.info('device name' + JSON.stringify(data)); 2382 }) 2383} catch (err) { 2384 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2385} 2386``` 2387 2388 2389### getDeviceName 2390 2391getDeviceName(): Promise<string> 2392 2393client获取远端蓝牙低功耗设备名。使用Promise异步回调。 2394 2395**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2396 2397**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2398 2399**系统能力**：SystemCapability.Communication.Bluetooth.Core 2400 2401**返回值：** 2402 2403| 类型 | 说明 | 2404| --------------------- | ---------------------------------- | 2405| Promise<string> | client获取对端server设备名，通过promise形式获取。 | 2406 2407**错误码**： 2408 2409以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2410 2411| 错误码ID | 错误信息 | 2412| -------- | ---------------------------- | 2413|201 | Permission denied. | 2414|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 2415|801 | Capability not supported. | 2416|2900001 | Service stopped. | 2417|2900099 | Operation failed. | 2418 2419**示例：** 2420 2421```js 2422import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2423// promise 2424try { 2425 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 2426 gattClient.connect(); 2427 gattClient.getDeviceName().then((data: string) => { 2428 console.info('device name' + JSON.stringify(data)); 2429 }) 2430} catch (err) { 2431 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2432} 2433``` 2434 2435 2436### getServices 2437 2438getServices(callback: AsyncCallback<Array<GattService>>): void 2439 2440client端获取蓝牙低功耗设备的所有服务，即服务发现。使用Callback异步回调。 2441 2442**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2443 2444**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2445 2446**系统能力**：SystemCapability.Communication.Bluetooth.Core 2447 2448**参数：** 2449 2450| 参数名 | 类型 | 必填 | 说明 | 2451| -------- | ---------------------------------------- | ---- | ------------------------ | 2452| callback | AsyncCallback<Array<[GattService](#gattservice)>> | 是 | client进行服务发现，通过注册回调函数获取。 | 2453 2454**错误码**： 2455 2456以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2457 2458| 错误码ID | 错误信息 | 2459| -------- | ---------------------------- | 2460|201 | Permission denied. | 2461|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 2462|801 | Capability not supported. | 2463|2900001 | Service stopped. | 2464|2900099 | Operation failed. | 2465 2466**示例：** 2467 2468```js 2469import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2470// callback 模式。 2471let getServices = (code: BusinessError, gattServices: Array<ble.GattService>) => { 2472 if (code && code.code != 0) { 2473 console.info('bluetooth code is ' + code.code); 2474 return; 2475 } 2476 let services: Array<ble.GattService> = gattServices; 2477 console.info('bluetooth services size is ', services.length); 2478 for (let i = 0; i < services.length; i++) { 2479 console.info('bluetooth serviceUuid is ' + services[i].serviceUuid); 2480 } 2481} 2482 2483try { 2484 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2485 device.connect(); 2486 device.getServices(getServices); 2487} catch (err) { 2488 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2489} 2490``` 2491 2492 2493### getServices 2494 2495getServices(): Promise<Array<GattService>> 2496 2497client端获取蓝牙低功耗设备的所有服务，即服务发现。使用Promise异步回调。 2498 2499**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2500 2501**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2502 2503**系统能力**：SystemCapability.Communication.Bluetooth.Core 2504 2505**返回值：** 2506 2507| 类型 | 说明 | 2508| ---------------------------------------- | --------------------------- | 2509| Promise<Array<[GattService](#gattservice)>> | client进行服务发现，通过promise形式获取。 | 2510 2511**错误码**： 2512 2513以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2514 2515| 错误码ID | 错误信息 | 2516| -------- | ---------------------------- | 2517|201 | Permission denied. | 2518|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2519|801 | Capability not supported. | 2520|2900001 | Service stopped. | 2521|2900099 | Operation failed. | 2522 2523**示例：** 2524 2525```js 2526import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2527// Promise 模式。 2528try { 2529 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2530 device.connect(); 2531 device.getServices().then((result: Array<ble.GattService>) => { 2532 console.info('getServices successfully:' + JSON.stringify(result)); 2533 }); 2534} catch (err) { 2535 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2536} 2537``` 2538 2539 2540### readCharacteristicValue 2541 2542readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void 2543 2544client端读取蓝牙低功耗设备特定服务的特征值。使用Callback异步回调。 2545 2546**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2547 2548**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2549 2550**系统能力**：SystemCapability.Communication.Bluetooth.Core 2551 2552**参数：** 2553 2554| 参数名 | 类型 | 必填 | 说明 | 2555| -------------- | ---------------------------------------- | ---- | ----------------------- | 2556| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 待读取的特征值。 | 2557| callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | 是 | client读取特征值，通过注册回调函数获取。 | 2558 2559**错误码**： 2560 2561以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2562 2563| 错误码ID | 错误信息 | 2564| -------- | ---------------------------- | 2565|201 | Permission denied. | 2566|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2567|801 | Capability not supported. | 2568|2900001 | Service stopped. | 2569|2901000 | Read forbidden. | 2570|2900099 | Operation failed. | 2571 2572**示例：** 2573 2574```js 2575import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2576function readCcc(code: BusinessError, BLECharacteristic: ble.BLECharacteristic) { 2577 if (code.code != 0) { 2578 return; 2579 } 2580 console.info('bluetooth characteristic uuid: ' + BLECharacteristic.characteristicUuid); 2581 let value = new Uint8Array(BLECharacteristic.characteristicValue); 2582 console.info('bluetooth characteristic value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); 2583} 2584 2585let descriptors: Array<ble.BLEDescriptor> = []; 2586let bufferDesc = new ArrayBuffer(8); 2587let descV = new Uint8Array(bufferDesc); 2588descV[0] = 11; 2589let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2590characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2591descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2592descriptors[0] = descriptor; 2593 2594let bufferCCC = new ArrayBuffer(8); 2595let cccV = new Uint8Array(bufferCCC); 2596cccV[0] = 1; 2597let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2598characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2599characteristicValue: bufferCCC, descriptors:descriptors}; 2600 2601try { 2602 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2603 device.readCharacteristicValue(characteristic, readCcc); 2604} catch (err) { 2605 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2606} 2607``` 2608 2609 2610### readCharacteristicValue 2611 2612readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic> 2613 2614client端读取蓝牙低功耗设备特定服务的特征值。使用Promise异步回调。 2615 2616**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2617 2618**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2619 2620**系统能力**：SystemCapability.Communication.Bluetooth.Core 2621 2622**参数：** 2623 2624| 参数名 | 类型 | 必填 | 说明 | 2625| -------------- | --------------------------------------- | ---- | -------- | 2626| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 待读取的特征值。 | 2627 2628**返回值：** 2629 2630| 类型 | 说明 | 2631| ---------------------------------------- | -------------------------- | 2632| Promise<[BLECharacteristic](#blecharacteristic)> | client读取特征值，通过promise形式获取。 | 2633 2634**错误码**： 2635 2636以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2637 2638| 错误码ID | 错误信息 | 2639| -------- | ---------------------------- | 2640|201 | Permission denied. | 2641|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2642|801 | Capability not supported. | 2643|2900001 | Service stopped. | 2644|2901000 | Read forbidden. | 2645|2900099 | Operation failed. | 2646 2647**示例：** 2648 2649```js 2650import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2651let descriptors: Array<ble.BLEDescriptor> = []; 2652let bufferDesc = new ArrayBuffer(8); 2653let descV = new Uint8Array(bufferDesc); 2654descV[0] = 11; 2655let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2656characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2657descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2658descriptors[0] = descriptor; 2659 2660let bufferCCC = new ArrayBuffer(8); 2661let cccV = new Uint8Array(bufferCCC); 2662cccV[0] = 1; 2663let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2664characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2665characteristicValue: bufferCCC, descriptors:descriptors}; 2666 2667try { 2668 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2669 device.readCharacteristicValue(characteristic); 2670} catch (err) { 2671 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2672} 2673``` 2674 2675 2676### readDescriptorValue 2677 2678readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void 2679 2680client端读取蓝牙低功耗设备特定的特征包含的描述符。使用Callback异步回调。 2681 2682**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2683 2684**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2685 2686**系统能力**：SystemCapability.Communication.Bluetooth.Core 2687 2688**参数：** 2689 2690| 参数名 | 类型 | 必填 | 说明 | 2691| ---------- | ---------------------------------------- | ---- | ----------------------- | 2692| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 待读取的描述符。 | 2693| callback | AsyncCallback<[BLEDescriptor](#bledescriptor)> | 是 | client读取描述符，通过注册回调函数获取。 | 2694 2695**错误码**： 2696 2697以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2698 2699| 错误码ID | 错误信息 | 2700| -------- | ---------------------------- | 2701|201 | Permission denied. | 2702|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2703|801 | Capability not supported. | 2704|2900001 | Service stopped. | 2705|2901000 | Read forbidden. | 2706|2900099 | Operation failed. | 2707 2708**示例：** 2709 2710```js 2711import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2712function readDesc(code: BusinessError, BLEDescriptor: ble.BLEDescriptor) { 2713 if (code.code != 0) { 2714 return; 2715 } 2716 console.info('bluetooth descriptor uuid: ' + BLEDescriptor.descriptorUuid); 2717 let value = new Uint8Array(BLEDescriptor.descriptorValue); 2718 console.info('bluetooth descriptor value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); 2719} 2720 2721let bufferDesc = new ArrayBuffer(8); 2722let descV = new Uint8Array(bufferDesc); 2723descV[0] = 11; 2724let descriptor: ble.BLEDescriptor = { 2725 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2726 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2727 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2728 descriptorValue: bufferDesc 2729}; 2730try { 2731 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2732 device.readDescriptorValue(descriptor, readDesc); 2733} catch (err) { 2734 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2735} 2736``` 2737 2738 2739### readDescriptorValue 2740 2741readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor> 2742 2743client端读取蓝牙低功耗设备特定的特征包含的描述符。使用Promise异步回调。 2744 2745**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2746 2747**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2748 2749**系统能力**：SystemCapability.Communication.Bluetooth.Core 2750 2751**参数：** 2752 2753| 参数名 | 类型 | 必填 | 说明 | 2754| ---------- | ------------------------------- | ---- | -------- | 2755| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 待读取的描述符。 | 2756 2757**返回值：** 2758 2759| 类型 | 说明 | 2760| ---------------------------------------- | -------------------------- | 2761| Promise<[BLEDescriptor](#bledescriptor)> | client读取描述符，通过promise形式获取。 | 2762 2763**错误码**： 2764 2765以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2766 2767| 错误码ID | 错误信息 | 2768| -------- | ---------------------------- | 2769|201 | Permission denied. | 2770|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2771|801 | Capability not supported. | 2772|2900001 | Service stopped. | 2773|2901000 | Read forbidden. | 2774|2900099 | Operation failed. | 2775 2776**示例：** 2777 2778```js 2779import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2780let bufferDesc = new ArrayBuffer(8); 2781let descV = new Uint8Array(bufferDesc); 2782descV[0] = 11; 2783let descriptor: ble.BLEDescriptor = { 2784 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2785 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2786 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2787 descriptorValue: bufferDesc 2788}; 2789try { 2790 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2791 device.readDescriptorValue(descriptor); 2792} catch (err) { 2793 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2794} 2795``` 2796 2797 2798### writeCharacteristicValue 2799 2800writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<void>): void 2801 2802client端向低功耗蓝牙设备写入特定的特征值。使用Callback异步回调。 2803 2804**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2805 2806**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2807 2808**系统能力**：SystemCapability.Communication.Bluetooth.Core 2809 2810**参数：** 2811 2812| 参数名 | 类型 | 必填 | 说明 | 2813| -------------- | --------------------------------------- | ---- | ------------------- | 2814| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙设备特征对应的二进制值及其它参数。 | 2815| writeType | [GattWriteType](#gattwritetype) | 是 | 蓝牙设备特征的写入类型。 | 2816| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | 2817 2818**错误码**： 2819 2820以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2821 2822| 错误码ID | 错误信息 | 2823| -------- | ---------------------------- | 2824|201 | Permission denied. | 2825|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2826|801 | Capability not supported. | 2827|2900001 | Service stopped. | 2828|2901001 | Write forbidden. | 2829|2900099 | Operation failed. | 2830 2831**示例：** 2832 2833```js 2834import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2835let descriptors: Array<ble.BLEDescriptor> = []; 2836let bufferDesc = new ArrayBuffer(8); 2837let descV = new Uint8Array(bufferDesc); 2838descV[0] = 11; 2839let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2840 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2841 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2842descriptors[0] = descriptor; 2843 2844let bufferCCC = new ArrayBuffer(8); 2845let cccV = new Uint8Array(bufferCCC); 2846cccV[0] = 1; 2847let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2848 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2849 characteristicValue: bufferCCC, descriptors:descriptors}; 2850function writeCharacteristicValueCallBack(code: BusinessError) { 2851 if (code != null) { 2852 return; 2853 } 2854 console.info('bluetooth writeCharacteristicValue success'); 2855} 2856try { 2857 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2858 device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE, writeCharacteristicValueCallBack); 2859} catch (err) { 2860 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2861} 2862``` 2863 2864 2865### writeCharacteristicValue 2866 2867writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<void> 2868 2869client端向低功耗蓝牙设备写入特定的特征值。使用Promise异步回调。 2870 2871**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2872 2873**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2874 2875**系统能力**：SystemCapability.Communication.Bluetooth.Core 2876 2877**参数：** 2878 2879| 参数名 | 类型 | 必填 | 说明 | 2880| -------------- | --------------------------------------- | ---- | ------------------- | 2881| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙设备特征对应的二进制值及其它参数。 | 2882| writeType | [GattWriteType](#gattwritetype) | 是 | 蓝牙设备特征的写入类型。 | 2883 2884**返回值：** 2885 2886| 类型 | 说明 | 2887| ---------------------------------------- | -------------------------- | 2888| Promise<void> | client读取描述符，通过promise形式获取。 | 2889 2890**错误码**： 2891 2892以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2893 2894| 错误码ID | 错误信息 | 2895| -------- | ---------------------------- | 2896|201 | Permission denied. | 2897|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2898|801 | Capability not supported. | 2899|2900001 | Service stopped. | 2900|2901001 | Write forbidden. | 2901|2900099 | Operation failed. | 2902 2903**示例：** 2904 2905```js 2906import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2907let descriptors: Array<ble.BLEDescriptor> = []; 2908let bufferDesc = new ArrayBuffer(8); 2909let descV = new Uint8Array(bufferDesc); 2910descV[0] = 11; 2911let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2912 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2913 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2914descriptors[0] = descriptor; 2915 2916let bufferCCC = new ArrayBuffer(8); 2917let cccV = new Uint8Array(bufferCCC); 2918cccV[0] = 1; 2919let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2920 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2921 characteristicValue: bufferCCC, descriptors:descriptors}; 2922try { 2923 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2924 device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE); 2925} catch (err) { 2926 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2927} 2928``` 2929 2930 2931### writeDescriptorValue 2932 2933writeDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<void>): void 2934 2935client端向低功耗蓝牙设备特定的描述符写入二进制数据。使用Callback异步回调。 2936 2937**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2938 2939**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2940 2941**系统能力**：SystemCapability.Communication.Bluetooth.Core 2942 2943**参数：** 2944 2945| 参数名 | 类型 | 必填 | 说明 | 2946| ---------- | ------------------------------- | ---- | ------------------ | 2947| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 蓝牙设备描述符的二进制值及其它参数。 | 2948| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | 2949 2950**错误码**： 2951 2952以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2953 2954| 错误码ID | 错误信息 | 2955| -------- | ---------------------------- | 2956|201 | Permission denied. | 2957|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2958|801 | Capability not supported. | 2959|2900001 | Service stopped. | 2960|2901001 | Write forbidden. | 2961|2900099 | Operation failed. | 2962 2963**示例：** 2964 2965```js 2966import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2967let bufferDesc = new ArrayBuffer(8); 2968let descV = new Uint8Array(bufferDesc); 2969descV[0] = 22; 2970let descriptor: ble.BLEDescriptor = { 2971 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2972 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2973 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2974 descriptorValue: bufferDesc 2975}; 2976try { 2977 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2978 device.writeDescriptorValue(descriptor, (err: BusinessError) => { 2979 if (err) { 2980 console.info('notifyCharacteristicChanged callback failed'); 2981 } else { 2982 console.info('notifyCharacteristicChanged callback successful'); 2983 } 2984 }); 2985} catch (err) { 2986 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2987} 2988``` 2989 2990 2991### writeDescriptorValue 2992 2993writeDescriptorValue(descriptor: BLEDescriptor): Promise<void> 2994 2995client端向低功耗蓝牙设备特定的描述符写入二进制数据。使用Promise异步回调。 2996 2997**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2998 2999**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3000 3001**系统能力**：SystemCapability.Communication.Bluetooth.Core 3002 3003**参数：** 3004 3005| 参数名 | 类型 | 必填 | 说明 | 3006| ---------- | ------------------------------- | ---- | ------------------ | 3007| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 蓝牙设备描述符的二进制值及其它参数。 | 3008 3009**返回值：** 3010 3011| 类型 | 说明 | 3012| ---------------------------------------- | -------------------------- | 3013| Promise<void> | client读取描述符，通过promise形式获取。 | 3014 3015**错误码**： 3016 3017以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3018 3019| 错误码ID | 错误信息 | 3020| -------- | ---------------------------- | 3021|201 | Permission denied. | 3022|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3023|801 | Capability not supported. | 3024|2900001 | Service stopped. | 3025|2901001 | Write forbidden. | 3026|2900099 | Operation failed. | 3027 3028**示例：** 3029 3030```js 3031import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3032let bufferDesc = new ArrayBuffer(8); 3033let descV = new Uint8Array(bufferDesc); 3034descV[0] = 22; 3035let descriptor: ble.BLEDescriptor = { 3036 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3037 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3038 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 3039 descriptorValue: bufferDesc 3040}; 3041try { 3042 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3043 device.writeDescriptorValue(descriptor).then(() => { 3044 console.info('writeDescriptorValue promise success'); 3045 }); 3046} catch (err) { 3047 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3048} 3049``` 3050 3051 3052### getRssiValue 3053 3054getRssiValue(callback: AsyncCallback<number>): void 3055 3056client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。使用Callback异步回调。 3057 3058**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3059 3060**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3061 3062**系统能力**：SystemCapability.Communication.Bluetooth.Core 3063 3064**参数：** 3065 3066| 参数名 | 类型 | 必填 | 说明 | 3067| -------- | --------------------------- | ---- | ------------------------------ | 3068| callback | AsyncCallback<number> | 是 | 返回信号强度。单位 dBm，通过注册回调函数获取。 | 3069 3070**错误码**： 3071 3072以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3073 3074| 错误码ID | 错误信息 | 3075| -------- | ---------------------------- | 3076|201 | Permission denied. | 3077|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3078|801 | Capability not supported. | 3079|2900099 | Operation failed. | 3080 3081**示例：** 3082 3083```js 3084import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3085// callback 3086try { 3087 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 3088 gattClient.connect(); 3089 let rssi = gattClient.getRssiValue((err: BusinessError, data: number)=> { 3090 console.info('rssi err ' + JSON.stringify(err)); 3091 console.info('rssi value' + JSON.stringify(data)); 3092 }) 3093} catch (err) { 3094 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3095} 3096``` 3097 3098 3099### getRssiValue 3100 3101getRssiValue(): Promise<number> 3102 3103client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。使用Promise异步回调。 3104 3105**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3106 3107**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3108 3109**系统能力**：SystemCapability.Communication.Bluetooth.Core 3110 3111**返回值：** 3112 3113| 类型 | 说明 | 3114| --------------------- | --------------------------------- | 3115| Promise<number> | 返回信号强度。单位 dBm，通过promise形式获取。 | 3116 3117**错误码**： 3118 3119以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3120 3121| 错误码ID | 错误信息 | 3122| -------- | ---------------------------- | 3123|201 | Permission denied. | 3124|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 3125|801 | Capability not supported. | 3126|2900099 | Operation failed. | 3127 3128**示例：** 3129 3130```js 3131import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3132// promise 3133try { 3134 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 3135 gattClient.getRssiValue().then((data: number) => { 3136 console.info('rssi' + JSON.stringify(data)); 3137 }) 3138} catch (err) { 3139 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3140} 3141``` 3142 3143 3144### setBLEMtuSize 3145 3146setBLEMtuSize(mtu: number): void 3147 3148client协商远端蓝牙低功耗设备的最大传输单元(Maximum Transmission Unit, MTU)，调用[connect](#connect)接口连接成功后才能使用。 3149 3150**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3151 3152**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3153 3154**系统能力**：SystemCapability.Communication.Bluetooth.Core 3155 3156**参数：** 3157 3158| 参数名 | 类型 | 必填 | 说明 | 3159| ---- | ------ | ---- | -------------- | 3160| mtu | number | 是 | 设置范围为22~512字节。 | 3161 3162**错误码**： 3163 3164以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3165 3166| 错误码ID | 错误信息 | 3167| -------- | ---------------------------- | 3168|201 | Permission denied. | 3169|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3170|801 | Capability not supported. | 3171|2900001 | Service stopped. | 3172|2900099 | Operation failed. | 3173 3174**示例：** 3175 3176```js 3177import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3178try { 3179 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3180 device.setBLEMtuSize(128); 3181} catch (err) { 3182 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3183} 3184``` 3185 3186 3187### setCharacteristicChangeNotification 3188 3189setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void 3190 3191向服务端发送设置通知此特征值请求。使用Callback异步回调。 3192 3193**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3194 3195**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3196 3197**系统能力**：SystemCapability.Communication.Bluetooth.Core 3198 3199**参数：** 3200 3201| 参数名 | 类型 | 必填 | 说明 | 3202| -------------- | --------------------------------------- | ---- | ----------------------------- | 3203| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 3204| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 3205| callback | AsyncCallback<void> | 是 | 回调函数。当发送成功，err为undefined，否则为错误对象。 | 3206 3207**错误码**： 3208 3209以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3210 3211| 错误码ID | 错误信息 | 3212| -------- | ---------------------------- | 3213|201 | Permission denied. | 3214|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3215|801 | Capability not supported. | 3216|2900001 | Service stopped. | 3217|2900099 | Operation failed. | 3218 3219**示例：** 3220 3221```js 3222import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3223// 创建descriptors。 3224let descriptors: Array<ble.BLEDescriptor> = []; 3225let arrayBuffer = new ArrayBuffer(8); 3226let descV = new Uint8Array(arrayBuffer); 3227descV[0] = 11; 3228let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3229 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3230 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3231descriptors[0] = descriptor; 3232let arrayBufferC = new ArrayBuffer(8); 3233let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3234 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3235try { 3236 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3237 device.setCharacteristicChangeNotification(characteristic, false, (err: BusinessError) => { 3238 if (err) { 3239 console.info('notifyCharacteristicChanged callback failed'); 3240 } else { 3241 console.info('notifyCharacteristicChanged callback successful'); 3242 } 3243 }); 3244} catch (err) { 3245 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3246} 3247 3248``` 3249 3250 3251### setCharacteristicChangeNotification 3252 3253setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean): Promise<void> 3254 3255向服务端发送设置通知此特征值请求。使用Promise异步回调。 3256 3257**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3258 3259**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3260 3261**系统能力**：SystemCapability.Communication.Bluetooth.Core 3262 3263**参数：** 3264 3265| 参数名 | 类型 | 必填 | 说明 | 3266| -------------- | --------------------------------------- | ---- | ----------------------------- | 3267| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 3268| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 3269 3270**返回值：** 3271 3272| 类型 | 说明 | 3273| ---------------------------------------- | -------------------------- | 3274| Promise<void> | 返回Promise对象。 | 3275 3276**错误码**： 3277 3278以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3279 3280| 错误码ID | 错误信息 | 3281| -------- | ---------------------------- | 3282|201 | Permission denied. | 3283|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3284|801 | Capability not supported. | 3285|2900001 | Service stopped. | 3286|2900099 | Operation failed. | 3287 3288**示例：** 3289 3290```js 3291import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3292// 创建descriptors。 3293let descriptors: Array<ble.BLEDescriptor> = []; 3294let arrayBuffer = new ArrayBuffer(8); 3295let descV = new Uint8Array(arrayBuffer); 3296descV[0] = 11; 3297let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3298 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3299 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3300descriptors[0] = descriptor; 3301let arrayBufferC = new ArrayBuffer(8); 3302let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3303 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3304try { 3305 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3306 device.setCharacteristicChangeNotification(characteristic, false); 3307} catch (err) { 3308 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3309} 3310 3311``` 3312 3313 3314### setCharacteristicChangeIndication 3315 3316setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void 3317 3318向服务端发送设置通知此特征值请求，需要对端设备的回复。使用Callback异步回调。 3319 3320**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3321 3322**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3323 3324**系统能力**：SystemCapability.Communication.Bluetooth.Core 3325 3326**参数：** 3327 3328| 参数名 | 类型 | 必填 | 说明 | 3329| -------------- | --------------------------------------- | ---- | ----------------------------- | 3330| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 3331| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 3332| callback | AsyncCallback<void> | 是 | 回调函数。当发送成功，err为undefined，否则为错误对象。 | 3333 3334**错误码**： 3335 3336以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3337 3338| 错误码ID | 错误信息 | 3339| -------- | ---------------------------- | 3340|201 | Permission denied. | 3341|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3342|801 | Capability not supported. | 3343|2900001 | Service stopped. | 3344|2900099 | Operation failed. | 3345 3346**示例：** 3347 3348```js 3349import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3350// 创建descriptors。 3351let descriptors: Array<ble.BLEDescriptor> = []; 3352let arrayBuffer = new ArrayBuffer(8); 3353let descV = new Uint8Array(arrayBuffer); 3354descV[0] = 11; 3355let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3356 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3357 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3358descriptors[0] = descriptor; 3359let arrayBufferC = new ArrayBuffer(8); 3360let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3361 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3362try { 3363 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3364 device.setCharacteristicChangeIndication(characteristic, false, (err: BusinessError) => { 3365 if (err) { 3366 console.info('notifyCharacteristicChanged callback failed'); 3367 } else { 3368 console.info('notifyCharacteristicChanged callback successful'); 3369 } 3370 }); 3371} catch (err) { 3372 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3373} 3374 3375``` 3376 3377 3378### setCharacteristicChangeIndication 3379 3380setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean): Promise<void> 3381 3382向服务端发送设置通知此特征值请求，需要对端设备的回复。使用Promise异步回调。 3383 3384**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3385 3386**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3387 3388**系统能力**：SystemCapability.Communication.Bluetooth.Core 3389 3390**参数：** 3391 3392| 参数名 | 类型 | 必填 | 说明 | 3393| -------------- | --------------------------------------- | ---- | ----------------------------- | 3394| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 3395| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 3396 3397**返回值：** 3398 3399| 类型 | 说明 | 3400| ---------------------------------------- | -------------------------- | 3401| Promise<void> | 返回Promise对象。 | 3402 3403**错误码**： 3404 3405以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3406 3407| 错误码ID | 错误信息 | 3408| -------- | ---------------------------- | 3409|201 | Permission denied. | 3410|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3411|801 | Capability not supported. | 3412|2900001 | Service stopped. | 3413|2900099 | Operation failed. | 3414 3415**示例：** 3416 3417```js 3418import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3419// 创建descriptors。 3420let descriptors: Array<ble.BLEDescriptor> = []; 3421let arrayBuffer = new ArrayBuffer(8); 3422let descV = new Uint8Array(arrayBuffer); 3423descV[0] = 11; 3424let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3425 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3426 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3427descriptors[0] = descriptor; 3428let arrayBufferC = new ArrayBuffer(8); 3429let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3430 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3431try { 3432 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3433 device.setCharacteristicChangeIndication(characteristic, false); 3434} catch (err) { 3435 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3436} 3437 3438``` 3439 3440 3441### on('BLECharacteristicChange') 3442 3443on(type: 'BLECharacteristicChange', callback: Callback<BLECharacteristic>): void 3444 3445订阅蓝牙低功耗设备的特征值变化事件。需要先调用[setCharacteristicChangeNotification](#setcharacteristicchangenotification)接口或[setCharacteristicChangeIndication](#setcharacteristicchangeindication)接口才能接收server端的通知。使用Callback异步回调。 3446 3447**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3448 3449**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3450 3451**系统能力**：SystemCapability.Communication.Bluetooth.Core 3452 3453**参数：** 3454 3455| 参数名 | 类型 | 必填 | 说明 | 3456| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3457| type | string | 是 | 填写"BLECharacteristicChange"字符串，表示特征值变化事件。 | 3458| callback | Callback<[BLECharacteristic](#blecharacteristic)> | 是 | 表示蓝牙低功耗设备的特征值变化事件的回调函数。 | 3459 3460**错误码**： 3461 3462以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3463 3464| 错误码ID | 错误信息 | 3465| -------- | ---------------------------- | 3466|201 | Permission denied. | 3467|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3468|801 | Capability not supported. | 3469 3470**示例：** 3471 3472```js 3473import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3474function CharacteristicChange(characteristicChangeReq: ble.BLECharacteristic) { 3475 let serviceUuid: string = characteristicChangeReq.serviceUuid; 3476 let characteristicUuid: string = characteristicChangeReq.characteristicUuid; 3477 let value: Uint8Array = new Uint8Array(characteristicChangeReq.characteristicValue); 3478} 3479try { 3480 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3481 device.on('BLECharacteristicChange', CharacteristicChange); 3482} catch (err) { 3483 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3484} 3485``` 3486 3487 3488### off('BLECharacteristicChange') 3489 3490off(type: 'BLECharacteristicChange', callback?: Callback<BLECharacteristic>): void 3491 3492取消订阅蓝牙低功耗设备的特征值变化事件。 3493 3494**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3495 3496**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3497 3498**系统能力**：SystemCapability.Communication.Bluetooth.Core 3499 3500**参数：** 3501 3502| 参数名 | 类型 | 必填 | 说明 | 3503| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3504| type | string | 是 | 填写"BLECharacteristicChange"字符串，表示特征值变化事件。 | 3505| callback | Callback<[BLECharacteristic](#blecharacteristic)> | 否 | 表示取消订阅蓝牙低功耗设备的特征值变化事件。不填该参数则取消订阅该type对应的所有回调。 | 3506 3507**错误码**： 3508 3509以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3510 3511| 错误码ID | 错误信息 | 3512| -------- | ---------------------------- | 3513|201 | Permission denied. | 3514|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3515|801 | Capability not supported. | 3516 3517**示例：** 3518 3519```js 3520import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3521try { 3522 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3523 device.off('BLECharacteristicChange'); 3524} catch (err) { 3525 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3526} 3527``` 3528 3529 3530### on('BLEConnectionStateChange') 3531 3532on(type: 'BLEConnectionStateChange', callback: Callback<BLEConnectionChangeState>): void 3533 3534client端订阅蓝牙低功耗设备的连接状态变化事件。使用Callback异步回调。 3535 3536**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3537 3538**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3539 3540**系统能力**：SystemCapability.Communication.Bluetooth.Core 3541 3542**参数：** 3543 3544| 参数名 | 类型 | 必填 | 说明 | 3545| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3546| type | string | 是 | 填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。 | 3547| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 是 | 表示连接状态，已连接或断开。 | 3548 3549**错误码**： 3550 3551以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3552 3553| 错误码ID | 错误信息 | 3554| -------- | ---------------------------- | 3555|201 | Permission denied. | 3556|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3557|801 | Capability not supported. | 3558 3559**示例：** 3560 3561```js 3562import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3563function ConnectStateChanged(state: ble.BLEConnectionChangeState) { 3564 console.info('bluetooth connect state changed'); 3565 let connectState: ble.ProfileConnectionState = state.state; 3566} 3567try { 3568 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3569 device.on('BLEConnectionStateChange', ConnectStateChanged); 3570} catch (err) { 3571 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3572} 3573``` 3574 3575 3576### off('BLEConnectionStateChange') 3577 3578off(type: 'BLEConnectionStateChange', callback?: Callback<BLEConnectionChangeState>): void 3579 3580取消订阅蓝牙低功耗设备的连接状态变化事件。 3581 3582**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3583 3584**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3585 3586**系统能力**：SystemCapability.Communication.Bluetooth.Core 3587 3588**参数：** 3589 3590| 参数名 | 类型 | 必填 | 说明 | 3591| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3592| type | string | 是 | 填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。 | 3593| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 否 | 表示取消订阅蓝牙低功耗设备的连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。 | 3594 3595**错误码**： 3596 3597以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3598 3599| 错误码ID | 错误信息 | 3600| -------- | ---------------------------- | 3601|201 | Permission denied. | 3602|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3603|801 | Capability not supported. | 3604 3605**示例：** 3606 3607```js 3608import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3609try { 3610 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3611 device.off('BLEConnectionStateChange'); 3612} catch (err) { 3613 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3614} 3615``` 3616 3617 3618### on('BLEMtuChange') 3619 3620on(type: 'BLEMtuChange', callback: Callback<number>): void 3621 3622client端订阅MTU状态变化事件。使用Callback异步回调。 3623 3624**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3625 3626**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3627 3628**系统能力**：SystemCapability.Communication.Bluetooth.Core 3629 3630**参数：** 3631 3632| 参数名 | 类型 | 必填 | 说明 | 3633| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3634| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 3635| callback | Callback<number> | 是 | 返回MTU字节数的值，通过注册回调函数获取。 | 3636 3637**错误码**： 3638 3639以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3640 3641| 错误码ID | 错误信息 | 3642| -------- | ---------------------------- | 3643|201 | Permission denied. | 3644|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3645|801 | Capability not supported. | 3646 3647**示例：** 3648 3649```js 3650import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3651try { 3652 let gattClient: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3653 gattClient.on('BLEMtuChange', (mtu: number) => { 3654 console.info('BLEMtuChange, mtu: ' + mtu); 3655 }); 3656} catch (err) { 3657 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3658} 3659``` 3660 3661 3662### off('BLEMtuChange') 3663 3664off(type: 'BLEMtuChange', callback?: Callback<number>): void 3665 3666client端取消订阅MTU状态变化事件。 3667 3668**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3669 3670**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3671 3672**系统能力**：SystemCapability.Communication.Bluetooth.Core 3673 3674**参数：** 3675 3676| 参数名 | 类型 | 必填 | 说明 | 3677| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3678| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 3679| callback | Callback<number> | 否 | 返回MTU字节数的值，通过注册回调函数获取。不填该参数则取消订阅该type对应的所有回调。 | 3680 3681**错误码**： 3682 3683以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3684 3685| 错误码ID | 错误信息 | 3686| -------- | ---------------------------- | 3687|201 | Permission denied. | 3688|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3689|801 | Capability not supported. | 3690 3691**示例：** 3692 3693```js 3694import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3695try { 3696 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3697 device.off('BLEMtuChange'); 3698} catch (err) { 3699 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3700} 3701``` 3702 3703## ble.createBleScanner<sup>15+</sup> 3704 3705createBleScanner(): BleScanner 3706 3707**原子化服务API**: 从API version 15开始，该接口支持在原子化服务中使用。 3708 3709**系统能力**：SystemCapability.Communication.Bluetooth.Core 3710 3711**返回值：** 3712 3713| 类型 | 说明 | 3714| ------------ | ------------- | 3715| [BleScanner](#blescanner15) | 返回一个BleScanner的实例。 | 3716 3717**示例：** 3718 3719```js 3720import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3721import { ble } from '@kit.ConnectivityKit'; 3722let bleScanner: ble.BleScanner = ble.createBleScanner(); 3723console.info('create bleScanner success'); 3724``` 3725 3726## BleScanner<sup>15+</sup> 3727 3728BLE多路扫描类，使用BleScanner类中的方法之前需要创建该类的实例进行操作，通过createBleScanner()方法构造此实例。 3729 3730### startScan<sup>15+</sup> 3731 3732startScan(filters: Array<ScanFilter>, options?: ScanOptions): Promise<void> 3733 3734发起BLE扫描流程，使用Promise异步回调。 3735 3736**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3737 3738**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 3739 3740**系统能力**：SystemCapability.Communication.Bluetooth.Core 3741 3742**参数：** 3743 3744| 参数名 | 类型 | 必填 | 说明 | 3745| ------- | -------------------------------------- | ---- | ----------------------------------- | 3746| filters | Array<[ScanFilter](#scanfilter)> | 是 | 表示扫描结果过滤策略集合，符合过滤条件的设备会被保留。如果不使用过滤的方式，该参数设置为null。 | 3747| options | [ScanOptions](#scanoptions) | 否 | 表示扫描的可选参数配置。 | 3748 3749**错误码**： 3750 3751以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3752 3753| 错误码ID | 错误信息 | 3754| -------- | ---------------------------- | 3755|201 | Permission denied. | 3756|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3757|801 | Capability not supported. | 3758|2900001 | Service stopped. | 3759|2900003 | Bluetooth disabled. | 3760|2900009 | Fails to start scan as it is out of hardware. | 3761|2900099 | Operation failed. | 3762|2902050 | Failed to start scan as Ble scan is already started by the app.| 3763 3764**示例：** 3765 3766```js 3767import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3768import { ble } from '@kit.ConnectivityKit'; 3769let bleScanner: ble.BleScanner = ble.createBleScanner(); 3770function onReceiveEvent(scanReport: ble.ScanReport) { 3771 console.info('BLE scan device find result = '+ JSON.stringify(scanReport)); 3772} 3773try { 3774 bleScanner.on("BLEDeviceFind", onReceiveEvent); 3775 let scanFilter: ble.ScanFilter = { 3776 deviceId:"XX:XX:XX:XX:XX:XX", 3777 name:"test", 3778 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" 3779 }; 3780 let scanOptions: ble.ScanOptions = { 3781 interval: 500, 3782 dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER, 3783 matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE, 3784 reportMode: ble.ScanReportMode.FENCE_SENSITIVITY_LOW 3785 } 3786 bleScanner.startScan([scanFilter],scanOptions); 3787 console.info('startScan success'); 3788} catch (err) { 3789 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3790} 3791``` 3792 3793### stopScan<sup>15+</sup> 3794 3795stopScan(): Promise<void> 3796 3797停止BLE扫描流程。 3798 3799**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3800 3801**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 3802 3803**系统能力**：SystemCapability.Communication.Bluetooth.Core 3804 3805**错误码**： 3806 3807以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3808 3809| 错误码ID | 错误信息 | 3810| -------- | ---------------------------- | 3811|201 | Permission denied. | 3812|801 | Capability not supported. | 3813|2900001 | Service stopped. | 3814|2900003 | Bluetooth disabled. | 3815|2900099 | Operation failed. | 3816 3817**示例：** 3818 3819```js 3820import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3821import { ble } from '@kit.ConnectivityKit'; 3822let bleScanner: ble.BleScanner = ble.createBleScanner(); 3823try { 3824 bleScanner.stopScan(); 3825 console.info('startScan success'); 3826} catch (err) { 3827 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3828} 3829``` 3830 3831### on('BLEDeviceFind')<sup>15+</sup> 3832 3833on(type: 'BLEDeviceFind', callback: Callback<ScanReport>): void 3834 3835订阅BLE设备发现上报事件。使用Callback异步回调。 3836 3837**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3838 3839**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 3840 3841**系统能力**：SystemCapability.Communication.Bluetooth.Core 3842 3843**参数：** 3844 3845| 参数名 | 类型 | 必填 | 说明 | 3846| -------- | ---------------------------------------- | ---- | ----------------------------------- | 3847| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 3848| callback | Callback<[ScanReport](#scanreport15)> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | 3849 3850**错误码**： 3851 3852以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3853 3854| 错误码ID | 错误信息 | 3855| -------- | ---------------------------- | 3856|201 | Permission denied. | 3857|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3858|801 | Capability not supported. | 3859|2900099 | Operation failed. | 3860 3861**示例：** 3862 3863```js 3864import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3865import { ble } from '@kit.ConnectivityKit'; 3866function onReceiveEvent(scanReport: ble.ScanReport) { 3867 console.info('bluetooth device find = '+ JSON.stringify(scanReport)); 3868} 3869let bleScanner: ble.BleScanner = ble.createBleScanner(); 3870try { 3871 bleScanner.on('BLEDeviceFind', onReceiveEvent); 3872} catch (err) { 3873 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3874} 3875``` 3876 3877### off('BLEDeviceFind')<sup>15+</sup> 3878 3879off(type: 'BLEDeviceFind', callback?: Callback<ScanReport>): void 3880 3881取消订阅BLE设备发现上报事件。 3882 3883**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3884 3885**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 3886 3887**系统能力**：SystemCapability.Communication.Bluetooth.Core 3888 3889**参数：** 3890 3891| 参数名 | 类型 | 必填 | 说明 | 3892| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3893| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 3894| callback | Callback<[ScanReport](#scanreport15)> | 否 | 表示取消订阅BLE设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | 3895 3896**错误码**： 3897 3898以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3899 3900| 错误码ID | 错误信息 | 3901| -------- | ---------------------------- | 3902|201 | Permission denied. | 3903|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3904|801 | Capability not supported. | 3905|2900099 | Operation failed. | 3906 3907**示例：** 3908 3909```js 3910import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3911import { ble } from '@kit.ConnectivityKit'; 3912function onReceiveEvent(scanReport: ble.ScanReport) { 3913 console.info('bluetooth device find = '+ JSON.stringify(scanReport)); 3914} 3915let bleScanner: ble.BleScanner = ble.createBleScanner(); 3916try { 3917 bleScanner.on('BLEDeviceFind', onReceiveEvent); 3918 bleScanner.off('BLEDeviceFind', onReceiveEvent); 3919} catch (err) { 3920 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3921} 3922``` 3923 3924## GattService 3925 3926描述service的接口参数定义。 3927 3928**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3929 3930**系统能力**：SystemCapability.Communication.Bluetooth.Core 3931 3932| 名称 | 类型 | 可读 | 可写 | 说明 | 3933| --------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | 3934| serviceUuid | string | 是 | 是 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 3935| isPrimary | boolean | 是 | 是 | 如果是主服务设置为true，否则设置为false。 | 3936| characteristics | Array<[BLECharacteristic](#blecharacteristic)> | 是 | 是 | 当前服务包含的特征列表。 | 3937| includeServices | Array<[GattService](#gattservice)> | 是 | 是 | 当前服务依赖的其它服务。 | 3938 3939 3940## BLECharacteristic 3941 3942描述characteristic的接口参数定义 。 3943 3944**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3945 3946**系统能力**：SystemCapability.Communication.Bluetooth.Core 3947 3948| 名称 | 类型 | 可读 | 可写 | 说明 | 3949| ------------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | 3950| serviceUuid | string | 是 | 是 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 3951| characteristicUuid | string | 是 | 是 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 3952| characteristicValue | ArrayBuffer | 是 | 是 | 特征对应的二进制值。 | 3953| descriptors | Array<[BLEDescriptor](#bledescriptor)> | 是 | 是 | 特定特征的描述符列表。 | 3954| properties | [GattProperties](#gattproperties) | 是 | 是 | 特定特征的属性描述。 | 3955 3956 3957## BLEDescriptor 3958 3959描述descriptor的接口参数定义。 3960 3961**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3962 3963**系统能力**：SystemCapability.Communication.Bluetooth.Core 3964 3965| 名称 | 类型 | 可读 | 可写 | 说明 | 3966| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | 3967| serviceUuid | string | 是 | 是 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 3968| characteristicUuid | string | 是 | 是 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 3969| descriptorUuid | string | 是 | 是 | 描述符(descriptor)的UUID。例如：00002902-0000-1000-8000-00805f9b34fb。 | 3970| descriptorValue | ArrayBuffer | 是 | 是 | 描述符对应的二进制值。 | 3971 3972 3973## NotifyCharacteristic 3974 3975描述server端特征值变化时发送的特征通知参数定义。 3976 3977**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3978 3979**系统能力**：SystemCapability.Communication.Bluetooth.Core 3980 3981| 名称 | 类型 | 可读 | 可写 | 说明 | 3982| ------------------- | ----------- | ---- | ---- | ---------------------------------------- | 3983| serviceUuid | string | 是 | 是 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 3984| characteristicUuid | string | 是 | 是 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 3985| characteristicValue | ArrayBuffer | 是 | 是 | 特征对应的二进制值。 | 3986| confirm | boolean | 是 | 是 | 如果是indication，对端需要回复确认，则设置为true。<br>如果是notification，对端不需要回复确认，则设置为false。 | 3987 3988 3989## CharacteristicReadRequest 3990 3991描述server端订阅后收到的特征值读请求事件参数结构。 3992 3993**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3994 3995**系统能力**：SystemCapability.Communication.Bluetooth.Core 3996 3997| 名称 | 类型 | 可读 | 可写 | 说明 | 3998| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 3999| deviceId | string | 是 | 否 | 表示发送特征值读请求的远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4000| transId | number | 是 | 否 | 表示读请求的传输ID，server端回复响应时需填写相同的传输ID。 | 4001| offset | number | 是 | 否 | 表示读特征值数据的起始位置。例如：k表示从第k个字节开始读，server端回复响应时需填写相同的offset。 | 4002| characteristicUuid | string | 是 | 否 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 4003| serviceUuid | string | 是 | 否 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4004 4005 4006## CharacteristicWriteRequest 4007 4008描述server端订阅后收到的特征值写请求事件参数结构。 4009 4010**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4011 4012**系统能力**：SystemCapability.Communication.Bluetooth.Core 4013 4014| 名称 | 类型 | 可读 | 可写 | 说明 | 4015| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 4016| deviceId | string | 是 | 否 | 表示发送特征值写请求的远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4017| transId | number | 是 | 否 | 表示写请求的传输ID，server端回复响应时需填写相同的传输ID。 | 4018| offset | number | 是 | 否 | 表示写特征值数据的起始位置。例如：k表示从第k个字节开始写，server端回复响应时需填写相同的offset。 | 4019| isPrepared | boolean | 是 | 否 | 表示写请求是否立即执行。true表示立即执行。 | 4020| needRsp | boolean | 是 | 否 | 表示是否要给client端回复响应。true表示需要回复。 | 4021| value | ArrayBuffer | 是 | 否 | 表示写入的描述符二进制数据。 | 4022| characteristicUuid | string | 是 | 否 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 4023| serviceUuid | string | 是 | 否 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4024 4025 4026## DescriptorReadRequest 4027 4028描述server端订阅后收到的描述符读请求事件参数结构。 4029 4030**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4031 4032**系统能力**：SystemCapability.Communication.Bluetooth.Core 4033 4034| 名称 | 类型 | 可读 | 可写 | 说明 | 4035| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 4036| deviceId | string | 是 | 否 | 表示发送描述符读请求的远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4037| transId | number | 是 | 否 | 表示读请求的传输ID，server端回复响应时需填写相同的传输ID。 | 4038| offset | number | 是 | 否 | 表示读描述符数据的起始位置。例如：k表示从第k个字节开始读，server端回复响应时需填写相同的offset。 | 4039| descriptorUuid | string | 是 | 否 | 表示描述符(descriptor)的UUID。例如：00002902-0000-1000-8000-00805f9b34fb。 | 4040| characteristicUuid | string | 是 | 否 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 4041| serviceUuid | string | 是 | 否 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4042 4043 4044## DescriptorWriteRequest 4045 4046描述server端订阅后收到的描述符写请求事件参数结构。 4047 4048**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4049 4050**系统能力**：SystemCapability.Communication.Bluetooth.Core 4051 4052| 名称 | 类型 | 可读 | 可写 | 说明 | 4053| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | 4054| deviceId | string | 是 | 否 | 表示发送描述符写请求的远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4055| transId | number | 是 | 否 | 表示写请求的传输ID，server端回复响应时需填写相同的传输ID。 | 4056| offset | number | 是 | 否 | 表示写描述符数据的起始位置。例如：k表示从第k个字节开始写，server端回复响应时需填写相同的offset。 | 4057| isPrepared | boolean | 是 | 否 | 表示写请求是否立即执行。 | 4058| needRsp | boolean | 是 | 否 | 表示是否要给client端回复响应。 | 4059| value | ArrayBuffer | 是 | 否 | 表示写入的描述符二进制数据。 | 4060| descriptorUuid | string | 是 | 否 | 表示描述符(descriptor)的UUID。例如：00002902-0000-1000-8000-00805f9b34fb。 | 4061| characteristicUuid | string | 是 | 否 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 4062| serviceUuid | string | 是 | 否 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4063 4064 4065## ServerResponse 4066 4067描述server端回复client端读/写请求的响应参数结构。 4068 4069**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4070 4071**系统能力**：SystemCapability.Communication.Bluetooth.Core 4072 4073| 名称 | 类型 | 可读 | 可写 | 说明 | 4074| -------- | ----------- | ---- | ---- | -------------------------------------- | 4075| deviceId | string | 是 | 否 | 表示远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4076| transId | number | 是 | 否 | 表示请求的传输ID，与订阅的读/写请求事件携带的ID保持一致。 | 4077| status | number | 是 | 否 | 表示响应的状态，设置为0即可，表示正常。 | 4078| offset | number | 是 | 否 | 表示请求的读/写起始位置，与订阅的读/写请求事件携带的offset保持一致。 | 4079| value | ArrayBuffer | 是 | 否 | 表示回复响应的二进制数据。 | 4080 4081 4082## BLEConnectionChangeState 4083 4084描述Gatt profile连接状态。 4085 4086**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4087 4088**系统能力**：SystemCapability.Communication.Bluetooth.Core 4089 4090| 名称 | 类型 | 可读 | 可写 | 说明 | 4091| -------- | ------------------------------------------------- | ---- | ---- | --------------------------------------------- | 4092| deviceId | string | 是 | 否 | 表示远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4093| state | [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 是 | 是 | 表示BLE连接状态的枚举。 | 4094 4095 4096## ScanResult 4097 4098扫描结果上报数据。 4099 4100**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4101 4102**系统能力**：SystemCapability.Communication.Bluetooth.Core 4103 4104| 名称 | 类型 | 可读 | 可写 | 说明 | 4105| -------- | ----------- | ---- | ---- | ---------------------------------- | 4106| deviceId | string | 是 | 否 | 表示扫描到的设备地址。例如："XX:XX:XX:XX:XX:XX"。<br>基于信息安全考虑，此处获取的设备地址为随机MAC地址。<br>- 配对成功后，该地址不会变更。<br>- 已配对设备取消配对后重新扫描或蓝牙服务下电时，该随机地址会变更。 | 4107| rssi | number | 是 | 否 | 表示扫描到的设备的rssi值。 | 4108| data | ArrayBuffer | 是 | 否 | 表示扫描到的设备发送的广播包。 | 4109| deviceName | string | 是 | 否 | 表示扫描到的设备名称。 | 4110| connectable | boolean | 是 | 否 | 表示扫描到的设备是否可连接。true表示可连接，false表示不可连接。 | 4111 4112 4113## AdvertiseSetting 4114 4115描述蓝牙低功耗设备发送广播的参数。 4116 4117**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4118 4119**系统能力**：SystemCapability.Communication.Bluetooth.Core 4120 4121| 名称 | 类型 | 可读 | 可写 | 说明 | 4122| ----------- | ------- | ---- | ---- | ---------------------------------------- | 4123| interval | number | 是 | 是 | 表示广播间隔。<br>最小值设置32个slot表示20ms，最大值设置16777215个slot，默认值设置为1600个slot表示1s。(传统广播模式下最大值为16384个slot表示10.24s) | 4124| txPower | number | 是 | 是 | 表示发送功率。<br>最小值设置-127，最大值设置1，默认值设置-7，单位dbm。<br>推荐值：高档(1)，中档(-7)，低档(-15)。 | 4125| connectable | boolean | 是 | 是 | 表示是否是可连接广播。<br>默认值设置为true，表示可连接。false表示不可连接。 | 4126 4127 4128## AdvertiseData 4129 4130描述BLE广播数据包的内容，广播包数据长度为31个字节。 4131 4132**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4133 4134**系统能力**：SystemCapability.Communication.Bluetooth.Core 4135 4136| 名称 | 类型 | 可读 | 可写 | 说明 | 4137| --------------- | ---------------------------------------- | ---- | ---- | --------------------------- | 4138| serviceUuids | Array<string> | 是 | 是 | 表示要广播的服务 UUID 列表。 | 4139| manufactureData | Array<[ManufactureData](#manufacturedata)> | 是 | 是 | 表示要广播的广播的制造商信息列表。 | 4140| serviceData | Array<[ServiceData](#servicedata)> | 是 | 是 | 表示要广播的服务数据列表。 | 4141| includeDeviceName | boolean | 是 | 是 | 表示是否携带设备名，可选参数。<br>true表示携带，false或未设置此参数表示不携带。<br>注意：带上设备名时广播包长度不能超出31个字节。 | 4142 4143## AdvertisingParams<sup>11+</sup> 4144 4145描述首次启动广播设置的参数。 4146 4147**系统能力**：SystemCapability.Communication.Bluetooth.Core 4148 4149| 名称 | 类型 | 可读 | 可写 | 说明 | 4150| ------------------- | ------------------------------- | ----- | ----- | ------------------------ | 4151| advertisingSettings<sup>11+</sup> | [AdvertiseSetting](#advertisesetting) | 是 | 是 | 表示发送广播的相关参数。 | 4152| advertisingData<sup>11+</sup> | [AdvertiseData](#advertisedata) | 是 | 是 | 表示广播的数据包内容。 | 4153| advertisingResponse<sup>11+</sup> | [AdvertiseData](#advertisedata) | 是 | 是 | 表示回复扫描请求的响应内容。 | 4154| duration<sup>11+</sup> | number | 是 | 是 | 表示发送广播持续的时间。<br>单位为10ms，有效范围为1(10ms)~65535(655350ms)。<br>如果未指定此参数或者将其设置为0，则会连续发送广播。 | 4155 4156## AdvertisingEnableParams<sup>11+</sup> 4157 4158描述临时启动广播设置的参数。 4159 4160**系统能力**：SystemCapability.Communication.Bluetooth.Core 4161 4162| 名称 | 类型 | 可读 | 可写 | 说明 | 4163| ------------------- | --------------------- | ----- | ----- | ------------------------ | 4164| advertisingId<sup>11+</sup> | number | 是 | 是 | 表示当前广播的ID标识。 | 4165| duration<sup>11+</sup> | number | 是 | 是 | 表示发送广播持续的时间。<br>单位为10ms，有效范围为1(10ms)~65535(655350ms)。<br>如果未指定此参数或者将其设置为0，则会连续发送广播。 | 4166 4167## AdvertisingDisableParams<sup>11+</sup> 4168 4169描述临时停止广播设置的参数。 4170 4171**系统能力**：SystemCapability.Communication.Bluetooth.Core 4172 4173| 名称 | 类型 | 可读 | 可写 | 说明 | 4174| ------------------- | --------------------- | ----- | ----- | ------------------------ | 4175| advertisingId<sup>11+</sup> | number | 是 | 是 | 表示当前广播的ID标识。 | 4176 4177## AdvertisingStateChangeInfo<sup>11+</sup> 4178 4179描述广播启动、停止等状态信息。 4180 4181**系统能力**：SystemCapability.Communication.Bluetooth.Core 4182 4183| 名称 | 类型 | 可读 | 可写 | 说明 | 4184| ------------------- | --------------------------------------- | ----- | ----- | ------------------------ | 4185| advertisingId<sup>11+</sup> | number | 是 | 是 | 表示广播ID标识。 | 4186| state<sup>11+</sup> | [AdvertisingState](#advertisingstate11) | 是 | 是 | 表示广播状态。 | 4187 4188## ManufactureData 4189 4190描述BLE广播数据包的内容。 4191 4192**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4193 4194**系统能力**：SystemCapability.Communication.Bluetooth.Core 4195 4196| 名称 | 类型 | 可读 | 可写 | 说明 | 4197| ---------------- | ------------------- | ---- | ---- | ------------------ | 4198| manufactureId | number | 是 | 是 | 表示制造商的ID，由蓝牙SIG分配。 | 4199| manufactureValue | ArrayBuffer | 是 | 是 | 表示制造商发送的制造商数据。 | 4200 4201 4202## ServiceData 4203 4204描述广播包中服务数据内容。 4205 4206**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4207 4208**系统能力**：SystemCapability.Communication.Bluetooth.Core 4209 4210| 名称 | 类型 | 可读 | 可写 | 说明 | 4211| ------------ | ----------- | ---- | ---- | ---------- | 4212| serviceUuid | string | 是 | 是 | 表示服务的UUID。 | 4213| serviceValue | ArrayBuffer | 是 | 是 | 表示服务数据。 | 4214 4215 4216## ScanFilter 4217 4218扫描过滤参数。 4219 4220**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4221 4222**系统能力**：SystemCapability.Communication.Bluetooth.Core 4223 4224| 名称 | 类型 | 必填 | 说明 | 4225| ------------------------------------------ | -------- | ---- | ------------------------------------------------------------ | 4226| deviceId | string | 否 | 表示过滤的BLE设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4227| name | string | 否 | 表示过滤的BLE设备名。 | 4228| serviceUuid | string | 否 | 表示过滤包含该UUID服务的设备。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4229| serviceUuidMask | string | 否 | 表示过滤包含该UUID服务掩码的设备。例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | 4230| serviceSolicitationUuid | string | 否 | 表示过滤包含该UUID服务请求的设备。例如：00001888-0000-1000-8000-00805F9B34FB。 | 4231| serviceSolicitationUuidMask | string | 否 | 表示过滤包含该UUID服务请求掩码的设备。例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | 4232| serviceData | ArrayBuffer | 否 | 表示过滤包含该服务相关数据的设备。例如：[0x90,0x00,0xF1,0xF2]。 | 4233| serviceDataMask | ArrayBuffer | 否 | 表示过滤包含该服务相关数据掩码的设备。例如：[0xFF,0xFF,0xFF,0xFF]。 | 4234| manufactureId | number | 否 | 表示过滤包含该制造商ID的设备。例如：0x0006。 | 4235| manufactureData | ArrayBuffer | 否 | 表示过滤包含该制造商相关数据的设备。例如：[0x1F,0x2F,0x3F]。 | 4236| manufactureDataMask | ArrayBuffer | 否 | 表示过滤包含该制造商相关数据掩码的设备。例如：[0xFF,0xFF,0xFF]。 | 4237 4238 4239## ScanOptions 4240 4241扫描的配置参数。 4242 4243**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4244 4245**系统能力**：SystemCapability.Communication.Bluetooth.Core 4246 4247| 名称 | 类型 | 可读 | 可写 | 说明 | 4248| --------- | ----------------------- | ---- | ---- | -------------------------------------- | 4249| interval | number | 是 | 是 | 表示扫描结果上报延迟时间，默认值为0。 | 4250| dutyMode | [ScanDuty](#scanduty) | 是 | 是 | 表示扫描模式，默认值为SCAN_MODE_LOW_POWER。 | 4251| matchMode | [MatchMode](#matchmode) | 是 | 是 | 表示硬件的过滤匹配模式，默认值为MATCH_MODE_AGGRESSIVE。 | 4252| phyType<sup>12+</sup> | [PhyType](#phytype12) | 是 | 是 | 表示扫描中使用的PHY类型。 | 4253| reportMode<sup>15+</sup> | [ScanReportMode](#scanreportmode15) | 是 | 是 | 表示扫描结果数据上报模式。 | 4254 4255 4256## GattProperties<a name="GattProperties"></a> 4257 4258描述gatt characteristic的属性。 4259 4260**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4261 4262**系统能力**：SystemCapability.Communication.Bluetooth.Core 4263 4264| 名称 | 类型 | 必填 | 说明 | 4265| -------- | ------ |---- | ----------- | 4266| write | boolean | 否 | 表示该特征支持写操作，true表示需要对端设备的回复。 | 4267| writeNoResponse | boolean | 否 | true表示该特征支持写操作，无需对端设备回复。 | 4268| read | boolean | 否 | true表示该特征支持读操作。 | 4269| notify | boolean | 否 | true表示该特征可通知对端设备。 | 4270| indicate | boolean | 否 | true表示该特征可通知对端设备，需要对端设备的回复。 | 4271 4272 4273## GattWriteType<a name="GattWriteType"></a> 4274 4275枚举，表示gatt写入类型。 4276 4277**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4278 4279**系统能力**：SystemCapability.Communication.Bluetooth.Core 4280 4281| 名称 | 值 | 说明 | 4282| ------------------------------------| ------ | --------------- | 4283| WRITE | 1 | 表示写入特征值，需要对端设备的回复。 | 4284| WRITE_NO_RESPONSE | 2 | 表示写入特征值，不需要对端设备的回复。 | 4285 4286 4287## ScanDuty 4288 4289枚举，扫描模式。 4290 4291**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4292 4293**系统能力**：SystemCapability.Communication.Bluetooth.Core 4294 4295| 名称 | 值 | 说明 | 4296| --------------------- | ---- | ------------ | 4297| SCAN_MODE_LOW_POWER | 0 | 表示低功耗模式，默认值。 | 4298| SCAN_MODE_BALANCED | 1 | 表示均衡模式。 | 4299| SCAN_MODE_LOW_LATENCY | 2 | 表示低延迟模式。 | 4300 4301 4302## MatchMode 4303 4304枚举，硬件过滤匹配模式。 4305 4306**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4307 4308**系统能力**：SystemCapability.Communication.Bluetooth.Core 4309 4310| 名称 | 值 | 说明 | 4311| --------------------- | ---- | ---------------------------------------- | 4312| MATCH_MODE_AGGRESSIVE | 1 | 表示硬件上报扫描结果门限较低，比如扫描到的功率较低或者一段时间扫描到的次数较少也触发上报，默认值。 | 4313| MATCH_MODE_STICKY | 2 | 表示硬件上报扫描结果门限较高，更高的功率门限以及扫描到多次才会上报。 | 4314 4315## AdvertisingState<sup>11+</sup> 4316 4317枚举，广播状态。 4318 4319**系统能力**：SystemCapability.Communication.Bluetooth.Core 4320 4321| 名称 | 值 | 说明 | 4322| -------- | ---- | ------------------------------ | 4323| STARTED<sup>11+</sup> | 1 | 表示首次启动广播后的状态。 | 4324| ENABLED<sup>11+</sup> | 2 | 表示临时启动广播后的状态。 | 4325| DISABLED<sup>11+</sup> | 3 | 表示临时停止广播后的状态。 | 4326| STOPPED<sup>11+</sup> | 4 | 表示完全停止广播后的状态。 | 4327 4328## PhyType<sup>12+</sup> 4329 4330枚举，扫描中使用的PHY类型。 4331 4332**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4333 4334**系统能力**：SystemCapability.Communication.Bluetooth.Core 4335 4336| 名称 | 值 | 说明 | 4337| -------- | ---- | ------------------------------ | 4338| PHY_LE_1M<sup>12+</sup> | 1 | 表示扫描中使用1M PHY。 | 4339| PHY_LE_ALL_SUPPORTED<sup>12+</sup> | 255 | 表示扫描中使用蓝牙协议支持的PHY模式。 | 4340 4341## ScanReport<sup>15+</sup> 4342 4343扫描结果数据上报。 4344 4345**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 4346 4347**系统能力**：SystemCapability.Communication.Bluetooth.Core 4348 4349| 名称 | 类型 | 只读 | 可选 | 说明 | 4350| --------- | ----------------------- | ---- | ---- | ------------------------------ | 4351| reportType | [ScanReportType](#scanreporttype15) | 否 | 否 | 表示扫描报告类型。 | 4352| scanResult | Array<[ScanResult](#scanresult)> | 否 | 否 |扫描结果数据。 | 4353 4354## ScanReportType<sup>15+</sup> 4355 4356枚举，扫描结果数据上报类型。 4357 4358**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 4359 4360**系统能力**：SystemCapability.Communication.Bluetooth.Core 4361 4362| 名称 | 值 | 说明 | 4363| -------- | ---- | ------------------------------ | 4364| ON_FOUND | 1 | 表示发现广播包。 | 4365| ON_LOST | 2 | 表示丢失广播包。 | 4366 4367## ScanReportMode<sup>15+</sup> 4368 4369枚举，扫描结果数据上报模式。 4370 4371**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 4372 4373**系统能力**：SystemCapability.Communication.Bluetooth.Core 4374 4375| 名称 | 值 | 说明 | 4376| -------- | ---- | ------------------------------ | 4377| NORMAL | 1 | 表示常规扫描上报模式。 |