diff --git a/zh-cn/application-dev/reference/apis/js-apis-bluetooth.md b/zh-cn/application-dev/reference/apis/js-apis-bluetooth.md old mode 100755 new mode 100644 index 0dee02f1250d67ccc0be39e220008359b7157e1c..94fa29479a6f8d4ab97edf9b93df19387eb438eb --- a/zh-cn/application-dev/reference/apis/js-apis-bluetooth.md +++ b/zh-cn/application-dev/reference/apis/js-apis-bluetooth.md @@ -13,17 +13,6 @@ import bluetooth from '@ohos.bluetooth'; ``` -## 权限 - -ohos.permission.USE_BLUETOOTH - -ohos.permission.MANAGE_BLUETOOTH - -ohos.permission.DISCOVER_BLUETOOTH - -ohos.permission.LOCATION - - ## bluetooth.enableBluetooth8+ enableBluetooth(): boolean @@ -237,6 +226,8 @@ cancelPairedDevice(deviceId: string): boolean **系统能力**：SystemCapability.Communication.Bluetooth.Core。 +**系统API**：该接口为系统接口，三方应用不支持调用。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -979,13 +970,13 @@ getProfile(profileId: ProfileId): A2dpSourceProfile | HandsFreeAudioGatewayProfi | 参数名 | 类型 | 必填 | 说明 | | --------- | --------- | ---- | ------------------------------------- | -| ProfileId | profileId | 是 | 表示profile的枚举值，例如：PROFILE_A2DP_SOURCE。 | +| profileId | [ProfileId](#ProfileId) | 是 | 表示profile的枚举值，例如：PROFILE_A2DP_SOURCE。 | **返回值：** -| 类型 | 说明 | -| ---------------------------------------- | ---------------------------------------- | -| A2dpSourceProfile 或者 HandsFreeAudioGatewayProfile | 对应的profile的对象实例，当前支持A2dpSourceProfile， HandsFreeAudioGatewayProfile。 | +| 类型 | 说明 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [A2dpSourceProfile](#A2dpSourceProfile)或[HandsFreeAudioGatewayProfile](#HandsFreeAudioGatewayProfile) | 对应的profile的对象实例，当前支持A2dpSourceProfile， HandsFreeAudioGatewayProfile。 | **示例：** @@ -993,6 +984,32 @@ getProfile(profileId: ProfileId): A2dpSourceProfile | HandsFreeAudioGatewayProfi let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); ``` +## bluetooth.getProfile9+ + +getProfile(profileId: ProfileId): A2dpSourceProfile | HandsFreeAudioGatewayProfile | HidHostProfile + +通过ProfileId，获取profile的对象实例，API9新增了HidHostProfile。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | --------- | ---- | ------------------------------------- | +| profileId | [ProfileId](#ProfileId) | 是 | 表示profile的枚举值，例如：PROFILE_A2DP_SOURCE。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [A2dpSourceProfile](#A2dpSourceProfile)或 [HandsFreeAudioGatewayProfile](#HandsFreeAudioGatewayProfile)或[HidHostProfile](#HidHostProfile) | 对应的profile的对象实例，当前支持A2dpSourceProfile/HandsFreeAudioGatewayProfile/HidHostProfile。 | + +**示例：** + +```js +let hidHost = bluetooth.getProfile(PROFILE_HID_HOST); +``` + ## bluetooth.BLE @@ -1215,11 +1232,16 @@ getConnectionDevices(): Array<string> **返回值：** -| | | -| ------------------- | ------------- | | 类型 | 说明 | +| ------------------- | ------------- | | Array<string> | 返回已连接设备的地址列表。 | +**示例：** + +```js +let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE) +let retArray = a2dpSrc.getConnectionDevices(); +``` ### getDeviceState8+ @@ -1236,15 +1258,19 @@ getDeviceState(device: string): ProfileConnectionState | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------- | | device | string | 是 | 远端设备地址。 | -| **返回值：** -| | | -| ------------------------------------------------- | ----------------------- | | 类型 | 说明 | +| ------------------------------------------------- | ----------------------- | | [ProfileConnectionState](#profileconnectionstate) | 返回profile的连接状态。 | +**示例：** + +```js +let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE) +let ret = a2dpSrc.getDeviceState('XX:XX:XX:XX:XX:XX'); +``` ## A2dpSourceProfile @@ -1266,13 +1292,11 @@ connect(device: string): boolean | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------- | | device | string | 是 | 远端设备地址。 | -| **返回值：** -| | | -| ------- | ------------------- | | 类型 | 说明 | +| ------- | ------------------- | | boolean | 成功返回true，失败返回false。 | **示例：** @@ -1298,13 +1322,11 @@ disconnect(device: string): boolean | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------- | | device | string | 是 | 远端设备地址。 | -| **返回值：** -| | | -| ------- | ------------------- | | 类型 | 说明 | +| ------- | ------------------- | | boolean | 成功返回true，失败返回false。 | **示例：** @@ -1315,7 +1337,7 @@ let ret = a2dpSrc.disconnect('XX:XX:XX:XX:XX:XX'); ``` -### A2dpSourceProfile.on('connectionStateChange')8+ +### on('connectionStateChange')8+ on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void @@ -1340,11 +1362,12 @@ on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#Stat function onReceiveEvent(data) { console.info('a2dp state = '+ JSON.stringify(data)); } -A2dpSourceProfile.on('connectionStateChange', onReceiveEvent); +let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +a2dpSrc.on('connectionStateChange', onReceiveEvent); ``` -### A2dpSourceProfile.off('connectionStateChange')8+ +### off('connectionStateChange')8+ off(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void @@ -1357,7 +1380,7 @@ off(type: "connectionStateChange", callback: Callback<[StateChangeParam](#Sta | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | 是 | 填写"connectionStateChange"字符串，表示连接状态变化事件。 | -| callback | Callback<[StateChangeParam](#StateChangeParam)> | 是 | 表示回调函数的入参。 | +| callback | Callback<[StateChangeParam](#StateChangeParam)> | 否 | 表示回调函数的入参。 | **返回值：** @@ -1369,7 +1392,9 @@ off(type: "connectionStateChange", callback: Callback<[StateChangeParam](#Sta function onReceiveEvent(data) { console.info('a2dp state = '+ JSON.stringify(data)); } -A2dpSourceProfile.off('connectionStateChange', onReceiveEvent); +let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +a2dpSrc.on('connectionStateChange', onReceiveEvent); +a2dpSrc.off('connectionStateChange', onReceiveEvent); ``` @@ -1389,9 +1414,8 @@ getPlayingState(device: string): PlayingState **返回值：** -| | | -| ----------------------------- | ---------- | | 类型 | 说明 | +| ----------------------------- | ---------- | | [PlayingState](#PlayingState) | 远端设备的播放状态。 | **示例：** @@ -1422,13 +1446,11 @@ connect(device: string): boolean | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------- | | device | string | 是 | 远端设备地址。 | -| **返回值：** -| | | -| ------- | ------------------- | | 类型 | 说明 | +| ------- | ------------------- | | boolean | 成功返回true，失败返回false。 | **示例：** @@ -1454,7 +1476,6 @@ disconnect(device: string): boolean | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------- | | device | string | 是 | 远端设备地址。 | -| **返回值：** @@ -1470,7 +1491,7 @@ let ret = hfpAg.disconnect('XX:XX:XX:XX:XX:XX'); ``` -### HandsFreeAudioGatewayProfile.on('connectionStateChange')8+ +### on('connectionStateChange')8+ on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void @@ -1495,11 +1516,12 @@ on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#Stat function onReceiveEvent(data) { console.info('hfp state = '+ JSON.stringify(data)); } -HandsFreeAudioGatewayProfile.on('connectionStateChange', onReceiveEvent); +let hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY); +hfpAg.on('connectionStateChange', onReceiveEvent); ``` -### HandsFreeAudioGatewayProfile.off('connectionStateChange')8+ +### off('connectionStateChange')8+ off(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void @@ -1512,7 +1534,7 @@ off(type: "connectionStateChange", callback: Callback<[StateChangeParam](#Sta | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | type | string | 是 | 填写"connectionStateChange"字符串，表示连接状态变化事件。 | -| callback | Callback<[StateChangeParam](#StateChangeParam)> | 是 | 表示回调函数的入参。 | +| callback | Callback<[StateChangeParam](#StateChangeParam)> | 否 | 表示回调函数的入参。 | **返回值：** @@ -1524,7 +1546,139 @@ off(type: "connectionStateChange", callback: Callback<[StateChangeParam](#Sta function onReceiveEvent(data) { console.info('hfp state = '+ JSON.stringify(data)); } -HandsFreeAudioGatewayProfile.off('connectionStateChange', onReceiveEvent); +let hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY); +hfpAg.on('connectionStateChange', onReceiveEvent); +hfpAg.off('connectionStateChange', onReceiveEvent); +``` + + +## HidHostProfile + +使用HidHostProfile方法之前需要创建该类的实例进行操作，通过getProfile()方法构造此实例。 + + +### connect9+ + +connect(device: string): boolean + +连接设备的HidHost服务。 + +**需要权限**：ohos.permission.DISCOVER_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**系统API**：该接口为系统接口，三方应用不支持调用。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| device | string | 是 | 远端设备地址。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------- | --------------------------------- | +| boolean | 成功返回true，失败返回false。 | + +**示例：** + +```js +let hidHostProfile = bluetooth.getProfile(PROFILE_HID_HOST); +let ret = hidHostProfile.connect('XX:XX:XX:XX:XX:XX'); +``` + + +### disconnect9+ + +disconnect(device: string): boolean + +断开连接设备的HidHost服务。 + +**需要权限**：ohos.permission.DISCOVER_BLUETOOTH + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**系统API**：该接口为系统接口，三方应用不支持调用。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| device | string | 是 | 远端设备地址。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------- | --------------------------------- | +| boolean | 成功返回true，失败返回false。 | + +**示例：** + +```js +let hidHostProfile = bluetooth.getProfile(PROFILE_HID_HOST); +let ret = hidHostProfile.disconnect('XX:XX:XX:XX:XX:XX'); +``` + + +### on('connectionStateChange')9+ + +on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void + +订阅HidHost连接状态变化事件。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 填写"connectionStateChange"字符串，表示连接状态变化事件。 | +| callback | Callback<[StateChangeParam](#StateChangeParam)> | 是 | 表示回调函数的入参。 | + +**返回值：** + +无 + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('hidHost state = '+ JSON.stringify(data)); +} +let hidHost = bluetooth.getProfile(PROFILE_HID_HOST); +hidHost.on('connectionStateChange', onReceiveEvent); +``` + + +### off('connectionStateChange')9+ + +off(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void + +取消订阅HidHost连接状态变化事件。 + +**系统能力**：SystemCapability.Communication.Bluetooth.Core。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------- | ---- | --------------------------------------------------------- | +| type | string | 是 | 填写"connectionStateChange"字符串，表示连接状态变化事件。 | +| callback | Callback<[StateChangeParam](#StateChangeParam)> | 否 | 表示回调函数的入参。 | + +**返回值：** + +无 + +**示例：** + +```js +function onReceiveEvent(data) { + console.info('hidHost state = '+ JSON.stringify(data)); +} +let hidHost = bluetooth.getProfile(PROFILE_HID_HOST); +hidHost.on('connectionStateChange', onReceiveEvent); +hidHost.off('connectionStateChange', onReceiveEvent); ``` @@ -3436,11 +3590,12 @@ let rssi = gattClient.getRssiValue().then((data) => { ## ProfileId8+ -枚举，蓝牙profile id。 +蓝牙profile枚举，API9新增PROFILE_HID_HOST。 **系统能力**：SystemCapability.Communication.Bluetooth.Core。 | 名称 | 默认值 | 说明 | | -------------------------------- | ------ | --------------- | | PROFILE_A2DP_SOURCE | 0x0001 | 表示A2DP profile。 | -| PROFILE_HANDS_FREE_AUDIO_GATEWAY | 0x0004 | 表示HFP profile。 | \ No newline at end of file +| PROFILE_HANDS_FREE_AUDIO_GATEWAY | 0x0004 | 表示HFP profile。 | +| PROFILE_HID_HOST9+ | 0x0006 | 表示HID profile。 | \ No newline at end of file