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