diff --git a/en/application-dev/reference/apis/js-apis-bluetooth.md b/en/application-dev/reference/apis/js-apis-bluetooth.md index 8c2e4f41606e44f93d872427c2c81b1ecf70cb4f..1e280124850de1ccfa9658365d97c3219b1d5b2b 100644 --- a/en/application-dev/reference/apis/js-apis-bluetooth.md +++ b/en/application-dev/reference/apis/js-apis-bluetooth.md @@ -1,9 +1,9 @@ # Bluetooth -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> **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. + +Provides classic Bluetooth capabilities and Bluetooth Low Energy (BLE) scan and advertising. ## Modules to Import @@ -201,7 +201,7 @@ Obtains the connection state of a profile. | Name | Type | Mandatory | Description | | --------- | --------- | ---- | ------------------------------------- | -| ProfileId | profileId | Yes | ID of the target profile, for example, **PROFILE_A2DP_SOURCE**.| +| ProfileId | profileId | Yes | ID of the profile to obtain, for example, **PROFILE_A2DP_SOURCE**.| **Return value** @@ -212,7 +212,7 @@ Obtains the connection state of a profile. **Example** ```js -let result = bluetooth.getProfileConnState(PROFILE_A2DP_SOURCE); +let result = bluetooth.getProfileConnState(bluetooth.ProfileId.PROFILE_A2DP_SOURCE); ``` @@ -355,7 +355,7 @@ Sets the Bluetooth scan mode so that the device can be discovered by a remote de ```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); +let result = bluetooth.setBluetoothScanMode(bluetooth.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100); ``` @@ -720,7 +720,7 @@ bluetooth.off('stateChange', onReceiveEvent); ``` -## bluetooth.sppListen8+ +## bluetooth.sppListen8+ sppListen(name: string, option: SppOption, callback: AsyncCallback<number>): void @@ -773,6 +773,14 @@ Listens for a connection to be made to this socket from the client and accepts i **Example** ```js +let serverNumber = -1; +function serverSocket(code, number) { + console.log('bluetooth error code: ' + code.code); + if (code.code == 0) { + console.log('bluetooth serverSocket Number: ' + number); + serverNumber = number; + } +} let clientNumber = -1; function acceptClientSocket(code, number) { console.log('bluetooth error code: ' + code.code); @@ -807,6 +815,7 @@ Initiates an SPP connection to a remote device from the client. **Example** ```js + let clientNumber = -1; function clientSocket(code, number) { if (code.code != 0) { @@ -838,6 +847,14 @@ Closes the listening socket of the server. **Example** ```js +let serverNumber = -1; +function serverSocket(code, number) { + console.log('bluetooth error code: ' + code.code); + if (code.code == 0) { + console.log('bluetooth serverSocket Number: ' + number); + serverNumber = number; + } +} bluetooth.sppCloseServerSocket(serverNumber); ``` @@ -860,6 +877,15 @@ Closes the client socket. **Example** ```js +let clientNumber = -1; +function clientSocket(code, number) { + if (code.code != 0) { + return; + } + console.log('bluetooth serverSocket Number: ' + number); + // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. + clientNumber = number; +} bluetooth.sppCloseClientSocket(clientNumber); ``` @@ -888,6 +914,15 @@ Writes data to the remote device through the socket. **Example** ```js +let clientNumber = -1; +function clientSocket(code, number) { + if (code.code != 0) { + return; + } + console.log('bluetooth serverSocket Number: ' + number); + // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. + clientNumber = number; +} let arrayBuffer = new ArrayBuffer(8); let data = new Uint8Array(arrayBuffer); data[0] = 123; @@ -923,6 +958,15 @@ No value is returned. **Example** ```js +let clientNumber = -1; +function clientSocket(code, number) { + if (code.code != 0) { + return; + } + console.log('bluetooth serverSocket Number: ' + number); + // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. + clientNumber = number; +} function dataRead(dataBuffer) { let data = new Uint8Array(dataBuffer); console.log('bluetooth data is: ' + data[0]); @@ -954,6 +998,15 @@ No value is returned. **Example** ```js +let clientNumber = -1; +function clientSocket(code, number) { + if (code.code != 0) { + return; + } + console.log('bluetooth serverSocket Number: ' + number); + // The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client. + clientNumber = number; +} bluetooth.off('sppRead', clientNumber); ``` @@ -981,14 +1034,14 @@ Obtains a profile object. **Example** ```js -let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +let a2dpSrc = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_A2DP_SOURCE); ``` ## bluetooth.getProfile9+ getProfile(profileId: ProfileId): A2dpSourceProfile | HandsFreeAudioGatewayProfile | HidHostProfile -Obtains the profile object instance based on **ProfileId**. API version 9 is added with **HidHostProfile**. +Obtains a profile instance. **HidHostProfile** is added in API version 9. **System capability**: SystemCapability.Communication.Bluetooth.Core @@ -996,7 +1049,7 @@ Obtains the profile object instance based on **ProfileId**. API version 9 is add | Name | Type | Mandatory | Description | | --------- | --------- | ---- | ------------------------------------- | -| profileId | [ProfileId](#ProfileId) | Yes | ID of the target profile, for example, **PROFILE_A2DP_SOURCE**.| +| profileId | [ProfileId](#ProfileId) | Yes | ID of the profile to obtain, for example, **PROFILE_A2DP_SOURCE**.| **Return value** @@ -1007,7 +1060,7 @@ Obtains the profile object instance based on **ProfileId**. API version 9 is add **Example** ```js -let hidHost = bluetooth.getProfile(PROFILE_HID_HOST); +let hidHost = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_HID_HOST); ``` @@ -1239,7 +1292,7 @@ No value is returned. **Example** ```js -let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE) +let a2dpSrc = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_A2DP_SOURCE) let retArray = a2dpSrc.getConnectionDevices(); ``` @@ -1257,7 +1310,7 @@ Obtains the connection state of the profile. | Name | Type | Mandatory | Description | | ------ | ------ | ---- | ------- | -| device | string | Yes | Address of the remote device.| +| device | string | Yes | Address of the target device.| **Return value** @@ -1268,7 +1321,7 @@ Obtains the connection state of the profile. **Example** ```js -let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE) +let a2dpSrc = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_A2DP_SOURCE) let ret = a2dpSrc.getDeviceState('XX:XX:XX:XX:XX:XX'); ``` @@ -1277,7 +1330,7 @@ let ret = a2dpSrc.getDeviceState('XX:XX:XX:XX:XX:XX'); Before using a method of **A2dpSourceProfile**, you need to create an instance of this class by using the **getProfile()** method. -### connect8+ +### connect8+ connect(device: string): boolean @@ -1302,12 +1355,12 @@ Sets up an Advanced Audio Distribution Profile (A2DP) connection. **Example** ```js -let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE) +let a2dpSrc = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_A2DP_SOURCE) let ret = a2dpSrc.connect('XX:XX:XX:XX:XX:XX'); ``` -### disconnect8+ +### disconnect8+ disconnect(device: string): boolean @@ -1332,7 +1385,7 @@ Disconnects an A2DP connection. **Example** ```js -let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +let a2dpSrc = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_A2DP_SOURCE); let ret = a2dpSrc.disconnect('XX:XX:XX:XX:XX:XX'); ``` @@ -1362,7 +1415,7 @@ No value is returned. function onReceiveEvent(data) { console.info('a2dp state = '+ JSON.stringify(data)); } -let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +let a2dpSrc = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_A2DP_SOURCE); a2dpSrc.on('connectionStateChange', onReceiveEvent); ``` @@ -1392,7 +1445,7 @@ No value is returned. function onReceiveEvent(data) { console.info('a2dp state = '+ JSON.stringify(data)); } -let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +let a2dpSrc = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_A2DP_SOURCE); a2dpSrc.on('connectionStateChange', onReceiveEvent); a2dpSrc.off('connectionStateChange', onReceiveEvent); ``` @@ -1410,7 +1463,7 @@ Obtains the playing state of a device. | Name | Type | Mandatory | Description | | ------ | ------ | ---- | ------- | -| device | string | Yes | Address of the remote device.| +| device | string | Yes | Address of the target device.| **Return value** @@ -1421,7 +1474,7 @@ Obtains the playing state of a device. **Example** ```js -let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE); +let a2dpSrc = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_A2DP_SOURCE); let state = a2dpSrc.getPlayingState('XX:XX:XX:XX:XX:XX'); ``` @@ -1431,7 +1484,7 @@ let state = a2dpSrc.getPlayingState('XX:XX:XX:XX:XX:XX'); Before using a method of **HandsFreeAudioGatewayProfile**, you need to create an instance of this class by using the **getProfile()** method. -### connect8+ +### connect8+ connect(device: string): boolean @@ -1445,7 +1498,7 @@ Sets up a Hands-free Profile (HFP) connection of a device. | Name | Type | Mandatory | Description | | ------ | ------ | ---- | ------- | -| device | string | Yes | Address of the remote device.| +| device | string | Yes | Address of the target device.| **Return value** @@ -1456,12 +1509,12 @@ Sets up a Hands-free Profile (HFP) connection of a device. **Example** ```js -let hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY); +let hfpAg = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_HANDS_FREE_AUDIO_GATEWAY); let ret = hfpAg.connect('XX:XX:XX:XX:XX:XX'); ``` -### disconnect8+ +### disconnect8+ disconnect(device: string): boolean @@ -1475,7 +1528,7 @@ Disconnects the HFP connection of a device. | Name | Type | Mandatory | Description | | ------ | ------ | ---- | ------- | -| device | string | Yes | Address of the remote device.| +| device | string | Yes | Address of the target device.| **Return value** @@ -1486,7 +1539,7 @@ Disconnects the HFP connection of a device. **Example** ```js -let hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY); +let hfpAg = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_HANDS_FREE_AUDIO_GATEWAY); let ret = hfpAg.disconnect('XX:XX:XX:XX:XX:XX'); ``` @@ -1516,7 +1569,7 @@ No value is returned. function onReceiveEvent(data) { console.info('hfp state = '+ JSON.stringify(data)); } -let hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY); +let hfpAg = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_HANDS_FREE_AUDIO_GATEWAY); hfpAg.on('connectionStateChange', onReceiveEvent); ``` @@ -1546,7 +1599,7 @@ No value is returned. function onReceiveEvent(data) { console.info('hfp state = '+ JSON.stringify(data)); } -let hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY); +let hfpAg = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_HANDS_FREE_AUDIO_GATEWAY); hfpAg.on('connectionStateChange', onReceiveEvent); hfpAg.off('connectionStateChange', onReceiveEvent); ``` @@ -1573,7 +1626,7 @@ Connects to the HidHost service of a device. | Name | Type | Mandatory | Description | | ------ | ------ | ---- | ------- | -| device | string | Yes | Address of the remote device.| +| device | string | Yes | Address of the target device.| **Return value** @@ -1584,7 +1637,7 @@ Connects to the HidHost service of a device. **Example** ```js -let hidHostProfile = bluetooth.getProfile(PROFILE_HID_HOST); +let hidHostProfile = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_HID_HOST); let ret = hidHostProfile.connect('XX:XX:XX:XX:XX:XX'); ``` @@ -1605,7 +1658,7 @@ Disconnects from the HidHost service of a device. | Name | Type | Mandatory | Description | | ------ | ------ | ---- | ------- | -| device | string | Yes | Address of the remote device.| +| device | string | Yes | Address of the target device.| **Return value** @@ -1616,7 +1669,7 @@ Disconnects from the HidHost service of a device. **Example** ```js -let hidHostProfile = bluetooth.getProfile(PROFILE_HID_HOST); +let hidHostProfile = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_HID_HOST); let ret = hidHostProfile.disconnect('XX:XX:XX:XX:XX:XX'); ``` @@ -1646,7 +1699,7 @@ No value is returned. function onReceiveEvent(data) { console.info('hidHost state = '+ JSON.stringify(data)); } -let hidHost = bluetooth.getProfile(PROFILE_HID_HOST); +let hidHost = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_HID_HOST); hidHost.on('connectionStateChange', onReceiveEvent); ``` @@ -1676,7 +1729,7 @@ No value is returned. function onReceiveEvent(data) { console.info('hidHost state = '+ JSON.stringify(data)); } -let hidHost = bluetooth.getProfile(PROFILE_HID_HOST); +let hidHost = bluetooth.getProfile(bluetooth.ProfileId.PROFILE_HID_HOST); hidHost.on('connectionStateChange', onReceiveEvent); hidHost.off('connectionStateChange', onReceiveEvent); ``` @@ -1819,7 +1872,7 @@ cccV[0] = 1; let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; let characteristicN = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', - characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptorsN}; + characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; characteristics[0] = characteristic; // Create a gattService instance. @@ -1911,8 +1964,11 @@ Notifies the connected client device when a characteristic value changes. **Example** ```js +let arrayBufferC = new ArrayBuffer(8); +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; let notifyCharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', - characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: notifyCcc.characteristicValue, confirm: false}; + characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: characteristic.characteristicValue, confirm: false}; let server = bluetooth.BLE.createGattServer(); server.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacteristic); ``` @@ -2138,7 +2194,7 @@ Subscribes to the descriptor read request events. | 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. | +| callback | Callback<[DescriptorReadReq](#descriptorreadreq)> | Yes | Callback invoked to return a descriptor read request event from the GATT client. | **Return value** @@ -2279,7 +2335,6 @@ let gattServer = bluetooth.BLE.createGattServer(); gattServer.off("descriptorWrite"); ``` - ### on('connectStateChange') on(type: "connectStateChange", callback: Callback<BLEConnectChangedState>): void @@ -2488,7 +2543,7 @@ Obtains all services of the remote BLE device. This API uses a promise to return // Promise let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); device.connect(); -let services = device.getServices(); +var services = device.getServices(); console.log("bluetooth services size is ", services.length); for (let i = 0; i < services.length; i++) { @@ -2826,8 +2881,11 @@ Sets the function of notifying the GATT client when the characteristic value of **Example** ```js +let arrayBufferC = new ArrayBuffer(8); +let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', + characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX'); -device.setNotifyCharacteristicChanged(notifyCcc, false); +device.setNotifyCharacteristicChanged(characteristic, false); ``` @@ -3296,11 +3354,19 @@ Defines the scan filter parameters. **System capability**: SystemCapability.Communication.Bluetooth.Core -| Name | Type | Readable | Writable | Description | -| ----------- | ------ | ---- | ---- | ---------------------------------------- | -| 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**.| +| Name | Type | Readable| Writable| Description | +| ---------------------------------------- | ----------- | ---- | ---- | ------------------------------------------------------------ | +| 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 | Service UUID of the device to filter, for example, **00001888-0000-1000-8000-00805f9b34fb**.| +| serviceUuidMask9+ | string | Yes | Yes | Service UUID mask of the device to filter, for example, **FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF**.| +| serviceSolicitationUuid9+ | string | Yes | Yes | Service solicitation UUID of the device to filter, for example, **00001888-0000-1000-8000-00805F9B34FB**.| +| serviceSolicitationUuidMask9+ | string | Yes | Yes | Service solicitation UUID mask of the device to filter, for example, **FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF**.| +| serviceData9+ | ArrayBuffer | Yes | Yes | Service data of the device to filter, for example, **[0x90, 0x00, 0xF1, 0xF2]**.| +| serviceDataMask9+ | ArrayBuffer | Yes | Yes | Service data mask of the device to filter, for example, **[0xFF,0xFF,0xFF,0xFF]**.| +| manufacturerId9+ | number | Yes | Yes | Manufacturer ID of the device to filter, for example, **0x0006**. | +| manufactureData9+ | ArrayBuffer | Yes | Yes | Manufacturer data of the device to filter, for example, **[0x1F,0x2F,0x3F]**.| +| manufactureDataMask9+ | ArrayBuffer | Yes | Yes | Manufacturer data mask of the device to filter, for example, **[0xFF, 0xFF, 0xFF]**.| ## ScanOptions diff --git a/en/application-dev/reference/apis/js-apis-system-bluetooth.md b/en/application-dev/reference/apis/js-apis-system-bluetooth.md index 27223da59dd798215ff27a2a6bad0f49282097c9..9f2ef61d8465f220a97884f3097c43b203e07b80 100644 --- a/en/application-dev/reference/apis/js-apis-system-bluetooth.md +++ b/en/application-dev/reference/apis/js-apis-system-bluetooth.md @@ -1,7 +1,7 @@ # Bluetooth -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> **NOTE**
> > - The APIs of this module are no longer maintained since API version 7. You are advised to use [`@ohos.bluetooth`](js-apis-bluetooth.md). > @@ -15,7 +15,6 @@ import bluetooth from '@system.bluetooth'; ``` - ## bluetooth.startBLEScan(OBJECT) Scans for Bluetooth Low Energy (BLE) devices nearby. This operation consumes system resources. Call [bluetooth.stopBLEScan](#bluetoothstopblescanobject) to stop the scan after a BLE device is detected and connected. @@ -25,7 +24,6 @@ Scans for Bluetooth Low Energy (BLE) devices nearby. This operation consumes sys **System capability**: SystemCapability.Communication.Bluetooth.Lite **Parameters** - **Table 1** StartBLEScanOptions | Name| Type| Mandatory| Description| @@ -61,7 +59,6 @@ Stops scanning for BLE devices nearby. This API is used with [bluetooth.startBLE **System capability**: SystemCapability.Communication.Bluetooth.Lite **Parameters** - **Table 2** StopBLEScanOptions | Name| Type| Mandatory| Description| @@ -74,6 +71,7 @@ Stops scanning for BLE devices nearby. This API is used with [bluetooth.startBLE ``` bluetooth.stopBLEScan({ + interval:0, success() { console.log('call bluetooth.stopBLEScan success.'); }, @@ -96,7 +94,6 @@ Subscribes to the newly detected BLE device. If this API is called multiple time **System capability**: SystemCapability.Communication.Bluetooth.Lite **Parameters** - **Table 3** SubscribeBLEFoundOptions | Name| Type| Mandatory| Description| @@ -123,7 +120,7 @@ Subscribes to the newly detected BLE device. If this API is called multiple time **Example** ``` - bluetooth.startaBLEScan({ + bluetooth.startBLEScan({ success() { bluetooth.subscribeBLEFound({ success(data) {