@ohos.bluetooth.ble (蓝牙ble模块)(系统接口)

本模块提供了基于低功耗蓝牙（Bluetooth Low Energy，BLE）技术的蓝牙能力，首批接口包括基于通用属性协议（Generic Attribute Profile，GATT）的写特征值方法。

说明：

本模块首批接口从API version 23开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.bluetooth.ble (蓝牙ble模块)。

导入模块

import { ble } from '@kit.ConnectivityKit';

GattClientDevice

GATT客户端类，提供了和服务端进行连接和数据传输等操作方法。

使用该类的方法前，需通过createGattClientDevice方法构造该类的实例。
通过创建不同的该类实例，可以管理多路GATT连接。

writeCharacteristicValueWithContext

writeCharacteristicValueWithContext(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<GattRspContext>

client端向指定的server端特征值写入数据。使用Promise异步回调。

与writeCharacteristicValue接口不同，此接口新增了返回server端响应信息的功能。在完成特征值写入操作后，调用方可以获取本端接收到server端回复消息的时间戳等信息。
为获取server端的响应信息，此接口仅支持writeType为WRITE的写入模式。
需要先调用getServices，获取到server端所有支持的能力，且包含指定的入参特征值UUID；否则会写入失败。
异步回调结果返回后，才能调用下一次读取或者写入操作，如readCharacteristicValue、readDescriptorValue、writeCharacteristicValue、writeDescriptorValue、setCharacteristicChangeNotification和setCharacteristicChangeIndication。
应用单次可写入的特征值数据长度限制为（MTU-3）字节。调用方可根据实际需要通过setBLEMtuSize接口指定MTU大小，进而修改单次可写入的特征值数据长度。

系统接口：此接口为系统接口。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core

参数：

参数名	类型	必填	说明
characteristic	BLECharacteristic	是	需要写入的特征值，包含写入的数据内容。
writeType	GattWriteType	是	写入特征值的方式。

返回值：

类型	说明
Promise<GattRspContext>	Promise对象，返回GattRspContext对象。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID	错误信息
201	Permission denied.
202	Non-system applications are not allowed to use system APIs.
801	Capability not supported.
2900011	The operation is busy. The last operation is not complete.
2900099	Operation failed.
2901001	Write forbidden.
2901003	The connection is not established.
2901004	The connection is congested.
2901005	The connection is not encrypted.
2901006	The connection is not authenticated.
2901007	The connection is not authorized.

示例：

let descriptors: Array<ble.BLEDescriptor>  = [];
let bufferDesc = new ArrayBuffer(2);
let descV = new Uint8Array(bufferDesc);
descV[0] = 0; // 以Client Characteristic Configuration描述符为例，表示bit0、bit1均为0，notification和indication均不开启
let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
  characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
  descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc};
descriptors[0] = descriptor;

let bufferCCC = new ArrayBuffer(8);
let cccV = new Uint8Array(bufferCCC);
cccV[0] = 1;
let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
  characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
  characteristicValue: bufferCCC, descriptors:descriptors};
try {
    let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
    device.writeCharacteristicValueWithContext(characteristic, ble.GattWriteType.WRITE).then((rspContext: ble.GattRspContext) => {
        console.info('timestamp is: ' + rspContext.timestamp);
    });
} catch (err) {
    console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
}

GattRspContext

client端调用writeCharacteristicValueWithContext等接口并接收到server端的回复消息后，蓝牙子系统上报给应用的信息。

系统接口：此接口为系统接口。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	只读	可选	说明
timestamp	number	否	否	本端接收到对端GATT回复消息的时间点，格式为微秒级的UNIX时间戳。

ScanFilter

扫描BLE广播的过滤条件，只有符合该条件的广播报文才会上报。

系统能力：SystemCapability.Communication.Bluetooth.Core

名称	类型	只读	可选	说明
irk²³⁺	Uint8Array	否	是	通过蓝牙设备地址解析秘钥（Identity Resolving Key, IRK）过滤携带可解析私有地址的BLE广播报文。蓝牙设备的可解析私有地址会随时间变化，若已知该设备的IRK和Public类型地址或者Static Random类型的地址，即可过滤同一个蓝牙设备在不同时间发出的BLE广播报文。使用本参数时，必须同时通过ScanFilter中的address参数指定地址和地址类型等信息。其中，地址必须为有效的Public类型地址或Static Random类型地址，addressType必须设置为REAL，rawAddressType必须根据address的实际情况进行设置。系统接口：此接口为系统接口。