1# 蓝牙子系统Changelog 2 3## cl.bluetooth.1 蓝牙BLE接口错误码变更 4 5 6**访问级别** 7 8公开接口 9 10**变更原因** 11 12蓝牙子系统BLE相关接口错误码不够清晰，开发者无法通过错误信息明确需要如何修复问题，影响开发效率。 13 14**变更影响** 15 16此变更涉及应用适配。 17 18变更前：BLE广播、BLE扫描、GATT Client、GATT Server接口异常时仅返回2900099错误码。 19 20变更后：BLE广播、BLE扫描、GATT Client、GATT Server接口异常时会返回更详细的错误码。 21 22**起始API Level** 23 2410 25 26**变更发生版本** 27 28从OpenHarmony SDK 6.0.0.32开始。 29 30**变更的接口/组件** 31 32| 模块名 | 命名空间 | 类名 | 接口声明 |主要变更点说明 | 33| ------------------------------------ | ------------------- | -- | ------------------------------------------------------------ | -------------- | 34| @ohos.bluetooth.ble.d.ts | ble | | function startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void; | 新增2900010错误码：广播资源已耗尽；<br>新增2902054错误码：广播报文数据长度超限； | 35| @ohos.bluetooth.ble.d.ts | ble | | function startAdvertising(advertisingParams: AdvertisingParams, callback: AsyncCallback<number>): void; | 新增2900010错误码：广播资源已耗尽；<br>新增2902054错误码：广播报文数据长度超限； | 36| @ohos.bluetooth.ble.d.ts | ble | | function startAdvertising(advertisingParams: AdvertisingParams): Promise<number>; | 新增2900010错误码：广播资源已耗尽；<br>新增2902054错误码：广播报文数据长度超限； | 37| @ohos.bluetooth.ble.d.ts | ble | | function enableAdvertising(advertisingEnableParams: AdvertisingEnableParams, callback: AsyncCallback<void>): void; | 新增2902055错误码：无效的广播ID； | 38| @ohos.bluetooth.ble.d.ts | ble | | function enableAdvertising(advertisingEnableParams: AdvertisingEnableParams): Promise<void>; | 新增2902055错误码：无效的广播ID； | 39| @ohos.bluetooth.ble.d.ts | ble | | function disableAdvertising(advertisingDisableParams: AdvertisingDisableParams, callback: AsyncCallback<void>): void; | 新增2902055错误码：无效的广播ID； | 40| @ohos.bluetooth.ble.d.ts | ble | | function disableAdvertising(advertisingDisableParams: AdvertisingDisableParams): Promise<void>; | 新增2902055错误码：无效的广播ID； | 41| @ohos.bluetooth.ble.d.ts | ble | | function stopAdvertising(advertisingId: number, callback: AsyncCallback<void>): void; | 新增2902055错误码：无效的广播ID； | 42| @ohos.bluetooth.ble.d.ts | ble | | function stopAdvertising(advertisingId: number): Promise<void>; | 新增2902055错误码：无效的广播ID； | 43| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901000错误码：读失败，对端禁止读操作；<br>新增2901003错误码：读失败，未与对端建立连接；<br>新增2901004错误码：读失败，连接链路拥塞；<br>新增2901005错误码：读失败，连接链路未加密；<br>新增2901006错误码：读失败，连接链路未认证；<br>新增2901007错误码：读失败，连接链路未授权； | 44| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic>; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901000错误码：读失败，对端禁止读操作；<br>新增2901003错误码：读失败，未与对端建立连接；<br>新增2901004错误码：读失败，连接链路拥塞；<br>新增2901005错误码：读失败，连接链路未加密；<br>新增2901006错误码：读失败，连接链路未认证；<br>新增2901007错误码：读失败，连接链路未授权； | 45| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901000错误码：读失败，对端禁止读操作；<br>新增2901003错误码：读失败，未与对端建立连接；<br>新增2901004错误码：读失败，连接链路拥塞；<br>新增2901005错误码：读失败，连接链路未加密；<br>新增2901006错误码：读失败，连接链路未认证；<br>新增2901007错误码：读失败，连接链路未授权； | 46| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor>; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901000错误码：读失败，对端禁止读操作；<br>新增2901003错误码：读失败，未与对端建立连接；<br>新增2901004错误码：读失败，连接链路拥塞；<br>新增2901005错误码：读失败，连接链路未加密；<br>新增2901006错误码：读失败，连接链路未认证；<br>新增2901007错误码：读失败，连接链路未授权； | 47| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<void> ): void; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901001错误码：写失败，对端禁止写操作；<br>新增2901003错误码：写失败，未与对端建立连接；<br>新增2901004错误码：写失败，连接链路拥塞；<br>新增2901005错误码：写失败，连接链路未加密；<br>新增2901006错误码：写失败，连接链路未认证；<br>新增2901007错误码：写失败，连接链路未授权； | 48| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<void>; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901001错误码：写失败，对端禁止写操作；<br>新增2901003错误码：写失败，未与对端建立连接；<br>新增2901004错误码：写失败，连接链路拥塞；<br>新增2901005错误码：写失败，连接链路未加密；<br>新增2901006错误码：写失败，连接链路未认证；<br>新增2901007错误码：写失败，连接链路未授权； | 49| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | writeDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<void>): void; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901001错误码：写失败，对端禁止写操作；<br>新增2901003错误码：写失败，未与对端建立连接；<br>新增2901004错误码：写失败，连接链路拥塞；<br>新增2901005错误码：写失败，连接链路未加密；<br>新增2901006错误码：写失败，连接链路未认证；<br>新增2901007错误码：写失败，连接链路未授权； | 50| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | writeDescriptorValue(descriptor: BLEDescriptor): Promise<void>; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901001错误码：写失败，对端禁止写操作；<br>新增2901003错误码：写失败，未与对端建立连接；<br>新增2901004错误码：写失败，连接链路拥塞；<br>新增2901005错误码：写失败，连接链路未加密；<br>新增2901006错误码：写失败，连接链路未认证；<br>新增2901007错误码：写失败，连接链路未授权； | 51| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | getRssiValue(callback: AsyncCallback<number>): void; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901003错误码：未与对端建立连接； | 52| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | getRssiValue(): Promise<number>; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901003错误码：未与对端建立连接； | 53| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901003错误码：未与对端建立连接； | 54| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean): Promise<void>; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901003错误码：未与对端建立连接； | 55| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | setCharacteristicChangeIndication( characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901003错误码：未与对端建立连接； | 56| @ohos.bluetooth.ble.d.ts | ble | GattClientDevice | setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean): Promise<void>; | 新增2900011错误码：操作忙碌，需等待上一次操作结束；<br>新增2901003错误码：未与对端建立连接； | 57 58**适配指导** 59 60应用可将接口调用的错误码打印出来，辅助定位问题。 61 62以广播报文数据超过最大长度限制导致开启BLE广播失败为例： 63 64```ts 65let advSettings: ble.AdvertiseSetting = { 66 "interval": 160, 67 "connectable": true, 68}; 69// 1）开发者构造的广播报文数据长度超过最大长度限制 70let serviceUuidsArray: Array<string> = new Array(); 71serviceUuidsArray.push("00001111-1111-1000-8000-00805f9b34fb"); 72serviceUuidsArray.push("00001111-2222-1000-8000-00805f9b34fb"); 73serviceUuidsArray.push("00001111-3333-1000-8000-00805f9b34fb"); 74let advData: ble.AdvertiseData = { 75 "serviceUuids": serviceUuidsArray, 76 "manufactureData": new Array(), 77 "serviceData": new Array(), 78 "includeDeviceName": true, 79}; 80 81try { 82 ble.startAdvertising(advSettings, advData); 83} catch (err) { 84 // 2）通过日志打印发现接口调用报错2902054，即表示广播报文数据长度超过最大长度限制 85 console.error("errCode: " + err.code + ", errMessage: " + err.message); 86} 87// 3）开发者根据错误码确定广播报文构造方式的合理性。建议： 88// - 是否有必要携带本机蓝牙设备名 89// - 是否将部分广播报文构造成入参advResponse 90``` 91