diff --git a/en/application-dev/reference/apis/js-apis-bluetooth.md b/en/application-dev/reference/apis/js-apis-bluetooth.md index 588c942cb2b77556023606197b23a106f9ffc0be..e8ccbc86d3803b9f2eb70e9cbb7421e43f6e45ab 100644 --- a/en/application-dev/reference/apis/js-apis-bluetooth.md +++ b/en/application-dev/reference/apis/js-apis-bluetooth.md @@ -1,5 +1,7 @@ -> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note：** -> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +# Bluetooth + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. > > The Bluetooth module provides Classic Bluetooth capabilities and Bluetooth Low Energy (BLE) scan and advertising. @@ -22,59 +24,73 @@ ohos.permission.DISCOVER_BLUETOOTH ohos.permission.LOCATION -## bluetooth.enableBluetooth + + +## bluetooth.enableBluetooth8+ enableBluetooth(): boolean Enables Bluetooth. -**Return values:** +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if Bluetooth is enabled; returns **false** otherwise. | +| boolean | Returns **true** if Bluetooth is enabled; returns **false** otherwise.| -**Example:** +**Example** -``` +```js let enable = bluetooth.enableBluetooth(); ``` -## bluetooth.disableBluetooth +## bluetooth.disableBluetooth8+ disableBluetooth(): boolean Disables Bluetooth. -**Return values:** +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if Bluetooth is disabled; returns **false** otherwise. | +| boolean | Returns **true** if Bluetooth is disabled; returns **false** otherwise.| -**Example:** +**Example** -``` +```js let disable = bluetooth.disableBluetooth(); ``` -## bluetooth.getLocalName +## bluetooth.getLocalName8+ getLocalName(): string Obtains the name of the local Bluetooth device. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| string | Name of the local Bluetooth device. | +| string | Name of the local Bluetooth device obtained.| -**Example:** +**Example** -``` +```js let localName = bluetooth.getLocalName(); ``` @@ -85,15 +101,19 @@ getState(): BluetoothState Obtains the Bluetooth state. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| [BluetoothState](#bluetoothstate) | Bluetooth state obtained. | +| [BluetoothState](#bluetoothstate) | Bluetooth state obtained.| -**Example:** +**Example** -``` +```js let state = bluetooth.getState(); ``` @@ -104,40 +124,48 @@ getBtConnectionState(): ProfileConnectionState Obtains the profile connection state of this Bluetooth device. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| [ProfileConnectionState](#profileconnectionstate) | Profile connection state obtained. | +| [ProfileConnectionState](#profileconnectionstate) | Profile connection state obtained.| -**Example:** +**Example** -``` +```js let connectionState = bluetooth.getBtConnectionState(); ``` -## bluetooth.setLocalName +## bluetooth.setLocalName8+ setLocalName(name: string): boolean Sets the name of the local Bluetooth device. -**Parameters:** +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| name | string | Yes | Bluetooth device name to be set. It cannot exceed 128 characters. | +| name | string | Yes| Bluetooth device name to set. It cannot exceed 248 characters.| -**Return values:** +**Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` +```js let ret = bluetooth.setLocalName('device_name'); ``` @@ -148,106 +176,242 @@ pairDevice(deviceId: string): boolean Initiates Bluetooth pairing. -**Parameters:** +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | Address of the peer device to pair, for example, **8F:8F:8E:8E:6D:6D**. | +| deviceId | string | Yes| Address of the remote device to pair, for example, XX:XX:XX:XX:XX:XX.| -**Return values:** +**Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** +```js +// The address can be scanned. +let result = bluetooth.pairDevice("XX:XX:XX:XX:XX:XX"); ``` -// The actual address can be scanned. -let result = bluetooth.pairDevice("8F:8F:8E:8E:6D:6D"); + + +## bluetooth.getProfileConnState8+ + +getProfileConnState(profileId: ProfileId): ProfileConnectionState + +Obtains the connection status of a profile. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| ProfileId | profileId | Yes| ID of the target profile, for example, **PROFILE_A2DP_SOURCE**.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| [ProfileConnectionState](#ProfileConnectionState) | Profile connection state obtained.| + +**Example** + +```js +let result = bluetooth.getProfileConnState(PROFILE_A2DP_SOURCE); ``` -## bluetooth.getPairedDevices +## bluetooth.cancelPairedDevice8+ + +cancelPairedDevice(deviceId: string): boolean + +Cancels a paired remote device. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| deviceId | string | Yes| Address of the remote device to cancel, for example, XX:XX:XX:XX:XX:XX.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```js +let result = bluetooth.cancelPairedDevice("XX:XX:XX:XX:XX:XX"); +``` + + +## bluetooth.getRemoteDeviceName8+ + +getRemoteDeviceName(deviceId: string): string + +Obtains the name of the remote Bluetooth device. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| deviceId | string | Yes| Address of the target remote device, for example, XX:XX:XX:XX:XX:XX.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| string | Device name (a string) obtained.| + +**Example** + +```js +let remoteDeviceName = bluetooth.getRemoteDeviceName("XX:XX:XX:XX:XX:XX"); +``` + + +## bluetooth.getRemoteDeviceClass8+ + +getRemoteDeviceClass(deviceId: string): DeviceClass + +Obtains the type of the remote Bluetooth device. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| deviceId | string | Yes| Address of the target remote device, for example, XX:XX:XX:XX:XX:XX.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| [DeviceClass](#deviceclass) | Type of a remote device obtained.| + +**Example** + +```js +let remoteDeviceClass = bluetooth.getRemoteDeviceClass("XX:XX:XX:XX:XX:XX"); +``` + + +## bluetooth.getPairedDevices8+ getPairedDevices(): Array<string> Obtains the Bluetooth pairing list. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| Array<string> | List of the addresses of the paired Bluetooth devices. | +| Array<string> | List of the addresses of the paired Bluetooth devices.| -**Example:** +**Example** -``` +```js let devices = bluetooth.getPairedDevices(); ``` -## bluetooth.setBluetoothScanMode +## bluetooth.setBluetoothScanMode8+ setBluetoothScanMode(mode: ScanMode, duration: number): boolean -Sets the Bluetooth scan mode so that the device can be discovered by a peer device. +Sets the Bluetooth scan mode so that the device can be discovered by a remote device. + +**Required permissions**: ohos.permission.USE_BLUETOOTH -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| mode | [ScanMode](#scanmode) | Yes | Bluetooth scan mode. | -| duration | number | Yes | Duration (in seconds) in which the device can be discovered. The value **0** indicates unlimited time. | +| mode | [ScanMode](#scanmode) | Yes| Bluetooth scan mode to set.| +| duration | number | Yes| Duration (in seconds) in which the device can be discovered. The value **0** indicates unlimited time.| -**Return values:** +**Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` +```js // The device can be discovered and connected only when the discoverable and connectable mode is used. let result = bluetooth.setBluetoothScanMode(ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100); ``` -## bluetooth.getBluetoothScanMode +## bluetooth.getBluetoothScanMode8+ getBluetoothScanMode(): ScanMode Obtains the Bluetooth scan mode. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| [ScanMode](#scanmode) | Bluetooth scan mode obtained. | +| [ScanMode](#scanmode) | Bluetooth scan mode obtained.| -**Example:** +**Example** -``` +```js let scanMode = bluetooth.getBluetoothScanMode(); ``` -## bluetooth.startBluetoothDiscovery +## bluetooth.startBluetoothDiscovery8+ startBluetoothDiscovery(): boolean -Starts Bluetooth scan to discover peer devices. +Starts Bluetooth scan to discover remote devices. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH and ohos.permission.LOCATION -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` +```js let deviceId; function onReceiveEvent(data) { deviceId = data; @@ -257,48 +421,56 @@ let result = bluetooth.startBluetoothDiscovery(); ``` -## bluetooth.stopBluetoothDiscovery +## bluetooth.stopBluetoothDiscovery8+ stopBluetoothDiscovery(): boolean Stops Bluetooth scan. -**Return values:** +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` +```js let result = bluetooth.stopBluetoothDiscovery(); ``` -## bluetooth.setDevicePairingConfirmation +## bluetooth.setDevicePairingConfirmation8+ setDevicePairingConfirmation(device: string, accept: boolean): boolean Sets the device pairing confirmation. -**Parameters:** +**Required permissions**: ohos.permission.MANAGE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| device | string | Yes | Address of the peer device, for example, **8F:8F:8E:8E:6D:6D**. | -| accept | boolean | Yes | Whether to accept the pairing request. The value **true** means to accept the pairing request, and the value **false** means the opposite. | +| device | string | Yes| Address of the target remote device, for example, XX:XX:XX:XX:XX:XX.| +| accept | boolean | Yes| Whether to accept the pairing request. The value **true** means to accept the pairing request, and the value **false** means the opposite.| -**Return values:** +**Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` -// Subscribe to the pinRequired event and configure the pairing confirmation after receiving a pairing request from the peer device. +```js +// Subscribe to the pinRequired event and configure the pairing confirmation after receiving a pairing request from the remote device. function onReceivePinRequiredEvent(data) { // data is the input parameter for the pairing request. console.info('pin required = '+ JSON.stringify(data)); bluetooth.setDevicePairingConfirmation(data.deviceId, true); @@ -307,26 +479,30 @@ bluetooth.on("pinRequired", onReceivePinRequiredEvent); ``` -## bluetooth.on('bluetoothDeviceFind') +## bluetooth.on('bluetoothDeviceFind')8+ on(type: "bluetoothDeviceFind", callback: Callback<Array<string>>): void Subscribes to the Bluetooth device discovery events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **bluetoothDeviceFind** indicates an event reported when a Bluetooth device is discovered. | -| callback | Callback<Array<string>> | Yes | Callback invoked to return the discovered devices. You need to implement this callback. | +| type | string | Yes| Event type. The value **bluetoothDeviceFind** indicates an event reported when a Bluetooth device is discovered.| +| callback | Callback<Array<string>> | Yes| Callback invoked to return the discovered devices. You need to implement this callback.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { // data is a set of Bluetooth device addresses. console.info('bluetooth device find = '+ JSON.stringify(data)); } @@ -334,26 +510,30 @@ bluetooth.on('bluetoothDeviceFind', onReceiveEvent); ``` -## bluetooth.off('bluetoothDeviceFind') +## bluetooth.off('bluetoothDeviceFind')8+ off(type: "bluetoothDeviceFind", callback?: Callback<Array<string>>): void Unsubscribes from the Bluetooth device discovery events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **bluetoothDeviceFind** indicates an event reported when a Bluetooth device is discovered. | -| callback | Callback<Array<string>> | No | Callback used to report the discovered devices. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **bluetoothDeviceFind** indicates an event reported when a Bluetooth device is discovered.| +| callback | Callback<Array<string>> | No| Callback used to report the discovered devices. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { console.info('bluetooth device find = '+ JSON.stringify(data)); } @@ -362,26 +542,30 @@ bluetooth.off('bluetoothDeviceFind', onReceiveEvent); ``` -## bluetooth.on('pinRequired') +## bluetooth.on('pinRequired')8+ on(type: "pinRequired", callback: Callback<PinRequiredParam>): void -Subscribes to the pairing request events of the peer Bluetooth device. +Subscribes to the pairing request events of the remote Bluetooth device. -**Parameters:** +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **pinRequired** indicates a pairing request event. | -| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | Yes | Callback invoked to return the pairing request. You need to implement this callback. | +| type | string | Yes| Event type. The value **pinRequired** indicates a pairing request event.| +| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | Yes| Callback invoked to return the pairing request. You need to implement this callback.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { // data is the pairing request parameter. console.info('pin required = '+ JSON.stringify(data)); } @@ -389,26 +573,30 @@ bluetooth.on('pinRequired', onReceiveEvent); ``` -## bluetooth.off('pinRequired') +## bluetooth.off('pinRequired')8+ off(type: "pinRequired", callback?: Callback<PinRequiredParam>): void -Unsubscribes from the pairing request events of the peer Bluetooth device. +Unsubscribes from the pairing request events of the remote Bluetooth device. -**Parameters:** +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **pinRequired** indicates a pairing request event. | -| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | No | Callback used to report the Bluetooth pairing request. The input parameter is the pairing request parameter. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **pinRequired** indicates a pairing request event.| +| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | No| Callback used to report the Bluetooth pairing request. The input parameter is the pairing request parameter. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { console.info('pin required = '+ JSON.stringify(data)); } @@ -417,26 +605,30 @@ bluetooth.off('pinRequired', onReceiveEvent); ``` -## bluetooth.on('bondStateChange') +## bluetooth.on('bondStateChange')8+ on(type: "bondStateChange", callback: Callback<BondState>): void Subscribes to the Bluetooth pairing state change events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **bondStateChange** indicates a Bluetooth pairing state change event. | -| callback | Callback<[BondState](#bondstate)> | Yes | Callback invoked to return the pairing state. You need to implement this callback. | +| type | string | Yes| Event type. The value **bondStateChange** indicates a Bluetooth pairing state change event.| +| callback | Callback<[BondState](#bondstate)> | Yes| Callback invoked to return the pairing state. You need to implement this callback.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { // data, as the input parameter of the callback, indicates the pairing state. console.info('pair state = '+ JSON.stringify(data)); } @@ -444,26 +636,30 @@ bluetooth.on('bondStateChange', onReceiveEvent); ``` -## bluetooth.off('bondStateChange') +## bluetooth.off('bondStateChange')8+ off(type: "bondStateChange", callback?: Callback<BondState>): void Unsubscribes from the Bluetooth pairing state change events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **bondStateChange** indicates a Bluetooth pairing state change event. | -| callback | Callback<[BondState](#bondstate)> | No | Callback used to report the change of the Bluetooth pairing state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **bondStateChange** indicates a Bluetooth pairing state change event.| +| callback | Callback<[BondState](#bondstate)> | No| Callback used to report the change of the Bluetooth pairing state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { console.info('bond state = '+ JSON.stringify(data)); } @@ -472,26 +668,30 @@ bluetooth.off('bondStateChange', onReceiveEvent); ``` -## bluetooth.on('stateChange') +## bluetooth.on('stateChange')8+ on(type: "stateChange", callback: Callback<BluetoothState>): void Subscribes to the Bluetooth connection state change events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **stateChange** indicates a Bluetooth connection state change event. | -| callback | Callback<[BluetoothState](#bluetoothstate)> | Yes | Callback invoked to return the Bluetooth connection state. You need to implement this callback. | +| type | string | Yes| Event type. The value **stateChange** indicates a Bluetooth connection state change event.| +| callback | Callback<[BluetoothState](#bluetoothstate)> | Yes| Callback invoked to return the Bluetooth connection state. You need to implement this callback.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { console.info('bluetooth state = '+ JSON.stringify(data)); } @@ -499,26 +699,30 @@ bluetooth.on('stateChange', onReceiveEvent); ``` -## bluetooth.off('stateChange') +## bluetooth.off('stateChange')8+ off(type: "stateChange", callback?: Callback<BluetoothState>): void Unsubscribes from the Bluetooth connection state change events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **stateChange** indicates a Bluetooth connection state change event. | -| callback | Callback<[BluetoothState](#bluetoothstate)> | No | Callback used to report the Bluetooth connection state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **stateChange** indicates a Bluetooth connection state change event.| +| callback | Callback<[BluetoothState](#bluetoothstate)> | No| Callback used to report the Bluetooth connection state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { console.info('bluetooth state = '+ JSON.stringify(data)); } @@ -527,23 +731,27 @@ bluetooth.off('stateChange', onReceiveEvent); ``` -## bluetooth.sppListen +## bluetooth.sppListen8+ sppListen(name: string, option: SppOption, callback: AsyncCallback<number>): void Creates a server listening socket. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| name | string | Yes | Service name. | -| option | [SppOption](#sppoption) | Yes | Serial port profile (SPP) listening configuration. | -| callback | AsyncCallback<number> | Yes | Callback invoked to return the server socket ID. | +| name | string | Yes| Name of the service.| +| option | [SppOption](#sppoption) | Yes| Serial port profile (SPP) listening configuration.| +| callback | AsyncCallback<number> | Yes| Callback invoked to return the server socket ID.| -**Example:** +**Example** -``` +```js let serverNumber = -1; function serverSocket(code, number) { console.log('bluetooth error code: ' + code.code); @@ -558,22 +766,24 @@ bluetooth.sppListen('server1', sppOption, serverSocket); ``` -## bluetooth.sppAccept +## bluetooth.sppAccept8+ sppAccept(serverSocket: number, callback: AsyncCallback<number>): void Listens for a connection to be made to this socket from the client and accepts it. -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| serverSocket | number | Yes | Server socket ID. | -| callback | AsyncCallback<number> | Yes | Callback invoked to return the client socket ID. | +| serverSocket | number | Yes| Server socket ID.| +| callback | AsyncCallback<number> | Yes| Callback invoked to return the client socket ID.| -**Example:** +**Example** -``` +```js let clientNumber = -1; function acceptClientSocket(code, number) { console.log('bluetooth error code: ' + code.code); @@ -587,23 +797,27 @@ bluetooth.sppAccept(serverNumber, acceptClientSocket); ``` -## bluetooth.sppConnect +## bluetooth.sppConnect8+ sppConnect(device: string, option: SppOption, callback: AsyncCallback<number>): void -Initiates an SPP connection to a peer device from the client. +Initiates an SPP connection to a remote device from the client. + +**Required permissions**: ohos.permission.USE_BLUETOOTH -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| device | string | Yes | Address of the peer device, for example, **8F:8F:8E:8E:6D:6D**. | -| option | [SppOption](#sppoption) | Yes | Configuration for connecting to the SPP client. | -| callback | AsyncCallback<number> | Yes | Callback invoked to return the client socket ID. | +| device | string | Yes| Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| +| option | [SppOption](#sppoption) | Yes| Configuration for connecting to the SPP client.| +| callback | AsyncCallback<number> | Yes| Callback invoked to return the client socket ID.| -**Example:** +**Example** -``` +```js let clientNumber = -1; function clientSocket(code, number) { if (code.code != 0) { @@ -614,70 +828,78 @@ function clientSocket(code, number) { clientNumber = number; } let sppOption = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0}; -bluetooth.sppConnect('8F:8F:8E:8E:6D:6D', sppOption, clientSocket); +bluetooth.sppConnect('XX:XX:XX:XX:XX:XX', sppOption, clientSocket); ``` -## bluetooth.sppCloseServerSocket +## bluetooth.sppCloseServerSocket8+ sppCloseServerSocket(socket: number): void Closes the listening socket of the server. -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| socket | number | Yes | ID of the listening socket on the server. The ID is obtained by **sppListen**. | +| socket | number | Yes| ID of the listening socket on the server. The ID is obtained by **sppListen**.| -**Example:** +**Example** -``` +```js bluetooth.sppCloseServerSocket(serverNumber); ``` -## bluetooth.sppCloseClientSocket +## bluetooth.sppCloseClientSocket8+ sppCloseClientSocket(socket: number): void Closes the client socket. -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| socket | number | Yes | Client socket ID, which is obtained by **sppAccept** or **sppConnect**. | +| Name| Type| Mandatory| Description| +| socket | number | Yes| Client socket ID, which is obtained by **sppAccept** or **sppConnect**.| -**Example:** +**Example** -``` +```js bluetooth.sppCloseClientSocket(clientNumber); ``` -## bluetooth.sppWrite +## bluetooth.sppWrite8+ sppWrite(clientSocket: number, data: ArrayBuffer): boolean -Writes data to the peer device through the socket. +Writes data to the remote device through the socket. -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept** or **sppConnect**. | -| data | ArrayBuffer | Yes | Data to write. | +| clientSocket | number | Yes| Client socket ID, which is obtained by **sppAccept** or **sppConnect**.| +| data | ArrayBuffer | Yes| Data to write.| -**Return values:** +**Return value** -| Type | Description | +| | | | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| Type | Description | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | -**Example:** +**Example** -``` +```js let arrayBuffer = new ArrayBuffer(8); let data = new Uint8Array(arrayBuffer); data[0] = 123; @@ -690,27 +912,29 @@ if (ret) { ``` -## bluetooth.on('sppRead') +## bluetooth.on('sppRead')8+ on(type: "sppRead", clientSocket: number, callback: Callback<ArrayBuffer>): void Subscribes to the SPP read request events. -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **sppRead** indicates an SPP read request event. | -| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept** or **sppConnect**. | -| callback | Callback<ArrayBuffer> | Yes | Callback invoked to return the data read. | +| type | string | Yes| Event type. The value **sppRead** indicates an SPP read request event.| +| clientSocket | number | Yes| Client socket ID, which is obtained by **sppAccept** or **sppConnect**.| +| callback | Callback<ArrayBuffer> | Yes| Callback invoked to return the data read.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function dataRead(dataBuffer) { let data = new Uint8Array(dataBuffer); console.log('bluetooth data is: ' + data[0]); @@ -719,31 +943,61 @@ bluetooth.on('sppRead', clientNumber, dataRead); ``` -## bluetooth.off('sppRead') +## bluetooth.off('sppRead')8+ off(type: "sppRead", clientSocket: number, callback?: Callback<ArrayBuffer>): void Unsubscribes from the SPP read request events. -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **sppRead** indicates an SPP read request event. | -| clientSocket | number | Yes | Client socket ID, which is obtained by **sppAccept** or **sppConnect**. | -| callback | Callback<ArrayBuffer> | No | Callback used to report an SPP read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **sppRead** indicates an SPP read request event.| +| clientSocket | number | Yes| Client socket ID, which is obtained by **sppAccept** or **sppConnect**.| +| callback | Callback<ArrayBuffer> | No| Callback used to report an SPP read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js bluetooth.off('sppRead', clientNumber); ``` +## bluetooth.getProfile8+ + +getProfile(profileId: ProfileId): A2dpSourceProfile | HandsFreeAudioGatewayProfile + +Obtains a profile object. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| ProfileId | profileId | Yes| ID of the profile to obtain, for example, **PROFILE_A2DP_SOURCE**.| + +**Return value** + +| | | +| -------- | -------- | +| Type | Description | +| A2dpSourceProfile or HandsFreeAudioGatewayProfile | Profile object obtained. Only **A2dpSourceProfile** and **HandsFreeAudioGatewayProfile** are supported. | + +**Example** + +```js +A2dpSourceProfile a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +``` + + ## bluetooth.BLE ### bluetooth.BLE.createGattServer @@ -752,15 +1006,17 @@ createGattServer(): GattServer Creates a **GattServer** instance. -**Return values:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Type | Description | +**Return value** + +| Type| Description| | -------- | -------- | -| [GattServer](#gattserver) | **GattServer** instance created. Before using a method of the server, you must create a **GattSever** instance. | +| [GattServer](#gattserver) | **GattServer** instance created. Before using a method of the server, you must create a **GattSever** instance.| -**Example:** +**Example** -``` +```js let gattServer = bluetooth.BLE.createGattServer(); ``` @@ -771,152 +1027,509 @@ createGattClientDevice(deviceId: string): GattClientDevice Creates a **GattClientDevice** instance. -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| deviceId | string | Yes| Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| [GattClientDevice](#gattclientdevice) | **GattClientDevice** instance created. Before using a method of the client, you must create a **GattClientDevice** instance.| + +**Example** + +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); +``` + + +### bluetooth.BLE.getConnectedBLEDevices + +getConnectedBLEDevices(): Array<string> + +Obtains the BLE devices connected to this device. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** -| Name | Type | Mandatory | Description | +| Type| Description| +| -------- | -------- | +| Array<string> | Addresses of the BLE devices connected to this device.| + +**Example** + +```js +let result = bluetooth.BLE.getConnectedBLEDevices(); +``` + + +### bluetooth.BLE.startBLEScan + +startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void + +Starts a BLE scan. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH, ohos.permission.MANAGE_BLUETOOTH, and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| filters | Array<[ScanFilter](#scanfilter)> | Yes| Criteria for filtering the scan result. Set this parameter to **null** if you do not want to filter the scan result.| +| options | [ScanOptions](#scanoptions) | No| Scan options.| + +**Return value** + +No value is returned. + +**Example** + +```js +function onReceiveEvent(data) { + console.info('BLE scan device find result = '+ JSON.stringify(data)); +} +bluetooth.BLE.on("BLEDeviceFind", onReceiveEvent); +bluetooth.BLE.startBLEScan( + [{ + deviceId:"XX:XX:XX:XX:XX:XX", + name:"test", + serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" + }], + { + interval: 500, + dutyMode: bluetooth.ScanDuty.SCAN_MODE_LOW_POWER, + matchMode: bluetooth.MatchMode.MATCH_MODE_AGGRESSIVE, + } +); +``` + + +### bluetooth.BLE.stopBLEScan + +stopBLEScan(): void + +Stops the BLE scan. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +No value is returned. + +**Example** + +```js +bluetooth.BLE.stopBLEScan(); +``` + + +### bluetooth.BLE.on('BLEDeviceFind') + +on(type: "BLEDeviceFind", callback: Callback<Array<ScanResult>>): void + +Subscribe to the BLE device discovery events. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type. The value **BLEDeviceFind** indicates an event reported when a BLE device is discovered.| +| callback | Callback<Array<[ScanResult](#scanresult)>> | Yes| Callback invoked to return the discovered devices. You need to implement this callback.| + +**Return value** + +No value is returned. + +**Example** + +```js +function onReceiveEvent(data) { + console.info('bluetooth device find = '+ JSON.stringify(data)); +} +bluetooth.BLE.on('BLEDeviceFind', onReceiveEvent); +``` + + +### bluetooth.BLE.off('BLEDeviceFind') + +off(type: "BLEDeviceFind", callback?: Callback<Array<ScanResult>>): void + +Unsubscribes from the BLE device discovery events. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type. The value **BLEDeviceFind** indicates an event reported when a BLE device is discovered.| +| callback | Callback<Array<[ScanResult](#scanresult)>> | No| Callback used to report the discovered devices. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| + +**Return value** + +No value is returned. + +**Example** + +```js +function onReceiveEvent(data) { + console.info('bluetooth device find = '+ JSON.stringify(data)); +} +bluetooth.BLE.on('BLEDeviceFind', onReceiveEvent); +bluetooth.BLE.off('BLEDeviceFind', onReceiveEvent); +``` + + +## BaseProfile + +Provides the profile base class. + + +### getConnectionDevices8+ + +getConnectionDevices(): Array<string> + +Obtains the connected devices. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +No value is returned. + +**Return value** + +| | | +| -------- | -------- | +| Type | Description | +| Array<string> | List of addresses of the connected devices. | + + +### getDeviceState8+ + +getDeviceState(device: string): ProfileConnectionState + +Obtains the connection status of the profile. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | Address of the peer device, for example, **8F:8F:8E:8E:6D:6D**. | +| device | string | Yes| Address of the remote device.| +| -**Return values:** +**Return value** +| | | +| -------- | -------- | | Type | Description | +| [ProfileConnectionState](#profileconnectionState) | Profile connection state obtained. | + + +## A2dpSourceProfile + +Before using a method of **A2dpSourceProfile**, you need to create an instance of this class by using the **getProfile()** method. + + +### connect8+ + +connect(device: string): boolean + +Sets up an Advanced Audio Distribution Profile (A2DP) connection. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| device | string | Yes| Address of the remote device to connect.| +| + +**Return value** + +| | | +| -------- | -------- | +| Type | Description | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | + +**Example** + +```js +A2dpSourceProfile a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +boolean ret = a2dpSrc.connect('XX:XX:XX:XX:XX:XX'); +``` + + +### disconnect8+ + +disconnect(device: string): boolean + +Disconnects an A2DP connection. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| device | string | Yes| Address of the remote device to disconnect.| +| + +**Return value** + +| | | +| -------- | -------- | +| Type | Description | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | + +**Example** + +```js +A2dpSourceProfile a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +boolean ret = a2dpSrc.disconnect('XX:XX:XX:XX:XX:XX'); +``` + + +### A2dpSourceProfile.on('connectionStateChange')8+ + +on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void + +Subscribes to the A2DP connection status change events. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type. The value **connectionStateChange** indicates an A2DP connection state change event.| +| callback | Callback<[StateChangeParam](#StateChangeParam)> | Yes| Callback invoked to return the A2DP connection state change event.| + +**Return value** + +No value is returned. + +**Example** + +```js +function onReceiveEvent(data) { + console.info('a2dp state = '+ JSON.stringify(data)); +} +A2dpSourceProfile.on('connectionStateChange', onReceiveEvent); +``` + + +### A2dpSourceProfile.off('connectionStateChange')8+ + +off(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void + +Unsubscribes from the A2DP connection status change events. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type. The value **connectionStateChange** indicates an A2DP connection state change event.| +| callback | Callback<[StateChangeParam](#StateChangeParam)> | Yes| Callback used to return the A2DP connection state change event.| + +**Return value** + +No value is returned. + +**Example** + +```js +function onReceiveEvent(data) { + console.info('a2dp state = '+ JSON.stringify(data)); +} +A2dpSourceProfile.off('connectionStateChange', onReceiveEvent); +``` + + +### getPlayingState + +getPlayingState(device: string): PlayingState + +Obtains the playing status of a device. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| device | string | Yes| Address of the target device.| + +**Return value** + +| | | | -------- | -------- | -| [GattClientDevice](#gattclientdevice) | **GattClientDevice** instance created. Before using a method of the client, you must create a **GattClientDevice** instance. | +| Type | Description | +| [PlayingState](#PlayingState) | Playing status obtained. | -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +A2dpSourceProfile a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +PlayingState state = a2dpSrc.getPlayingState('XX:XX:XX:XX:XX:XX'); ``` -### bluetooth.BLE.getConnectedBLEDevices +## HandsFreeAudioGatewayProfile -getConnectedBLEDevices(): Array<string> +Before using a method of **HandsFreeAudioGatewayProfile**, you need to create an instance of this class by using the **getProfile()** method. -Obtains the BLE devices connected to this device. -**Return values:** +### connect8+ -| Type | Description | -| -------- | -------- | -| Array<string> | Addresses of the BLE devices connected to this device. | +connect(device: string): boolean -**Example:** +Sets up a Hands-free Profile (HFP) connection of a device. -``` -let result = bluetooth.BLE.getConnectedBLEDevices(); -``` +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH +**System capability**: SystemCapability.Communication.Bluetooth.Core -### bluetooth.BLE.startBLEScan +**Parameters** -startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| device | string | Yes| Address of the target device.| +| -Starts a BLE scan. +**Return value** -**Parameters:** +| | | +| -------- | -------- | +| Type | Description | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | -| Name | Type | Mandatory | Description | -| -------- | -------- | -------- | -------- | -| filters | Array<[ScanFilter](#scanfilter)> | Yes | Criteria for filtering the scan result. Set this parameter to **null** if you do not want to filter the scan result. | -| options | [ScanOptions](#scanoptions) | No | Scan options. | +**Example** -**Return values:** +```js +HandsFreeAudioGatewayProfile hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY); +boolean ret = hfpAg.connect('XX:XX:XX:XX:XX:XX'); +``` -None. -**Example:** +### disconnect8+ -``` -function onReceiveEvent(data) { - console.info('BLE scan device find result = '+ JSON.stringify(data)); -} -bluetooth.BLE.on("BLEDeviceFind", onReceiveEvent); -bluetooth.BLE.startBLEScan( - [{ - deviceId:"8F:8F:8E:8E:6D:6D", - name:"test", - serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" - }], - { - interval: 500, - dutyMode: bluetooth.ScanDuty.SCAN_MODE_LOW_POWER, - matchMode: bluetooth.MatchMode.MATCH_MODE_AGGRESSIVE, - } -); -``` +disconnect(device: string): boolean +Disconnects the HFP connection of a device. -### bluetooth.BLE.stopBLEScan +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH -stopBLEScan(): void +**System capability**: SystemCapability.Communication.Bluetooth.Core -Stops the BLE scan. +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| device | string | Yes| Address of the target device.| +| -**Return values:** +**Return value** -None. +| | | +| -------- | -------- | +| Type | Description | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | -**Example:** +**Example** -``` -bluetooth.BLE.stopBLEScan(); +```js +HandsFreeAudioGatewayProfile hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY); +boolean ret = hfpAg.disconnect('XX:XX:XX:XX:XX:XX'); ``` -### bluetooth.BLE.on('BLEDeviceFind') +### HandsFreeAudioGatewayProfile.on('connectionStateChange')8+ -on(type: "BLEDeviceFind", callback: Callback<Array<ScanResult>>): void +on(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void -Subscribe to the BLE device discovery events. +Subscribes to the HFP connection status change events. + +**System capability**: SystemCapability.Communication.Bluetooth.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **BLEDeviceFind** indicates an event reported when a BLE device is discovered. | -| callback | Callback<Array<[ScanResult](#scanresult)>> | Yes | Callback invoked to return the discovered devices. You need to implement this callback. | +| type | string | Yes| Event type. The value **connectionStateChange** indicates an HFP connection state change event.| +| callback | Callback<[StateChangeParam](#StateChangeParam)> | Yes| Callback invoked to return the HFP connection state change event.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { - console.info('bluetooth device find = '+ JSON.stringify(data)); + console.info('hfp state = '+ JSON.stringify(data)); } -bluetooth.BLE.on('BLEDeviceFind', onReceiveEvent); +HandsFreeAudioGatewayProfile.on('connectionStateChange', onReceiveEvent); ``` -### bluetooth.BLE.off('BLEDeviceFind') +### HandsFreeAudioGatewayProfile.off('connectionStateChange')8+ -off(type: "BLEDeviceFind", callback?: Callback<Array<ScanResult>>): void +off(type: "connectionStateChange", callback: Callback<[StateChangeParam](#StateChangeParam)>): void -Unsubscribes from the BLE device discovery events. +Unsubscribes from the HFP connection status change events. -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **BLEDeviceFind** indicates an event reported when a BLE device is discovered. | -| callback | Callback<Array<[ScanResult](#scanresult)>> | No | Callback used to report the discovered devices. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **connectionStateChange** indicates an HFP connection state change event.| +| callback | Callback<[StateChangeParam](#StateChangeParam)> | Yes| Callback used to return the HFP connection state change event.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function onReceiveEvent(data) { - console.info('bluetooth device find = '+ JSON.stringify(data)); + console.info('hfp state = '+ JSON.stringify(data)); } -bluetooth.BLE.on('BLEDeviceFind', onReceiveEvent); -bluetooth.BLE.off('BLEDeviceFind', onReceiveEvent); +HandsFreeAudioGatewayProfile.off('connectionStateChange', onReceiveEvent); ``` @@ -931,21 +1544,25 @@ startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse? Starts BLE advertising. -**Parameters:** +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| setting | [AdvertiseSetting](#advertisesetting) | Yes | Settings related to BLE advertising. | -| advData | [AdvertiseData](#advertisedata) | Yes | Content of the BLE advertisement packet. | -| advResponse | [AdvertiseData](#advertisedata) | No | Response to the BLE scan request. | +| setting | [AdvertiseSetting](#advertisesetting) | Yes| Settings related to BLE advertising.| +| advData | [AdvertiseData](#advertisedata) | Yes| Content of the BLE advertisement packet.| +| advResponse | [AdvertiseData](#advertisedata) | No| Response to the BLE scan request.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let manufactureValueBuffer = new Uint8Array(4); manufactureValueBuffer[0] = 1; manufactureValueBuffer[1] = 2; @@ -994,13 +1611,17 @@ stopAdvertising(): void Stops BLE advertising. -**Return values:** +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH -None. +**System capability**: SystemCapability.Communication.Bluetooth.Core -**Example:** +**Return value** -``` +No value is returned. + +**Example** + +```js let server = bluetooth.BLE.createGattServer(); server.stopAdvertising(); ``` @@ -1012,21 +1633,25 @@ addService(service: GattService): boolean Adds a service to this GATT server. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| service | [GattService](#gattservice) | Yes | Service to add. | +| service | [GattService](#gattservice) | Yes| Service to add. Settings related to BLE advertising.| -**Return values:** +**Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` +```js // Create descriptors. let descriptors = []; let arrayBuffer = new ArrayBuffer(8); @@ -1067,21 +1692,26 @@ removeService(serviceUuid: string): boolean Removes a service from this GATT server. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| serviceUuid | string | Yes | Universally unique identifier (UUID) of the service to remove, for example, **00001810-0000-1000-8000-00805F9B34FB**. | +| serviceUuid | string | Yes| Universally unique identifier (UUID) of the service to remove, for example, **00001810-0000-1000-8000-00805F9B34FB**.| -**Return values:** +**Return value** -| Type | Description | +| | | | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| Type | Description | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | -**Example:** +**Example** -``` +```js let server = bluetooth.BLE.createGattServer(); server.removeService('00001810-0000-1000-8000-00805F9B34FB'); ``` @@ -1091,12 +1721,15 @@ server.removeService('00001810-0000-1000-8000-00805F9B34FB'); close(): void +Closes this GATT server to unregister it from the protocol stack. After this method is called, this [GattServer](#gattserver) cannot be used. -Closes this GATT server to unregister it from the protocol stack. After this method is called, this [GattServer](#gattserver) instance cannot be used. +**Required permissions**: ohos.permission.USE_BLUETOOTH -**Example:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -``` +**Example** + +```js let server = bluetooth.BLE.createGattServer(); server.close(); ``` @@ -1108,26 +1741,31 @@ notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharac Notifies the connected client device when a characteristic value changes. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | Address of the client device to notify, for example, **8F:8F:8E:8E:6D:6D**. | -| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | Yes | New characteristic value. | +| deviceId | string | Yes| Address of the client that receives notifications, for example, XX:XX:XX:XX:XX:XX.| +| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | Yes| New characteristic value.| -**Return values:** +**Return value** -| Type | Description | +| | | | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| Type | Description | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | -**Example:** +**Example** -``` +```js let notifyCharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: notifyCcc.characteristicValue, confirm: false}; let server = bluetooth.BLE.createGattServer(); -server.notifyCharacteristicChanged('8F:8F:8E:8E:6D:6D', notifyCharacteristic); +server.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacteristic); ``` @@ -1137,27 +1775,32 @@ sendResponse(serverResponse: ServerResponse): boolean Sends a response to a read or write request from the GATT client. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| serverResponse | [ServerResponse](#serverresponse) | Yes | Response returned by the GATT server. | +| serverResponse | [ServerResponse](#serverresponse) | Yes| Response returned by the GATT server.| -**Return values:** +**Return value** -| Type | Description | +| | | | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| Type | Description | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | -**Example:** +**Example** -``` -/* Send a response. */ +```js +/* send response */ let arrayBufferCCC = new ArrayBuffer(8); let cccValue = new Uint8Array(arrayBufferCCC); cccValue[0] = 1123; let serverResponse = { - "deviceId": "8F:8F:8E:8E:6D:6D", + "deviceId": "XX:XX:XX:XX:XX:XX", "transId": 0, "status": 0, "offset": 0, @@ -1180,20 +1823,24 @@ on(type: "characteristicRead", callback: Callback<CharacteristicReadReq>): Subscribes to the characteristic read request events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **characteristicRead** indicates a characteristic read request event. | -| callback | Callback<[CharacteristicReadReq](#characteristicreadreq)> | Yes | Callback invoked to return a characteristic read request from the GATT client. | +| type | string | Yes| Event type. The value **characteristicRead** indicates a characteristic read request event.| +| callback | Callback<[CharacteristicReadReq](#characteristicreadreq)> | Yes| Callback invoked to return a characteristic read request from the GATT client.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let arrayBufferCCC = new ArrayBuffer(8); let cccValue = new Uint8Array(arrayBufferCCC); cccValue[0] = 1123; @@ -1224,20 +1871,24 @@ off(type: "characteristicRead", callback?: Callback<CharacteristicReadReq> Unsubscribes from the characteristic read request events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **characteristicRead** indicates a characteristic read request event. | -| callback | Callback<[CharacteristicReadReq](#characteristicreadreq)> | No | Callback used to report a characteristic read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **characteristicRead** indicates a characteristic read request event.| +| callback | Callback<[CharacteristicReadReq](#characteristicreadreq)> | No| Callback used to report a characteristic read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let gattServer = bluetooth.BLE.createGattServer(); gattServer.off("characteristicRead"); ``` @@ -1249,20 +1900,24 @@ on(type: "characteristicWrite", callback: Callback<CharacteristicWriteReq> Subscribes to the characteristic write request events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **characteristicWrite** indicates a characteristic write request event. | -| callback | Callback<[DescriptorWriteReq](#descriptorwritereq)> | Yes | Callback invoked to return a characteristic write request from the GATT client. | +| type | string | Yes| Event type. The value **characteristicWrite** indicates a characteristic write request event.| +| callback | Callback<[DescriptorWriteReq](#descriptorwritereq)> | Yes| Callback invoked to return a characteristic write request from the GATT client.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let arrayBufferCCC = new ArrayBuffer(8); let cccValue = new Uint8Array(arrayBufferCCC); function WriteCharacteristicReq(CharacteristicWriteReq) { @@ -1296,20 +1951,24 @@ off(type: "characteristicWrite", callback?: Callback<CharacteristicWriteReq&g Unsubscribes from the characteristic write request events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **characteristicWrite** indicates a characteristic write request event. | -| callback | Callback<[CharacteristicWriteReq](#characteristicwritereq)> | No | Callback used to report a characteristic write request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **characteristicWrite** indicates a characteristic write request event.| +| callback | Callback<[CharacteristicWriteReq](#characteristicwritereq)> | No| Callback used to report a characteristic write request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let gattServer = bluetooth.BLE.createGattServer(); gattServer.off("characteristicWrite"); ``` @@ -1321,20 +1980,24 @@ on(type: "descriptorRead", callback: Callback<DescriptorReadReq>): void Subscribes to the descriptor read request events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **descriptorRead** indicates a descriptor read request event. | -| callback | Callback<[DescriptorReadReq](#descriptorreadreq)> | Yes | Callback invoked to return a descriptor read request from the GATT client. | +| type | string | Yes| Event type. The value **descriptorRead** indicates a descriptor read request event.| +| callback | Callback<[DescriptorReadReq](#descriptorreadreq)> | Yes| Callback invoked to return a descriptor read request event from the GATT client.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let arrayBufferDesc = new ArrayBuffer(8); let descValue = new Uint8Array(arrayBufferDesc); descValue[0] = 1101; @@ -1365,20 +2028,24 @@ off(type: "descriptorRead", callback?: Callback<DescriptorReadReq>): void Unsubscribes from the descriptor read request events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **descriptorRead** indicates a descriptor read request event. | -| callback | Callback<[DescriptorReadReq](#descriptorreadreq)> | No | Callback used to report a descriptor read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **descriptorRead** indicates a descriptor read request event.| +| callback | Callback<[DescriptorReadReq](#descriptorreadreq)> | No| Callback used to report a descriptor read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let gattServer = bluetooth.BLE.createGattServer(); gattServer.off("descriptorRead"); ``` @@ -1390,20 +2057,24 @@ on(type: "descriptorWrite", callback: Callback<DescriptorWriteReq>): void Subscribes to the descriptor write request events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **descriptorWrite** indicates a descriptor write request event. | -| callback | Callback<[DescriptorWriteReq](#descriptorwritereq)> | Yes | Callback invoked to return a descriptor write request from the GATT client. | +| type | string | Yes| Event type. The value **descriptorWrite** indicates a descriptor write request event.| +| callback | Callback<[DescriptorWriteReq](#descriptorwritereq)> | Yes| Callback invoked to return a descriptor write request from the GATT client.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let arrayBufferDesc = new ArrayBuffer(8); let descValue = new Uint8Array(arrayBufferDesc); function WriteDescriptorReq(DescriptorWriteReq) { @@ -1437,20 +2108,24 @@ off(type: "descriptorWrite", callback?: Callback<DescriptorWriteReq>): voi Unsubscribes from the descriptor write request events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **descriptorWrite** indicates a descriptor write request event. | -| callback | Callback<[DescriptorWriteReq](#descriptorwritereq)> | No | Callback used to report a descriptor read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **descriptorWrite** indicates a descriptor write request event.| +| callback | Callback<[DescriptorWriteReq](#descriptorwritereq)> | No| Callback used to report a descriptor write request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let gattServer = bluetooth.BLE.createGattServer(); gattServer.off("descriptorWrite"); ``` @@ -1462,20 +2137,24 @@ on(type: "connectStateChange", callback: Callback<BLEConnectChangedState>) Subscribes to the BLE connection state change events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **connectStateChange** indicates a BLE connection state change event. | -| callback | Callback<[BLEConnectChangedState](#bleconnectchangedstate)> | Yes | Callback invoked to return the BLE connection state. | +| type | string | Yes| Event type. The value **connectStateChange** indicates a BLE connection state change event.| +| callback | Callback<[BLEConnectChangedState](#bleconnectchangedstate)> | Yes| Callback invoked to return the BLE connection state.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function Connected(BLEConnectChangedState) { let deviceId = BLEConnectChangedState.deviceId; let status = BLEConnectChangedState.state; @@ -1492,20 +2171,24 @@ off(type: "connectStateChange", callback?: Callback<BLEConnectChangedState> Unsubscribes from the BLE connection state change events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **connectStateChange** indicates a BLE connection state change event. | -| callback | Callback<[BLEConnectChangedState](#bleconnectchangedstate)> | No | Callback used to report the BLE connection state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **connectStateChange** indicates a BLE connection state change event.| +| callback | Callback<[BLEConnectChangedState](#bleconnectchangedstate)> | No| Callback used to report the BLE connection state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js let gattServer = bluetooth.BLE.createGattServer(); gattServer.off("connectStateChange"); ``` @@ -1520,18 +2203,22 @@ Implements the GATT client. Before using a method of this class, you must create connect(): boolean -Initiates a connection to the peer BLE device. +Initiates a connection to the remote BLE device. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the connection is successful; returns **false** otherwise. | +| boolean | Returns **true** if the connection is successful; returns **false** otherwise.| -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); let ret = device.connect(); ``` @@ -1540,18 +2227,22 @@ let ret = device.connect(); disconnect(): boolean -Disconnects from the peer BLE device. +Disconnects from the remote BLE device. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the connection is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); let ret = device.disconnect(); ``` @@ -1562,16 +2253,20 @@ close(): boolean Closes this GATT client to unregister it from the protocol stack. After this method is called, this [GattClientDevice](#gattclientdevice) instance cannot be used. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); let ret = device.close(); ``` @@ -1582,21 +2277,25 @@ let ret = device.close(); getServices(callback: AsyncCallback<Array<GattService>>): void -Obtains all services of the peer BLE device. This method uses an asynchronous callback to return the result. +Obtains all services of the remote BLE device. This method uses an asynchronous callback to return the result. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<Array<[GattService](#gattservice)>> | Yes | Callback invoked to return the services obtained. | +| callback | AsyncCallback<Array<[GattService](#gattservice)>> | Yes| Callback invoked to return the services obtained.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js // Callback function getServices(code, gattServices) { if (code.code == 0) { @@ -1610,7 +2309,7 @@ function getServices(code, gattServices) { } } -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.connect(); device.getServices(getServices); ``` @@ -1620,21 +2319,25 @@ device.getServices(getServices); getServices(): Promise<Array<GattService>> -Obtains all services of the peer BLE device. This method uses a promise to return the result. +Obtains all services of the remote BLE device. This method uses a promise to return the result. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -**Return values:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Type | Description | +**Parameters** + +**Return value** + +| Type| Description| | -------- | -------- | -| Promise<Array<[GattService](#gattservice)>> | Promise used to return the services obtained. | +| Promise<Array<[GattService](#gattservice)>> | Promise used to return the services obtained.| -**Example:** +**Example** -``` +```js // Promise -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.connect(); let services = device.getServices(); console.log("bluetooth services size is ", services.length); @@ -1649,22 +2352,26 @@ for (let i = 0; i < services.length; i++) { readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void -Reads the characteristic value of the specific service of the peer BLE device. This method uses an asynchronous callback to return the result. +Reads the characteristic value of the specific service of the remote BLE device. This method uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.USE_BLUETOOTH -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Characteristic value to read. | -| callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | Yes | Callback invoked to return the characteristic value read. | +| characteristic | [BLECharacteristic](#blecharacteristic) | Yes| Characteristic value to read.| +| callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | Yes| Callback invoked to return the characteristic value read.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function readCcc(code, BLECharacteristic) { if (code.code != 0) { return; @@ -1674,7 +2381,7 @@ function readCcc(code, BLECharacteristic) { console.log('bluetooth characteristic value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); } -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); let descriptors = []; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); @@ -1699,24 +2406,29 @@ device.readCharacteristicValue(characteristic, readCcc); readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic> -Reads the characteristic value of the specific service of the peer BLE device. This method uses a promise to return the result. +Reads the characteristic value of the specific service of the remote BLE device. This method uses a promise to return the result. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Characteristic value to read. | +| characteristic | [BLECharacteristic](#blecharacteristic) | Yes| Characteristic value to read.| -**Return values:** +**Return value** -| Type | Description | +| | | | -------- | -------- | -| Promise<[BLECharacteristic](#blecharacteristic)> | Promise used to return the characteristic value read. | +| Type | Description | +| Promise<[BLECharacteristic](#blecharacteristic)> | Promise used to return the characteristic value read. | -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); let descriptors = []; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); @@ -1741,22 +2453,26 @@ device.readCharacteristicValue(characteristic); readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void -Reads the descriptor contained in the specific characteristic of the peer BLE device. This method uses an asynchronous callback to return the result. +Reads the descriptor contained in the specific characteristic of the remote BLE device. This method uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.USE_BLUETOOTH -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| descriptor | [BLEDescriptor](#bledescriptor) | Yes | Descriptor to read. | -| callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | Yes | Callback invoked to return the descriptor read. | +| descriptor | [BLEDescriptor](#bledescriptor) | Yes| Descriptor to read.| +| callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | Yes| Callback invoked to return the descriptor read.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function readDesc(code, BLEDescriptor) { if (code.code != 0) { return; @@ -1766,7 +2482,7 @@ function readDesc(code, BLEDescriptor) { console.log('bluetooth descriptor value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); } -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 11; @@ -1781,24 +2497,29 @@ device.readDescriptorValue(descriptor, readDesc); readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor> -Reads the descriptor contained in the specific characteristic of the peer BLE device. This method uses a promise to return the result. +Reads the descriptor contained in the specific characteristic of the remote BLE device. This method uses a promise to return the result. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| descriptor | [BLEDescriptor](#bledescriptor) | Yes | Descriptor to read. | +| descriptor | [BLEDescriptor](#bledescriptor) | Yes| Descriptor to read.| -**Return values:** +**Return value** -| Type | Description | +| | | | -------- | -------- | -| Promise<[BLEDescriptor](#bledescriptor)> | Promise used to return the descriptor read. | +| Type | Description | +| Promise<[BLEDescriptor](#bledescriptor)> | Promise used to return the descriptor read. | -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 11; @@ -1813,25 +2534,28 @@ device.readDescriptorValue(descriptor); writeCharacteristicValue(characteristic: BLECharacteristic): boolean -Writes a characteristic value to the peer BLE device. +Writes a characteristic value to the remote BLE device. + +**Required permissions**: ohos.permission.USE_BLUETOOTH -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Binary value and other parameters of the BLE device characteristic. | +| characteristic | [BLECharacteristic](#blecharacteristic) | Yes| Binary value and other parameters of the BLE device characteristic.| -**Return values:** +**Return value** -| Name | Type | Mandatory | Description | +| Type| Description| | -------- | -------- | -| Name | Type | Mandatory | Description | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); let descriptors = []; let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); @@ -1860,24 +2584,28 @@ if (retWriteCcc) { writeDescriptorValue(descriptor: BLEDescriptor): boolean -Writes binary data to the specific descriptor of the peer BLE device. +Writes binary data to the specific descriptor of the remote BLE device. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| descriptor | [BLEDescriptor](#bledescriptor) | Yes | Binary value and other parameters of the BLE device descriptor. | +| descriptor | [BLEDescriptor](#bledescriptor) | Yes| Binary value and other parameters of the BLE device descriptor.| -**Return values:** +**Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); let bufferDesc = new ArrayBuffer(8); let descV = new Uint8Array(bufferDesc); descV[0] = 22; @@ -1897,24 +2625,28 @@ if (retWriteDesc) { setBLEMtuSize(mtu: number): boolean -Sets the maximum transmission unit (MTU) that can be transmitted between the GATT client and its peer BLE device. This method can be used only after a connection is set up by calling **connect**. +Sets the maximum transmission unit (MTU) that can be transmitted between the GATT client and its remote BLE device. This method can be used only after a connection is set up by calling [connect](#connect). + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| mtu | number | Yes | MTU to set, which ranges from 22 to 512 bytes. | +| mtu | number | Yes| MTU to set, which ranges from 22 to 512 bytes.| -**Return values:** +**Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.setBLEMtuSize(128); ``` @@ -1923,25 +2655,29 @@ device.setBLEMtuSize(128); setNotifyCharacteristicChanged(characteristic: BLECharacteristic, enable: boolean): boolean -Sets the function of notifying the GATT client when the characteristic value of the peer BLE device changes. +Sets the function of notifying the GATT client when the characteristic value of the remote BLE device changes. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | BLE characteristic to listen for. | -| enable | boolean | Yes | Whether to enable the notify function. The value **true** means to enable the notify function, and the value **false** means the opposite. | +| characteristic | [BLECharacteristic](#blecharacteristic) | Yes| BLE characteristic to listen for.| +| enable | boolean | Yes| Whether to enable the notify function. The value **true** means to enable the notify function, and the value **false** means the opposite.| -**Return values:** +**Return value** -| Type | Description | +| Type| Description| | -------- | -------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise. | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.setNotifyCharacteristicChanged(notifyCcc, false); ``` @@ -1952,26 +2688,30 @@ on(type: "BLECharacteristicChange", callback: Callback<BLECharacteristic>) Subscribes to the BLE characteristic change events. The client can receive a notification from the server only after the **setNotifyCharacteristicChanged** method is called. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **BLECharacteristicChange** indicates a characteristic value change event. | -| callback | Callback<[BLECharacteristic](#blecharacteristic)> | Yes | Callback invoked to return the characteristic value changes. | +| type | string | Yes| Event type. The value **BLECharacteristicChange** indicates a characteristic value change event.| +| callback | Callback<[BLECharacteristic](#blecharacteristic)> | Yes| Callback invoked to return the characteristic value changes.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function CharacteristicChange(CharacteristicChangeReq) { let serviceUuid = CharacteristicChangeReq.serviceUuid; let characteristicUuid = CharacteristicChangeReq.characteristicUuid; let value = new Uint8Array(CharacteristicChangeReq.characteristicValue); } -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.on('BLECharacteristicChange', CharacteristicChange); ``` @@ -1982,21 +2722,25 @@ off(type: "BLECharacteristicChange", callback?: Callback<BLECharacteristic> Unsubscribes from the BLE characteristic change events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **BLECharacteristicChange** indicates a characteristic value change event. | -| callback | Callback<[BLECharacteristic](#blecharacteristic)> | No | Callback used to report the characteristic value. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **BLECharacteristicChange** indicates a characteristic value change event.| +| callback | Callback<[BLECharacteristic](#blecharacteristic)> | No| Callback used to report the characteristic value. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.off('BLECharacteristicChange'); ``` @@ -2007,25 +2751,29 @@ on(type: "BLEConnectionStateChange", callback: Callback<BLEConnectChangedStat Subscribes to the BLE connection state change events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Name | Type | Mandatory | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **BLEConnectionStateChange** indicates a BLE connection state change event. | -| callback | Callback<[BLEConnectChangedState](#bleconnectchangedstate)> | Yes | Callback invoked to return the BLE connection state. | +| type | string | Yes| Event type. The value **BLEConnectionStateChange** indicates a BLE connection state change event.| +| callback | Callback<[BLEConnectChangedState](#bleconnectchangedstate)> | Yes| Callback invoked to return the BLE connection state.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` +```js function ConnectStateChanged(state) { console.log('bluetooth connect state changed'); let connectState = state.state; } -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.on('BLEConnectionStateChange', ConnectStateChanged); ``` @@ -2036,21 +2784,25 @@ off(type: "BLEConnectionStateChange", callback?: Callback<BLEConnectChangedSt Unsubscribes from the BLE connection state change events. -**Parameters:** +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes | Event type. The value **BLEConnectionStateChange** indicates a BLE connection state change event. | -| callback | Callback<[BLEConnectChangedState](#bleconnectchangedstate)> | No | Callback used to report the BLE connection state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. | +| type | string | Yes| Event type. The value **BLEConnectionStateChange** indicates a BLE connection state change event.| +| callback | Callback<[BLEConnectChangedState](#bleconnectchangedstate)> | No| Callback used to report the BLE connection state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` -let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D'); +```js +let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.off('BLEConnectionStateChange'); ``` @@ -2059,23 +2811,27 @@ device.off('BLEConnectionStateChange'); getDeviceName(callback: AsyncCallback<string>): void -Obtains the name of the peer BLE device. This method uses an asynchronous callback to return the result. +Obtains the name of the remote BLE device. This method uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.USE_BLUETOOTH + +**System capability**: SystemCapability.Communication.Bluetooth.Core -**Parameters:** +**Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<string> | Yes | Callback invoked to return the peer BLE device name. | +| callback | AsyncCallback<string> | Yes| Callback invoked to return the remote BLE device name obtained.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` -// Callback -let gattClient = bluetooth.BLE.createGattClientDevice("8F:8F:8E:8E:6D:6D"); +```js +// callback +let gattClient = bluetooth.BLE.createGattClientDevice("XX:XX:XX:XX:XX:XX"); let deviceName = gattClient.getDeviceName((err, data)=> { console.info('device name err ' + JSON.stringify(err)); console.info('device name' + JSON.stringify(data)); @@ -2087,19 +2843,23 @@ let deviceName = gattClient.getDeviceName((err, data)=> { getDeviceName(): Promise<string> -Obtains the name of the peer BLE device. This method uses a promise to return the result. +Obtains the name of the remote BLE device. This method uses a promise to return the result. -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| Promise<string> | Promise used to return the peer BLE device name. | +| Promise<string> | Promise used to return the remote BLE device name.| -**Example:** +**Example** -``` -// Promise -let gattClient = bluetooth.BLE.createGattClientDevice("8F:8F:8E:8E:6D:6D"); +```js +// promise +let gattClient = bluetooth.BLE.createGattClientDevice("XX:XX:XX:XX:XX:XX"); let ret = device.connect(); let deviceName = gattClient.getDeviceName().then((data) => { console.info('device name' + JSON.stringify(data)); @@ -2111,23 +2871,27 @@ let deviceName = gattClient.getDeviceName().then((data) => { getRssiValue(callback: AsyncCallback<number>): void -Obtains the received signal strength indication (RSSI) of the peer BLE device. This method uses an asynchronous callback to return the result. It can be used only after a connection is set up by calling [connect](#connect). +Obtains the received signal strength indication (RSSI) of the remote BLE device. This method uses an asynchronous callback to return the result. It can be used only after a connection is set up by calling [connect](#connect). + +**Required permissions**: ohos.permission.USE_BLUETOOTH -**Parameters:** +**System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Mandatory | Description | +**Parameters** + +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<number> | Yes | Callback invoked to return the RSSI, in dBm. | +| callback | AsyncCallback<number> | Yes| Callback invoked to return the RSSI, in dBm.| -**Return values:** +**Return value** -None. +No value is returned. -**Example:** +**Example** -``` -// Callback -let gattClient = bluetooth.BLE.createGattClientDevice("8F:8F:8E:8E:6D:6D"); +```js +// callback +let gattClient = bluetooth.BLE.createGattClientDevice("XX:XX:XX:XX:XX:XX"); let ret = device.connect(); let rssi = gattClient.getRssiValue((err, data)=> { console.info('rssi err ' + JSON.stringify(err)); @@ -2140,327 +2904,548 @@ let rssi = gattClient.getRssiValue((err, data)=> { getRssiValue(): Promise<number> -Obtains the RSSI of the peer BLE device. This method uses a promise to return the result. It can be used only after a connection is set up by calling [connect](#connect). +Obtains the RSSI of the remote BLE device. This method uses a promise to return the result. It can be used only after a connection is set up by calling [connect](#connect). -**Return values:** +**Required permissions**: ohos.permission.USE_BLUETOOTH -| Type | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +**Return value** + +| Type| Description| | -------- | -------- | -| Promise<number> | Promise used to return the RSSI, in dBm. | +| Promise<number> | Promise used to return the RSSI, in dBm.| -**Example:** +**Example** -``` -// Promise -let gattClient = bluetooth.BLE.createGattClientDevice("8F:8F:8E:8E:6D:6D"); +```js +// promise +let gattClient = bluetooth.BLE.createGattClientDevice("XX:XX:XX:XX:XX:XX"); let rssi = gattClient.getRssiValue().then((data) => { console.info('rssi' + JSON.stringify(data)); }) ``` - -## ScanMode +## ScanMode8+ Enumerates the scan modes. -| Mode | Default Value | Description | -| -------- | -------- | -------- | -| SCAN_MODE_NONE | 0 | No scan mode is specified. | -| SCAN_MODE_CONNECTABLE | 1 | Discoverable mode. | -| SCAN_MODE_GENERAL_DISCOVERABLE | 2 | General discoverable mode. | -| SCAN_MODE_LIMITED_DISCOVERABLE | 3 | Limited discoverable mode. | -| SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4 | General connectable and discoverable mode. | -| SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5 | Limited connectable and discoverable mode. | +**System capability**: SystemCapability.Communication.Bluetooth.Core +| Name| Default Value| Description| +| -------- | -------- | -------- | +| SCAN_MODE_NONE | 0 | No scan mode.| +| SCAN_MODE_CONNECTABLE | 1 | Connectable mode.| +| SCAN_MODE_GENERAL_DISCOVERABLE | 2 | General discoverable mode.| +| SCAN_MODE_LIMITED_DISCOVERABLE | 3 | Limited discoverable mode.| +| SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4 | General connectable and discoverable mode.| +| SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5 | Limited connectable and discoverable mode.| -## BondState +## BondState8+ Enumerates the pairing states. -| State | Default Value | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| | -------- | -------- | -------- | -| BOND_STATE_INVALID | 0 | Invalid pairing. | -| BOND_STATE_BONDING | 1 | Pairing. | -| BOND_STATE_BONDED | 2 | Paired. | +| BOND_STATE_INVALID | 0 | Invalid pairing.| +| BOND_STATE_BONDING | 1 | Pairing.| +| BOND_STATE_BONDED | 2 | Paired.| -## SppOption +## SppOption8+ Defines the SPP configuration parameters. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| uuid | string | Yes | Yes | UUID of the SPP. | -| isPrimary | boolean | Yes | Yes | Whether it is a secure channel. | -| type | [SppType](#SppType) | Yes | Yes | Type of the SPP link. | +| uuid | string | Yes| Yes| UUID of the SPP.| +| secure | boolean | Yes| Yes| Whether it is a secure channel.| +| type | [SppType](#spptype) | Yes| Yes| Type of the SPP link.| -## SppType +## SppType8+ Enumerates the SPP link types. -| Type | Default Value | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| | -------- | -------- | -------- | -| SPP_RFCOMM | 0 | Radio frequency communication (RFCOMM) link type. | +| SPP_RFCOMM | 0 | Radio frequency communication (RFCOMM) link type.| ## GattService Defines the GATT service API parameters. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**. | -| isPrimary | boolean | Yes | Yes | Whether the service is a primary service. The value **true** means a primary service. | -| characteristics | Array<[BLECharacteristic](#BLECharacteristic)> | Yes | Yes | List of characteristics of the service. | -| includeServices | Array<[GattService](#GattService)> | Yes | Yes | Services on which the service depends. | +| serviceUuid | string | Yes| Yes| UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| +| isPrimary | boolean | Yes| Yes| Whether the service is a primary service. The value **true** means a primary service.| +| characteristics | Array<[BLECharacteristic](#blecharacteristic)> | Yes| Yes| List of characteristics of the service.| +| includeServices | Array<[GattService](#gattservice)> | Yes| Yes| Services on which the service depends.| ## BLECharacteristic Defines the characteristic API parameters. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**. | -| characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**. | -| characteristicValue | ArrayBuffer | Yes | Yes | Binary value of the characteristic. | -| descriptors | Array<[BLEDescriptor](#BLEDescriptor)> | Yes | Yes | List of descriptors of the characteristic. | +| serviceUuid | string | Yes| Yes| UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| +| characteristicUuid | string | Yes| Yes| UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| +| characteristicValue | ArrayBuffer | Yes| Yes| Binary value of the characteristic.| +| descriptors | Array<[BLEDescriptor](#bledescriptor)> | Yes| Yes| List of descriptors of the characteristic.| ## BLEDescriptor Defines the descriptor API parameters. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**. | -| characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**. | -| descriptorUuid | string | Yes | Yes | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**. | -| descriptorValue | ArrayBuffer | Yes | Yes | Binary value of the descriptor. | +| serviceUuid | string | Yes| Yes| UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| +| characteristicUuid | string | Yes| Yes| UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| +| descriptorUuid | string | Yes| Yes| UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| +| descriptorValue | ArrayBuffer | Yes| Yes| Binary value of the descriptor.| ## NotifyCharacteristic Defines the parameters in the notifications sent when the server characteristic value changes. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**. | -| characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**. | -| characteristicValue | ArrayBuffer | Yes | Yes | Binary value of the characteristic. | -| confirm | boolean | Yes | Yes | Whether the notification needs to be confirmed by the peer end. For a notification, set it to **true**. In this case, the peer end must confirm the receipt of the notification. For an indication, set it to **false**. In this case, the peer end does not need to confirm the receipt of the notification. | +| serviceUuid | string | Yes| Yes| UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| +| characteristicUuid | string | Yes| Yes| UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| +| characteristicValue | ArrayBuffer | Yes| Yes| Binary value of the characteristic.| +| confirm | boolean | Yes| Yes| Whether the notification needs to be confirmed by the remote end. For a notification, set it to **true**. In this case, the remote end must confirm the receipt of the notification. For an indication, set it to **false**. In this case, the remote end does not need to confirm the receipt of the notification.| ## CharacteristicReadReq Defines the parameters of the **CharacteristicReadReq** event received by the server. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | No | Address of the client that sends the request, for example, **8F:8F:8E:8E:6D:6D**. | -| transId | number | Yes | No | Transmission ID of the read request. The response returned by the server must use the same transmission ID. | -| offset | number | Yes | No | Position from which the characteristic value is read. For example, **k** means to read from the _k_th byte. The response returned by the server must use the same offset. | -| characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**. | -| serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**. | +| deviceId | string | Yes| No| Address of the remote device that sends the **CharacteristicReadReq** event, for example, XX:XX:XX:XX:XX:XX.| +| transId | number | Yes| No| Transmission ID of the read request. The response returned by the server must use the same transmission ID.| +| offset | number | Yes| No| Position from which the characteristic value is read. For example, **k** means to read from the kth byte. The response returned by the server must use the same offset.| +| characteristicUuid | string | Yes| No| UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| +| serviceUuid | string | Yes| No| UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| ## CharacteristicWriteReq Defines the parameters of the **CharacteristicWriteReq** event received by the server. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | No | Address of the client that sends the request, for example, **8F:8F:8E:8E:6D:6D**. | -| transId | number | Yes | No | Transmission ID of the write request. The response returned by the server must use the same transmission ID. | -| offset | number | Yes | No | Start position for writing the characteristic value. For example, **k** means to write from the _k_th byte. The response returned by the server must use the same offset. | -| descriptorUuid | string | Yes | No | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**. | -| characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**. | -| serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**. | +| deviceId | string | Yes| No| Address of the remote device that sends the **CharacteristicWriteReq** event, for example, XX:XX:XX:XX:XX:XX.| +| transId | number | Yes| No| Transmission ID of the write request. The response returned by the server must use the same transmission ID.| +| offset | number | Yes| No| Start position for writing the characteristic value. For example, **k** means to write from the kth byte. The response returned by the server must use the same offset.| +| descriptorUuid | string | Yes| No| UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| +| characteristicUuid | string | Yes| No| UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| +| serviceUuid | string | Yes| No| UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| ## DescriptorReadReq Defines the parameters of the **DescriptorReadReq** event received by the server. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | No | Address of the client that sends the request, for example, **8F:8F:8E:8E:6D:6D**. | -| transId | number | Yes | No | Transmission ID of the read request. The response returned by the server must use the same transmission ID. | -| offset | number | Yes | No | Position from which the descriptor is read. For example, **k** means to read from the _k_th byte. The response returned by the server must use the same offset. | -| descriptorUuid | string | Yes | No | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**. | -| characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**. | -| serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**. | +| deviceId | string | Yes| No| Address of the remote device that sends a **DescriptorReadReq** event, for example, XX:XX:XX:XX:XX:XX.| +| transId | number | Yes| No| Transmission ID of the read request. The response returned by the server must use the same transmission ID.| +| offset | number | Yes| No| Position from which the descriptor is read. For example, **k** means to read from the kth byte. The response returned by the server must use the same offset.| +| descriptorUuid | string | Yes| No| UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| +| characteristicUuid | string | Yes| No| UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| +| serviceUuid | string | Yes| No| UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| ## DescriptorWriteReq Defines the parameters of the **DescriptorWriteReq** event received by the server. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | No | Address of the client that sends the request, for example, **8F:8F:8E:8E:6D:6D**. | -| transId | number | Yes | No | Transmission ID of the write request. The response returned by the server must use the same transmission ID. | -| offset | number | Yes | No | Start position for writing the descriptor. For example, **k** means to write from the _k_th byte. The response returned by the server must use the same offset. | -| isPrep | boolean | Yes | No | Whether the write request is executed immediately. | -| needRsp | boolean | Yes | No | Whether to send a response to the GATT client. | -| value | ArrayBuffer | Yes | No | Binary value of the descriptor to write. | -| descriptorUuid | string | Yes | No | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**. | -| characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**. | -| serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**. | +| deviceId | string | Yes| No| Address of the remote device that sends a **DescriptorWriteReq** event, for example, XX:XX:XX:XX:XX:XX.| +| transId | number | Yes| No| Transmission ID of the write request. The response returned by the server must use the same transmission ID.| +| offset | number | Yes| No| Start position for writing the descriptor. For example, **k** means to write from the kth byte. The response returned by the server must use the same offset.| +| isPrep | boolean | Yes| No| Whether the write request is executed immediately.| +| needRsp | boolean | Yes| No| Whether to send a response to the GATT client.| +| value | ArrayBuffer | Yes| No| Binary value of the descriptor to write.| +| descriptorUuid | string | Yes| No| UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| +| characteristicUuid | string | Yes| No| UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| +| serviceUuid | string | Yes| No| UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| ## ServerResponse Defines the parameters of the server's response to the GATT client's read/write request. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | No | Address of the client, for example, **8F:8F:8E:8E:6D:6D**. | -| transId | number | Yes | No | Transmission ID of the request. The value must be the same as the ID carried in the read/write request received. | -| status | number | Yes | No | Response state. Set this parameter to **0**, which indicates a normal response. | -| offset | number | Yes | No | Start read/write position. The value must be the same as the **offset** carried in the read/write request. | -| value | ArrayBuffer | Yes | No | Binary data in the response. | +| deviceId | string | Yes| No| Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| +| transId | number | Yes| No| Transmission ID of the request. The value must be the same as the ID carried in the read/write request received.| +| status | number | Yes| No| Response state. Set this parameter to **0**, which indicates a normal response.| +| offset | number | Yes| No| Start read/write position. The value must be the same as the offset carried in the read/write request.| +| value | ArrayBuffer | Yes| No| Binary data in the response.| ## BLEConnectChangedState Defines the parameters of **BLEConnectChangedState**. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | No | Address of the peer device, for example, **8F:8F:8E:8E:6D:6D**. | -| state | [ProfileConnectionState](#ProfileConnectionState) | Yes | Yes | BLE connection state. | +| deviceId | string | Yes| No| Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| +| state | [ProfileConnectionState](#profileconnectionState) | Yes| Yes| BLE connection state.| ## ProfileConnectionState Enumerates the profile connection states. -| Name | Default Value | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| | -------- | -------- | -------- | -| STATE_DISCONNECTED | 0 | Disconnected. | -| STATE_CONNECTING | 1 | Connecting. | -| STATE_CONNECTED | 2 | Connected. | -| STATE_DISCONNECTING | 3 | Disconnecting. | +| STATE_DISCONNECTED | 0 | Disconnected.| +| STATE_CONNECTING | 1 | Connecting.| +| STATE_CONNECTED | 2 | Connected.| +| STATE_DISCONNECTING | 3 | Disconnecting.| ## ScanFilter Defines the scan filter parameters. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | Yes | Address of the BLE device to filter, for example, **8F:8F:8E:8E:6D:6D**. | -| name | string | Yes | Yes | Name of the BLE device to filter. | -| serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**. | +| deviceId | string | Yes| Yes| Address of the BLE device to filter, for example, XX:XX:XX:XX:XX:XX.| +| name | string | Yes| Yes| Name of the BLE device to filter.| +| serviceUuid | string | Yes| Yes| UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| ## ScanOptions Defines the scan configuration parameters. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| interval | number | Yes | Yes | Delay in reporting the scan result. The default value is **0**. | -| dutyMode | [ScanDuty](#ScanDuty) | Yes | Yes | Scan duty. The default value is **SCAN_MODE_LOW_POWER**. | -| matchMode | [MatchMode](#MatchMode) | Yes | Yes | Hardware match mode for BLE scan filters. The default value is **MATCH_MODE_AGGRESSIVE**. | +| interval | number | Yes| Yes| Delay in reporting the scan result. The default value is **0**.| +| dutyMode | [ScanDuty](#scanduty) | Yes| Yes| Scan duty. The default value is **SCAN_MODE_LOW_POWER**.| +| matchMode | [MatchMode](#matchmode) | Yes| Yes| Hardware filtering match mode. The default value is **MATCH_MODE_AGGRESSIVE**.| ## ScanDuty Enumerates the scan duty options. -| Name | Default Value | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| | -------- | -------- | -------- | -| SCAN_MODE_LOW_POWER | 0 | Low-power mode, which is the default value. | -| SCAN_MODE_BALANCED | 1 | Balanced mode. | -| SCAN_MODE_LOW_LATENCY | 2 | Low-latency mode. | +| SCAN_MODE_LOW_POWER | 0 | Low-power mode, which is the default value.| +| SCAN_MODE_BALANCED | 1 | Balanced mode.| +| SCAN_MODE_LOW_LATENCY | 2 | Low-latency mode.| ## MatchMode Enumerates the hardware match modes of BLE scan filters. -| Name | Default Value | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| | -------- | -------- | -------- | -| MATCH_MODE_AGGRESSIVE | 1 | Hardware reports the scan result with a lower threshold of signal strength and few number of matches in a duration. This is the default value. | -| SCAN_MODE_LOW_LATENCY | 2 | Hardware reports the scan result with a higher threshold of signal strength and sightings. | +| MATCH_MODE_AGGRESSIVE | 1 | Hardware reports the scan result with a lower threshold of signal strength and few number of matches in a duration. This is the default value.| +| MATCH_MODE_STICKY | 2 | Hardware reports the scan result with a higher threshold of signal strength and sightings.| ## ScanResult Defines the scan result. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | No | Address of the device discovered, for example, **8F:8F:8E:8E:6D:6D**. | -| rssi | number | Yes | No | RSSI of the device. | -| data | ArrayBuffer | Yes | No | Advertisement packets sent by the device. | +| deviceId | string | Yes| No| Address of the scanned device, for example, XX:XX:XX:XX:XX:XX.| +| rssi | number | Yes| No| RSSI of the device.| +| data | ArrayBuffer | Yes| No| Advertisement packets sent by the device.| ## BluetoothState Enumerates the Bluetooth states. -| Name | Default Value | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| | -------- | -------- | -------- | -| STATE_OFF | 0 | Bluetooth is turned off. | -| STATE_TURNING_ON | 1 | Bluetooth is being turned on. | -| STATE_ON | 2 | Bluetooth is turned on. | -| STATE_TURNING_OFF | 3 | Bluetooth is being turned off. | -| STATE_BLE_TURNING_ON | 4 | The LE-only mode is being turned on for Bluetooth. | -| STATE_BLE_ON | 5 | Bluetooth is in LE-only mode. | -| STATE_BLE_TURNING_OFF | 6 | The LE-only mode is being turned off for Bluetooth. | +| STATE_OFF | 0 | Bluetooth is turned off.| +| STATE_TURNING_ON | 1 | Bluetooth is being turned on.| +| STATE_ON | 2 | Bluetooth is turned on.| +| STATE_TURNING_OFF | 3 | Bluetooth is being turned off.| +| STATE_BLE_TURNING_ON | 4 | The LE-only mode is being turned on for Bluetooth.| +| STATE_BLE_ON | 5 | Bluetooth is in LE-only mode.| +| STATE_BLE_TURNING_OFF | 6 | The LE-only mode is being turned off for Bluetooth.| ## AdvertiseSetting Defines the BLE advertising parameters. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| interval | number | Yes | Yes | Interval for BLE advertising. The minimum value is **32** slots (20 ms). The maximum value is **16777215** slots. The default value is **1600** slots (1s). | -| txPower | number | Yes | Yes | Transmit power, in dBm. The value range is –127 to 1. The default value is **–7**. | -| connectable | boolean | Yes | Yes | Whether the advertisement is connectable. The default value is **true**. | +| interval | number | Yes| Yes| Interval for BLE advertising. The minimum value is **32** slots (20 ms). The maximum value is **16777215** slots. The default value is **1600** slots (1s).| +| txPower | number | Yes| Yes| Transmit power, in dBm. The value range is –127 to 1. The default value is **–7**.| +| connectable | boolean | Yes| Yes| Whether the advertisement is connectable. The default value is **true**.| ## AdvertiseData Defines the content of a BLE advertisement packet. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| serviceUuids | Array<string> | Yes | Yes | List of service UUIDs to be broadcasted. | -| manufactureData | Array<[ManufactureData](#ManufactureData)> | Yes | Yes | List of manufacturers to be broadcasted. | -| serviceData | Array<[ServiceData](#ServiceData)> | Yes | Yes | List of service data to be broadcasted. | +| serviceUuids | Array<string> | Yes| Yes| List of service UUIDs to broadcast.| +| manufactureData | Array<[ManufactureData](#manufacturedata)> | Yes| Yes| List of manufacturers to broadcast.| +| serviceData | Array<[ServiceData](#servicedata)> | Yes| Yes| List of service data to broadcast.| ## ManufactureData Defines the content of a BLE advertisement packet. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| manufactureId | Array<string> | Yes | Yes | Manufacturer ID allocated by the Bluetooth SIG. | -| manufactureValue | ArrayBuffer | Yes | Yes | Manufacturer data. | +| manufactureId | Array<string> | Yes| Yes| Manufacturer ID allocated by the Bluetooth SIG.| +| manufactureValue | ArrayBuffer | Yes| Yes| Manufacturer data.| ## ServiceData Defines the service data contained in an advertisement packet. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| serviceUuid | string | Yes | Yes | Service UUID. | -| serviceValue | ArrayBuffer | Yes | Yes | Service data. | +| serviceUuid | string | Yes| Yes| Service UUID.| +| serviceValue | ArrayBuffer | Yes| Yes| Service data.| -## PinRequiredParam +## PinRequiredParam8+ Defines the pairing request parameters. -| Name | Type | Readable | Writable | Description | +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| deviceId | string | Yes | No | ID of the device to pair. | -| pinCode | string | Yes | No | Key for the device pairing. | +| deviceId | string | Yes| No| ID of the device to pair.| +| pinCode | string | Yes| No| Key for the device pairing.| + + +## StateChangeParam8+ + +Defines the profile state change parameters. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| deviceId | string | Yes| No| Address of a Bluetooth device.| +| state | [ProfileConnectionState](#ProfileConnectionState) | Yes| No| Profile connection state of the device.| + + +## DeviceClass8+ + +Defines the class of a Bluetooth device. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| majorClass | [MajorClass](#majorclass) | Yes| No| Major classes of Bluetooth devices.| +| majorMinorClass | [MajorMinorClass](#majorminorclass) | Yes| No| Major and minor classes of Bluetooth devices.| +| classOfDevice | number | Yes| No| Class of the device.| + + + +## MajorClass8+ + +Enumerates the major classes of Bluetooth devices. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| MAJOR_MISC | 0x0000 | Miscellaneous device.| +| MAJOR_COMPUTER | 0x0100 | Computer.| +| MAJOR_PHONE | 0x0200 | Mobile phone.| +| MAJOR_NETWORKING | 0x0300 | Network device.| +| MAJOR_AUDIO_VIDEO | 0x0400 | Audio or video device.| +| MAJOR_PERIPHERAL | 0x0500 | Peripheral device.| +| MAJOR_IMAGING | 0x0600 | Imaging device.| +| MAJOR_WEARABLE | 0x0700 | Wearable device.| +| MAJOR_TOY | 0x0800 | Toy.| +| MAJOR_HEALTH | 0x0900 | Health device.| +| MAJOR_UNCATEGORIZED | 0x1F00 | Unclassified device.| + + +## MajorMinorClass8+ + +Enumerates the major and minor classes of Bluetooth devices. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| COMPUTER_UNCATEGORIZED | 0x0100 | Unclassified computer.| +| COMPUTER_DESKTOP | 0x0104 | Desktop computer.| +| COMPUTER_SERVER | 0x0108 | Server.| +| COMPUTER_LAPTOP | 0x010C | Laptop.| +| COMPUTER_HANDHELD_PC_PDA | 0x0110 | Hand-held computer.| +| COMPUTER_PALM_SIZE_PC_PDA | 0x0114 | Palmtop computer.| +| COMPUTER_WEARABLE | 0x0118 | Wearable computer.| +| COMPUTER_TABLET | 0x011C | Tablet.| +| PHONE_UNCATEGORIZED | 0x0200 | Unclassified mobile phone.| +| PHONE_CELLULAR | 0x0204 | Portable phone.| +| PHONE_CORDLESS | 0x0208 | Cordless phone.| +| PHONE_SMART | 0x020C | Smartphone.| +| PHONE_MODEM_OR_GATEWAY | 0x0210 | Modem or gateway phone.| +| PHONE_ISDN | 0x0214 | ISDN phone.| +| NETWORK_FULLY_AVAILABLE | 0x0300 | Device with network fully available.| +| NETWORK_1_TO_17_UTILIZED | 0x0320 | Device used on network 1 to 17.| +| NETWORK_17_TO_33_UTILIZED | 0x0340 | Device used on network 17 to 33.| +| NETWORK_33_TO_50_UTILIZED | 0x0360 | Device used on network 33 to 50.| +| NETWORK_60_TO_67_UTILIZED | 0x0380 | Device used on network 60 to 67.| +| NETWORK_67_TO_83_UTILIZED | 0x03A0 | Device used on network 67 to 83.| +| NETWORK_83_TO_99_UTILIZED | 0x03C0 | Device used on network 83 to 99.| +| NETWORK_NO_SERVICE | 0x03E0 | Device without network service +| AUDIO_VIDEO_UNCATEGORIZED | 0x0400 | Unclassified audio or video device.| +| AUDIO_VIDEO_WEARABLE_HEADSET | 0x0404 | Wearable audio or video headset.| +| AUDIO_VIDEO_HANDSFREE | 0x0408 | Hands-free audio or video device.| +| AUDIO_VIDEO_MICROPHONE | 0x0410 | Audio or video microphone.| +| AUDIO_VIDEO_LOUDSPEAKER | 0x0414 | Audio or video loudspeaker.| +| AUDIO_VIDEO_HEADPHONES | 0x0418 | Audio or video headphones.| +| AUDIO_VIDEO_PORTABLE_AUDIO | 0x041C | Portable audio or video device.| +| AUDIO_VIDEO_CAR_AUDIO | 0x0420 | In-vehicle audio or video device.| +| AUDIO_VIDEO_SET_TOP_BOX | 0x0424 | Audio or video STB device.| +| AUDIO_VIDEO_HIFI_AUDIO | 0x0428 | High-fidelity speaker device.| +| AUDIO_VIDEO_VCR| 0x042C | Video cassette recording (VCR) device.| +| AUDIO_VIDEO_VIDEO_CAMERA | 0x0430 | Camera.| +| AUDIO_VIDEO_CAMCORDER | 0x0434 | Camcorder| +| AUDIO_VIDEO_VIDEO_MONITOR | 0x0438 | Audio or video monitor.| +| AUDIO_VIDEO_VIDEO_DISPLAY_AND_LOUDSPEAKER | 0x043C | Video display or loudspeaker.| +| AUDIO_VIDEO_VIDEO_CONFERENCING | 0x0440 | Video conferencing device.| +| AUDIO_VIDEO_VIDEO_GAMING_TOY | 0x0448 | Audio or video gaming toy.| +| PERIPHERAL_NON_KEYBOARD_NON_POINTING | 0x0500 | Non-keyboard or non-pointing peripheral device.| +| PERIPHERAL_KEYBOARD | 0x0540 | Keyboard device.| +| PERIPHERAL_POINTING_DEVICE | 0x0580 | Pointing peripheral device.| +| PERIPHERAL_KEYBOARD_POINTING| 0x05C0 | Keyboard pointing device.| +| PERIPHERAL_UNCATEGORIZED | 0x0500 | Unclassified peripheral device.| +| PERIPHERAL_JOYSTICK | 0x0504 | Peripheral joystick.| +| PERIPHERAL_GAMEPAD | 0x0508 | Peripheral game pad| +| PERIPHERAL_REMOTE_CONTROL | 0x05C0 | Peripheral remote control device| +| PERIPHERAL_SENSING_DEVICE | 0x0510 | Peripheral sensing device.| +| PERIPHERAL_DIGITIZER_TABLET | 0x0514 | Peripheral digitizer tablet.| +| PERIPHERAL_CARD_READER | 0x0518 | Peripheral card reader.| +| PERIPHERAL_DIGITAL_PEN | 0x051C | Peripheral digital pen.| +| PERIPHERAL_SCANNER_RFID | 0x0520 | Peripheral RFID scanner.| +| PERIPHERAL_GESTURAL_INPUT | 0x0522 | Gesture input device.| +| IMAGING_UNCATEGORIZED | 0x0600 | Unclassified imaging device.| +| IMAGING_DISPLAY | 0x0610 | Imaging display device.| +| IMAGING_CAMERA | 0x0620 | Imaging camera device.| +| IMAGING_SCANNER | 0x0640 | Imaging scanner.| +| IMAGING_PRINTER | 0x0680 | Imaging printer.| +| WEARABLE_UNCATEGORIZED | 0x0700 | Unclassified wearable device.| +| WEARABLE_WRIST_WATCH | 0x0704 | Smart watch.| +| WEARABLE_PAGER | 0x0708 | Wearable pager.| +| WEARABLE_JACKET | 0x070C | Smart jacket.| +| WEARABLE_HELMET | 0x0710 | Wearable helmet.| +| WEARABLE_GLASSES | 0x0714 | Wearable glasses.| +| TOY_UNCATEGORIZED | 0x0800 | Unclassified toy.| +| TOY_ROBOT| 0x0804 | Toy robot.| +| TOY_VEHICLE | 0x0808 | Toy vehicle.| +| TOY_DOLL_ACTION_FIGURE | 0x080C | Humanoid toy doll.| +| TOY_CONTROLLER | 0x0810 | Toy controller.| +| TOY_GAME | 0x0814 | Toy gaming device.| +| HEALTH_UNCATEGORIZED | 0x0900 | Unclassified health devices.| +| HEALTH_BLOOD_PRESSURE | 0x0904 | Blood pressure device.| +| HEALTH_THERMOMETER | 0x0908 | Thermometer| +| HEALTH_WEIGHING | 0x090C | Body scale.| +| HEALTH_GLUCOSE | 0x0910 | Blood glucose monitor.| +| HEALTH_PULSE_OXIMETER | 0x0914 | Pulse oximeter.| +| HEALTH_PULSE_RATE | 0x0918 | Heart rate monitor.| +| HEALTH_DATA_DISPLAY | 0x091C | Health data display.| +| HEALTH_STEP_COUNTER | 0x0920 | Step counter.| +| HEALTH_BODY_COMPOSITION_ANALYZER | 0x0924 | Body composition analyzer.| +| HEALTH_PEAK_FLOW_MOITOR | 0x0928 | Hygrometer.| +| HEALTH_MEDICATION_MONITOR | 0x092C | Medication monitor.| +| HEALTH_KNEE_PROSTHESIS | 0x0930 | Prosthetic knee.| +| HEALTH_ANKLE_PROSTHESIS | 0x0934 | Prosthetic ankle.| +| HEALTH_GENERIC_HEALTH_MANAGER | 0x0938 | Generic health management device.| +| HEALTH_PERSONAL_MOBILITY_DEVICE | 0x093C | Personal mobility device.| + + +## PlayingState8+ + +Enumerates the A2DP playing states. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| STATE_NOT_PLAYING | 0x0000 | Not playing.| +| STATE_PLAYING | 0x0001 | Playing.| + + +## ProfileId8+ + +Enumerates the Bluetooth profile IDs. + +**System capability**: SystemCapability.Communication.Bluetooth.Core + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| PROFILE_A2DP_SOURCE | 0x0001 | A2DP profile.| +| PROFILE_HANDS_FREE_AUDIO_GATEWAY | 0x0004 | HFP profile.|