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