# bluetooth

Bluetooth模块用于管理蓝牙设备，搜索附近蓝牙设备、实现简单数据传输等。

## 方法：

- closeBluetoothAdapter: 关闭蓝牙模块
- getBluetoothAdapterState: 获取本机蓝牙适配器状态
- getBluetoothDevices: 获取已搜索到的蓝牙设备
- getConnectedBluetoothDevices: 根据uuid获取处于已连接的设备
- onBluetoothAdapterStateChange: 监听蓝牙适配器状态变化事件
- onBluetoothDeviceFound: 监听搜索到新设备的事件
- openBluetoothAdapter: 初始化蓝牙模块
- startBluetoothDevicesDiscovery: 开始搜索附近的蓝牙设备
- stopBluetoothDevicesDiscovery: 停止搜寻附近的蓝牙外围设备
- closeBLEConnection: 断开与低功耗蓝牙设备的连接
- createBLEConnection: 连接低功耗蓝牙设备
- getBLEDeviceCharacteristics: 获取蓝牙设备指定服务中所有特征值(characteristic)
- getBLEDeviceServices: 获取蓝牙设备的所有服务(service)
- notifyBLECharacteristicValueChange: 启用低功耗蓝牙设备特征值变化时的notify功能，订阅特征值
- onBLECharacteristicValueChange: 监听低功耗蓝牙设备的特征值变化事件
- onBLEConnectionStateChange: 监听低功耗蓝牙设备连接状态变化事件
- readBLECharacteristicValue: 读取低功耗蓝牙设备指定特征值的二进制数据值
- writeBLECharacteristicValue: 向低功耗蓝牙设备指定特征值写入二进制数据

## 对象：

- BluetoothDeviceInfo: 蓝牙设备信息
- BluetoothService: 蓝牙设备服务信息
- Bluetoothcharacteristic: 蓝牙设备特征值
- BluetoothcharacteristicProperties: 蓝牙设备特征值支持的操作类型

## 回调方法：

- BluetoothSuccessCallback: 成功回调函数
- BluetoothFailCallback: 失败回调函数
- BluetoothCompleteCallback: 操作完成回调函数
- BluetoothAdapterStateChangeCallback: 蓝牙适配器状态变化事件回调函数
- BluetoothDeviceFoundCallback: 蓝牙适配器搜索到新设备事件回调函数
- BLEConnectionStateChangeCallback: 低功耗蓝牙设备连接状态变化事件回调函数
- BLECharacteristicValueChangeCallback: 低功耗蓝牙设备的特征值变化事件回调函数

## 权限：

5+功能模块（permissions）

    {
    // ...
    "permissions":{
    	// ...
    	"Bluetooth": {
    		"description": "Bluetooth"
    	}
    }
    }

# BluetoothDeviceInfo

蓝牙设备信息

    interface BluetoothDeviceInfo {
    	readonly attribute String name;
    	readonly attribute String deviceId;
    	readonly attribute String RSSI;
    	readonly attribute ArrayBuffer advertisData;
    	readonly attribute Array<String> advertisServiceUUIDs;
    	readonly attribute String localName;
    	readonly attribute JSON serviceData;
    }

## 属性：

- name: (String 类型 )蓝牙设备名称

  某些设备可能没有此字段值。

- deviceId: (String 类型 )蓝牙设备的id
- RSSI: (String 类型 )蓝牙设备的信号强度
- advertisData: (ArrayBuffer 类型 )蓝牙设备的广播数据段中的ManufacturerData数据段
- advertisServiceUUIDs: (Array[ String ] 类型 )蓝牙设备的广播数据段中的ServiceUUIDs数据段
- localName: (String 类型 )蓝牙设备的广播数据段中的LocalName数据段
- serviceData: (JSON 类型 )蓝牙设备的广播数据段中的ServiceData数据段

# BluetoothService

蓝牙设备服务信息

    interface BluetoothService {
    	readonly attribute String uuid;
    	readonly attribute Boolean isPrimary;
    }

## 属性：

- uuid: (String 类型 )蓝牙设备服务的uuid
- isPrimary: (Boolean 类型 )是否为设备的主服务

# Bluetoothcharacteristic

蓝牙设备特征值

    interface Bluetoothcharacteristic {
    	readonly attribute String uuid;
    	readonly attribute BluetoothcharacteristicProperties properties;
    }

## 属性：

- uuid: (String 类型 )蓝牙设备特征值的uuid
- properties: (BluetoothcharacteristicProperties 类型 )设备特征值支持的操作类型

# BluetoothcharacteristicProperties

蓝牙设备特征值支持的操作类型

    interface BluetoothcharacteristicProperties {
    	readonly attribute Boolean read;
    	readonly attribute Boolean write;
    	readonly attribute Boolean notify;
    	readonly attribute Boolean indicate;
    }

## 属性：

- read: (Boolean 类型 )特征值是否支持read操作
- write: (Boolean 类型 )特征值是否支持write操作
- notify: (Boolean 类型 )特征值是否支持notify操作
- indicate: (Boolean 类型 )特征值是否支持indicate操作

# BluetoothSuccessCallback

成功回调函数

    void onSuccess(JSON event){
    }

## 说明：

不同接口触发的成功回调参数event包含的属性存在差异，具体参考对应的接口描述说明。

## 参数：

- event: ( JSON ) 必选 回调参数
  回调参数包含的属性由调用接口决定，具体参考对应的接口描述说明。

## 返回值：

void : 无

# BluetoothFailCallback

失败回调函数

    function void onFail(Exception error){
    	// Handle error
    	var code = error.code; // 错误编码
    	var message = error.message; // 错误描述信息
    }

## 参数：

- error: ( Exception ) 必选 回调参数，错误信息
  可通过error.code（Number类型）获取错误编码； 可通过error.message（String类型）获取错误描述信息。

## 返回值：

void : 无

# BluetoothCompleteCallback

操作完成回调函数

    function void onComplete(JSON event){
    }

## 说明：

调用成功或失败都会触发此回调。

## 参数：

- event: ( JSON ) 可选 回调参数
  调用成功时回调参数与BluetoothSuccessCallback一致，调用失败时回调参数与BluetoothFailCallback一致。

## 返回值：

void : 无

# BluetoothAdapterStateChangeCallback

蓝牙适配器状态变化事件回调函数

    function void onStateChange(JSON event){
    	// event.available
    	// event.discovering
    }

## 说明：

蓝牙适配器状态发生变化时触发此回调。

## 参数：

- event: ( JSON ) 可选 返回参数
  回调函数参数event对象包括以下属性： available - Boolean，蓝牙适配器是否可用； discovering - Boolean，蓝牙适配器是否处于搜索状态。

## 返回值：

void : 无

# BluetoothDeviceFoundCallback

蓝牙适配器搜索到新设备事件回调函数

    function void onDeviceFound(JSON event){
    	// event.devices
    }

## 说明：

搜索到蓝牙设备时触发此回调。

## 参数：

- event: ( JSON ) 可选 返回参数
  回调函数参数event对象包括以下属性： devices - Array<BluetoothDeviceInfo>，设备列表信息。

## 返回值：

void : 无

# BLEConnectionStateChangeCallback

低功耗蓝牙设备连接状态变化事件回调函数

    function void onStateChange(JSON event){
    	// event.deviceId
    	// event.connected
    }

## 说明：

蓝牙设备连接状态发生变化时触发此回调。

## 参数：

- event: ( JSON ) 可选 返回参数
  回调函数参数event对象包括以下属性： deviceId - String类型，蓝牙设备id； connected - Boolean类型，是否处于已连接状态。

## 返回值：

void : 无

# BLECharacteristicValueChangeCallback

低功耗蓝牙设备的特征值变化事件回调函数

    function void onValueChange(JSON event){
    	// event.deviceId
    	// event.serviceId
    	// event.characteristicId
    	// event.value
    }

## 说明：

蓝牙设备对应的特征值发生变化时触发此回调。

## 参数：

- event: ( JSON ) 可选 返回参数
  回调函数参数event对象包括以下属性： deviceId - String类型，蓝牙设备id； serviceId - String类型，蓝牙服务的uuid； characteristicId - String类型，蓝牙特征值的uuid； value - ArrayBuffer类型，特征值的最新值。

## 返回值：

void : 无