openharmony 鸿蒙 changelogs-bluetooth

2025-06-16 浏览 (1)

蓝牙子系统Changelog

cl.bluetooth.1 蓝牙BLE接口错误码变更

访问级别

公开接口

变更原因

蓝牙子系统BLE相关接口错误码不够清晰，开发者无法通过错误信息明确需要如何修复问题，影响开发效率。

变更影响

此变更涉及应用适配。

变更前：BLE广播、BLE扫描、GATT Client、GATT Server接口异常时仅返回2900099错误码。

变更后：BLE广播、BLE扫描、GATT Client、GATT Server接口异常时会返回更详细的错误码。

起始API Level

10

变更发生版本

从OpenHarmony SDK 6.0.0.32开始。

变更的接口/组件

模块名命名空间类名接口声明主要变更点说明
@ohos.bluetooth.ble.d.tsblefunction startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void;新增2900010错误码：广播资源已耗尽；
新增2902054错误码：广播报文数据长度超限；
@ohos.bluetooth.ble.d.tsblefunction startAdvertising(advertisingParams: AdvertisingParams, callback: AsyncCallback<number>): void;新增2900010错误码：广播资源已耗尽；
新增2902054错误码：广播报文数据长度超限；
@ohos.bluetooth.ble.d.tsblefunction startAdvertising(advertisingParams: AdvertisingParams): Promise<number>;新增2900010错误码：广播资源已耗尽；
新增2902054错误码：广播报文数据长度超限；
@ohos.bluetooth.ble.d.tsblefunction enableAdvertising(advertisingEnableParams: AdvertisingEnableParams, callback: AsyncCallback<void>): void;新增2902055错误码：无效的广播ID；
@ohos.bluetooth.ble.d.tsblefunction enableAdvertising(advertisingEnableParams: AdvertisingEnableParams): Promise<void>;新增2902055错误码：无效的广播ID；
@ohos.bluetooth.ble.d.tsblefunction disableAdvertising(advertisingDisableParams: AdvertisingDisableParams, callback: AsyncCallback<void>): void;新增2902055错误码：无效的广播ID；
@ohos.bluetooth.ble.d.tsblefunction disableAdvertising(advertisingDisableParams: AdvertisingDisableParams): Promise<void>;新增2902055错误码：无效的广播ID；
@ohos.bluetooth.ble.d.tsblefunction stopAdvertising(advertisingId: number, callback: AsyncCallback<void>): void;新增2902055错误码：无效的广播ID；
@ohos.bluetooth.ble.d.tsblefunction stopAdvertising(advertisingId: number): Promise<void>;新增2902055错误码：无效的广播ID；
@ohos.bluetooth.ble.d.tsbleGattClientDevicereadCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901000错误码：读失败，对端禁止读操作；
新增2901003错误码：读失败，未与对端建立连接；
新增2901004错误码：读失败，连接链路拥塞；
新增2901005错误码：读失败，连接链路未加密；
新增2901006错误码：读失败，连接链路未认证；
新增2901007错误码：读失败，连接链路未授权；
@ohos.bluetooth.ble.d.tsbleGattClientDevicereadCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic>;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901000错误码：读失败，对端禁止读操作；
新增2901003错误码：读失败，未与对端建立连接；
新增2901004错误码：读失败，连接链路拥塞；
新增2901005错误码：读失败，连接链路未加密；
新增2901006错误码：读失败，连接链路未认证；
新增2901007错误码：读失败，连接链路未授权；
@ohos.bluetooth.ble.d.tsbleGattClientDevicereadDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901000错误码：读失败，对端禁止读操作；
新增2901003错误码：读失败，未与对端建立连接；
新增2901004错误码：读失败，连接链路拥塞；
新增2901005错误码：读失败，连接链路未加密；
新增2901006错误码：读失败，连接链路未认证；
新增2901007错误码：读失败，连接链路未授权；
@ohos.bluetooth.ble.d.tsbleGattClientDevicereadDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor>;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901000错误码：读失败，对端禁止读操作；
新增2901003错误码：读失败，未与对端建立连接；
新增2901004错误码：读失败，连接链路拥塞；
新增2901005错误码：读失败，连接链路未加密；
新增2901006错误码：读失败，连接链路未认证；
新增2901007错误码：读失败，连接链路未授权；
@ohos.bluetooth.ble.d.tsbleGattClientDevicewriteCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<void> ): void;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901001错误码：写失败，对端禁止写操作；
新增2901003错误码：写失败，未与对端建立连接；
新增2901004错误码：写失败，连接链路拥塞；
新增2901005错误码：写失败，连接链路未加密；
新增2901006错误码：写失败，连接链路未认证；
新增2901007错误码：写失败，连接链路未授权；
@ohos.bluetooth.ble.d.tsbleGattClientDevicewriteCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<void>;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901001错误码：写失败，对端禁止写操作；
新增2901003错误码：写失败，未与对端建立连接；
新增2901004错误码：写失败，连接链路拥塞；
新增2901005错误码：写失败，连接链路未加密；
新增2901006错误码：写失败，连接链路未认证；
新增2901007错误码：写失败，连接链路未授权；
@ohos.bluetooth.ble.d.tsbleGattClientDevicewriteDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<void>): void;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901001错误码：写失败，对端禁止写操作；
新增2901003错误码：写失败，未与对端建立连接；
新增2901004错误码：写失败，连接链路拥塞；
新增2901005错误码：写失败，连接链路未加密；
新增2901006错误码：写失败，连接链路未认证；
新增2901007错误码：写失败，连接链路未授权；
@ohos.bluetooth.ble.d.tsbleGattClientDevicewriteDescriptorValue(descriptor: BLEDescriptor): Promise<void>;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901001错误码：写失败，对端禁止写操作；
新增2901003错误码：写失败，未与对端建立连接；
新增2901004错误码：写失败，连接链路拥塞；
新增2901005错误码：写失败，连接链路未加密；
新增2901006错误码：写失败，连接链路未认证；
新增2901007错误码：写失败，连接链路未授权；
@ohos.bluetooth.ble.d.tsbleGattClientDevicegetRssiValue(callback: AsyncCallback<number>): void;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901003错误码：未与对端建立连接；
@ohos.bluetooth.ble.d.tsbleGattClientDevicegetRssiValue(): Promise<number>;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901003错误码：未与对端建立连接；
@ohos.bluetooth.ble.d.tsbleGattClientDevicesetCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901003错误码：未与对端建立连接；
@ohos.bluetooth.ble.d.tsbleGattClientDevicesetCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean): Promise<void>;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901003错误码：未与对端建立连接；
@ohos.bluetooth.ble.d.tsbleGattClientDevicesetCharacteristicChangeIndication( characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901003错误码：未与对端建立连接；
@ohos.bluetooth.ble.d.tsbleGattClientDevicesetCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean): Promise<void>;新增2900011错误码：操作忙碌，需等待上一次操作结束；
新增2901003错误码：未与对端建立连接；

适配指导

应用可将接口调用的错误码打印出来，辅助定位问题。

以广播报文数据超过最大长度限制导致开启BLE广播失败为例：

let advSettings: ble.AdvertiseSetting = {
  "interval": 160,
  "connectable": true,
};
// 1）开发者构造的广播报文数据长度超过最大长度限制
let serviceUuidsArray: Array<string> = new Array();
serviceUuidsArray.push("00001111-1111-1000-8000-00805f9b34fb");
serviceUuidsArray.push("00001111-2222-1000-8000-00805f9b34fb");
serviceUuidsArray.push("00001111-3333-1000-8000-00805f9b34fb");
let advData: ble.AdvertiseData = {
  "serviceUuids": serviceUuidsArray,
  "manufactureData": new Array(),
  "serviceData": new Array(),
  "includeDeviceName": true,
};

try {
  ble.startAdvertising(advSettings, advData);
} catch (err) {
  // 2）通过日志打印发现接口调用报错2902054，即表示广播报文数据长度超过最大长度限制
  console.error("errCode: " + err.code + ", errMessage: " + err.message);
}
// 3）开发者根据错误码确定广播报文构造方式的合理性。建议：
//  - 是否有必要携带本机蓝牙设备名
//  - 是否将部分广播报文构造成入参advResponse

你可能感兴趣的鸿蒙文章

harmony 鸿蒙文件管理子系统ChangeLog

harmony 鸿蒙元能力子系统Changelog

harmony 鸿蒙ArkTS方舟编程语言Changelog

harmony 鸿蒙ArkUI子系统Changelog

harmony 鸿蒙驱动子系统扩展外设管理模块Changelog

harmony 鸿蒙图片框架Changelog

harmony 鸿蒙multimedia子系统变更说明

harmony 鸿蒙启动子系统变更说明

harmony 鸿蒙ArkWeb子系统Changelog

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/DetCbj