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