From a488a554300b89b0f12ea431d01c0c414e0bc0f9 Mon Sep 17 00:00:00 2001 From: lverpeng Date: Sat, 22 Jul 2023 17:56:01 +0800 Subject: [PATCH] add api10 Signed-off-by: lverpeng --- .../reference/apis/Readme-CN.md | 12 +- .../reference/apis/js-apis-bluetooth-a2dp.md | 184 ++ .../apis/js-apis-bluetooth-access.md | 207 ++ .../apis/js-apis-bluetooth-baseProfile.md | 388 +++ .../reference/apis/js-apis-bluetooth-ble.md | 2539 +++++++++++++++++ .../apis/js-apis-bluetooth-connection.md | 1397 +++++++++ .../apis/js-apis-bluetooth-constant.md | 181 ++ .../reference/apis/js-apis-bluetooth-hfp.md | 128 + .../reference/apis/js-apis-bluetooth-hid.md | 128 + .../reference/apis/js-apis-bluetooth-pan.md | 158 + .../apis/js-apis-bluetooth-socket.md | 410 +++ .../apis/js-apis-bluetoothManager.md | 1452 ++++------ 12 files changed, 6341 insertions(+), 843 deletions(-) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-a2dp.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-access.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-baseProfile.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-ble.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-connection.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-constant.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-hfp.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-hid.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-pan.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-bluetooth-socket.md diff --git a/zh-cn/application-dev/reference/apis/Readme-CN.md b/zh-cn/application-dev/reference/apis/Readme-CN.md index 56544e598f..5dffddfee7 100644 --- a/zh-cn/application-dev/reference/apis/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis/Readme-CN.md @@ -319,8 +319,18 @@ - [@ohos.request (上传下载)](js-apis-request.md) - 通信与连接 + - [@ohos.bluetooth.a2dp(蓝牙a2dp模块)(推荐)](js-apis-bluetooth-a2dp.md) + - [@ohos.bluetooth.access(蓝牙access模块)(推荐)](js-apis-bluetooth-access.md) + - [@ohos.bluetooth.baseProfile(蓝牙baseProfile模块)(推荐)](js-apis-bluetooth-baseProfile.md) + - [@ohos.bluetooth.ble(蓝牙ble模块)(推荐)](js-apis-bluetooth-ble.md) + - [@ohos.bluetooth.connection(蓝牙connection模块)(推荐)](js-apis-bluetooth-connection.md) + - [@ohos.bluetooth.constant(蓝牙constant模块)(推荐)](js-apis-bluetooth-constant.md) + - [@ohos.bluetooth.hfp(蓝牙hfp模块)(推荐)](js-apis-bluetooth-hfp.md) + - [@ohos.bluetooth.hid(蓝牙hid模块)(推荐)](js-apis-bluetooth-hid.md) + - [@ohos.bluetooth.pan(蓝牙pan模块)(推荐)](js-apis-bluetooth-pan.md) + - [@ohos.bluetooth.socket(蓝牙socket模块)(推荐)](js-apis-bluetooth-socket.md) - [@ohos.bluetooth (蓝牙)(待停用)](js-apis-bluetooth.md) - - [@ohos.bluetoothManager (蓝牙)(推荐)](js-apis-bluetoothManager.md) + - [@ohos.bluetoothManager (蓝牙)(待停用)](js-apis-bluetoothManager.md) - [@ohos.connectedTag (有源标签)](js-apis-connectedTag.md) - [@ohos.nfc.cardEmulation (标准NFC-cardEmulation)](js-apis-cardEmulation.md) - [@ohos.nfc.controller (标准NFC)](js-apis-nfcController.md) diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-a2dp.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-a2dp.md new file mode 100644 index 0000000000..c71ff7b62a --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-a2dp.md @@ -0,0 +1,184 @@ +# @ohos.bluetooth.a2dp (蓝牙a2dp模块) + +a2dp模块提供了访问蓝牙音频接口的方法。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + + +## 导入模块 + +```js +import a2dp from '@ohos.bluetooth.a2dp'; +``` + + +## a2dp.createA2dpSrcProfile + +createA2dpSrcProfile(): A2dpSourceProfile + +创建a2dp profile实例。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ----------------------------- | ---------- | +| A2dpSourceProfile | 返回该profile的实例。 | + +**示例：** + +```js +try { + let a2dpProfile = a2dp.createA2dpSrcProfile(); + console.info('a2dp success'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## A2dpSourceProfile + +使用A2dpSourceProfile方法之前需要创建该类的实例进行操作，通过createA2dpSrcProfile()方法构造此实例。 + + +### connect + +connect(deviceId: string): void + +发起设备的A2dp服务连接请求。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| deviceId | string | 是 | 远端设备地址。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let a2dpSrc = a2dp.createA2dpSrcProfile(); + a2dpSrc.connect('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### disconnect + +disconnect(deviceId: string): void + +断开设备的a2dp服务连接。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| deviceId | string | 是 | 远端设备地址。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let a2dpSrc = a2dp.createA2dpSrcProfile(); + a2dpSrc.disconnect('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### getPlayingState + +getPlayingState(deviceId: string): PlayingState + +获取设备的播放状态。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| device | string | 是 | 远端设备地址。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------------- | ---------- | +| [PlayingState](#PlayingState) | 远端设备的播放状态。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let a2dpSrc = a2dp.createA2dpSrcProfile(); + let state = a2dpSrc.getPlayingState('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + +## PlayingState + +枚举，蓝牙A2DP 播放状态。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| ----------------- | ------ | ------- | +| STATE_NOT_PLAYING | 0x0000 | 表示未播放。 | +| STATE_PLAYING | 0x0001 | 表示正在播放。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-access.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-access.md new file mode 100644 index 0000000000..3220b7eb30 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-access.md @@ -0,0 +1,207 @@ +# @ohos.bluetooth.access (蓝牙access模块) + +access模块提供了打开和关闭蓝牙、获取蓝牙状态的方法。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + +```js +import access from '@ohos.bluetooth.access'; +``` + + +## access.enableBluetooth + +enableBluetooth(): void + +开启蓝牙。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------ | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + access.enableBluetooth(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## access.disableBluetooth + +disableBluetooth(): void + +关闭蓝牙。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +|错误码ID | 错误信息 | +| -------- | ------------------ | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + access.disableBluetooth(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## access.getState + +getState(): BluetoothState + +获取蓝牙开关状态。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ---------------- | +| [BluetoothState](#bluetoothstate) | 表示蓝牙开关状态。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +|错误码ID | 错误信息 | +| -------- | ------------------ | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let state = access.getState(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## access.on('stateChange') + +on(type: "stateChange", callback: Callback<BluetoothState>): void + +订阅蓝牙设备开关状态事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------- | ----- | ---------------------------------------------------------- | +| type | string | 是 | 填写"stateChange"字符串，表示蓝牙状态改变事件。 | +| callback | Callback<[BluetoothState](#bluetoothstate)> | 是 | 表示回调函数的入参，蓝牙状态。回调函数由用户创建通过该接口注册。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +|错误码ID | 错误信息 | +| -------- | ------------------ | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('bluetooth state = '+ JSON.stringify(data)); +} +try { + access.on('stateChange', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## access.off('stateChange') + +off(type: "stateChange", callback?: Callback<BluetoothState>): void + +取消订阅蓝牙设备开关状态事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"stateChange"字符串，表示蓝牙状态改变事件。 | +| callback | Callback<[BluetoothState](#bluetoothstate)> | 否 | 表示取消订阅蓝牙状态改变事件上报。不填该参数则取消订阅该type对应的所有回调。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('bluetooth state = '+ JSON.stringify(data)); +} +try { + access.on('stateChange', onReceiveEvent); + access.off('stateChange', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## BluetoothState + +枚举，蓝牙开关状态。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| --------------------- | ---- | ------------------ | +| STATE_OFF | 0 | 表示蓝牙已关闭。 | +| STATE_TURNING_ON | 1 | 表示蓝牙正在打开。 | +| STATE_ON | 2 | 表示蓝牙已打开。 | +| STATE_TURNING_OFF | 3 | 表示蓝牙正在关闭。 | +| STATE_BLE_TURNING_ON | 4 | 表示蓝牙正在打开LE-only模式。 | +| STATE_BLE_ON | 5 | 表示蓝牙正处于LE-only模式。 | +| STATE_BLE_TURNING_OFF | 6 | 表示蓝牙正在关闭LE-only模式。 | + diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-baseProfile.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-baseProfile.md new file mode 100644 index 0000000000..7c8c593a3f --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-baseProfile.md @@ -0,0 +1,388 @@ +# @ohos.bluetooth.baseProfile (蓝牙baseProfile模块) + +baseProfile模块提供了基础的profile方法。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + + +## 导入模块 + +```js +import baseProfile from '@ohos.bluetooth.baseProfile'; +``` + + +## ConnectionStrategy + +枚举，表示Profile的连接策略。 + +**系统接口：** 此接口为系统接口。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| -------------------------------- | ------ | --------------- | +| CONNECTION_STRATEGY_UNSUPPORTED | 0 | 当设备未配对时的默认连接策略。
此接口为系统接口。 | +| CONNECTION_STRATEGY_ALLOWED | 1 | 设备允许接受或发起配对时的连接策略。
此接口为系统接口。 | +| CONNECTION_STRATEGY_FORBIDDEN | 2 | 设备不允许接受或发起配对时的连接策略。
此接口为系统接口。 | + + +## StateChangeParam + +描述profile状态改变参数。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| -------- | ----------------------------- | ---- | ---- | ------------------------------- | +| deviceId | string | 是 | 否 | 表示蓝牙设备地址。 | +| state | ProfileConnectionState | 是 | 否 | 表示蓝牙设备的profile连接状态。 | + + +## baseProfile.setConnectionStrategy + +setConnectionStrategy(deviceId: string, strategy: ConnectionStrategy, callback: AsyncCallback<void>): void + +设置该设备Profile的连接策略。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| strategy | [ConnectionStrategy](#connectionstrategy) | 是 |Profile的连接策略。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当设置成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +import a2dp from '@ohos.bluetooth.a2dp'; +try { + let a2dpSrc = a2dp.createA2dpSrcProfile(); + let setRet = a2dpSrc.setConnectionStrategy('XX:XX:XX:XX:XX:XX', 0, (err, data) => { + console.info('setConnectionStrategy, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data)); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + +## baseProfile.setConnectionStrategy + +setConnectionStrategy(deviceId: string, strategy: ConnectionStrategy): Promise<void> + +设置该设备Profile的连接策略。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| strategy | [ConnectionStrategy](#connectionstrategy) | 是 |Profile的连接策略。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<void> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +import a2dp from '@ohos.bluetooth.a2dp'; +try { + let a2dpSrc = a2dp.createA2dpSrcProfile(); + let setRet = a2dpSrc.setConnectionStrategy('XX:XX:XX:XX:XX:XX', 1).then((data) => { + console.info('setConnectionStrategy'); + }, (err) => { + console.error('setConnectionStrategy errCode: ' + err.code + ', errMessage: ' + err.message); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + +## baseProfile.getConnectionStrategy + +getConnectionStrategy(deviceId: string, callback: AsyncCallback<ConnectionStrategy>): void + +获取该Profile的连接策略。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| callback | AsyncCallback<[ConnectionStrategy](#connectionstrategy)> | 是 | 回调函数。当获取策略成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +import a2dp from '@ohos.bluetooth.a2dp'; +try { + let a2dpSrc = a2dp.createA2dpSrcProfile(); + let setRet = a2dpSrc.getConnectionStrategy('XX:XX:XX:XX:XX:XX', 0, (err, data) => { + console.info('getConnectionStrategy, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data)); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + +## baseProfile.getConnectionStrategy + +getConnectionStrategy(deviceId: string): Promise<ConnectionStrategy> + +获取该Profile的连接策略。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<[ConnectionStrategy](#connectionstrategy)> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +import a2dp from '@ohos.bluetooth.a2dp'; +try { + let a2dpSrc = a2dp.createA2dpSrcProfile(); + let setRet = a2dpSrc.getConnectionStrategy('XX:XX:XX:XX:XX:XX', 1).then((data) => { + console.info('getConnectionStrategy'); + }, (error) => { + console.error('getConnectionStrategy errCode: ' + err.code + ', errMessage: ' + err.message); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## baseProfile.getConnectedDevices + +getConnectedDevices(): Array<string> + +获取已连接设备列表。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------------- | +| Array<string> | 返回当前已连接设备的地址。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +import a2dp from '@ohos.bluetooth.a2dp'; +try { + let a2dpSrc = a2dp.createA2dpSrcProfile(); + let retArray = a2dpSrc.getConnectedDevices(); +} catch (err) { + console.error("errCode:" + err.code + ",errMessage:" + err.message); +} +``` + + +## baseProfile.getConnectionState + +getConnectionState(deviceId: string): ProfileConnectionState + +获取设备profile的连接状态。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| deviceId | string | 是 | 远端设备地址。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------------- | ----------------------- | +| [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 返回profile的连接状态。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +import a2dp from '@ohos.bluetooth.a2dp'; +try { + let a2dpSrc = a2dp.createA2dpSrcProfile(); + let ret = a2dpSrc.getConnectionState('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## baseProfile.on('connectionStateChange') + +on(type: 'connectionStateChange', callback: Callback<StateChangeParam>): void + +订阅连接状态变化事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"connectionStateChange"字符串，表示连接状态变化事件。 | +| callback | Callback<[StateChangeParam](#statechangeparam)> | 是 | 表示回调函数的入参。 | + +**示例：** + +```js +import a2dp from '@ohos.bluetooth.a2dp'; +try { + function onReceiveEvent(data) { + console.info('a2dp state = '+ JSON.stringify(data)); + } + let a2dpSrc = a2dp.createA2dpSrcProfile(); + a2dpSrc.on('connectionStateChange', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## baseProfile.off('connectionStateChange') + +off(type: 'connectionStateChange', callback?: Callback<[StateChangeParam](#StateChangeParam)>): void + +取消订阅a2dp连接状态变化事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"connectionStateChange"字符串，表示连接状态变化事件。 | +| callback | Callback<[StateChangeParam](#StateChangeParam)> | 否 | 表示回调函数的入参。 | + +**示例：** + +```js +import a2dp from '@ohos.bluetooth.a2dp'; +try { + function onReceiveEvent(data) { + console.info('a2dp state = '+ JSON.stringify(data)); + } + let a2dpSrc = a2dp.createA2dpSrcProfile(); + a2dpSrc.on('connectionStateChange', onReceiveEvent); + a2dpSrc.off('connectionStateChange', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-ble.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-ble.md new file mode 100644 index 0000000000..d8e3fee736 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-ble.md @@ -0,0 +1,2539 @@ +# @ohos.bluetooth.ble (蓝牙ble模块) + +ble模块提供了访问蓝牙个人区域网相关功能的方法。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + + +## 导入模块 + +```js +import ble from '@ohos.bluetooth.ble'; +``` + + +## ble.createGattServer + +createGattServer(): GattServer + +创建Gatt profile实例。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ----------------------------- | ---------- | +| GattServer | 返回一个JavaScript Gatt服务的实例。 | + +**示例：** + +```js +let gattServer = ble.createGattServer(); +console.info('gatt success'); +``` + + +## ble.createGattClientDevice + +createGattClientDevice(deviceId: string): GattClientDevice + +创建一个可使用的GattClientDevice实例。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------ | +| deviceId | string | 是 | 对端设备地址， 例如："XX:XX:XX:XX:XX:XX"。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------- | ------------------------------------ | +| [GattClientDevice](#gattclientdevice) | client端类，使用client端方法之前需要创建该类的实例进行操作。 | + +**示例：** + +```js +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## ble.getConnectedBLEDevices + +getConnectedBLEDevices(): Array<string> + +获取和当前设备连接的BLE设备。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------------- | +| Array<string> | 返回当前设备作为Server端时连接BLE设备地址集合。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let result = ble.getConnectedBLEDevices(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## ble.startBLEScan + +startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void + +发起BLE扫描流程。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | -------------------------------------- | ---- | ----------------------------------- | +| filters | Array<[ScanFilter](#scanfilter)> | 是 | 表示扫描结果过滤策略集合，如果不使用过滤的方式，该参数设置为null。 | +| options | [ScanOptions](#scanoptions) | 否 | 表示扫描的参数配置，可选参数。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('BLE scan device find result = '+ JSON.stringify(data)); +} +try { + ble.on("BLEDeviceFind", onReceiveEvent); + ble.startBLEScan( + [{ + deviceId:"XX:XX:XX:XX:XX:XX", + name:"test", + serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" + }], + { + interval: 500, + dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER, + matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE, + } + ); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## ble.stopBLEScan + +stopBLEScan(): void + +停止BLE扫描流程。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + ble.stopBLEScan(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## ble.startAdvertising + +startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void + +开始发送BLE广播。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ------------------------------------- | ---- | -------------- | +| setting | [AdvertiseSetting](#advertisesetting) | 是 | BLE广播的相关参数。 | +| advData | [AdvertiseData](#advertisedata) | 是 | BLE广播包内容。 | +| advResponse | [AdvertiseData](#advertisedata) | 否 | BLE回复扫描请求回复响应。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +let manufactureValueBuffer = new Uint8Array(4); +manufactureValueBuffer[0] = 1; +manufactureValueBuffer[1] = 2; +manufactureValueBuffer[2] = 3; +manufactureValueBuffer[3] = 4; + +let serviceValueBuffer = new Uint8Array(4); +serviceValueBuffer[0] = 4; +serviceValueBuffer[1] = 6; +serviceValueBuffer[2] = 7; +serviceValueBuffer[3] = 8; +console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); +console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); +try { + ble.startAdvertising({ + interval:150, + txPower:0, + connectable:true, + },{ + serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], + manufactureData:[{ + manufactureId:4567, + manufactureValue:manufactureValueBuffer.buffer + }], + serviceData:[{ + serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", + serviceValue:serviceValueBuffer.buffer + }], + },{ + serviceUuids:["00001889-0000-1000-8000-00805f9b34fb"], + manufactureData:[{ + manufactureId:1789, + manufactureValue:manufactureValueBuffer.buffer + }], + serviceData:[{ + serviceUuid:"00001889-0000-1000-8000-00805f9b34fb", + serviceValue:serviceValueBuffer.buffer + }], + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## ble.stopAdvertising + +stopAdvertising(): void + +停止发送BLE广播。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + ble.stopAdvertising(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## ble.on('BLEDeviceFind') + +on(type: 'BLEDeviceFind', callback: Callback<Array<ScanResult>>): void + +订阅BLE设备发现上报事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ----------------------------------- | +| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | +| callback | Callback<Array<[ScanResult](#scanresult)>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('bluetooth device find = '+ JSON.stringify(data)); +} +try { + ble.on('BLEDeviceFind', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## ble.off('BLEDeviceFind') + +off(type: 'BLEDeviceFind', callback?: Callback<Array<ScanResult>>): void + +取消订阅BLE设备发现上报事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | +| callback | Callback<Array<[ScanResult](#scanresult)>> | 否 | 表示取消订阅BLE设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('bluetooth device find = '+ JSON.stringify(data)); +} +try { + ble.on('BLEDeviceFind', onReceiveEvent); + ble.off('BLEDeviceFind', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## GattServer + +server端类，使用server端方法之前需要创建该类的实例进行操作，通过createGattServer()方法构造此实例。 + + +### addService + +addService(service: GattService): void + +server端添加服务。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | --------------------------- | ---- | ------------------------ | +| service | [GattService](#gattservice) | 是 | 服务端的service数据。BLE广播的相关参数 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +// 创建descriptors +let descriptors = []; +let arrayBuffer = new ArrayBuffer(8); +let descV = new Uint8Array(arrayBuffer); +descV[0] = 11; +let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; +descriptors[0] = descriptor; + +// 创建characteristics +let characteristics = []; +let arrayBufferC = new ArrayBuffer(8); +let cccV = new Uint8Array(arrayBufferC); +cccV[0] = 1; +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; +let characteristicN = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; +characteristics[0] = characteristic; + +// 创建gattService +let gattService = {serviceUuid:'00001810-0000-1000-8000-00805F9B34FB', isPrimary: true, characteristics:characteristics, includeServices:[]}; + +try { + gattServer.addService(gattService); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### removeService + +removeService(serviceUuid: string): void + +删除已添加的服务。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ------ | ---- | ---------------------------------------- | +| serviceUuid | string | 是 | service的UUID，例如“00001810-0000-1000-8000-00805F9B34FB”。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +let server = ble.createGattServer(); +try { + server.removeService('00001810-0000-1000-8000-00805F9B34FB'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### close + +close(): void + +关闭服务端功能，去注册server在协议栈的注册，调用该接口后[GattServer](#gattserver)实例将不能再使用。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +let server = ble.createGattServer(); +try { + server.close(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### notifyCharacteristicChanged + +notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic, callback: AsyncCallback<void>): void + +server端特征值发生变化时，主动通知已连接的client设备。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | +| deviceId | string | 是 | 接收通知的client端设备地址，例如“XX:XX:XX:XX:XX:XX”。 | +| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | 是 | 通知的特征值数据。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当通知成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +let arrayBufferC = new ArrayBuffer(8); +let notifyCharacter = { + "serviceUuid": '00001810-0000-1000-8000-00805F9B34FB', + "characteristicUuid": '00001820-0000-1000-8000-00805F9B34FB', + "characteristicValue": arrayBufferC, + "confirm": true, +}; +try { + gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter, (err) => { + if (err) { + console.info('notifyCharacteristicChanged callback failed'); + } else { + console.info('notifyCharacteristicChanged callback successful'); + } + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### notifyCharacteristicChanged + +notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic): Promise<void> + +server端特征值发生变化时，主动通知已连接的client设备。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | +| deviceId | string | 是 | 接收通知的client端设备地址，例如“XX:XX:XX:XX:XX:XX”。 | +| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | 是 | 通知的特征值数据。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<void> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +let arrayBufferC = new ArrayBuffer(8); +let notifyCharacter = { + "serviceUuid": '00001810-0000-1000-8000-00805F9B34FB', + "characteristicUuid": '00001820-0000-1000-8000-00805F9B34FB', + "characteristicValue": arrayBufferC, + "confirm": true, +}; +try { + gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter).then(() => { + console.info('notifyCharacteristicChanged promise successfull'); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### sendResponse + +sendResponse(serverResponse: ServerResponse): void + +server端回复client端的读写请求。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------- | ---- | --------------- | +| serverResponse | [ServerResponse](#serverresponse) | 是 | server端回复的响应数据。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +/* send response */ +let arrayBufferCCC = new ArrayBuffer(8); +let cccValue = new Uint8Array(arrayBufferCCC); +cccValue[0] = 1123; +let serverResponse = { + 'deviceId': 'XX:XX:XX:XX:XX:XX', + 'transId': 0, + 'status': 0, + 'offset': 0, + 'value': arrayBufferCCC, +}; +try { + gattServer.sendResponse(serverResponse); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### on('characteristicRead') + +on(type: 'characteristicRead', callback: Callback<CharacteristicReadRequest>): void + +server端订阅特征值读请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------------------- | +| type | string | 是 | 填写"characteristicRead"字符串，表示特征值读请求事件。 | +| callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | 是 | 表示回调函数的入参，client端发送的读请求数据。 | + +**示例：** + +```js +let arrayBufferCCC = new ArrayBuffer(8); +let cccValue = new Uint8Array(arrayBufferCCC); +cccValue[0] = 1123; +function ReadCharacteristicReq(CharacteristicReadRequest) { + let deviceId = CharacteristicReadRequest.deviceId; + let transId = CharacteristicReadRequest.transId; + let offset = CharacteristicReadRequest.offset; + let characteristicUuid = CharacteristicReadRequest.characteristicUuid; + + let serverResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; + + try { + gattServer.sendResponse(serverResponse); + } catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); + } +} +gattServer.on('characteristicRead', ReadCharacteristicReq); +``` + + +### off('characteristicRead') + +off(type: 'characteristicRead', callback?: Callback<CharacteristicReadRequest>): void + +server端取消订阅特征值读请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"characteristicRead"字符串，表示特征值读请求事件。 | +| callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | 否 | 表示取消订阅特征值读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | + +**示例：** + +```js +gattServer.off('characteristicRead'); +``` + + +### on('characteristicWrite') + +on(type: 'characteristicWrite', callback: Callback<CharacteristicWriteRequest>): void + +server端订阅特征值写请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | -------------------------------------- | +| type | string | 是 | 填写"characteristicWrite"字符串，表示特征值写请求事件。 | +| callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | 是 | 表示回调函数的入参，client端发送的写请求数据。 | + +**示例：** + +```js +let arrayBufferCCC = new ArrayBuffer(8); +let cccValue = new Uint8Array(arrayBufferCCC); +function WriteCharacteristicReq(CharacteristicWriteRequest) { + let deviceId = CharacteristicWriteRequest.deviceId; + let transId = CharacteristicWriteRequest.transId; + let offset = CharacteristicWriteRequest.offset; + let isPrepared = CharacteristicWriteRequest.isPrepared; + let needRsp = CharacteristicWriteRequest.needRsp; + let value = new Uint8Array(CharacteristicWriteRequest.value); + let characteristicUuid = CharacteristicWriteRequest.characteristicUuid; + + cccValue[0] = value[0]; + let serverResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; + + try { + gattServer.sendResponse(serverResponse); + } catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); + } +} +gattServer.on('characteristicWrite', WriteCharacteristicReq); +``` + + +### off('characteristicWrite') + +off(type: 'characteristicWrite', callback?: Callback<CharacteristicWriteRequest>): void + +server端取消订阅特征值写请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"characteristicWrite"字符串，表示特征值写请求事件。 | +| callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | 否 | 表示取消订阅特征值写请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | + +**示例：** + +```js +gattServer.off('characteristicWrite'); +``` + + +### on('descriptorRead') + +on(type: 'descriptorRead', callback: Callback<DescriptorReadRequest>): void + +server端订阅描述符读请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | --------------------------------- | +| type | string | 是 | 填写"descriptorRead"字符串，表示描述符读请求事件。 | +| callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | 是 | 表示回调函数的入参，client端发送的读请求数据。 | + +**示例：** + +```js +let arrayBufferDesc = new ArrayBuffer(8); +let descValue = new Uint8Array(arrayBufferDesc); +descValue[0] = 1101; +function ReadDescriptorReq(DescriptorReadRequest) { + let deviceId = DescriptorReadRequest.deviceId; + let transId = DescriptorReadRequest.transId; + let offset = DescriptorReadRequest.offset; + let descriptorUuid = DescriptorReadRequest.descriptorUuid; + + let serverResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; + + try { + gattServer.sendResponse(serverResponse); + } catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); + } +} +gattServer.on('descriptorRead', ReadDescriptorReq); +``` + + +### off('descriptorRead') + +off(type: 'descriptorRead', callback?: Callback<DescriptorReadRequest>): void + +server端取消订阅描述符读请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"descriptorRead"字符串，表示描述符读请求事件。 | +| callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | 否 | 表示取消订阅描述符读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | + +**示例：** + +```js +gattServer.off('descriptorRead'); +``` + + +### on('descriptorWrite') + +on(type: 'descriptorWrite', callback: Callback<DescriptorWriteRequest>): void + +server端订阅描述符写请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------- | +| type | string | 是 | 填写"descriptorWrite"字符串，表示描述符写请求事件。 | +| callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | 是 | 表示回调函数的入参，client端发送的写请求数据。 | + +**示例：** + +```js +let arrayBufferDesc = new ArrayBuffer(8); +let descValue = new Uint8Array(arrayBufferDesc); +function WriteDescriptorReq(DescriptorWriteRequest) { + let deviceId = DescriptorWriteRequest.deviceId; + let transId = DescriptorWriteRequest.transId; + let offset = DescriptorWriteRequest.offset; + let isPrepared = DescriptorWriteRequest.isPrepared; + let needRsp = DescriptorWriteRequest.needRsp; + let value = new Uint8Array(DescriptorWriteRequest.value); + let descriptorUuid = DescriptorWriteRequest.descriptorUuid; + + descValue[0] = value[0]; + let serverResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; + + try { + gattServer.sendResponse(serverResponse); + } catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); + } +} +gattServer.on('descriptorRead', WriteDescriptorReq); +``` + + +### off('descriptorWrite') + +off(type: 'descriptorWrite', callback?: Callback<DescriptorWriteRequest>): void + +server端取消订阅描述符写请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"descriptorWrite"字符串，表示描述符写请求事件。 | +| callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | 否 | 表示取消订阅描述符写请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | + +**示例：** + +```js +gattServer.off('descriptorWrite'); +``` + + +### on('connectionStateChange') + +on(type: 'connectionStateChange', callback: Callback<BLEConnectionChangeState>): void + +server端订阅BLE连接状态变化事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"connectionStateChange"字符串，表示BLE连接状态变化事件。 | +| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 是 | 表示回调函数的入参，连接状态。 | + +**示例：** + +```js +function Connected(BLEConnectionChangeState) { + let deviceId = BLEConnectionChangeState.deviceId; + let status = BLEConnectionChangeState.state; +} +gattServer.on('connectionStateChange', Connected); +``` + + +### off('connectionStateChange') + +off(type: 'connectionStateChange', callback?: Callback<BLEConnectionChangeState>): void + +server端取消订阅BLE连接状态变化事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"connectionStateChange"字符串，表示BLE连接状态变化事件。 | +| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 否 | 表示取消订阅BLE连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。 | + +**示例：** + +```js +gattServer.off('connectionStateChange'); +``` + + +## GattClientDevice + +client端类，使用client端方法之前需要创建该类的实例进行操作，通过createGattClientDevice(deviceId: string)方法构造此实例。 + + +### connect + +connect(): void + +client端发起连接远端蓝牙低功耗设备。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.connect(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### disconnect + +disconnect(): void + +client端断开与远端蓝牙低功耗设备的连接。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.disconnect(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### close + +close(): void + +关闭客户端功能，注销client在协议栈的注册，调用该接口后[GattClientDevice](#gattclientdevice)实例将不能再使用。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.close(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### getDeviceName + +getDeviceName(callback: AsyncCallback<string>): void + +client获取远端蓝牙低功耗设备名。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------- | +| callback | AsyncCallback<string> | 是 | client获取对端server设备名，通过注册回调函数获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +// callback +try { + let gattClient = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); + gattClient.connect(); + let deviceName = gattClient.getDeviceName((err, data)=> { + console.info('device name err ' + JSON.stringify(err)); + console.info('device name' + JSON.stringify(data)); + }) +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### getDeviceName + +getDeviceName(): Promise<string> + +client获取远端蓝牙低功耗设备名。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| --------------------- | ---------------------------------- | +| Promise<string> | client获取对端server设备名，通过promise形式获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +// promise +try { + let gattClient = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); + gattClient.connect(); + let deviceName = gattClient.getDeviceName().then((data) => { + console.info('device name' + JSON.stringify(data)); + }) +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### getServices + +getServices(callback: AsyncCallback<Array<GattService>>): void + +client端获取蓝牙低功耗设备的所有服务，即服务发现 。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------ | +| callback | AsyncCallback<Array<[GattService](#gattservice)>> | 是 | client进行服务发现，通过注册回调函数获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +// callkback 模式 +function getServices(code, gattServices) { + if (code.code == 0) { + let services = gattServices; + console.log('bluetooth code is ' + code.code); + console.log('bluetooth services size is ', services.length); + + for (let i = 0; i < services.length; i++) { + console.log('bluetooth serviceUuid is ' + services[i].serviceUuid); + } + } +} + +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.connect(); + device.getServices(getServices); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### getServices + +getServices(): Promise<Array<GattService>> + +client端获取蓝牙低功耗设备的所有服务，即服务发现。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | --------------------------- | +| Promise<Array<[GattService](#gattservice)>> | client进行服务发现，通过promise形式获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +// Promise 模式 +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.connect(); + device.getServices().then(result => { + console.info('getServices successfully:' + JSON.stringify(result)); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### readCharacteristicValue + +readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void + +client端读取蓝牙低功耗设备特定服务的特征值。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ---------------------------------------- | ---- | ----------------------- | +| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 待读取的特征值。 | +| callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | 是 | client读取特征值，通过注册回调函数获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2901000 | Read forbidden. | +|2900099 | Operation failed. | + +**示例：** + +```js +function readCcc(code, BLECharacteristic) { + if (code.code != 0) { + return; + } + console.log('bluetooth characteristic uuid: ' + BLECharacteristic.characteristicUuid); + let value = new Uint8Array(BLECharacteristic.characteristicValue); + console.log('bluetooth characteristic value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); +} + +let descriptors = []; +let bufferDesc = new ArrayBuffer(8); +let descV = new Uint8Array(bufferDesc); +descV[0] = 11; +let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', +characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', +descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; +descriptors[0] = descriptor; + +let bufferCCC = new ArrayBuffer(8); +let cccV = new Uint8Array(bufferCCC); +cccV[0] = 1; +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', +characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', +characteristicValue: bufferCCC, descriptors:descriptors}; + +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.readCharacteristicValue(characteristic, readCcc); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### readCharacteristicValue + +readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic> + +client端读取蓝牙低功耗设备特定服务的特征值。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------- | ---- | -------- | +| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 待读取的特征值。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------- | +| Promise<[BLECharacteristic](#blecharacteristic)> | client读取特征值，通过promise形式获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2901000 | Read forbidden. | +|2900099 | Operation failed. | + +**示例：** + +```js +let descriptors = []; +let bufferDesc = new ArrayBuffer(8); +let descV = new Uint8Array(bufferDesc); +descV[0] = 11; +let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', +characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', +descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; +descriptors[0] = descriptor; + +let bufferCCC = new ArrayBuffer(8); +let cccV = new Uint8Array(bufferCCC); +cccV[0] = 1; +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', +characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', +characteristicValue: bufferCCC, descriptors:descriptors}; + +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.readCharacteristicValue(characteristic); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### readDescriptorValue + +readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void + +client端读取蓝牙低功耗设备特定的特征包含的描述符。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ---------------------------------------- | ---- | ----------------------- | +| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 待读取的描述符。 | +| callback | AsyncCallback<[BLEDescriptor](#bledescriptor)> | 是 | client读取描述符，通过注册回调函数获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2901000 | Read forbidden. | +|2900099 | Operation failed. | + +**示例：** + +```js +function readDesc(code, BLEDescriptor) { + if (code.code != 0) { + return; + } + console.log('bluetooth descriptor uuid: ' + BLEDescriptor.descriptorUuid); + let value = new Uint8Array(BLEDescriptor.descriptorValue); + console.log('bluetooth descriptor value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); +} + +let bufferDesc = new ArrayBuffer(8); +let descV = new Uint8Array(bufferDesc); +descV[0] = 11; +let descriptor = { + serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', + descriptorValue: bufferDesc +}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.readDescriptorValue(descriptor, readDesc); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### readDescriptorValue + +readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor> + +client端读取蓝牙低功耗设备特定的特征包含的描述符。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------------- | ---- | -------- | +| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 待读取的描述符。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------- | +| Promise<[BLEDescriptor](#bledescriptor)> | client读取描述符，通过promise形式获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2901000 | Read forbidden. | +|2900099 | Operation failed. | + +**示例：** + +```js +let bufferDesc = new ArrayBuffer(8); +let descV = new Uint8Array(bufferDesc); +descV[0] = 11; +let descriptor = { + serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', + descriptorValue: bufferDesc +}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.readDescriptorValue(descriptor); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### writeCharacteristicValue + +writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<void>): void + +client端向低功耗蓝牙设备写入特定的特征值。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------- | ---- | ------------------- | +| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙设备特征对应的二进制值及其它参数。 | +| writeType | GattWriteType | 是 | 蓝牙设备特征的写入类型。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2901001 | Write forbidden. | +|2900099 | Operation failed. | + +**示例：** + +```js +let descriptors = []; +let bufferDesc = new ArrayBuffer(8); +let descV = new Uint8Array(bufferDesc); +descV[0] = 11; +let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; +descriptors[0] = descriptor; + +let bufferCCC = new ArrayBuffer(8); +let cccV = new Uint8Array(bufferCCC); +cccV[0] = 1; +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + characteristicValue: bufferCCC, descriptors:descriptors}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.writeCharacteristicValue(characteristic); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### writeCharacteristicValue + +writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<void> + +client端向低功耗蓝牙设备写入特定的特征值。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------- | ---- | ------------------- | +| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙设备特征对应的二进制值及其它参数。 | +| writeType | GattWriteType | 是 | 蓝牙设备特征的写入类型。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------- | +| Promise<void> | client读取描述符，通过promise形式获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2901001 | Write forbidden. | +|2900099 | Operation failed. | + +**示例：** + +```js +let descriptors = []; +let bufferDesc = new ArrayBuffer(8); +let descV = new Uint8Array(bufferDesc); +descV[0] = 11; +let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; +descriptors[0] = descriptor; + +let bufferCCC = new ArrayBuffer(8); +let cccV = new Uint8Array(bufferCCC); +cccV[0] = 1; +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + characteristicValue: bufferCCC, descriptors:descriptors}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.writeCharacteristicValue(characteristic); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### writeDescriptorValue + +writeDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<void>): void + +client端向低功耗蓝牙设备特定的描述符写入二进制数据。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------------- | ---- | ------------------ | +| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 蓝牙设备描述符的二进制值及其它参数。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2901001 | Write forbidden. | +|2900099 | Operation failed. | + +**示例：** + +```js +let bufferDesc = new ArrayBuffer(8); +let descV = new Uint8Array(bufferDesc); +descV[0] = 22; +let descriptor = { + serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', + descriptorValue: bufferDesc +}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.writeDescriptorValue(descriptor); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### writeDescriptorValue + +writeDescriptorValue(descriptor: BLEDescriptor): Promise<void> + +client端向低功耗蓝牙设备特定的描述符写入二进制数据。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------------- | ---- | ------------------ | +| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 蓝牙设备描述符的二进制值及其它参数。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------- | +| Promise<void> | client读取描述符，通过promise形式获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2901001 | Write forbidden. | +|2900099 | Operation failed. | + +**示例：** + +```js +let bufferDesc = new ArrayBuffer(8); +let descV = new Uint8Array(bufferDesc); +descV[0] = 22; +let descriptor = { + serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', + descriptorValue: bufferDesc +}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.writeDescriptorValue(descriptor); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### getRssiValue + +getRssiValue(callback: AsyncCallback<number>): void + +client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------ | +| callback | AsyncCallback<number> | 是 | 返回信号强度，单位 dBm，通过注册回调函数获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +// callback +try { + let gattClient = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); + gattClient.connect(); + let rssi = gattClient.getRssiValue((err, data)=> { + console.info('rssi err ' + JSON.stringify(err)); + console.info('rssi value' + JSON.stringify(data)); + }) +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### getRssiValue + +getRssiValue(): Promise<number> + +client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| --------------------- | --------------------------------- | +| Promise<number> | 返回信号强度，单位 dBm，通过promise形式获取。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +// promise +try { + let gattClient = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); + let rssi = gattClient.getRssiValue().then((data) => { + console.info('rssi' + JSON.stringify(data)); + }) +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### setBLEMtuSize + +setBLEMtuSize(mtu: number): void + +client协商远端蓝牙低功耗设备的最大传输单元（Maximum Transmission Unit, MTU），调用[connect](#connect)接口连接成功后才能使用。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | -------------- | +| mtu | number | 是 | 设置范围为22~512字节。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.setBLEMtuSize(128); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### setCharacteristicChangeNotification + +setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void + +向服务端发送设置通知此特征值请求。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------- | ---- | ----------------------------- | +| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | +| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当发送成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +// 创建descriptors +let descriptors = []; +let arrayBuffer = new ArrayBuffer(8); +let descV = new Uint8Array(arrayBuffer); +descV[0] = 11; +let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; +descriptors[0] = descriptor; +let arrayBufferC = new ArrayBuffer(8); +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.setCharacteristicChangeNotification(characteristic, false); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} + +``` + + +### setCharacteristicChangeNotification + +setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean): Promise<void> + +向服务端发送设置通知此特征值请求。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------- | ---- | ----------------------------- | +| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | +| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------- | +| Promise<void> | 返回Promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +// 创建descriptors +let descriptors = []; +let arrayBuffer = new ArrayBuffer(8); +let descV = new Uint8Array(arrayBuffer); +descV[0] = 11; +let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; +descriptors[0] = descriptor; +let arrayBufferC = new ArrayBuffer(8); +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.setCharacteristicChangeNotification(characteristic, false); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} + +``` + + +### setCharacteristicChangeIndication + +setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void + +向服务端发送设置通知此特征值请求。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------- | ---- | ----------------------------- | +| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | +| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当发送成功，err为undefined，否则为错误对象。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------- | +| Promise<void> | 返回Promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +// 创建descriptors +let descriptors = []; +let arrayBuffer = new ArrayBuffer(8); +let descV = new Uint8Array(arrayBuffer); +descV[0] = 11; +let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; +descriptors[0] = descriptor; +let arrayBufferC = new ArrayBuffer(8); +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.setCharacteristicChangeIndication(characteristic, false); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} + +``` + + +### setCharacteristicChangeIndication + +setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean): Promise<void> + +向服务端发送设置通知此特征值请求。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | --------------------------------------- | ---- | ----------------------------- | +| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | +| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | -------------------------- | +| Promise<void> | 返回Promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +// 创建descriptors +let descriptors = []; +let arrayBuffer = new ArrayBuffer(8); +let descV = new Uint8Array(arrayBuffer); +descV[0] = 11; +let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', + descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; +descriptors[0] = descriptor; +let arrayBufferC = new ArrayBuffer(8); +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.setCharacteristicChangeIndication(characteristic, false); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} + +``` + + +### on('BLECharacteristicChange') + +on(type: 'BLECharacteristicChange', callback: Callback<BLECharacteristic>): void + +订阅蓝牙低功耗设备的特征值变化事件。需要先调用setNotifyCharacteristicChanged接口才能接收server端的通知。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"BLECharacteristicChange"字符串，表示特征值变化事件。 | +| callback | Callback<[BLECharacteristic](#blecharacteristic)> | 是 | 表示蓝牙低功耗设备的特征值变化事件的回调函数。 | + +**示例：** + +```js +function CharacteristicChange(CharacteristicChangeReq) { + let serviceUuid = CharacteristicChangeReq.serviceUuid; + let characteristicUuid = CharacteristicChangeReq.characteristicUuid; + let value = new Uint8Array(CharacteristicChangeReq.characteristicValue); +} +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.on('BLECharacteristicChange', CharacteristicChange); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### off('BLECharacteristicChange') + +off(type: 'BLECharacteristicChange', callback?: Callback<BLECharacteristic>): void + +取消订阅蓝牙低功耗设备的特征值变化事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"BLECharacteristicChange"字符串，表示特征值变化事件。 | +| callback | Callback<[BLECharacteristic](#blecharacteristic)> | 否 | 表示取消订阅蓝牙低功耗设备的特征值变化事件。不填该参数则取消订阅该type对应的所有回调。 | + +**示例：** + +```js +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.off('BLECharacteristicChange'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### on('BLEConnectionStateChange') + +on(type: 'BLEConnectionStateChange', callback: Callback<BLEConnectionChangeState>): void + +client端订阅蓝牙低功耗设备的连接状态变化事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。 | +| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 是 | 表示连接状态，已连接或断开。 | + +**示例：** + +```js +function ConnectStateChanged(state) { + console.log('bluetooth connect state changed'); + let connectState = state.state; +} +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.on('BLEConnectionStateChange', ConnectStateChanged); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### off('BLEConnectionStateChange') + +off(type: 'BLEConnectionStateChange', callback?: Callback<BLEConnectionChangeState>): void + +取消订阅蓝牙低功耗设备的连接状态变化事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。 | +| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 否 | 表示取消订阅蓝牙低功耗设备的连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。 | + +**示例：** + +```js +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.off('BLEConnectionStateChange'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### on('BLEMtuChange') + +on(type: 'BLEMtuChange', callback: Callback<number>): void + +订阅Mtu状态变化事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"BLEMtuChange"字符串，表示Mtu状态变化事件。 | +| callback | Callback<number> | 是 | 表示Mtu状态，已连接或是断开。 | + +**示例：** + +```js +try { + let gattClient = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + gattClient.on('BLEMtuChange', (mtu) => { + console.info('BLEMtuChange, mtu: ' + mtu); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### off('BLEMtuChange') + +off(type: 'BLEMtuChange', callback?: Callback<number>): void + +订阅Mtu状态变化事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"BLEMtuChange"字符串，表示Mtu状态变化事件。 | +| callback | Callback<number> | 否 | 表示取消订阅Mtu状态变化事件。不填该参数则取消订阅该type对应的所有回调。 | + +**示例：** + +```js +try { + let device = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); + device.off('BLEMtuChange'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## GattService + +描述service的接口参数定义。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| --------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | +| serviceUuid | string | 是 | 是 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | +| isPrimary | boolean | 是 | 是 | 如果是主服务设置为true，否则设置为false。 | +| characteristics | Array<[BLECharacteristic](#blecharacteristic)> | 是 | 是 | 当前服务包含的特征列表。 | +| includeServices | Array<[GattService](#gattservice)> | 是 | 是 | 当前服务依赖的其它服务。 | + + +## BLECharacteristic + +描述characteristic的接口参数定义 。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | +| serviceUuid | string | 是 | 是 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | +| characteristicUuid | string | 是 | 是 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | +| characteristicValue | ArrayBuffer | 是 | 是 | 特征对应的二进制值。 | +| descriptors | Array<[BLEDescriptor](#bledescriptor)> | 是 | 是 | 特定特征的描述符列表。 | +| properties | [GattProperties](#gattproperties) | 是 | 是 | 特定特征的属性描述。 | + + +## BLEDescriptor + +描述descriptor的接口参数定义 。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | +| serviceUuid | string | 是 | 是 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | +| characteristicUuid | string | 是 | 是 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | +| descriptorUuid | string | 是 | 是 | 描述符（descriptor）的UUID，例如：00002902-0000-1000-8000-00805f9b34fb。 | +| descriptorValue | ArrayBuffer | 是 | 是 | 描述符对应的二进制值。 | + + +## NotifyCharacteristic + +描述server端特征值变化时发送的特征通知参数定义。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------------- | ----------- | ---- | ---- | ---------------------------------------- | +| serviceUuid | string | 是 | 是 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | +| characteristicUuid | string | 是 | 是 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | +| characteristicValue | ArrayBuffer | 是 | 是 | 特征对应的二进制值。 | +| confirm | boolean | 是 | 是 | 如果是notification则对端回复确认设置为true，如果是indication则对端不需要回复确认设置为false。 | + + +## CharacteristicReadRequest + +描述server端订阅后收到的特征值读请求事件参数结构。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------------ | ------ | ---- | ---- | ---------------------------------------- | +| deviceId | string | 是 | 否 | 表示发送特征值读请求的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| transId | number | 是 | 否 | 表示读请求的传输ID，server端回复响应时需填写相同的传输ID。 | +| offset | number | 是 | 否 | 表示读特征值数据的起始位置。例如：k表示从第k个字节开始读，server端回复响应时需填写相同的offset。 | +| characteristicUuid | string | 是 | 否 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | +| serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | + + +## CharacteristicWriteRequest + +描述server端订阅后收到的特征值写请求事件参数结构。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------------ | ------ | ---- | ---- | ---------------------------------------- | +| deviceId | string | 是 | 否 | 表示发送特征值写请求的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| transId | number | 是 | 否 | 表示写请求的传输ID，server端回复响应时需填写相同的传输ID。 | +| offset | number | 是 | 否 | 表示写特征值数据的起始位置。例如：k表示从第k个字节开始写，server端回复响应时需填写相同的offset。 | +| isPrepared | boolean | 是 | 否 | 表示写请求是否立即执行。 | +| needRsp | boolean | 是 | 否 | 表示是否要给client端回复响应。 | +| value | ArrayBuffer | 是 | 否 | 表示写入的描述符二进制数据。 | +| characteristicUuid | string | 是 | 否 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | +| serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | + + +## DescriptorReadRequest + +描述server端订阅后收到的描述符读请求事件参数结构。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------------ | ------ | ---- | ---- | ---------------------------------------- | +| deviceId | string | 是 | 否 | 表示发送描述符读请求的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| transId | number | 是 | 否 | 表示读请求的传输ID，server端回复响应时需填写相同的传输ID。 | +| offset | number | 是 | 否 | 表示读描述符数据的起始位置。例如：k表示从第k个字节开始读，server端回复响应时需填写相同的offset。 | +| descriptorUuid | string | 是 | 否 | 表示描述符（descriptor）的UUID，例如：00002902-0000-1000-8000-00805f9b34fb。 | +| characteristicUuid | string | 是 | 否 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | +| serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | + + +## DescriptorWriteRequest + +描述server端订阅后收到的描述符写请求事件参数结构。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | +| deviceId | string | 是 | 否 | 表示发送描述符写请求的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| transId | number | 是 | 否 | 表示写请求的传输ID，server端回复响应时需填写相同的传输ID。 | +| offset | number | 是 | 否 | 表示写描述符数据的起始位置。例如：k表示从第k个字节开始写，server端回复响应时需填写相同的offset。 | +| isPrepared | boolean | 是 | 否 | 表示写请求是否立即执行。 | +| needRsp | boolean | 是 | 否 | 表示是否要给client端回复响应。 | +| value | ArrayBuffer | 是 | 否 | 表示写入的描述符二进制数据。 | +| descriptorUuid | string | 是 | 否 | 表示描述符（descriptor）的UUID，例如：00002902-0000-1000-8000-00805f9b34fb。 | +| characteristicUuid | string | 是 | 否 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | +| serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | + + +## ServerResponse + +描述server端回复client端读/写请求的响应参数结构。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| -------- | ----------- | ---- | ---- | -------------------------------------- | +| deviceId | string | 是 | 否 | 表示远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| transId | number | 是 | 否 | 表示请求的传输ID，与订阅的读/写请求事件携带的ID保持一致。 | +| status | number | 是 | 否 | 表示响应的状态，设置为0即可，表示正常。 | +| offset | number | 是 | 否 | 表示请求的读/写起始位置，与订阅的读/写请求事件携带的offset保持一致。 | +| value | ArrayBuffer | 是 | 否 | 表示回复响应的二进制数据。 | + + +## BLEConnectionChangeState + +描述Gatt profile连接状态 。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| -------- | ------------------------------------------------- | ---- | ---- | --------------------------------------------- | +| deviceId | string | 是 | 否 | 表示远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| state | [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 是 | 是 | 表示BLE连接状态的枚举。 | + + +## ScanResult + +扫描结果上报数据。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| -------- | ----------- | ---- | ---- | ---------------------------------- | +| deviceId | string | 是 | 否 | 表示扫描到的设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| rssi | number | 是 | 否 | 表示扫描到的设备的rssi值。 | +| data | ArrayBuffer | 是 | 否 | 表示扫描到的设备发送的广播包。 | +| deviceName | string | 是 | 否 | 表示扫描到的设备名称。 | +| connectable | boolean | 是 | 否 | 表示扫描到的设备是否可连接。 | + + +## AdvertiseSetting + +描述蓝牙低功耗设备发送广播的参数。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ----------- | ------- | ---- | ---- | ---------------------------------------- | +| interval | number | 是 | 是 | 表示广播间隔，最小值设置32个slot表示20ms，最大值设置16384个slot，默认值设置为1600个slot表示1s。 | +| txPower | number | 是 | 是 | 表示发送功率，最小值设置-127，最大值设置1，默认值设置-7，单位dbm。 | +| connectable | boolean | 是 | 是 | 表示是否是可连接广播，默认值设置为true。 | + + +## AdvertiseData + +描述BLE广播数据包的内容。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| --------------- | ---------------------------------------- | ---- | ---- | --------------------------- | +| serviceUuids | Array<string> | 是 | 是 | 表示要广播的服务 UUID 列表。 | +| manufactureData | Array<[ManufactureData](#manufacturedata)> | 是 | 是 | 表示要广播的广播的制造商信息列表。 | +| serviceData | Array<[ServiceData](#servicedata)> | 是 | 是 | 表示要广播的服务数据列表。 | +| includeDeviceName | boolean | 是 | 是 | 表示是否携带设备名，可选参数。 | + + +## ManufactureData + +描述BLE广播数据包的内容。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ---------------- | ------------------- | ---- | ---- | ------------------ | +| manufactureId | number | 是 | 是 | 表示制造商的ID，由蓝牙SIG分配。 | +| manufactureValue | ArrayBuffer | 是 | 是 | 表示制造商发送的制造商数据。 | + + +## ServiceData + +描述广播包中服务数据内容。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------------ | ----------- | ---- | ---- | ---------- | +| serviceUuid | string | 是 | 是 | 表示服务的UUID。 | +| serviceValue | ArrayBuffer | 是 | 是 | 表示服务数据。 | + + +## ScanFilter + +扫描过滤参数。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ---------------------------------------- | ----------- | ---- | ---- | ------------------------------------------------------------ | +| deviceId | string | 是 | 是 | 表示过滤的BLE设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| name | string | 是 | 是 | 表示过滤的BLE设备名。 | +| serviceUuid | string | 是 | 是 | 表示过滤包含该UUID服务的设备，例如：00001888-0000-1000-8000-00805f9b34fb。 | +| serviceUuidMask | string | 是 | 是 | 表示过滤包含该UUID服务掩码的设备，例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | +| serviceSolicitationUuid | string | 是 | 是 | 表示过滤包含该UUID服务请求的设备，例如：00001888-0000-1000-8000-00805F9B34FB。 | +| serviceSolicitationUuidMask | string | 是 | 是 | 表示过滤包含该UUID服务请求掩码的设备，例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | +| serviceData | ArrayBuffer | 是 | 是 | 表示过滤包含该服务相关数据的设备，例如：[0x90,0x00,0xF1,0xF2]。 | +| serviceDataMask | ArrayBuffer | 是 | 是 | 表示过滤包含该服务相关数据掩码的设备，例如：[0xFF,0xFF,0xFF,0xFF]。 | +| manufactureId | number | 是 | 是 | 表示过滤包含该制造商ID的设备，例如：0x0006。 | +| manufactureData | ArrayBuffer | 是 | 是 | 表示过滤包含该制造商相关数据的设备，例如：[0x1F,0x2F,0x3F]。 | +| manufactureDataMask | ArrayBuffer | 是 | 是 | 表示过滤包含该制造商相关数据掩码的设备，例如：[0xFF,0xFF,0xFF]。 | + + +## ScanOptions + +扫描的配置参数。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| --------- | ----------------------- | ---- | ---- | -------------------------------------- | +| interval | number | 是 | 是 | 表示扫描结果上报延迟时间，默认值为0。 | +| dutyMode | [ScanDuty](#scanduty) | 是 | 是 | 表示扫描模式，默认值为SCAN_MODE_LOW_POWER。 | +| matchMode | [MatchMode](#matchmode) | 是 | 是 | 表示硬件的过滤匹配模式，默认值为MATCH_MODE_AGGRESSIVE。 | + + +## GattProperties + +描述gatt characteristic的属性。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------ |---- | ----------- | +| write | boolean | 是 | 表示该特征支持写操作，需要对端设备的回复。 | +| writeNoResponse | boolean | 是 | 表示该特征支持写操作，无需对端设备回复。 | +| read | boolean | 是 | 表示该特征支持读操作。 | +| notify | boolean | 是 | 表示该特征可通知对端设备。 | +| indicate | boolean | 是 | 表示该特征可通知对端设备，需要对端设备的回复。 | + + +## GattWriteType + +枚举，表示gatt写入类型。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| ------------------------------------| ------ | --------------- | +| WRITE | 1 | 表示写入特征值，需要对端设备的回复。 | +| WRITE_NO_RESPONSE | 2 | 表示写入特征值，不需要对端设备的回复。 | + + +## ScanDuty + +枚举，扫描模式。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| --------------------- | ---- | ------------ | +| SCAN_MODE_LOW_POWER | 0 | 表示低功耗模式，默认值。 | +| SCAN_MODE_BALANCED | 1 | 表示均衡模式。 | +| SCAN_MODE_LOW_LATENCY | 2 | 表示低延迟模式。 | + + +## MatchMode + +枚举，硬件过滤匹配模式。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| --------------------- | ---- | ---------------------------------------- | +| MATCH_MODE_AGGRESSIVE | 1 | 表示硬件上报扫描结果门限较低，比如扫描到的功率较低或者一段时间扫描到的次数较少也触发上报，默认值。 | +| MATCH_MODE_STICKY | 2 | 表示硬件上报扫描结果门限较高，更高的功率门限以及扫描到多次才会上报。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-connection.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-connection.md new file mode 100644 index 0000000000..5c20c42210 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-connection.md @@ -0,0 +1,1397 @@ +# @ohos.bluetooth.connection (蓝牙connection模块) + +connection模块提供了对蓝牙操作和管理的方法。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + + +## 导入模块 + +```js +import connection from '@ohos.bluetooth.connection'; +``` + + +## connection.pairDevice + +pairDevice(deviceId: string, callback: AsyncCallback<void>): void + +发起蓝牙配对。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当配对成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + // 实际的地址可由扫描流程获取 + connection.pairDevice('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.pairDevice + +pairDevice(deviceId: string): Promise<void> + +发起蓝牙配对。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<void> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + // 实际的地址可由扫描流程获取 + connection.pairDevice('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.pairCredibleDevice + +pairCredibleDevice(deviceId: string, transport: BluetoothTransport, callback: AsyncCallback<void>): void + +向可信的远端设备发起蓝牙配对。通过非蓝牙扫描的方式(例如NFC等)获取到外设的地址，可以通过该接口发起配对。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| transport | [BluetoothTransport](#bluetoothtransport) | 是 | 表示设备类型，例如传统蓝牙设备或低功耗蓝牙设备。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当发起配对成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.pairCredibleDevice('68:13:24:79:4C:8C', 1, err => { + if (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); + return; + } + console.info('pairCredibleDevice, err: ' + JSON.stringify(err)); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.pairCredibleDevice + +pairCredibleDevice(deviceId: string, transport: BluetoothTransport): Promise<void> + +向可信的远端设备发起蓝牙配对。通过非蓝牙扫描的方式(例如NFC等)获取到外设的地址，可以通过该接口发起配对。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| transport | [BluetoothTransport](#bluetoothtransport) | 是 | 表示设备类型，例如传统蓝牙设备或低功耗蓝牙设备。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------------- | ------------------- | +| Promise<void> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.pairCredibleDevice('68:13:24:79:4C:8C', 0).then(() => { + console.info('PairCredibleDevice'); + }, err => { + console.error('PairCredibleDevice:errCode' + err.code + ', errMessage: ' + err.message); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.cancelPairedDevice + +cancelPairedDevice(deviceId: string, callback: AsyncCallback<void>): void + +删除配对的远程设备。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------- | +| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当删除远程配对设备成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.cancelPairedDevice('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.cancelPairedDevice + +cancelPairedDevice(deviceId: string): Promise<void> + +删除配对的远程设备。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------- | +| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<void> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.cancelPairedDevice('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.cancelPairingDevice + +cancelPairingDevice(deviceId: string, callback: AsyncCallback<void>): void + +删除正在配对中的远程设备。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------- | +| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当删除远程配对设备成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.cancelPairingDevice('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.cancelPairingDevice + +cancelPairingDevice(deviceId: string): Promise<void> + +删除正在配对中的远程设备。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------- | +| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<void> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.cancelPairingDevice('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.getRemoteDeviceName + +getRemoteDeviceName(deviceId: string): string + +获取对端蓝牙设备的名称。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | --------------------------------- | +| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------- | +| string | 以字符串格式返回设备名称。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let remoteDeviceName = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.getRemoteDeviceClass + +getRemoteDeviceClass(deviceId: string): DeviceClass + +获取对端蓝牙设备的类别。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | --------------------------------- | +| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------- | -------- | +| [DeviceClass](#deviceclass) | 远程设备的类别。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let remoteDeviceClass = connection.getRemoteDeviceClass('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.getLocalName + +getLocalName(): string + +获取蓝牙本地设备名称。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ------ | --------- | +| string | 蓝牙本地设备名称。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let localName = connection.getLocalName(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.getPairedDevices + +getPairedDevices(): Array<string> + +获取蓝牙配对列表。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Array<string> | 已配对蓝牙设备的地址列表。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let devices = connection.getPairedDevices(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.getProfileConnectionState + +getProfileConnectionState(profileId?: ProfileId): ProfileConnectionState + +依据ProfileId获取指定profile的连接状态。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | --------- | ---- | ------------------------------------- | +| ProfileId | [profileId](js-apis-bluetooth-constant.md#profileid) | 否 | 表示profile的枚举值，例如：PROFILE_A2DP_SOURCE。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------------- | ------------------- | +| [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | profile的连接状态。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +import constant from '@ohos.bluetooth.constant'; +try { + let result = connection.getProfileConnectionState(constant.ProfileId.PROFILE_A2DP_SOURCE); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.setDevicePairingConfirmation + +setDevicePairingConfirmation(deviceId: string, accept: boolean): void + +设置设备配对请求确认。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | -------------------------------- | +| deviceId | string | 是 | 表示远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| accept | boolean | 是 | 接受配对请求设置为true，否则设置为false。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js + +try { + // 订阅“pinRequired”配对请求事件，收到远端配对请求后设置配对确认 + function onReceivePinRequiredEvent(data) { // data为配对请求的入参，配对请求参数 + console.info('pin required = '+ JSON.stringify(data)); + connection.setDevicePairingConfirmation(data.deviceId, true); + } + connection.on('pinRequired', onReceivePinRequiredEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.setDevicePinCode + +setDevicePinCode(deviceId: string, code: string, callback: AsyncCallback<void>): void + +当蓝牙配对类型[PinType](#pintype)为PIN_TYPE_ENTER_PIN_CODE或PIN_TYPE_PIN_16_DIGITS时调用此接口，请求用户输入PIN码。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | -------------------------------- | +| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | +| code | string | 是 | 用户输入的PIN码。 | +| callback | AsyncCallback<void> | 是 | 回调函数，当设置PinCode成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +//callback +try { + connection.setDevicePinCode('11:22:33:44:55:66', '12345', (err, data) => { + console.info('setDevicePinCode,device name err:' + JSON.stringify(err) + ',device name:' + JSON.stringify(data)); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.setDevicePinCode + +setDevicePinCode(deviceId: string, code: string): Promise<void> + +当蓝牙配对类型[PinType](#pintype)为PIN_TYPE_ENTER_PIN_CODE或PIN_TYPE_PIN_16_DIGITS时调用此接口，请求用户输入PIN码。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | -------------------------------- | +| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | +| code | string | 是 | 用户输入的PIN码。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<void> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +//promise +try { + connection.setDevicePinCode('11:22:33:44:55:66', '12345').then(() => { + console.info('setDevicePinCode'); + }, error => { + console.info('setDevicePinCode: errCode:' + error.code + ',errMessage' + error.message); + }) + +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.setLocalName + +setLocalName(name: string): void + +设置蓝牙本地设备名称。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | --------------------- | +| name | string | 是 | 要设置的蓝牙名称，最大长度为248字节数。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.setLocalName('device_name'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.setBluetoothScanMode + +setBluetoothScanMode(mode: ScanMode, duration: number): void + +设置蓝牙扫描模式，可以被远端设备发现。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ---------------------------- | +| mode | [ScanMode](#scanmode) | 是 | 蓝牙扫描模式。 | +| duration | number | 是 | 设备可被发现的持续时间，单位为毫秒；设置为0则持续可发现。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + // 设置为可连接可发现才可被远端设备扫描到，可以连接。 + connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.getBluetoothScanMode + +getBluetoothScanMode(): ScanMode + +获取蓝牙扫描模式。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| --------------------- | ------- | +| [ScanMode](#scanmode) | 蓝牙扫描模式。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let scanMode = connection.getBluetoothScanMode(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.startBluetoothDiscovery + +startBluetoothDiscovery(): void + +开启蓝牙扫描，可以发现远端设备。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +let deviceId; +function onReceiveEvent(data) { + deviceId = data; +} +try { + connection.on('bluetoothDeviceFind', onReceiveEvent); + connection.startBluetoothDiscovery(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.stopBluetoothDiscovery + +stopBluetoothDiscovery(): void + +关闭蓝牙扫描。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.stopBluetoothDiscovery(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.getLocalProfileUuids + +getLocalProfileUuids(callback: AsyncCallback<Array<ProfileUuids>>): void + +获取本地设备的profile UUID。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| callback | AsyncCallback<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids)>> | 是 | 回调函数。当获取UUID成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.getLocalProfileUuids('XX:XX:XX:XX:XX:XX', (err, data) => { + console.info('getLocalProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data)); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.getLocalProfileUuids + +getLocalProfileUuids(): Promise<Array<ProfileUuids>> + +获取本地设备的profile UUID。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids)>> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.getLocalProfileUuids('XX:XX:XX:XX:XX:XX').then(() => { + console.info('getLocalProfileUuids'); + }, err => { + console.error('getLocalProfileUuids: errCode' + err.code + ', errMessage: ' + err.message); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.getRemoteProfileUuids + +getRemoteProfileUuids(deviceId: string, callback: AsyncCallback<Array<ProfileUuids>>): void + +获取对端蓝牙设备支持的Profile UUID。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| callback | AsyncCallback<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids)>> | 是 | 回调函数。当获取UUID成功，err为undefined，否则为错误对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX', (err, data) => { + console.info('getRemoteProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data)); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} + +``` + + +## connection.getRemoteProfileUuids + +getRemoteProfileUuids(deviceId: string): Promise<Array<ProfileUuids>> + +获取对端蓝牙设备支持的Profile UUID。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ----------------------------------- | +| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids)>> | 返回promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX').then(() => { + console.info('getRemoteProfileUuids'); + }, err => { + console.error('getRemoteProfileUuids: errCode' + err.code + ', errMessage: ' + err.message); + }); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.on('bluetoothDeviceFind') + +on(type: 'bluetoothDeviceFind', callback: Callback<Array<string>>): void + +订阅蓝牙设备发现上报事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------- | ---- | -------------------------------------- | +| type | string | 是 | 填写"bluetoothDeviceFind"字符串，表示蓝牙设备发现事件。 | +| callback | Callback<Array<string>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { // data为蓝牙设备地址集合 + console.info('bluetooth device find = '+ JSON.stringify(data)); +} +try { + connection.on('bluetoothDeviceFind', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.off('bluetoothDeviceFind') + +off(type: 'bluetoothDeviceFind', callback?: Callback<Array<string>>): void + +取消订阅蓝牙设备发现上报事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"bluetoothDeviceFind"字符串，表示蓝牙设备发现事件。 | +| callback | Callback<Array<string>> | 否 | 表示取消订阅蓝牙设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('bluetooth device find = '+ JSON.stringify(data)); +} +try { + connection.on('bluetoothDeviceFind', onReceiveEvent); + connection.off('bluetoothDeviceFind', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.on('bondStateChange') + +on(type: 'bondStateChange', callback: Callback<BondStateParam>): void + +订阅蓝牙配对状态改变事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------------------ | +| type | string | 是 | 填写"bondStateChange"字符串，表示蓝牙配对状态改变事件。 | +| callback | Callback<[BondStateParam](#BondStateParam)> | 是 | 表示回调函数的入参，配对的状态。回调函数由用户创建通过该接口注册。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { // data为回调函数入参，表示配对的状态 + console.info('pair state = '+ JSON.stringify(data)); +} +try { + connection.on('bondStateChange', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.off('bondStateChange') + +off(type: 'bondStateChange', callback?: Callback<BondStateParam>): void + +取消订阅蓝牙配对状态改变事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"bondStateChange"字符串，表示蓝牙配对状态改变事件。 | +| callback | Callback<[BondStateParam](#BondStateParam)> | 否 | 表示取消订阅蓝牙配对状态改变事件上报。不填该参数则取消订阅该type对应的所有回调。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('bond state = '+ JSON.stringify(data)); +} +try { + connection.on('bondStateChange', onReceiveEvent); + connection.off('bondStateChange', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.on('pinRequired') + +on(type: 'pinRequired', callback: Callback<PinRequiredParam>): void + +订阅远端蓝牙设备的配对请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | -------------------------------- | +| type | string | 是 | 填写"pinRequired"字符串，表示配对请求事件。 | +| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | 是 | 表示回调函数的入参，配对请求。回调函数由用户创建通过该接口注册。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { // data为配对请求参数 + console.info('pin required = '+ JSON.stringify(data)); +} +try { + connection.on('pinRequired', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## connection.off('pinRequired') + +off(type: 'pinRequired', callback?: Callback<PinRequiredParam>): void + +取消订阅远端蓝牙设备的配对请求事件。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"pinRequired"字符串，表示配对请求事件。 | +| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | 否 | 表示取消订阅蓝牙配对请求事件上报，入参为配对请求参数。不填该参数则取消订阅该type对应的所有回调。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900099 | Operation failed. | + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('pin required = '+ JSON.stringify(data)); +} +try { + connection.on('pinRequired', onReceiveEvent); + connection.off('pinRequired', onReceiveEvent); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## BondStateParam + +描述配对状态参数。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| -------- | ------ | ---- | ---- | ----------- | +| deviceId | string | 是 | 否 | 表示要配对的设备ID。 | +| state | BondState | 是 | 否 | 表示配对设备的状态。 | + + +## PinRequiredParam + +描述配对请求参数。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| -------- | ------ | ---- | ---- | ----------- | +| deviceId | string | 是 | 否 | 表示要配对的设备ID。 | +| pinCode | string | 是 | 否 | 表示要配对的密钥。 | +| pinType | [PinType](#pintype) | 是 | 否 | 表示要配对的设备类型。
此接口为系统接口。 | + + +## DeviceClass + +描述蓝牙设备的类别。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| --------------- | ----------------------------------- | ---- | ---- | ---------------- | +| majorClass | [MajorClass](js-apis-bluetooth-constant.md#majorclass) | 是 | 否 | 表示蓝牙设备主要类别的枚举。 | +| majorMinorClass | [MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass) | 是 | 否 | 表示主要次要蓝牙设备类别的枚举。 | +| classOfDevice | number | 是 | 否 | 表示设备类别。 | + + +## BluetoothTransport + +枚举，表示设备类型。例如传统蓝牙设备或低功耗蓝牙设备，支持双模默认使用TRANSPORT_BR_EDR。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| -------------------------------- | ------ | --------------- | +| TRANSPORT_BR_EDR | 0 | 表示传统蓝牙(BR/EDR)设备。 | +| TRANSPORT_LE | 1 | 表示低功耗蓝牙(BLE)设备。 | + + +## ScanMode + +枚举，扫描模式。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| ---------------------------------------- | ---- | --------------- | +| SCAN_MODE_NONE | 0 | 没有扫描模式。 | +| SCAN_MODE_CONNECTABLE | 1 | 可连接扫描模式。 | +| SCAN_MODE_GENERAL_DISCOVERABLE | 2 | general发现模式。 | +| SCAN_MODE_LIMITED_DISCOVERABLE | 3 | limited发现模式。 | +| SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4 | 可连接general发现模式。 | +| SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5 | 可连接limited发现模式。 | + + +## BondState + +枚举，配对状态。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| ------------------ | ---- | ------ | +| BOND_STATE_INVALID | 0 | 无效的配对。 | +| BOND_STATE_BONDING | 1 | 正在配对。 | +| BOND_STATE_BONDED | 2 | 已配对。 | + + +## PinType + +枚举，蓝牙配对类型。 + +**系统接口：** 此接口为系统接口。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| -------------------------------- | ------ | --------------- | +| PIN_TYPE_ENTER_PIN_CODE | 0 | 用户需要输入对端设备上显示的PIN码。
此接口为系统接口。 | +| PIN_TYPE_ENTER_PASSKEY | 1 | 用户需要输入对端设备上显示的PASSKEY。
此接口为系统接口。 | +| PIN_TYPE_CONFIRM_PASSKEY | 2 | 用户需要确认本地设备上显示的PASSKEY。
此接口为系统接口。 | +| PIN_TYPE_NO_PASSKEY_CONSENT | 3 | 无PASSKEY，用户需要接受或拒绝配对请求。
此接口为系统接口。 | +| PIN_TYPE_NOTIFY_PASSKEY | 4 | 本地设备显示PASSKEY，用户需要在对端设备上输入该PASSKEY。
此接口为系统接口。 | +| PIN_TYPE_DISPLAY_PIN_CODE | 5 | bluetooth 2.0设备，用户需要输入对端设备上显示的PIN码。
此接口为系统接口。 | +| PIN_TYPE_OOB_CONSENT | 6 | 用户需要接受或拒绝OOB配对请求。
此接口为系统接口。 | +| PIN_TYPE_PIN_16_DIGITS | 7 | 用户需要输入对端设备上显示的16位PIN码。
此接口为系统接口。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-constant.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-constant.md new file mode 100644 index 0000000000..94a8cae201 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-constant.md @@ -0,0 +1,181 @@ +# @ohos.bluetooth.constant (蓝牙constant模块) + +constant模块提供了蓝牙中常量的定义。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + + +## 导入模块 + +```js +import constant from '@ohos.bluetooth.constant'; +``` + +## ProfileId + +蓝牙profile枚举。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| -------------------------------- | ------ | --------------- | +| PROFILE_A2DP_SOURCE | 1 | 表示A2DP profile。 | +| PROFILE_HANDSFREE_AUDIO_GATEWAY | 4 | 表示HFP profile。 | +| PROFILE_HID_HOST | 6 | 表示HID profile。 | +| PROFILE_PAN_NETWORK | 7 | 表示PAN profile。 | + + +## ProfileUuids + +枚举，表示Profile的UUID。 + +**系统接口：** 此接口为系统接口。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| ------------------------------------| ------ | --------------- | +| PROFILE_UUID_HFP_AG | '0000111F-0000-1000-8000-00805F9B34FB' | 代表HFPAG Profile的UUID。
此接口为系统接口。 | +| PROFILE_UUID_HFP_HF | '0000111E-0000-1000-8000-00805F9B34FB' | 代表HFPHF Profile的UUID。
此接口为系统接口。 | +| PROFILE_UUID_HSP_AG | '00001112-0000-1000-8000-00805F9B34FB' | 代表HSPAG Profile的UUID。
此接口为系统接口。 | +| PROFILE_UUID_HSP_HS | '00001108-0000-1000-8000-00805F9B34FB' | 代表HSPHS Profile的UUID。
此接口为系统接口。 | +| PROFILE_UUID_A2DP_SRC | '0000110A-0000-1000-8000-00805F9B34FB' | 代表A2DPSRC Profile的UUID。
此接口为系统接口。 | +| PROFILE_UUID_A2DP_SINK | '0000110B-0000-1000-8000-00805F9B34FB' | 代表A2DPSINK Profile的UUID。
此接口为系统接口。 | +| PROFILE_UUID_AVRCP_CT | '0000110E-0000-1000-8000-00805F9B34FB' | 代表AVRCPCT Profile的UUID。
此接口为系统接口。 | +| PROFILE_UUID_AVRCP_TG | '0000110C-0000-1000-8000-00805F9B34FB' | 代表AVRCPTG Profile的UUID。
此接口为系统接口。 | +| PROFILE_UUID_HID | '00001124-0000-1000-8000-00805F9B34FB' | 代表HID Profile的UUID。
此接口为系统接口。 | +| PROFILE_UUID_HOGP | '00001812-0000-1000-8000-00805F9B34FB' | 代表HOGP Profile的UUID。
此接口为系统接口。 | + + +## ProfileConnectionState + +枚举，蓝牙设备的profile连接状态。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| ------------------- | ---- | -------------- | +| STATE_DISCONNECTED | 0 | 表示profile已断连。 | +| STATE_CONNECTING | 1 | 表示profile正在连接。 | +| STATE_CONNECTED | 2 | 表示profile已连接。 | +| STATE_DISCONNECTING | 3 | 表示profile正在断连。 | + + +## MajorClass + +枚举，蓝牙设备主要类别。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| ------------------- | ------ | ---------- | +| MAJOR_MISC | 0x0000 | 表示杂项设备。 | +| MAJOR_COMPUTER | 0x0100 | 表示计算机设备。 | +| MAJOR_PHONE | 0x0200 | 表示手机设备。 | +| MAJOR_NETWORKING | 0x0300 | 表示网络设备。 | +| MAJOR_AUDIO_VIDEO | 0x0400 | 表示音频和视频设备。 | +| MAJOR_PERIPHERAL | 0x0500 | 表示外围设备。 | +| MAJOR_IMAGING | 0x0600 | 表示成像设备。 | +| MAJOR_WEARABLE | 0x0700 | 表示可穿戴设备。 | +| MAJOR_TOY | 0x0800 | 表示玩具设备。 | +| MAJOR_HEALTH | 0x0900 | 表示健康设备。 | +| MAJOR_UNCATEGORIZED | 0x1F00 | 表示未分类设备。 | + + +## MajorMinorClass + +枚举，主要次要蓝牙设备类别。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| ---------------------------------------- | ------ | --------------- | +| COMPUTER_UNCATEGORIZED | 0x0100 | 表示未分类计算机设备。 | +| COMPUTER_DESKTOP | 0x0104 | 表示台式计算机设备。 | +| COMPUTER_SERVER | 0x0108 | 表示服务器设备。 | +| COMPUTER_LAPTOP | 0x010C | 表示便携式计算机设备。 | +| COMPUTER_HANDHELD_PC_PDA | 0x0110 | 表示手持式计算机设备。 | +| COMPUTER_PALM_SIZE_PC_PDA | 0x0114 | 表示掌上电脑设备。 | +| COMPUTER_WEARABLE | 0x0118 | 表示可穿戴计算机设备。 | +| COMPUTER_TABLET | 0x011C | 表示平板电脑设备。 | +| PHONE_UNCATEGORIZED | 0x0200 | 表示未分类手机设备。 | +| PHONE_CELLULAR | 0x0204 | 表示便携式手机设备。 | +| PHONE_CORDLESS | 0x0208 | 表示无线电话设备。 | +| PHONE_SMART | 0x020C | 表示智能手机设备。 | +| PHONE_MODEM_OR_GATEWAY | 0x0210 | 表示调制解调器或网关手机设备。 | +| PHONE_ISDN | 0x0214 | 表示ISDN手机设备。 | +| NETWORK_FULLY_AVAILABLE | 0x0300 | 表示网络完全可用设备。 | +| NETWORK_1_TO_17_UTILIZED | 0x0320 | 表示使用网络1到17设备。 | +| NETWORK_17_TO_33_UTILIZED | 0x0340 | 表示使用网络17到33设备。 | +| NETWORK_33_TO_50_UTILIZED | 0x0360 | 表示使用网络33到50设备。 | +| NETWORK_60_TO_67_UTILIZED | 0x0380 | 表示使用网络60到67设备。 | +| NETWORK_67_TO_83_UTILIZED | 0x03A0 | 表示使用网络67到83设备。 | +| NETWORK_83_TO_99_UTILIZED | 0x03C0 | 表示使用网络83到99设备。 | +| NETWORK_NO_SERVICE | 0x03E0 | 表示网络无服务设备。 | +| AUDIO_VIDEO_UNCATEGORIZED | 0x0400 | 表示未分类音频视频设备。 | +| AUDIO_VIDEO_WEARABLE_HEADSET | 0x0404 | 表示可穿戴式音频视频设备。 | +| AUDIO_VIDEO_HANDSFREE | 0x0408 | 表示免提音频视频设备。 | +| AUDIO_VIDEO_MICROPHONE | 0x0410 | 表示麦克风音频视频设备。 | +| AUDIO_VIDEO_LOUDSPEAKER | 0x0414 | 表示扬声器音频视频设备。 | +| AUDIO_VIDEO_HEADPHONES | 0x0418 | 表示头戴式音频视频设备。 | +| AUDIO_VIDEO_PORTABLE_AUDIO | 0x041C | 表示便携式音频视频设备。 | +| AUDIO_VIDEO_CAR_AUDIO | 0x0420 | 表示汽车音频视频设备。 | +| AUDIO_VIDEO_SET_TOP_BOX | 0x0424 | 表示机顶盒音频视频设备。 | +| AUDIO_VIDEO_HIFI_AUDIO | 0x0428 | 表示高保真音响设备。 | +| AUDIO_VIDEO_VCR | 0x042C | 表示录像机音频视频设备。 | +| AUDIO_VIDEO_VIDEO_CAMERA | 0x0430 | 表示照相机音频视频设备。 | +| AUDIO_VIDEO_CAMCORDER | 0x0434 | 表示摄像机音频视频设备。 | +| AUDIO_VIDEO_VIDEO_MONITOR | 0x0438 | 表示监视器音频视频设备。 | +| AUDIO_VIDEO_VIDEO_DISPLAY_AND_LOUDSPEAKER | 0x043C | 表示视频显示器和扬声器设备。 | +| AUDIO_VIDEO_VIDEO_CONFERENCING | 0x0440 | 表示音频视频会议设备。 | +| AUDIO_VIDEO_VIDEO_GAMING_TOY | 0x0448 | 表示游戏玩具音频视频设备。 | +| PERIPHERAL_NON_KEYBOARD_NON_POINTING | 0x0500 | 表示非键盘非指向外围设备。 | +| PERIPHERAL_KEYBOARD | 0x0540 | 表示外设键盘设备。 | +| PERIPHERAL_POINTING_DEVICE | 0x0580 | 表示定点装置外围设备。 | +| PERIPHERAL_KEYBOARD_POINTING | 0x05C0 | 表示键盘指向外围设备。 | +| PERIPHERAL_UNCATEGORIZED | 0x0500 | 表示未分类外围设备。 | +| PERIPHERAL_JOYSTICK | 0x0504 | 表示周边操纵杆设备。 | +| PERIPHERAL_GAMEPAD | 0x0508 | 表示周边游戏板设备。 | +| PERIPHERAL_REMOTE_CONTROL | 0x05C0 | 表示远程控制外围设备。 | +| PERIPHERAL_SENSING_DEVICE | 0x0510 | 表示外围传感设备设备。 | +| PERIPHERAL_DIGITIZER_TABLET | 0x0514 | 表示外围数字化仪平板电脑设备。 | +| PERIPHERAL_CARD_READER | 0x0518 | 表示外围读卡器设备。 | +| PERIPHERAL_DIGITAL_PEN | 0x051C | 表示外设数码笔设备。 | +| PERIPHERAL_SCANNER_RFID | 0x0520 | 表示射频识别扫描仪外围设备。 | +| PERIPHERAL_GESTURAL_INPUT | 0x0522 | 表示手势输入外围设备。 | +| IMAGING_UNCATEGORIZED | 0x0600 | 表示未分类的图像设备。 | +| IMAGING_DISPLAY | 0x0610 | 表示图像显示设备。 | +| IMAGING_CAMERA | 0x0620 | 表示成像照相机设备。 | +| IMAGING_SCANNER | 0x0640 | 表示成像扫描仪设备。 | +| IMAGING_PRINTER | 0x0680 | 表示成像打印机设备。 | +| WEARABLE_UNCATEGORIZED | 0x0700 | 表示未分类的可穿戴设备。 | +| WEARABLE_WRIST_WATCH | 0x0704 | 表示可穿戴腕表设备。 | +| WEARABLE_PAGER | 0x0708 | 表示可穿戴寻呼机设备。 | +| WEARABLE_JACKET | 0x070C | 表示夹克可穿戴设备。 | +| WEARABLE_HELMET | 0x0710 | 表示可穿戴头盔设备。 | +| WEARABLE_GLASSES | 0x0714 | 表示可穿戴眼镜设备。 | +| TOY_UNCATEGORIZED | 0x0800 | 表示未分类的玩具设备。 | +| TOY_ROBOT | 0x0804 | 表示玩具机器人设备。 | +| TOY_VEHICLE | 0x0808 | 表示玩具车设备。 | +| TOY_DOLL_ACTION_FIGURE | 0x080C | 表示人形娃娃玩具设备。 | +| TOY_CONTROLLER | 0x0810 | 表示玩具控制器设备。 | +| TOY_GAME | 0x0814 | 表示玩具游戏设备。 | +| HEALTH_UNCATEGORIZED | 0x0900 | 表示未分类健康设备。 | +| HEALTH_BLOOD_PRESSURE | 0x0904 | 表示血压健康设备。 | +| HEALTH_THERMOMETER | 0x0908 | 表示温度计健康设备。 | +| HEALTH_WEIGHING | 0x090C | 表示体重健康设备。 | +| HEALTH_GLUCOSE | 0x0910 | 表示葡萄糖健康设备。 | +| HEALTH_PULSE_OXIMETER | 0x0914 | 表示脉搏血氧仪健康设备。 | +| HEALTH_PULSE_RATE | 0x0918 | 表示脉搏率健康设备。 | +| HEALTH_DATA_DISPLAY | 0x091C | 表示数据显示健康设备。 | +| HEALTH_STEP_COUNTER | 0x0920 | 表示阶梯计数器健康设备。 | +| HEALTH_BODY_COMPOSITION_ANALYZER | 0x0924 | 表示身体成分分析仪健康设备。 | +| HEALTH_PEAK_FLOW_MONITOR | 0x0928 | 表示湿度计健康设备。 | +| HEALTH_MEDICATION_MONITOR | 0x092C | 表示药物监视仪健康设备。 | +| HEALTH_KNEE_PROSTHESIS | 0x0930 | 表示膝盖假肢健康设备。 | +| HEALTH_ANKLE_PROSTHESIS | 0x0934 | 表示脚踝假肢健康设备。 | +| HEALTH_GENERIC_HEALTH_MANAGER | 0x0938 | 表示通用健康管理设备。 | +| HEALTH_PERSONAL_MOBILITY_DEVICE | 0x093C | 表示个人移动健康设备。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-hfp.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-hfp.md new file mode 100644 index 0000000000..cc4b75a674 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-hfp.md @@ -0,0 +1,128 @@ +# @ohos.bluetooth.hfp (蓝牙hfp模块) + +hfp模块提供了访问蓝牙呼叫接口的方法。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + + +## 导入模块 + +```js +import hfp from '@ohos.bluetooth.hfp'; +``` + + +## hfp.createHfpAgProfile + +createHfpAgProfile(): HandsFreeAudioGatewayProfile + +创建hfp profile实例。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ----------------------------- | ---------- | +| HandsFreeAudioGatewayProfile | 返回该profile的实例。 | + +**示例：** + +```js +try { + let hfpAgProfile = hfp.createHfpAgProfile(); + console.info('hfpAg success'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## HandsFreeAudioGatewayProfile + +使用HandsFreeAudioGatewayProfile方法之前需要创建该类的实例进行操作，通过createHfpAgProfile()方法构造此实例。 + + +### connect + +connect(deviceId: string): void + +连接设备的HFP服务。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| deviceId | string | 是 | 远端设备地址。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let hfpAg = hfp.createHfpAgProfile(); + hfpAg.connect('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### disconnect + +disconnect(deviceId: string): void + +断开连接设备的HFP服务。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| deviceId | string | 是 | 远端设备地址。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let hfpAg = hfp.createHfpAgProfile(); + hfpAg.disconnect('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-hid.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-hid.md new file mode 100644 index 0000000000..320f8c9965 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-hid.md @@ -0,0 +1,128 @@ +# @ohos.bluetooth.hid (蓝牙hid模块) + +hid模块提供了访问蓝牙hid相关功能的方法。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + + +## 导入模块 + +```js +import hid from '@ohos.bluetooth.hid'; +``` + + +## hid.createHidHostProfile + +createHidHostProfile(): HidHostProfile + +创建hid profile实例。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ----------------------------- | ---------- | +| HidHostProfile | 返回该profile的实例。 | + +**示例：** + +```js +try { + let hidHostProfile = hid.createHidHostProfile(); + console.info('hidHost success'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## HidHostProfile + +使用HidHostProfile方法之前需要创建该类的实例进行操作，通过createHidHostProfile()方法构造此实例。 + + +### connect + +connect(deviceId: string): void + +连接设备的HidHost服务。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| deviceId | string | 是 | 远端设备地址。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let hidHostProfile = hid.createHidHostProfile(); + hidHostProfile.connect('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### disconnect + +disconnect(deviceId: string): void + +断开连接设备的HidHost服务。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| deviceId | string | 是 | 远端设备地址。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let hidHostProfile = hid.createHidHostProfile(); + hidHostProfile.disconnect('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-pan.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-pan.md new file mode 100644 index 0000000000..4147424f19 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-pan.md @@ -0,0 +1,158 @@ +# @ohos.bluetooth.pan (蓝牙socket模块) + +pan模块提供了访问蓝牙个人区域网相关功能的方法。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + + +## 导入模块 + +```js +import pan from '@ohos.bluetooth.pan'; +``` + + +## pan.createPanProfile + +createPanProfile(): PanProfile + +创建pan profile实例。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| ----------------------------- | ---------- | +| PanProfile | 返回该profile的实例。 | + +**示例：** + +```js +try { + let panProfile = pan.createPanProfile(); + console.info('pan success'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## PanProfile + +使用PanProfile方法之前需要创建该类的实例进行操作，通过createPanProfile()方法构造此实例。 + + +### disconnect + +disconnect(deviceId: string): void + +断开连接设备的Pan服务。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| deviceId | string | 是 | 远端设备地址。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let panProfile = pan.createPanProfile(); + panProfile.disconnect('XX:XX:XX:XX:XX:XX'); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### setTethering + +setTethering(enable: boolean): void + +设置网络共享状态。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| value | boolean | 是 | 是否设置蓝牙共享。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +try { + let panProfile = pan.createPanProfile(); + panProfile.setTethering(false); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +### isTetheringOn + +isTetheringOn(): boolean + +获取网络共享状态。 + +**系统接口**：此接口为系统接口。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**返回值：** + +| 类型 | 说明 | +| --------------------- | --------------------------------- | +| boolean | 网络共享开启返回true，网络共享关闭返回false。 | + +**示例：** + +```js +try { + let panProfile = pan.createPanProfile(); + let ret = panProfile.isTetheringOn(); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth-socket.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-socket.md new file mode 100644 index 0000000000..9cdf80d487 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth-socket.md @@ -0,0 +1,410 @@ +# @ohos.bluetooth.socket (蓝牙socket模块) + +socket模块提供了操作和管理蓝牙socket的方法。 + +> **说明：** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + + +## 导入模块 + +```js +import socket from '@ohos.bluetooth.socket'; +``` + +## socket.sppListen + +sppListen(name: string, options: SppOptions, callback: AsyncCallback<number>): void + +创建一个服务端监听Socket。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ----------------------- | +| name | string | 是 | 服务的名称。 | +| option | [SppOptions](#sppoptions) | 是 | spp监听配置参数。 | +| callback | AsyncCallback<number> | 是 | 表示回调函数的入参，服务端Socket的id。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +let serverNumber = -1; +function serverSocket(code, number) { + console.log('bluetooth error code: ' + code.code); + if (code.code == 0) { + console.log('bluetooth serverSocket Number: ' + number); + serverNumber = number; + } +} + +let sppOption = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0}; +try { + socket.sppListen('server1', sppOption, serverSocket); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## socket.sppAccept + +sppAccept(serverSocket: number, callback: AsyncCallback<number>): void + +服务端监听socket等待客户端连接。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | --------------------------- | ---- | ----------------------- | +| serverSocket | number | 是 | 服务端socket的id。 | +| callback | AsyncCallback<number> | 是 | 表示回调函数的入参，客户端socket的id。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js +let serverNumber = -1; +function serverSocket(code, number) { + console.log('bluetooth error code: ' + code.code); + if (code.code == 0) { + console.log('bluetooth serverSocket Number: ' + number); + serverNumber = number; + } +} +let clientNumber = -1; +function acceptClientSocket(code, number) { + console.log('bluetooth error code: ' + code.code); + if (code.code == 0) { + console.log('bluetooth clientSocket Number: ' + number); + // 获取的clientNumber用作服务端后续读/写操作socket的id。 + clientNumber = number; + } +} +try { + socket.sppAccept(serverNumber, acceptClientSocket); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## socket.sppConnect + +sppConnect(deviceId: string, options: SppOptions, callback: AsyncCallback<number>): void + +客户端向远端设备发起spp连接。 + +**需要权限**：ohos.permission.ACCESS_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------ | +| deviceId | string | 是 | 对端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| option | [SppOptions](#sppoptions) | 是 | spp客户端连接配置参数。 | +| callback | AsyncCallback<number> | 是 | 表示回调函数的入参，客户端socket的id。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900003 | Bluetooth switch is off. | +|2900004 | Profile is not supported. | +|2900099 | Operation failed. | + +**示例：** + +```js + +let clientNumber = -1; +function clientSocket(code, number) { + if (code.code != 0) { + return; + } + console.log('bluetooth serverSocket Number: ' + number); + // 获取的clientNumber用作客户端后续读/写操作socket的id。 + clientNumber = number; +} +let sppOption = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0}; +try { + socket.sppConnect('XX:XX:XX:XX:XX:XX', sppOption, clientSocket); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## socket.sppCloseServerSocket + +sppCloseServerSocket(socket: number): void + +关闭服务端监听Socket，入参socket由sppListen接口返回。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | --------------- | +| socket | number | 是 | 服务端监听socket的id。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +let serverNumber = -1; +function serverSocket(code, number) { + console.log('bluetooth error code: ' + code.code); + if (code.code == 0) { + console.log('bluetooth serverSocket Number: ' + number); + serverNumber = number; + } +} +try { + socket.sppCloseServerSocket(serverNumber); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## socket.sppCloseClientSocket + +sppCloseClientSocket(socket: number): void + +关闭客户端socket，入参socket由sppAccept或sppConnect接口获取。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------- | +| socket | number | 是 | 客户端socket的id。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2900001 | Service stopped. | +|2900099 | Operation failed. | + +**示例：** + +```js +let clientNumber = -1; +function clientSocket(code, number) { + if (code.code != 0) { + return; + } + console.log('bluetooth serverSocket Number: ' + number); + // 获取的clientNumber用作客户端后续读/写操作socket的id。 + clientNumber = number; +} +try { + socket.sppCloseClientSocket(clientNumber); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## socket.sppWrite + +sppWrite(clientSocket: number, data: ArrayBuffer): void + +通过socket向远端发送数据，入参clientSocket由sppAccept或sppConnect接口获取 。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | ----------- | ---- | ------------- | +| clientSocket | number | 是 | 客户端socket的id。 | +| data | ArrayBuffer | 是 | 写入的数据。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2901054 | IO error. | +|2900099 | Operation failed. | + +**示例：** + +```js +let clientNumber = -1; +function clientSocket(code, number) { + if (code.code != 0) { + return; + } + console.log('bluetooth serverSocket Number: ' + number); + // 获取的clientNumber用作客户端后续读/写操作socket的id。 + clientNumber = number; +} +let arrayBuffer = new ArrayBuffer(8); +let data = new Uint8Array(arrayBuffer); +data[0] = 123; +try { + socket.sppWrite(clientNumber, arrayBuffer); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## socket.on('sppRead') + +on(type: 'sppRead', clientSocket: number, callback: Callback<ArrayBuffer>): void + +订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | --------------------------- | ---- | -------------------------- | +| type | string | 是 | 填写"sppRead"字符串，表示spp读请求事件。 | +| clientSocket | number | 是 | 客户端socket的id。 | +| callback | Callback<ArrayBuffer> | 是 | 表示回调函数的入参，读取到的数据。 | + +**错误码**： + +以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------- | +|2901054 | IO error. | +|2900099 | Operation failed. | + +**示例：** + +```js +let clientNumber = -1; +function clientSocket(code, number) { + if (code.code != 0) { + return; + } + console.log('bluetooth serverSocket Number: ' + number); + // 获取的clientNumber用作客户端后续读/写操作socket的id。 + clientNumber = number; +} +function dataRead(dataBuffer) { + let data = new Uint8Array(dataBuffer); + console.log('bluetooth data is: ' + data[0]); +} +try { + socket.on('sppRead', clientNumber, dataRead); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## socket.off('sppRead') + +off(type: 'sppRead', clientSocket: number, callback?: Callback<ArrayBuffer>): void + +取消订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------ | --------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"sppRead"字符串，表示spp读请求事件。 | +| clientSocket | number | 是 | 客户端Socket的id。 | +| callback | Callback<ArrayBuffer> | 否 | 表示取消订阅spp读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | + +**示例：** + +```js +let clientNumber = -1; +function clientSocket(code, number) { + if (code.code != 0) { + return; + } + console.log('bluetooth serverSocket Number: ' + number); + // 获取的clientNumber用作客户端后续读/写操作socket的id。 + clientNumber = number; +} +try { + socket.off('sppRead', clientNumber); +} catch (err) { + console.error('errCode: ' + err.code + ', errMessage: ' + err.message); +} +``` + + +## SppOptions + +描述spp的配置参数。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------ | ------------------- | ---- | ---- | ----------- | +| uuid | string | 是 | 是 | spp单据的uuid。 | +| secure | boolean | 是 | 是 | 是否是安全通道。 | +| type | [SppType](#SppType) | 是 | 是 | Spp链路类型。 | + + +## SppType + +枚举，Spp链路类型。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +| 名称 | 值 | 说明 | +| ---------- | ---- | ------------- | +| SPP_RFCOMM | 0 | 表示rfcomm链路类型。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetoothManager.md b/zh-cn/application-dev/reference/apis/js-apis-bluetoothManager.md index 110b382393..a594e5145f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-bluetoothManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetoothManager.md @@ -15,12 +15,15 @@ import bluetoothManager from '@ohos.bluetoothManager'; ``` -## bluetoothManager.enableBluetooth +## bluetoothManager.enableBluetooth(deprecated) enableBluetooth(): void 开启蓝牙。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[access.enableBluetooth](js-apis-bluetooth-access.md#accessenablebluetooth)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -45,12 +48,15 @@ try { ``` -## bluetoothManager.disableBluetooth +## bluetoothManager.disableBluetooth(deprecated) disableBluetooth(): void 关闭蓝牙。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[access.disableBluetooth](js-apis-bluetooth-access.md#accessdisablebluetooth)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -75,12 +81,15 @@ try { ``` -## bluetoothManager.getLocalName +## bluetoothManager.getLocalName(deprecated) getLocalName(): string 获取蓝牙本地设备名称。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.getLocalName](js-apis-bluetooth-connection.md#connectiongetlocalname)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -111,12 +120,15 @@ try { ``` -## bluetoothManager.getState +## bluetoothManager.getState(deprecated) getState(): BluetoothState 获取蓝牙开关状态。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[access.getState](js-apis-bluetooth-access.md#accessgetstate)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -147,12 +159,15 @@ try { ``` -## bluetoothManager.getBtConnectionState +## bluetoothManager.getBtConnectionState(deprecated) getBtConnectionState(): ProfileConnectionState 获取蓝牙本端的Profile连接状态，例如：任意一个支持的Profile连接状态为已连接，则此接口返回状态为已连接。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.getProfileConnectionState](js-apis-bluetooth-connection.md#connectiongetprofileconnectionstate)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -184,12 +199,15 @@ try { ``` -## bluetoothManager.setLocalName +## bluetoothManager.setLocalName(deprecated) setLocalName(name: string): void 设置蓝牙本地设备名称。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.setLocalName](js-apis-bluetooth-connection.md#connectionsetlocalname)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -221,12 +239,15 @@ try { ``` -## bluetoothManager.pairDevice +## bluetoothManager.pairDevice(deprecated) pairDevice(deviceId: string): void 发起蓝牙配对。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.pairDevice](js-apis-bluetooth-connection.md#connectionpairdevice)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -259,109 +280,15 @@ try { ``` -## bluetoothManager.pairCredibleDevice10+ - -pairCredibleDevice(deviceId: string, transport: BluetoothTransport, callback: AsyncCallback<void>): void - -向可信的远端设备发起蓝牙配对。通过非蓝牙扫描的方式(例如NFC等)获取到外设的地址，可以通过该接口发起配对。 - -**系统接口**：此接口为系统接口。 - -**需要权限**：ohos.permission.DISCOVER_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------------------- | -| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | -| transport | [BluetoothTransport](#bluetoothtransport10) | 是 | 表示设备类型，例如传统蓝牙设备或低功耗蓝牙设备。 | -| callback | AsyncCallback<void> | 是 | 回调函数。当发起配对成功，err为undefined，否则为错误对象。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900099 | Operation failed. | - -**示例：** - -```js -try { - bluetoothManager.pairCredibleDevice("68:13:24:79:4C:8C", 1, err => { - if (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); - return; - } - console.info("pairCredibleDevice,err:" + JSON.stringify(err)); - }); -} catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); -} -``` - - -## bluetoothManager.pairCredibleDevice10+ - -pairCredibleDevice(deviceId: string, transport: BluetoothTransport): Promise<void> - -向可信的远端设备发起蓝牙配对。通过非蓝牙扫描的方式(例如NFC等)获取到外设的地址，可以通过该接口发起配对。 - -**系统接口**：此接口为系统接口。 - -**需要权限**：ohos.permission.DISCOVER_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------------------- | -| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | -| transport | [BluetoothTransport](#bluetoothtransport10) | 是 | 表示设备类型，例如传统蓝牙设备或低功耗蓝牙设备。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------------------------------------- | ------------------- | -| Promise<void> | 返回promise对象。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900099 | Operation failed. | - -**示例：** - -```js -try { - bluetoothManager.pairCredibleDevice("68:13:24:79:4C:8C", 0).then(() => { - console.info("PairCredibleDevice"); - }, err => { - console.error("PairCredibleDevice:errCode" + err.code + ",errMessage:" + err.message); - }); -} catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); -} -``` - - -## bluetoothManager.getProfileConnectionState +## bluetoothManager.getProfileConnectionState(deprecated) getProfileConnectionState(profileId: ProfileId): ProfileConnectionState 依据ProfileId获取指定profile的连接状态。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.getProfileConnectionState](js-apis-bluetooth-connection.md#connectiongetprofileconnectionstate)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -400,12 +327,15 @@ try { ``` -## bluetoothManager.cancelPairedDevice +## bluetoothManager.cancelPairedDevice(deprecated) cancelPairedDevice(deviceId: string): void 删除配对的远程设备。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.cancelPairedDevice](js-apis-bluetooth-connection.md#connectioncancelpaireddevice)替代。 + **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.DISCOVER_BLUETOOTH @@ -439,12 +369,15 @@ try { ``` -## bluetoothManager.getRemoteDeviceName +## bluetoothManager.getRemoteDeviceName(deprecated) getRemoteDeviceName(deviceId: string): string 获取对端蓝牙设备的名称。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.getRemoteDeviceName](js-apis-bluetooth-connection.md#connectiongetremotedevicename)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -482,12 +415,15 @@ try { ``` -## bluetoothManager.getRemoteDeviceClass +## bluetoothManager.getRemoteDeviceClass(deprecated) getRemoteDeviceClass(deviceId: string): DeviceClass 获取对端蓝牙设备的类别。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.getRemoteDeviceClass](js-apis-bluetooth-connection.md#connectiongetremotedeviceclass)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -525,12 +461,15 @@ try { ``` -## bluetoothManager.getPairedDevices +## bluetoothManager.getPairedDevices(deprecated) getPairedDevices(): Array<string> 获取蓝牙配对列表。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.getPairedDevices](js-apis-bluetooth-connection.md#connectiongetpaireddevices)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -562,12 +501,15 @@ try { ``` -## bluetoothManager.setBluetoothScanMode +## bluetoothManager.setBluetoothScanMode(deprecated) setBluetoothScanMode(mode: ScanMode, duration: number): void 设置蓝牙扫描模式，可以被远端设备发现。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.setBluetoothScanMode](js-apis-bluetooth-connection.md#connectionsetbluetoothscanmode)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -601,12 +543,15 @@ try { ``` -## bluetoothManager.getBluetoothScanMode +## bluetoothManager.getBluetoothScanMode(deprecated) getBluetoothScanMode(): ScanMode 获取蓝牙扫描模式。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.getBluetoothScanMode](js-apis-bluetooth-connection.md#connectiongetbluetoothscanmode)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -638,12 +583,15 @@ try { ``` -## bluetoothManager.startBluetoothDiscovery +## bluetoothManager.startBluetoothDiscovery(deprecated) startBluetoothDiscovery(): void 开启蓝牙扫描，可以发现远端设备。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.startBluetoothDiscovery](js-apis-bluetooth-connection.md#connectionstartbluetoothdiscovery)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH 和 ohos.permission.LOCATION 和 ohos.permission.APPROXIMATELY_LOCATION **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -674,12 +622,15 @@ try { ``` -## bluetoothManager.stopBluetoothDiscovery +## bluetoothManager.stopBluetoothDiscovery(deprecated) stopBluetoothDiscovery(): void 关闭蓝牙扫描。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.stopBluetoothDiscovery](js-apis-bluetooth-connection.md#connectionstopbluetoothdiscovery)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -705,188 +656,15 @@ try { ``` -## bluetoothManager.getRemoteProfileUuids10+ - -getRemoteProfileUuids(device: string, callback: AsyncCallback<Array<ProfileUuids>>): void - -获取对端蓝牙设备支持的Profile UUID。 - -**系统接口**：此接口为系统接口。 - -**需要权限**：ohos.permission.USE_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------------------- | -| device | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | -| callback | AsyncCallback<Array<[ProfileUuids](#profileuuids10)>> | 是 | 回调函数。当获取UUID成功，err为undefined，否则为错误对象。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900099 | Operation failed. | - -**示例：** - -```js -try { - bluetoothManager.getRemoteProfileUuids("XX:XX:XX:XX:XX:XX", (err, data) => { - console.info("getRemoteProfileUuids, err: " + JSON.stringify(err) + ", data: " + JSON.stringify(data)); - }); -} catch (err) { - console.error("errCode: " + err.code + ", errMessage: " + err.message); -} - -``` - - -## bluetoothManager.getRemoteProfileUuids10+ - -getRemoteProfileUuids(device: string): Promise<Array<ProfileUuids>> - -获取对端蓝牙设备支持的Profile UUID。 - -**系统接口**：此接口为系统接口。 - -**需要权限**：ohos.permission.USE_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------------------- | -| device | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------- | ------------- | -| Promise<Array<[ProfileUuids](#profileuuids10)>> | 返回promise对象。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900099 | Operation failed. | - -**示例：** - -```js -try { - bluetoothManager.getRemoteProfileUuids("XX:XX:XX:XX:XX:XX").then(() => { - console.info("getRemoteProfileUuids"); - }, err => { - console.error("getRemoteProfileUuids: errCode" + err.code + ", errMessage: " + err.message); - }); -} catch (err) { - console.error("errCode: " + err.code + ", errMessage: " + err.message); -} -``` - - -## bluetoothManager.getLocalProfileUuids10+ - -getLocalProfileUuids(callback: AsyncCallback<Array<ProfileUuids>>): void - -获取本地设备的profile UUID。 - -**系统接口**：此接口为系统接口。 - -**需要权限**：ohos.permission.USE_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------------------- | -| callback | AsyncCallback<Array<[ProfileUuids](#profileuuids10)>> | 是 | 回调函数。当获取UUID成功，err为undefined，否则为错误对象。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900099 | Operation failed. | - -**示例：** - -```js -try { - bluetoothManager.getLocalProfileUuids("XX:XX:XX:XX:XX:XX", (err, data) => { - console.info("getLocalProfileUuids, err: " + JSON.stringify(err) + ", data: " + JSON.stringify(data)); - }); -} catch (err) { - console.error("errCode: " + err.code + ", errMessage: " + err.message); -} -``` - - -## bluetoothManager.getLocalProfileUuids10+ - -getLocalProfileUuids(): Promise<Array<ProfileUuids>> - -获取本地设备的profile UUID。 - -**系统接口**：此接口为系统接口。 - -**需要权限**：ohos.permission.USE_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**返回值：** - -| 类型 | 说明 | -| ------------------- | ------------- | -| Promise<Array<[ProfileUuids](#profileuuids10)>> | 返回promise对象。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900099 | Operation failed. | - -**示例：** - -```js -try { - bluetoothManager.getLocalProfileUuids("XX:XX:XX:XX:XX:XX").then(() => { - console.info("getLocalProfileUuids"); - }, err => { - console.error("getLocalProfileUuids: errCode" + err.code + ", errMessage: " + err.message); - }); -} catch (err) { - console.error("errCode: " + err.code + ", errMessage: " + err.message); -} -``` - - -## bluetoothManager.setDevicePairingConfirmation +## bluetoothManager.setDevicePairingConfirmation(deprecated) setDevicePairingConfirmation(device: string, accept: boolean): void 设置设备配对请求确认。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.setDevicePairingConfirmation](js-apis-bluetooth-connection.md#connectionsetdevicepairingconfirmation)替代。 + **需要权限**：ohos.permission.MANAGE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -925,104 +703,15 @@ try { ``` -## bluetoothManager.setDevicePinCode10+ - -setDevicePinCode(device: string, code: string, callback: AsyncCallback<void>): void - -当蓝牙配对类型[PinType](#pintype10)为PIN_TYPE_ENTER_PIN_CODE或PIN_TYPE_PIN_16_DIGITS时调用此接口，请求用户输入PIN码。 - -**需要权限**：ohos.permission.MANAGE_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------- | ---- | -------------------------------- | -| device | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | -| code | string | 是 | 用户输入的PIN码。 | -| callback | AsyncCallback<void> | 是 | 回调函数，当设置PinCode成功，err为undefined，否则为错误对象。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900099 | Operation failed. | - -**示例：** - -```js -//callback -try { - bluetoothManager.setDevicePinCode('11:22:33:44:55:66', '12345', (err, data) => { - console.info('setDevicePinCode,device name err:' + JSON.stringify(err) + ',device name:' + JSON.stringify(data)); - }); -} catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); -} -``` - - -## bluetoothManager.setDevicePinCode10+ - -setDevicePinCode(device: string, code: string): Promise<void> - -当蓝牙配对类型[PinType](#pintype10)为PIN_TYPE_ENTER_PIN_CODE或PIN_TYPE_PIN_16_DIGITS时调用此接口，请求用户输入PIN码。 - -**需要权限**：ohos.permission.MANAGE_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------- | ---- | -------------------------------- | -| device | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | -| code | string | 是 | 用户输入的PIN码。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------- | ------------- | -| Promise<void> | 返回promise对象。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900099 | Operation failed. | - -**示例：** - -```js -//promise -try { - bluetoothManager.setDevicePinCode('11:22:33:44:55:66', '12345').then(() => { - console.info('setDevicePinCode'); - }, error => { - console.info('setDevicePinCode: errCode:' + error.code + ',errMessage' + error.message); - }) - -} catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); -} -``` - - -## bluetoothManager.on('bluetoothDeviceFind') +## bluetoothManager.on('bluetoothDeviceFind')(deprecated) on(type: "bluetoothDeviceFind", callback: Callback<Array<string>>): void 订阅蓝牙设备发现上报事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.on('bluetoothDeviceFind')](js-apis-bluetooth-connection.md#connectiononbluetoothdevicefind)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1056,12 +745,15 @@ try { ``` -## bluetoothManager.off('bluetoothDeviceFind') +## bluetoothManager.off('bluetoothDeviceFind')(deprecated) off(type: "bluetoothDeviceFind", callback?: Callback<Array<string>>): void 取消订阅蓝牙设备发现上报事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.off('bluetoothDeviceFind')](js-apis-bluetooth-connection.md#connectionoffbluetoothdevicefind)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1096,12 +788,15 @@ try { ``` -## bluetoothManager.on('pinRequired') +## bluetoothManager.on('pinRequired')(deprecated) on(type: "pinRequired", callback: Callback<PinRequiredParam>): void 订阅远端蓝牙设备的配对请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.on('pinRequired')](js-apis-bluetooth-connection.md#connectiononpinrequired)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1135,12 +830,15 @@ try { ``` -## bluetoothManager.off('pinRequired') +## bluetoothManager.off('pinRequired')(deprecated) off(type: "pinRequired", callback?: Callback<PinRequiredParam>): void 取消订阅远端蓝牙设备的配对请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.off('pinRequired')](js-apis-bluetooth-connection.md#connectionoffpinrequired)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1175,12 +873,15 @@ try { ``` -## bluetoothManager.on('bondStateChange') +## bluetoothManager.on('bondStateChange')(deprecated) on(type: "bondStateChange", callback: Callback<BondStateParam>): void 订阅蓝牙配对状态改变事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.on('bondStateChange')](js-apis-bluetooth-connection.md#connectiononbondstatechange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1214,12 +915,15 @@ try { ``` -## bluetoothManager.off('bondStateChange') +## bluetoothManager.off('bondStateChange')(deprecated) off(type: "bondStateChange", callback?: Callback<BondStateParam>): void 取消订阅蓝牙配对状态改变事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.off('bondStateChange')](js-apis-bluetooth-connection.md#connectionoffbondstatechange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1254,12 +958,15 @@ try { ``` -## bluetoothManager.on('stateChange') +## bluetoothManager.on('stateChange')(deprecated) on(type: "stateChange", callback: Callback<BluetoothState>): void 订阅蓝牙设备开关状态事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[access.on('stateChange')](js-apis-bluetooth-access.md#accessonstatechange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1293,12 +1000,15 @@ try { ``` -## bluetoothManager.off('stateChange') +## bluetoothManager.off('stateChange')(deprecated) off(type: "stateChange", callback?: Callback<BluetoothState>): void 取消订阅蓝牙设备开关状态事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[access.off('stateChange')](js-apis-bluetooth-access.md#accessoffstatechange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1333,12 +1043,15 @@ try { ``` -## bluetoothManager.sppListen +## bluetoothManager.sppListen(deprecated) sppListen(name: string, option: SppOption, callback: AsyncCallback<number>): void 创建一个服务端监听Socket。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.sppListen](js-apis-bluetooth-socket.md#socketspplisten)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1383,12 +1096,15 @@ try { ``` -## bluetoothManager.sppAccept +## bluetoothManager.sppAccept(deprecated) sppAccept(serverSocket: number, callback: AsyncCallback<number>): void 服务端监听socket等待客户端连接。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.sppAccept](js-apis-bluetooth-socket.md#socketsppaccept)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -1437,12 +1153,15 @@ try { ``` -## bluetoothManager.sppConnect +## bluetoothManager.sppConnect(deprecated) sppConnect(device: string, option: SppOption, callback: AsyncCallback<number>): void 客户端向远端设备发起spp连接。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.sppConnect](js-apis-bluetooth-socket.md#socketsppconnect)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1488,12 +1207,15 @@ try { ``` -## bluetoothManager.sppCloseServerSocket +## bluetoothManager.sppCloseServerSocket(deprecated) sppCloseServerSocket(socket: number): void 关闭服务端监听Socket，入参socket由sppListen接口返回。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.sppCloseServerSocket](js-apis-bluetooth-socket.md#socketsppcloseserversocket)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -1530,12 +1252,15 @@ try { ``` -## bluetoothManager.sppCloseClientSocket +## bluetoothManager.sppCloseClientSocket(deprecated) sppCloseClientSocket(socket: number): void 关闭客户端socket，入参socket由sppAccept或sppConnect接口获取。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.sppCloseClientSocket](js-apis-bluetooth-socket.md#socketsppcloseclientsocket)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -1574,11 +1299,14 @@ try { ``` -## bluetoothManager.sppWrite +## bluetoothManager.sppWrite(deprecated) sppWrite(clientSocket: number, data: ArrayBuffer): void -通过socket向远端发送数据，入参clientSocket由sppAccept或sppConnect接口获取 。 +通过socket向远端发送数据，入参clientSocket由sppAccept或sppConnect接口获取。 + +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.sppWrite](js-apis-bluetooth-socket.md#socketsppwrite)替代。 **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1621,12 +1349,15 @@ try { ``` -## bluetoothManager.on('sppRead') +## bluetoothManager.on('sppRead')(deprecated) on(type: "sppRead", clientSocket: number, callback: Callback<ArrayBuffer>): void 订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.on('sppRead')](js-apis-bluetooth-socket.md#socketonsppread)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -1670,12 +1401,15 @@ try { ``` -## bluetoothManager.off('sppRead') +## bluetoothManager.off('sppRead')(deprecated) off(type: "sppRead", clientSocket: number, callback?: Callback<ArrayBuffer>): void 取消订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.off('sppRead')](js-apis-bluetooth-socket.md#socketoffsppread)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -1705,7 +1439,7 @@ try { } ``` -## bluetoothManager.getProfileInstance +## bluetoothManager.getProfileInstance(deprecated) getProfileInstance(profileId: ProfileId): A2dpSourceProfile | HandsFreeAudioGatewayProfile | HidHostProfile | PanProfile @@ -1738,12 +1472,15 @@ try { ## bluetoothManager.BLE -### createGattServer +### createGattServer(deprecated) createGattServer(): GattServer 创建一个可使用的GattServer实例。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.createGattServer](js-apis-bluetooth-ble.md#blecreategattserver)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **返回值：** @@ -1759,12 +1496,15 @@ let gattServer = bluetoothManager.BLE.createGattServer(); ``` -### createGattClientDevice +### createGattClientDevice(deprecated) createGattClientDevice(deviceId: string): GattClientDevice 创建一个可使用的GattClientDevice实例。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.createGattClientDevice](js-apis-bluetooth-ble.md#blecreategattclientdevice)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -1790,12 +1530,15 @@ try { ``` -### getConnectedBLEDevices +### getConnectedBLEDevices(deprecated) getConnectedBLEDevices(): Array<string> 获取和当前设备连接的BLE设备。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.getConnectedBLEDevices](js-apis-bluetooth-ble.md#blegetconnectedbledevices)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1827,12 +1570,15 @@ try { ``` -### startBLEScan +### startBLEScan(deprecated) startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void 发起BLE扫描流程。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.startBLEScan](js-apis-bluetooth-ble.md#blestartblescan)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 和 ohos.permission.LOCATION 和 ohos.permission.APPROXIMATELY_LOCATION **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -1864,196 +1610,34 @@ try { bluetoothManager.BLE.on("BLEDeviceFind", onReceiveEvent); bluetoothManager.BLE.startBLEScan( [{ - deviceId:"XX:XX:XX:XX:XX:XX", - name:"test", - serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" - }], - { - interval: 500, - dutyMode: bluetoothManager.ScanDuty.SCAN_MODE_LOW_POWER, - matchMode: bluetoothManager.MatchMode.MATCH_MODE_AGGRESSIVE, - } - ); -} catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); -} -``` - - -### stopBLEScan - -stopBLEScan(): void - -停止BLE扫描流程。 - -**需要权限**：ohos.permission.DISCOVER_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900099 | Operation failed. | - -**示例：** - -```js -try { - bluetoothManager.BLE.stopBLEScan(); -} catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); -} -``` - - -### on('BLEDeviceFind') - -on(type: "BLEDeviceFind", callback: Callback<Array<ScanResult>>): void - -订阅BLE设备发现上报事件。 - -**需要权限**：ohos.permission.USE_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ----------------------------------- | -| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | -| callback | Callback<Array<[ScanResult](#scanresult)>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900099 | Operation failed. | - -**示例：** - -```js -function onReceiveEvent(data) { - console.info('bluetooth device find = '+ JSON.stringify(data)); -} -try { - bluetoothManager.BLE.on('BLEDeviceFind', onReceiveEvent); -} catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); -} -``` - - -### off('BLEDeviceFind') - -off(type: "BLEDeviceFind", callback?: Callback<Array<ScanResult>>): void - -取消订阅BLE设备发现上报事件。 - -**需要权限**：ohos.permission.USE_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------------------------- | ---- | ---------------------------------------- | -| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | -| callback | Callback<Array<[ScanResult](#scanresult)>> | 否 | 表示取消订阅BLE设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900099 | Operation failed. | - -**示例：** - -```js -function onReceiveEvent(data) { - console.info('bluetooth device find = '+ JSON.stringify(data)); -} -try { - bluetoothManager.BLE.on('BLEDeviceFind', onReceiveEvent); - bluetoothManager.BLE.off('BLEDeviceFind', onReceiveEvent); -} catch (err) { - console.error("errCode:" + err.code + ",errMessage:" + err.message); -} -``` - - -## BaseProfile - -profile基类。 - - -### getConnectionDevices - -getConnectionDevices(): Array<string> - -获取已连接设备列表。 - -**需要权限**：ohos.permission.USE_BLUETOOTH - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -**返回值：** - -| 类型 | 说明 | -| ------------------- | ------------- | -| Array<string> | 返回已连接设备的地址列表。 | - -**错误码**： - -以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 - -| 错误码ID | 错误信息 | -| -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900004 | Profile is not supported. | -|2900099 | Operation failed. | - -**示例：** - -```js -try { - let a2dpSrc = bluetoothManager.getProfileInstance(bluetoothManager.ProfileId.PROFILE_A2DP_SOURCE) as bluetoothManager.A2dpSourceProfile; - let retArray = a2dpSrc.getConnectionDevices(); + deviceId:"XX:XX:XX:XX:XX:XX", + name:"test", + serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" + }], + { + interval: 500, + dutyMode: bluetoothManager.ScanDuty.SCAN_MODE_LOW_POWER, + matchMode: bluetoothManager.MatchMode.MATCH_MODE_AGGRESSIVE, + } + ); } catch (err) { console.error("errCode:" + err.code + ",errMessage:" + err.message); } ``` -### getDeviceState - -getDeviceState(device: string): ProfileConnectionState - -获取设备profile的连接状态。 -**需要权限**：ohos.permission.USE_BLUETOOTH +### stopBLEScan(deprecated) -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 +stopBLEScan(): void -**参数：** +停止BLE扫描流程。 -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------- | -| device | string | 是 | 远端设备地址。 | +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.startBLEScan](js-apis-bluetooth-ble.md#blestopblescan)替代。 -**返回值：** +**需要权限**：ohos.permission.DISCOVER_BLUETOOTH -| 类型 | 说明 | -| ------------------------------------------------- | ----------------------- | -| [ProfileConnectionState](#profileconnectionstate) | 返回profile的连接状态。 | +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 **错误码**： @@ -2063,39 +1647,38 @@ getDeviceState(device: string): ProfileConnectionState | -------- | ---------------------------- | |2900001 | Service stopped. | |2900003 | Bluetooth switch is off. | -|2900004 | Profile is not supported. | |2900099 | Operation failed. | **示例：** ```js try { - let a2dpSrc = bluetoothManager.getProfileInstance(bluetoothManager.ProfileId.PROFILE_A2DP_SOURCE) as bluetoothManager.A2dpSourceProfile; - let ret = a2dpSrc.getDeviceState('XX:XX:XX:XX:XX:XX'); + bluetoothManager.BLE.stopBLEScan(); } catch (err) { console.error("errCode:" + err.code + ",errMessage:" + err.message); } ``` -## bluetoothManager.setConnectionStrategy10+ -setConnectionStrategy(device: string, strategy: ConnectionStrategy, callback: AsyncCallback<void>): void +### on('BLEDeviceFind')(deprecated) -设置该设备Profile的连接策略。 +on(type: "BLEDeviceFind", callback: Callback<Array<ScanResult>>): void -**系统接口**：此接口为系统接口。 +订阅BLE设备发现上报事件。 -**需要权限**：ohos.permission.MANAGE_BLUETOOTH +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.on('BLEDeviceFind')](js-apis-bluetooth-ble.md#bleonbledevicefind)替代。 + +**需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------------------- | -| device | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | -| strategy | [ConnectionStrategy](#connectionstrategy10) | 是 |Profile的连接策略。 | -| callback | AsyncCallback<void> | 是 | 回调函数。当设置成功，err为undefined，否则为错误对象。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ----------------------------------- | +| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | +| callback | Callback<Array<[ScanResult](#scanresult)>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | **错误码**： @@ -2103,48 +1686,41 @@ setConnectionStrategy(device: string, strategy: ConnectionStrategy, callback: As | 错误码ID | 错误信息 | | -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900004 | Profile is not supported. | |2900099 | Operation failed. | **示例：** ```js +function onReceiveEvent(data) { + console.info('bluetooth device find = '+ JSON.stringify(data)); +} try { - let a2dpSrc = bluetoothManager.getProfileInstance(bluetoothManager.ProfileId.PROFILE_A2DP_SOURCE) as bluetoothManager.A2dpSourceProfile; - let setRet = a2dpSrc.setConnectionStrategy("XX:XX:XX:XX:XX:XX", 0, (err, data) => { - console.info("setConnectionStrategy, err: " + JSON.stringify(err) + ", data: " + JSON.stringify(data)); - }); + bluetoothManager.BLE.on('BLEDeviceFind', onReceiveEvent); } catch (err) { - console.error("errCode: " + err.code + ", errMessage: " + err.message); + console.error("errCode:" + err.code + ",errMessage:" + err.message); } ``` -## bluetoothManager.setConnectionStrategy10+ -setConnectionStrategy(device: string, strategy: ConnectionStrategy): Promise<void> +### off('BLEDeviceFind')(deprecated) -设置该设备Profile的连接策略。 +off(type: "BLEDeviceFind", callback?: Callback<Array<ScanResult>>): void -**系统接口**：此接口为系统接口。 +取消订阅BLE设备发现上报事件。 -**需要权限**：ohos.permission.MANAGE_BLUETOOTH +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.off('BLEDeviceFind')](js-apis-bluetooth-ble.md#bleoffbledevicefind)替代。 + +**需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------------------- | -| device | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | -| strategy | [ConnectionStrategy](#connectionstrategy10) | 是 |Profile的连接策略。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------- | ------------- | -| Promise<void> | 返回promise对象。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | +| callback | Callback<Array<[ScanResult](#scanresult)>> | 否 | 表示取消订阅BLE设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | **错误码**： @@ -2152,44 +1728,46 @@ setConnectionStrategy(device: string, strategy: ConnectionStrategy): Promise< | 错误码ID | 错误信息 | | -------- | ---------------------------- | -|2900001 | Service stopped. | -|2900003 | Bluetooth switch is off. | -|2900004 | Profile is not supported. | |2900099 | Operation failed. | **示例：** ```js +function onReceiveEvent(data) { + console.info('bluetooth device find = '+ JSON.stringify(data)); +} try { - let a2dpSrc = bluetoothManager.getProfileInstance(bluetoothManager.ProfileId.PROFILE_A2DP_SOURCE) as bluetoothManager.A2dpSourceProfile; - let setRet = a2dpSrc.setConnectionStrategy("XX:XX:XX:XX:XX:XX", 1).then((data) => { - console.info("setConnectionStrategy"); - }, err => { - console.error("setConnectionStrategy errCode: " + err.code + ", errMessage: " + err.message); - }); + bluetoothManager.BLE.on('BLEDeviceFind', onReceiveEvent); + bluetoothManager.BLE.off('BLEDeviceFind', onReceiveEvent); } catch (err) { - console.error("errCode: " + err.code + ", errMessage: " + err.message); + console.error("errCode:" + err.code + ",errMessage:" + err.message); } ``` -## bluetoothManager.getConnectionStrategy10+ -getConnectionStrategy(device: string, callback: AsyncCallback<ConnectionStrategy>): void +## BaseProfile + +profile基类。 -获取该Profile的连接策略。 -**系统接口**：此接口为系统接口。 +### getConnectionDevices(deprecated) -**需要权限**：ohos.permission.MANAGE_BLUETOOTH +getConnectionDevices(): Array<string> + +获取已连接设备列表。 + +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.getConnectedDevices](js-apis-bluetooth-baseProfile.md#baseprofilegetconnecteddevices)替代。 + +**需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 -**参数：** +**返回值：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------------------- | -| device | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | -| callback | AsyncCallback<[ConnectionStrategy](#connectionstrategy10)> | 是 | 回调函数。当获取策略成功，err为undefined，否则为错误对象。 | +| 类型 | 说明 | +| ------------------- | ------------- | +| Array<string> | 返回已连接设备的地址列表。 | **错误码**： @@ -2207,37 +1785,36 @@ getConnectionStrategy(device: string, callback: AsyncCallback<ConnectionStrat ```js try { let a2dpSrc = bluetoothManager.getProfileInstance(bluetoothManager.ProfileId.PROFILE_A2DP_SOURCE) as bluetoothManager.A2dpSourceProfile; - let setRet = a2dpSrc.getConnectionStrategy("XX:XX:XX:XX:XX:XX", 0, (err, data) => { - console.info("getConnectionStrategy, err: " + JSON.stringify(err) + ", data: " + JSON.stringify(data)); - }); + let retArray = a2dpSrc.getConnectionDevices(); } catch (err) { - console.error("errCode: " + err.code + ", errMessage: " + err.message); + console.error("errCode:" + err.code + ",errMessage:" + err.message); } ``` -## bluetoothManager.getConnectionStrategy10+ +### getDeviceState(deprecated) -getConnectionStrategy(device: string): Promise<ConnectionStrategy> +getDeviceState(device: string): ProfileConnectionState -获取该Profile的连接策略。 +获取设备profile的连接状态。 -**系统接口**：此接口为系统接口。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.getConnectionState](js-apis-bluetooth-baseProfile.md#baseprofilegetconnectionstate)替代。 -**需要权限**：ohos.permission.MANAGE_BLUETOOTH +**需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ----------------------------------- | -| device | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| device | string | 是 | 远端设备地址。 | **返回值：** -| 类型 | 说明 | -| ------------------- | ------------- | -| Promise<[ConnectionStrategy](#connectionstrategy10)> | 返回promise对象。 | +| 类型 | 说明 | +| ------------------------------------------------- | ----------------------- | +| [ProfileConnectionState](#profileconnectionstate) | 返回profile的连接状态。 | **错误码**： @@ -2255,27 +1832,30 @@ getConnectionStrategy(device: string): Promise<ConnectionStrategy> ```js try { let a2dpSrc = bluetoothManager.getProfileInstance(bluetoothManager.ProfileId.PROFILE_A2DP_SOURCE) as bluetoothManager.A2dpSourceProfile; - let setRet = a2dpSrc.getConnectionStrategy("XX:XX:XX:XX:XX:XX", 1).then((data) => { - console.info("getConnectionStrategy"); - }, (error) => { - console.error("getConnectionStrategy errCode: " + err.code + ", errMessage: " + err.message); - }); + let ret = a2dpSrc.getDeviceState('XX:XX:XX:XX:XX:XX'); } catch (err) { - console.error("errCode: " + err.code + ", errMessage: " + err.message); + console.error("errCode:" + err.code + ",errMessage:" + err.message); } ``` + ## A2dpSourceProfile 使用A2dpSourceProfile方法之前需要创建该类的实例进行操作，通过getProfile()方法构造此实例。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[a2dp.A2dpSourceProfile](js-apis-bluetooth-a2dp.md#a2dpsourceprofile)替代。 -### connect + +### connect(deprecated) connect(device: string): void 发起设备的A2dp服务连接请求。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[a2dp.A2dpSourceProfile#connect](js-apis-bluetooth-a2dp.md#connect)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -2309,12 +1889,15 @@ try { ``` -### disconnect +### disconnect(deprecated) disconnect(device: string): void 断开设备的a2dp服务连接。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[a2dp.A2dpSourceProfile#disconnect](js-apis-bluetooth-a2dp.md#disconnect)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -2348,12 +1931,15 @@ try { ``` -### on('connectionStateChange') +### on('connectionStateChange')(deprecated) on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void 订阅a2dp连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.on('connectionStateChange')](js-apis-bluetooth-baseProfile.md#baseprofileonconnectionstatechange)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -2378,12 +1964,15 @@ a2dpSrc.on('connectionStateChange', onReceiveEvent); ``` -### off('connectionStateChange') +### off('connectionStateChange')(deprecated) off(type: "connectionStateChange", callback?: Callback<[StateChangeParam](#StateChangeParam)>): void 取消订阅a2dp连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.off('connectionStateChange')](js-apis-bluetooth-baseProfile.md#baseprofileoffconnectionstatechange)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -2409,12 +1998,15 @@ a2dpSrc.off('connectionStateChange', onReceiveEvent); ``` -### getPlayingState +### getPlayingState(deprecated) getPlayingState(device: string): PlayingState 获取设备的播放状态。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[a2dp.A2dpSourceProfile#getPlayingState](js-apis-bluetooth-a2dp.md#getPlayingState)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -2452,10 +2044,13 @@ try { ``` -## HandsFreeAudioGatewayProfile +## HandsFreeAudioGatewayProfile(deprecated) 使用HandsFreeAudioGatewayProfile方法之前需要创建该类的实例进行操作，通过getProfile()方法构造此实例。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[hfp.HandsFreeAudioGatewayProfile](js-apis-bluetooth-hfp.md#HandsFreeAudioGatewayProfile)替代。 + ### connect @@ -2463,6 +2058,9 @@ connect(device: string): void 连接设备的HFP服务。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[hfp.HandsFreeAudioGatewayProfile#connect](js-apis-bluetooth-hfp.md#connect)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -2496,12 +2094,15 @@ try { ``` -### disconnect +### disconnect(deprecated) disconnect(device: string): void 断开连接设备的HFP服务。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[hfp.HandsFreeAudioGatewayProfile#disconnect](js-apis-bluetooth-hfp.md#disconnect)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -2535,12 +2136,15 @@ try { ``` -### on('connectionStateChange') +### on('connectionStateChange')(deprecated) on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void 订阅HFP连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.on('connectionStateChange')](js-apis-bluetooth-baseProfile.md#baseprofileonconnectionstatechange)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -2562,12 +2166,15 @@ hfpAg.on('connectionStateChange', onReceiveEvent); ``` -### off('connectionStateChange') +### off('connectionStateChange')(deprecated) off(type: "connectionStateChange", callback?: Callback<[StateChangeParam](#StateChangeParam)>): void 取消订阅HFP连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.off('connectionStateChange')](js-apis-bluetooth-baseProfile.md#baseprofileoffconnectionstatechange)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -2590,7 +2197,7 @@ hfpAg.off('connectionStateChange', onReceiveEvent); ``` -## HidHostProfile +## HidHostProfile(deprecated) 使用HidHostProfile方法之前需要创建该类的实例进行操作，通过getProfile()方法构造此实例。 @@ -2601,6 +2208,9 @@ connect(device: string): void 连接设备的HidHost服务。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[hid.HidHostProfile#connect](js-apis-bluetooth-hid.md#connect)替代。 + **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.DISCOVER_BLUETOOTH @@ -2636,12 +2246,15 @@ try { ``` -### disconnect +### disconnect(deprecated) disconnect(device: string): void 断开连接设备的HidHost服务。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[hid.HidHostProfile#disconnect](js-apis-bluetooth-hid.md#disconnect)替代。 + **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.DISCOVER_BLUETOOTH @@ -2677,12 +2290,15 @@ try { ``` -### on('connectionStateChange') +### on('connectionStateChange')(deprecated) on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void 订阅HidHost连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.on('connectionStateChange')](js-apis-bluetooth-baseProfile.md#baseprofileonconnectionstatechange)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -2703,12 +2319,15 @@ hidHost.on('connectionStateChange', onReceiveEvent); ``` -### off('connectionStateChange') +### off('connectionStateChange')(deprecated) off(type: "connectionStateChange", callback?: Callback<[StateChangeParam](#StateChangeParam)>): void 取消订阅HidHost连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.off('connectionStateChange')](js-apis-bluetooth-baseProfile.md#baseprofileoffconnectionstatechange)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -2734,13 +2353,19 @@ hidHost.off('connectionStateChange', onReceiveEvent); 使用PanProfile方法之前需要创建该类的实例进行操作，通过getProfile()方法构造此实例。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[pan.PanProfile](js-apis-bluetooth-pan.md#panprofile)替代。 + -### disconnect +### disconnect(deprecated) disconnect(device: string): void 断开连接设备的Pan服务。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[pan.PanProfile#disconnect](js-apis-bluetooth-pan.md#disconnect)替代。 + **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.USE_BLUETOOTH @@ -2776,12 +2401,15 @@ try { ``` -### on('connectionStateChange') +### on('connectionStateChange')(deprecated) on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void 订阅Pan连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.on('connectionStateChange')](js-apis-bluetooth-baseProfile.md#baseprofileonconnectionstatechange)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -2802,12 +2430,15 @@ panProfile.on('connectionStateChange', onReceiveEvent); ``` -### off('connectionStateChange') +### off('connectionStateChange')(deprecated) off(type: "connectionStateChange", callback?: Callback<[StateChangeParam](#StateChangeParam)>): void 取消订阅Pan连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.off('connectionStateChange')](js-apis-bluetooth-baseProfile.md#baseprofileoffconnectionstatechange)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 **参数：** @@ -2829,12 +2460,15 @@ panProfile.off('connectionStateChange', onReceiveEvent); ``` -### setTethering +### setTethering(deprecated) setTethering(enable: boolean): void 设置网络共享状态。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[pan.PanProfile#setTethering](js-apis-bluetooth-pan.md#setTethering)替代。 + **系统接口**：此接口为系统接口。 **需要权限**：ohos.permission.DISCOVER_BLUETOOTH @@ -2870,12 +2504,15 @@ try { ``` -### isTetheringOn +### isTetheringOn(deprecated) isTetheringOn(): boolean 获取网络共享状态。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[pan.PanProfile#isTetheringOn](js-apis-bluetooth-pan.md#isTetheringOn)替代。 + **系统接口**：此接口为系统接口。 **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -2902,13 +2539,19 @@ try { server端类，使用server端方法之前需要创建该类的实例进行操作，通过createGattServer()方法构造此实例。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer](js-apis-bluetooth-ble.md#GattServer)替代。 + -### startAdvertising +### startAdvertising(deprecated) startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void 开始发送BLE广播。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.startAdvertising](js-apis-bluetooth-ble.md#blestartadvertising)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -2951,7 +2594,7 @@ let gattServer = bluetoothManager.BLE.createGattServer(); try { gattServer.startAdvertising({ interval:150, - txPower:60, + txPower:0, connectable:true, },{ serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], @@ -2980,12 +2623,15 @@ try { ``` -### stopAdvertising +### stopAdvertising(deprecated) stopAdvertising(): void 停止发送BLE广播。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.stopAdvertising](js-apis-bluetooth-ble.md#blestopadvertising)替代。 + **需要权限**：ohos.permission.DISCOVER_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3012,12 +2658,15 @@ try { ``` -### addService +### addService(deprecated) addService(service: GattService): void server端添加服务。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#addService](js-apis-bluetooth-ble.md#addservice)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3074,12 +2723,15 @@ try { ``` -### removeService +### removeService(deprecated) removeService(serviceUuid: string): void 删除已添加的服务。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#removeService](js-apis-bluetooth-ble.md#removeservice)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3113,12 +2765,15 @@ try { ``` -### close +### close(deprecated) close(): void 关闭服务端功能，去注册server在协议栈的注册，调用该接口后[GattServer](#gattserver)实例将不能再使用。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#close](js-apis-bluetooth-ble.md#close)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3145,12 +2800,15 @@ try { ``` -### notifyCharacteristicChanged +### notifyCharacteristicChanged(deprecated) notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic): void server端特征值发生变化时，主动通知已连接的client设备。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#notifyCharacteristicChanged](js-apis-bluetooth-ble.md#notifycharacteristicchanged)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3198,12 +2856,15 @@ try { ``` -### sendResponse +### sendResponse(deprecated) sendResponse(serverResponse: ServerResponse): void server端回复client端的读写请求。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#sendResponse](js-apis-bluetooth-ble.md#sendresponse)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3248,12 +2909,15 @@ try { ``` -### on('characteristicRead') +### on('characteristicRead')(deprecated) on(type: "characteristicRead", callback: Callback<CharacteristicReadRequest>): void server端订阅特征值读请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#on('characteristicRead')](js-apis-bluetooth-ble.md#oncharacteristicread)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3291,12 +2955,15 @@ gattServer.on("characteristicRead", ReadCharacteristicReq); ``` -### off('characteristicRead') +### off('characteristicRead')(deprecated) off(type: "characteristicRead", callback?: Callback<CharacteristicReadRequest>): void server端取消订阅特征值读请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#off('characteristicRead')](js-apis-bluetooth-ble.md#offcharacteristicread)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3316,12 +2983,15 @@ gattServer.off("characteristicRead"); ``` -### on('characteristicWrite') +### on('characteristicWrite')(deprecated) on(type: "characteristicWrite", callback: Callback<CharacteristicWriteRequest>): void server端订阅特征值写请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#on('characteristicWrite')](js-apis-bluetooth-ble.md#oncharacteristicwrite)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3362,12 +3032,15 @@ gattServer.on("characteristicWrite", WriteCharacteristicReq); ``` -### off('characteristicWrite') +### off('characteristicWrite')(deprecated) off(type: "characteristicWrite", callback?: Callback<CharacteristicWriteRequest>): void server端取消订阅特征值写请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#off('characteristicWrite')](js-apis-bluetooth-ble.md#offcharacteristicwrite)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3387,12 +3060,15 @@ gattServer.off("characteristicWrite"); ``` -### on('descriptorRead') +### on('descriptorRead')(deprecated) on(type: "descriptorRead", callback: Callback<DescriptorReadRequest>): void server端订阅描述符读请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#on('descriptorRead')](js-apis-bluetooth-ble.md#ondescriptorread)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3430,12 +3106,15 @@ gattServer.on("descriptorRead", ReadDescriptorReq); ``` -### off('descriptorRead') +### off('descriptorRead')(deprecated) off(type: "descriptorRead", callback?: Callback<DescriptorReadRequest>): void server端取消订阅描述符读请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#off('descriptorRead')](js-apis-bluetooth-ble.md#offdescriptorread)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3455,12 +3134,15 @@ gattServer.off("descriptorRead"); ``` -### on('descriptorWrite') +### on('descriptorWrite')(deprecated) on(type: "descriptorWrite", callback: Callback<DescriptorWriteRequest>): void server端订阅描述符写请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#on('descriptorWrite')](js-apis-bluetooth-ble.md#ondescriptorwrite)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3501,12 +3183,15 @@ gattServer.on("descriptorRead", WriteDescriptorReq); ``` -### off('descriptorWrite') +### off('descriptorWrite')(deprecated) off(type: "descriptorWrite", callback?: Callback<DescriptorWriteRequest>): void server端取消订阅描述符写请求事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#off('descriptorWrite')](js-apis-bluetooth-ble.md#offdescriptorwrite)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3526,12 +3211,15 @@ gattServer.off("descriptorWrite"); ``` -### on('connectStateChange') +### on('connectStateChange')(deprecated) on(type: "connectStateChange", callback: Callback<BLEConnectChangedState>): void server端订阅BLE连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#on('connectionStateChange')](js-apis-bluetooth-ble.md#onconnectionstatechange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3556,12 +3244,15 @@ gattServer.on("connectStateChange", Connected); ``` -### off('connectStateChange') +### off('connectStateChange')(deprecated) off(type: "connectStateChange", callback?: Callback<BLEConnectChangedState>): void server端取消订阅BLE连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattServer#off('connectionStateChange')](js-apis-bluetooth-ble.md#offconnectionstatechange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3585,13 +3276,19 @@ gattServer.off("connectStateChange"); client端类，使用client端方法之前需要创建该类的实例进行操作，通过createGattClientDevice(deviceId: string)方法构造此实例。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice](js-apis-bluetooth-ble.md#gattclientdevice)替代。 + -### connect +### connect(deprecated) connect(): void client端发起连接远端蓝牙低功耗设备。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#connect](js-apis-bluetooth-ble.md#connect)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3618,12 +3315,15 @@ try { ``` -### disconnect +### disconnect(deprecated) disconnect(): void client端断开与远端蓝牙低功耗设备的连接。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#disconnect](js-apis-bluetooth-ble.md#disconnect)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3650,12 +3350,15 @@ try { ``` -### close +### close(deprecated) close(): void 关闭客户端功能，注销client在协议栈的注册，调用该接口后[GattClientDevice](#gattclientdevice)实例将不能再使用。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#close](js-apis-bluetooth-ble.md#close)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3684,11 +3387,14 @@ try { -### getServices +### getServices(deprecated) getServices(callback: AsyncCallback<Array<GattService>>): void -client端获取蓝牙低功耗设备的所有服务，即服务发现 。 +client端获取蓝牙低功耗设备的所有服务，即服务发现。 + +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#getServices](js-apis-bluetooth-ble.md#getservices)替代。 **需要权限**：ohos.permission.USE_BLUETOOTH @@ -3735,12 +3441,15 @@ try { ``` -### getServices +### getServices(deprecated) getServices(): Promise<Array<GattService>> client端获取蓝牙低功耗设备的所有服务，即服务发现。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#getServices](js-apis-bluetooth-ble.md#getservices-1)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3776,12 +3485,15 @@ try { ``` -### readCharacteristicValue +### readCharacteristicValue(deprecated) readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void client端读取蓝牙低功耗设备特定服务的特征值。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#readCharacteristicValue](js-apis-bluetooth-ble.md#readcharacteristicvalue)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3840,12 +3552,15 @@ try { ``` -### readCharacteristicValue +### readCharacteristicValue(deprecated) readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic> client端读取蓝牙低功耗设备特定服务的特征值。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#readCharacteristicValue](js-apis-bluetooth-ble.md#readcharacteristicvalue-1)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3900,12 +3615,15 @@ try { ``` -### readDescriptorValue +### readDescriptorValue(deprecated) readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void client端读取蓝牙低功耗设备特定的特征包含的描述符。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#readDescriptorValue](js-apis-bluetooth-ble.md#readdescriptorvalue)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -3957,12 +3675,15 @@ try { ``` -### readDescriptorValue +### readDescriptorValue(deprecated) readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor> client端读取蓝牙低功耗设备特定的特征包含的描述符。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#readDescriptorValue](js-apis-bluetooth-ble.md#readdescriptorvalue-1)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4010,12 +3731,15 @@ try { ``` -### writeCharacteristicValue +### writeCharacteristicValue(deprecated) writeCharacteristicValue(characteristic: BLECharacteristic): void client端向低功耗蓝牙设备写入特定的特征值。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#writeCharacteristicValue](js-apis-bluetooth-ble.md#writecharacteristicvalue)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4063,12 +3787,15 @@ try { ``` -### writeDescriptorValue +### writeDescriptorValue(deprecated) writeDescriptorValue(descriptor: BLEDescriptor): void client端向低功耗蓝牙设备特定的描述符写入二进制数据。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#writeCharacteristicValue](js-apis-bluetooth-ble.md#writecharacteristicvalue-1)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4111,12 +3838,15 @@ try { ``` -### setBLEMtuSize +### setBLEMtuSize(deprecated) setBLEMtuSize(mtu: number): void client协商远端蓝牙低功耗设备的最大传输单元（Maximum Transmission Unit, MTU），调用[connect](#connect)接口连接成功后才能使用。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#setBLEMtuSize](js-apis-bluetooth-ble.md#setBLEMtuSize)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4148,12 +3878,15 @@ try { ``` -### setNotifyCharacteristicChanged +### setNotifyCharacteristicChanged(deprecated) setNotifyCharacteristicChanged(characteristic: BLECharacteristic, enable: boolean): void 向服务端发送设置通知此特征值请求。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#setCharacteristicChangeNotification](js-apis-bluetooth-ble.md#setcharacteristicchangenotification)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4199,12 +3932,15 @@ try { ``` -### on('BLECharacteristicChange') +### on('BLECharacteristicChange')(deprecated) on(type: "BLECharacteristicChange", callback: Callback<BLECharacteristic>): void 订阅蓝牙低功耗设备的特征值变化事件。需要先调用setNotifyCharacteristicChanged接口才能接收server端的通知。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#on('BLECharacteristicChange')](js-apis-bluetooth-ble.md#onblecharacteristicchange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4233,12 +3969,15 @@ try { ``` -### off('BLECharacteristicChange') +### off('BLECharacteristicChange')(deprecated) off(type: "BLECharacteristicChange", callback?: Callback<BLECharacteristic>): void 取消订阅蓝牙低功耗设备的特征值变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#off('BLECharacteristicChange')](js-apis-bluetooth-ble.md#offblecharacteristicchange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4262,12 +4001,15 @@ try { ``` -### on('BLEConnectionStateChange') +### on('BLEConnectionStateChange')(deprecated) on(type: "BLEConnectionStateChange", callback: Callback<BLEConnectChangedState>): void client端订阅蓝牙低功耗设备的连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#on('BLEConnectionStateChange')](js-apis-bluetooth-ble.md#onbleconnectionstatechange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4295,12 +4037,15 @@ try { ``` -### off('BLEConnectionStateChange') +### off('BLEConnectionStateChange')(deprecated) off(type: "BLEConnectionStateChange", callback?: Callback<BLEConnectChangedState>): void 取消订阅蓝牙低功耗设备的连接状态变化事件。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#off('BLEConnectionStateChange')](js-apis-bluetooth-ble.md#offbleconnectionstatechange)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4324,12 +4069,15 @@ try { ``` -### getDeviceName +### getDeviceName(deprecated) getDeviceName(callback: AsyncCallback<string>): void client获取远端蓝牙低功耗设备名。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#getDeviceName](js-apis-bluetooth-ble.md#getdevicename)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4366,12 +4114,15 @@ try { ``` -### getDeviceName +### getDeviceName(deprecated) getDeviceName(): Promise<string> client获取远端蓝牙低功耗设备名。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#getDeviceName](js-apis-bluetooth-ble.md#getdevicename-1)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4407,12 +4158,15 @@ try { ``` -### getRssiValue +### getRssiValue(deprecated) getRssiValue(callback: AsyncCallback<number>): void client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#getRssiValue](js-apis-bluetooth-ble.md#getrssivalue)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4448,12 +4202,15 @@ try { ``` -### getRssiValue +### getRssiValue(deprecated) getRssiValue(): Promise<number> client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattClientDevice#getRssiValue](js-apis-bluetooth-ble.md#getrssivalue-1)替代。 + **需要权限**：ohos.permission.USE_BLUETOOTH **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4486,10 +4243,13 @@ try { } ``` -## ScanMode +## ScanMode(deprecated) 枚举，扫描模式。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.ScanMode](js-apis-bluetooth-connection.md#scanmode)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -4501,10 +4261,13 @@ try { | SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4 | 可连接general发现模式。 | | SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5 | 可连接limited发现模式。 | -## BondState +## BondState(deprecated) 枚举，配对状态。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.BondState](js-apis-bluetooth-connection.md#bondstate)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -4514,10 +4277,13 @@ try { | BOND_STATE_BONDED | 2 | 已配对。 | -## SppOption +## SppOption(deprecated) 描述spp的配置参数。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.SppOption](js-apis-bluetooth-socket.md#sppoptions)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4527,10 +4293,13 @@ try { | type | [SppType](#spptype) | 是 | 是 | Spp链路类型。 | -## SppType +## SppType(deprecated) 枚举，Spp链路类型。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[socket.SppType](js-apis-bluetooth-socket.md#spptype)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -4538,10 +4307,13 @@ try { | SPP_RFCOMM | 0 | 表示rfcomm链路类型。 | -## GattService +## GattService(deprecated) 描述service的接口参数定义。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.GattService](js-apis-bluetooth-ble.md#gattservice)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4552,9 +4324,12 @@ try { | includeServices | Array<[GattService](#gattservice)> | 是 | 是 | 当前服务依赖的其它服务。 | -## BLECharacteristic +## BLECharacteristic(deprecated) + +描述characteristic的接口参数定义。 -描述characteristic的接口参数定义 。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.BLECharacteristic](js-apis-bluetooth-ble.md#blecharacteristic)替代。 **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4564,12 +4339,14 @@ try { | characteristicUuid | string | 是 | 是 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | | characteristicValue | ArrayBuffer | 是 | 是 | 特征对应的二进制值。 | | descriptors | Array<[BLEDescriptor](#bledescriptor)> | 是 | 是 | 特定特征的描述符列表。 | -| properties10+ | [GattProperties](#gattproperties10) | 是 | 是 | 特定特征的属性描述。 | -## BLEDescriptor +## BLEDescriptor(deprecated) -描述descriptor的接口参数定义 。 +描述descriptor的接口参数定义。 + +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.BLEDescriptor](js-apis-bluetooth-ble.md#bledescriptor)替代。 **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4581,10 +4358,13 @@ try { | descriptorValue | ArrayBuffer | 是 | 是 | 描述符对应的二进制值。 | -## NotifyCharacteristic +## NotifyCharacteristic(deprecated) 描述server端特征值变化时发送的特征通知参数定义。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.NotifyCharacteristic](js-apis-bluetooth-ble.md#notifycharacteristic)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4595,10 +4375,13 @@ try { | confirm | boolean | 是 | 是 | 如果是notification则对端回复确认设置为true，如果是indication则对端不需要回复确认设置为false。 | -## CharacteristicReadRequest +## CharacteristicReadRequest(deprecated) 描述server端订阅后收到的特征值读请求事件参数结构。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.CharacteristicReadRequest](js-apis-bluetooth-ble.md#characteristicreadrequest)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4610,10 +4393,13 @@ try { | serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | -## CharacteristicWriteRequest +## CharacteristicWriteRequest(deprecated) 描述server端订阅后收到的特征值写请求事件参数结构。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.CharacteristicWriteRequest](js-apis-bluetooth-ble.md#characteristicwriterequest)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4626,10 +4412,13 @@ try { | serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | -## DescriptorReadRequest +## DescriptorReadRequest(deprecated) 描述server端订阅后收到的描述符读请求事件参数结构。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.DescriptorReadRequest](js-apis-bluetooth-ble.md#descriptorreadrequest)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4642,10 +4431,13 @@ try { | serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | -## DescriptorWriteRequest +## DescriptorWriteRequest(deprecated) 描述server端订阅后收到的描述符写请求事件参数结构。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.DescriptorWriteRequest](js-apis-bluetooth-ble.md#descriptorwriterequest)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4661,10 +4453,13 @@ try { | serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | -## ServerResponse +## ServerResponse(deprecated) 描述server端回复client端读/写请求的响应参数结构。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.ServerResponse](js-apis-bluetooth-ble.md#serverresponse)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4676,9 +4471,12 @@ try { | value | ArrayBuffer | 是 | 否 | 表示回复响应的二进制数据。 | -## BLEConnectChangedState +## BLEConnectChangedState(deprecated) + +描述Gatt profile连接状态。 -描述Gatt profile连接状态 。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[BLEConnectionChangeState](js-apis-bluetooth-ble.md#bleconnectionchangestate)替代。 **系统能力**：SystemCapability.Communication.Bluetooth.Core。 @@ -4688,10 +4486,13 @@ try { | state | [ProfileConnectionState](#profileconnectionstate) | 是 | 是 | 表示BLE连接状态的枚举。 | -## ProfileConnectionState +## ProfileConnectionState(deprecated) 枚举，蓝牙设备的profile连接状态。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[constant.ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -4702,10 +4503,13 @@ try { | STATE_DISCONNECTING | 3 | 表示profile正在断连。 | -## ScanFilter +## ScanFilter(deprecated) 扫描过滤参数。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.ScanFilter](js-apis-bluetooth-ble.md#scanfilter)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4723,10 +4527,13 @@ try { | manufactureDataMask | ArrayBuffer | 是 | 是 | 表示过滤包含该制造商相关数据掩码的设备，例如：[0xFF,0xFF,0xFF]。 | -## ScanOptions +## ScanOptions(deprecated) 扫描的配置参数。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.ScanOptions](js-apis-bluetooth-ble.md#scanoptions)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4736,10 +4543,13 @@ try { | matchMode | [MatchMode](#matchmode) | 是 | 是 | 表示硬件的过滤匹配模式，默认值为MATCH_MODE_AGGRESSIVE。 | -## ScanDuty +## ScanDuty(deprecated) 枚举，扫描模式。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.ScanDuty](js-apis-bluetooth-ble.md#scanduty)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -4749,10 +4559,13 @@ try { | SCAN_MODE_LOW_LATENCY | 2 | 表示低延迟模式。 | -## MatchMode +## MatchMode(deprecated) 枚举，硬件过滤匹配模式。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.MatchMode](js-apis-bluetooth-ble.md#matchmode)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -4761,10 +4574,13 @@ try { | MATCH_MODE_STICKY | 2 | 表示硬件上报扫描结果门限较高，更高的功率门限以及扫描到多次才会上报。 | -## ScanResult +## ScanResult(deprecated) 扫描结果上报数据。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.ScanResult](js-apis-bluetooth-ble.md#scanresult)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4772,13 +4588,15 @@ try { | deviceId | string | 是 | 否 | 表示扫描到的设备地址，例如："XX:XX:XX:XX:XX:XX"。 | | rssi | number | 是 | 否 | 表示扫描到的设备的rssi值。 | | data | ArrayBuffer | 是 | 否 | 表示扫描到的设备发送的广播包。 | -| deviceName10+ | string | 是 | 否 | 表示扫描到的设备名称。 | -## BluetoothState +## BluetoothState(deprecated) 枚举，蓝牙开关状态。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[access.BluetoothState](js-apis-bluetooth-access.md#bluetoothstate)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -4792,10 +4610,13 @@ try { | STATE_BLE_TURNING_OFF | 6 | 表示蓝牙正在关闭LE-only模式。 | -## AdvertiseSetting +## AdvertiseSetting(deprecated) 描述蓝牙低功耗设备发送广播的参数。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.AdvertiseSetting](js-apis-bluetooth-ble.md#advertisesetting)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4805,10 +4626,13 @@ try { | connectable | boolean | 是 | 是 | 表示是否是可连接广播，默认值设置为true。 | -## AdvertiseData +## AdvertiseData(deprecated) 描述BLE广播数据包的内容。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.AdvertiseData](js-apis-bluetooth-ble.md#advertisedata)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4816,13 +4640,15 @@ try { | serviceUuids | Array<string> | 是 | 是 | 表示要广播的服务 UUID 列表。 | | manufactureData | Array<[ManufactureData](#manufacturedata)> | 是 | 是 | 表示要广播的广播的制造商信息列表。 | | serviceData | Array<[ServiceData](#servicedata)> | 是 | 是 | 表示要广播的服务数据列表。 | -| includeDeviceName10+ | boolean | 是 | 是 | 表示是否携带设备名，可选参数。 | -## ManufactureData +## ManufactureData(deprecated) 描述BLE广播数据包的内容。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.ManufactureData](js-apis-bluetooth-ble.md#manufacturedata)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4831,10 +4657,13 @@ try { | manufactureValue | ArrayBuffer | 是 | 是 | 表示制造商发送的制造商数据。 | -## ServiceData +## ServiceData(deprecated) 描述广播包中服务数据内容。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[ble.ServiceData](js-apis-bluetooth-ble.md#servicedata)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4843,23 +4672,28 @@ try { | serviceValue | ArrayBuffer | 是 | 是 | 表示服务数据。 | -## PinRequiredParam +## PinRequiredParam(deprecated) 描述配对请求参数。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.PinRequiredParam](js-apis-bluetooth-connection.md#pinrequiredparam)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | | -------- | ------ | ---- | ---- | ----------- | | deviceId | string | 是 | 否 | 表示要配对的设备ID。 | | pinCode | string | 是 | 否 | 表示要配对的密钥。 | -| pinType10+ | [PinType](#pintype10) | 是 | 否 | 表示要配对的设备类型。
此接口为系统接口。 | -## BondStateParam +## BondStateParam(deprecated) 描述配对状态参数。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.BondStateParam](js-apis-bluetooth-connection.md#bondstateparam)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4868,10 +4702,13 @@ try { | state | BondState | 是 | 否 | 表示配对设备的状态。 | -## StateChangeParam +## StateChangeParam(deprecated) 描述profile状态改变参数。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[baseProfile.StateChangeParam](js-apis-bluetooth-baseProfile.md#statechangeparam)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4880,25 +4717,13 @@ try { | state | [ProfileConnectionState](#profileconnectionstate) | 是 | 否 | 表示蓝牙设备的profile连接状态。 | -## GattProperties10+ - -描述gatt characteristic的属性。 - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -| 名称 | 类型 | 必填 | 说明 | -| -------- | ------ |---- | ----------- | -| write10+ | boolean | 是 | 表示该特征支持写操作，需要对端设备的回复。 | -| writeNoResponse10+ | boolean | 是 | 表示该特征支持写操作，无需对端设备回复。 | -| read10+ | boolean | 是 | 表示该特征支持读操作。 | -| notify10+ | boolean | 是 | 表示该特征可通知对端设备。 | -| indicate10+ | boolean | 是 | 表示该特征可通知对端设备，需要对端设备的回复。 | - - -## DeviceClass +## DeviceClass(deprecated) 描述蓝牙设备的类别。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[connection.DeviceClass](js-apis-bluetooth-connection.md#deviceclass)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 类型 | 可读 | 可写 | 说明 | @@ -4908,10 +4733,13 @@ try { | classOfDevice | number | 是 | 否 | 表示设备类别。 | -## MajorClass +## MajorClass(deprecated) 枚举，蓝牙设备主要类别。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[constant.MajorClass](js-apis-bluetooth-constant.md#majorclass)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -4929,10 +4757,13 @@ try { | MAJOR_UNCATEGORIZED | 0x1F00 | 表示未分类设备。 | -## MajorMinorClass +## MajorMinorClass(deprecated) 枚举，主要次要蓝牙设备类别。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[constant.MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -5025,10 +4856,13 @@ try { | HEALTH_PERSONAL_MOBILITY_DEVICE | 0x093C | 表示个人移动健康设备。 | -## PlayingState +## PlayingState(deprecated) 枚举，蓝牙A2DP 播放状态。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[a2dp.PlayingState](js-apis-bluetooth-a2dp.md#playingstate)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -5037,10 +4871,13 @@ try { | STATE_PLAYING | 0x0001 | 表示正在播放。 | -## ProfileId +## ProfileId(deprecated) 蓝牙profile枚举，API9新增PROFILE_HID_HOST，PROFILE_PAN_NETWORK。 +> **说明：**
+> 从API version 9开始支持，从API version 10开始废弃。建议使用[constant.ProfileId](js-apis-bluetooth-constant.md#profileid)替代。 + **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 值 | 说明 | @@ -5049,72 +4886,3 @@ try { | PROFILE_HANDS_FREE_AUDIO_GATEWAY | 4 | 表示HFP profile。 | | PROFILE_HID_HOST | 6 | 表示HID profile。 | | PROFILE_PAN_NETWORK | 7 | 表示PAN profile。 | - - -## BluetoothTransport10+ - -枚举，表示设备类型。例如传统蓝牙设备或低功耗蓝牙设备，支持双模默认使用TRANSPORT_BR_EDR。 - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -| 名称 | 值 | 说明 | -| -------------------------------- | ------ | --------------- | -| TRANSPORT_BR_EDR10+ | 0 | 表示传统蓝牙(BR/EDR)设备。 | -| TRANSPORT_LE10+ | 1 | 表示低功耗蓝牙(BLE)设备。 | - - -## ConnectionStrategy10+ - -枚举，表示Profile的连接策略。 - -**系统接口：** 此接口为系统接口。 - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -| 名称 | 值 | 说明 | -| -------------------------------- | ------ | --------------- | -| CONNECT_STRATEGY_UNSUPPORTED 10+ | 0 | 当设备未配对时的默认连接策略。
此接口为系统接口。 | -| CONNECT_STRATEGY_ALLOWED 10+ | 1 | 设备允许接受或发起配对时的连接策略。
此接口为系统接口。 | -| CONNECT_STRATEGY_FORBIDDEN 10+ | 2 | 设备不允许接受或发起配对时的连接策略。
此接口为系统接口。 | - - -## PinType10+ - -枚举，蓝牙配对类型。 - -**系统接口：** 此接口为系统接口。 - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -| 名称 | 值 | 说明 | -| -------------------------------- | ------ | --------------- | -| PIN_TYPE_ENTER_PIN_CODE10+ | 0 | 用户需要输入对端设备上显示的PIN码。
此接口为系统接口。 | -| PIN_TYPE_ENTER_PASSKEY10+ | 1 | 用户需要输入对端设备上显示的PASSKEY。
此接口为系统接口。 | -| PIN_TYPE_CONFIRM_PASSKEY10+ | 2 | 用户需要确认本地设备上显示的PASSKEY。
此接口为系统接口。 | -| PIN_TYPE_NO_PASSKEY_CONSENT10+ | 3 | 无PASSKEY，用户需要接受或拒绝配对请求。
此接口为系统接口。 | -| PIN_TYPE_NOTIFY_PASSKEY10+ | 4 | 本地设备显示PASSKEY，用户需要在对端设备上输入该PASSKEY。
此接口为系统接口。 | -| PIN_TYPE_DISPLAY_PIN_CODE10+ | 5 | bluetooth 2.0设备，用户需要输入对端设备上显示的PIN码。
此接口为系统接口。 | -| PIN_TYPE_OOB_CONSENT10+ | 6 | 用户需要接受或拒绝OOB配对请求。
此接口为系统接口。 | -| PIN_TYPE_PIN_16_DIGITS10+ | 7 | 用户需要输入对端设备上显示的16位PIN码。
此接口为系统接口。 | - - -## ProfileUuids10+ - -枚举，表示Profile的UUID。 - -**系统接口：** 此接口为系统接口。 - -**系统能力**：SystemCapability.Communication.Bluetooth.Core。 - -| 名称 | 值 | 说明 | -| ------------------------------------| ------ | --------------- | -| PROFILE_UUID_HFP_AG 10+ | '0000111F-0000-1000-8000-00805F9B34FB' | 代表HFPAG Profile的UUID。
此接口为系统接口。 | -| PROFILE_UUID_HFP_HF 10+ | '0000111E-0000-1000-8000-00805F9B34FB' | 代表HFPHF Profile的UUID。
此接口为系统接口。 | -| PROFILE_UUID_HSP_AG 10+ | '00001112-0000-1000-8000-00805F9B34FB' | 代表HSPAG Profile的UUID。
此接口为系统接口。 | -| PROFILE_UUID_HSP_HS 10+ | '00001108-0000-1000-8000-00805F9B34FB' | 代表HSPHS Profile的UUID。
此接口为系统接口。 | -| PROFILE_UUID_A2DP_SRC 10+ | '0000110A-0000-1000-8000-00805F9B34FB' | 代表A2DPSRC Profile的UUID。
此接口为系统接口。 | -| PROFILE_UUID_A2DP_SINK 10+ | '0000110B-0000-1000-8000-00805F9B34FB' | 代表A2DPSINK Profile的UUID。
此接口为系统接口。 | -| PROFILE_UUID_AVRCP_CT 10+ | '0000110E-0000-1000-8000-00805F9B34FB' | 代表AVRCPCT Profile的UUID。
此接口为系统接口。 | -| PROFILE_UUID_AVRCP_TG 10+ | '0000110C-0000-1000-8000-00805F9B34FB' | 代表AVRCPTG Profile的UUID。
此接口为系统接口。 | -| PROFILE_UUID_HID 10+ | '00001124-0000-1000-8000-00805F9B34FB' | 代表HID Profile的UUID。
此接口为系统接口。 | -| PROFILE_UUID_HOGP 10+ | '00001812-0000-1000-8000-00805F9B34FB' | 代表HOGP Profile的UUID。
此接口为系统接口。 | -- GitLab