From 570e13f76a529e50322050b96a9ddd70ef344b4b Mon Sep 17 00:00:00 2001 From: Annie_wang Date: Mon, 18 Apr 2022 19:37:19 +0800 Subject: [PATCH] update docs Signed-off-by: Annie_wang --- .../apis/js-apis-system-bluetooth.md | 169 ++++++++++++++++++ .../reference/apis/js-apis-system-storage.md | 59 +++--- 2 files changed, 199 insertions(+), 29 deletions(-) create mode 100644 en/application-dev/reference/apis/js-apis-system-bluetooth.md diff --git a/en/application-dev/reference/apis/js-apis-system-bluetooth.md b/en/application-dev/reference/apis/js-apis-system-bluetooth.md new file mode 100644 index 0000000000..b952a91eab --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-system-bluetooth.md @@ -0,0 +1,169 @@ +# Bluetooth + + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **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). +> +> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. + + +## Modules to Import + + +``` +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. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.Bluetooth.Lite + +**Parameters** +**Table 1** StartBLEScanOptions + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| interval | number | No| Interval for reporting device information, in milliseconds. The default value is **0**, which means to report the detected device immediately and report other information at the given interval.| +| success | Function | No| Called when the operation is successful.| +| fail | Function | No| Called when the operation fails.| +| complete | Function | No| Called when the execution is complete.| + +**Example** + + ``` + bluetooth.startBLEScan({ + success() { + console.log('call bluetooth.startBLEScan success.'); + }, + fail(code, data) { + console.log('call bluetooth.startBLEScan failed, code: ${code}, data: ${data}.'); + }, + complete() { + console.log('call bluetooth.startBLEScan complete.'); + } + }); + ``` + + +## bluetooth.stopBLEScan(OBJECT) + +Stops scanning for BLE devices nearby. This API is used with [bluetooth.startBLEScan(OBJECT)](#bluetoothstartblescanobject) in pairs. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.Bluetooth.Lite + +**Parameters** +**Table 2** StopBLEScanOptions + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| success | Function | No| Called when the operation is successful.| +| fail | Function | No| Called when the operation fails.| +| complete | Function | No| Called when the execution is complete.| + +**Example** + + ``` + bluetooth.stopBLEScan({ + success() { + console.log('call bluetooth.stopBLEScan success.'); + }, + fail(data, code) { + console.log('call bluethooth.stopBLEScan fail, code: ${code}, data: ${data}.'); + }, + complete() { + console.log('call bluethooth.stopBLEScan complete.'); + } + }); + ``` + + +## bluetooth.subscribeBLEFound(OBJECT) + +Subscribes to the newly detected BLE device. If this API is called multiple times, the last call takes effect. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.Bluetooth.Lite + +**Parameters** +**Table 3** SubscribeBLEFoundOptions + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| success | Function | Yes| Called to report the newly detected device.| +| fail | Function | No| Called when the operation fails.| + +**Table 4** Return value in success + +| Name| Type| Description| +| -------- | -------- | -------- | +| devices | Array<BluetoothDevice> | List of the newly detected BLE devices.| + +**Table 5** BluethoothDevice + +| Name| Type| Description| +| -------- | -------- | -------- | +| addrType | string | Device address type, which can be:
- **public**: a public address
- **random**: a random address| +| addr | string | MAC address of the device.| +| rssi | number | Received signal strength indicator (RSSl) of the device.| +| txpower | string | **txpower** field in the Bluetooth advertising data.| +| data | hex string | Bluetooth advertising data (including advertising data and scan response data), in a hexadecimal string.| + +**Example** + + ``` + bluetooth.startaBLEScan({ + success() { + bluetooth.subscribeBLEFound({ + success(data) { + const [device] = data.devices; + if (!!device) { + bluetooth.stopBLEScan(); + } + } + }); + }, + fail(code, data) { + console.log('Failed to start BLE device scan, code: ${code}, data: ${data}'); + } + }); + ``` + + +## bluetooth.unsubscribeBLEFound() + +Unsubscribes from the newly detected devices. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.Bluetooth.Lite + +**Example** + + ``` + bluetooth.unsubscribeBLEFound(); + ``` + + +## Common Error Codes + +| Error Code| Description| +| -------- | -------- | +| 1100 | The Bluetooth adapter is not initialized.| +| 1101 | The Bluetooth adapter is unavailable.| +| 1102 | The specified device is not found.| +| 1103 | Connection failed.| +| 1104 | The specified service is not found.| +| 1105 | The specified characteristic value is not found.| +| 1106 | The Bluetooth device is disconnected.| +| 1107 | The characteristic value does not support this operation.| +| 1108 | Other exceptions reported by the system.| +| 1109 | The system version does not support BLE.| diff --git a/en/application-dev/reference/apis/js-apis-system-storage.md b/en/application-dev/reference/apis/js-apis-system-storage.md index 2440183d41..038558c55e 100644 --- a/en/application-dev/reference/apis/js-apis-system-storage.md +++ b/en/application-dev/reference/apis/js-apis-system-storage.md @@ -1,8 +1,9 @@ # Data Storage -> ![icon-note.gif](public_sys-resources/icon-note.gif) **Noteļ¼š** -> - The APIs of this module are no longer maintained since API version 6. It is recommended that you use [`@ohos.data.storage`](js-apis-data-storage.md) instead. -> +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> +> - The APIs of this module are no longer maintained since API Version 6. You are advised to use [`@ohos.data.storage`](js-apis-data-storage.md). From API Version 9, you are advised to use [`@ohos.data.preferences`](js-apis-data-preferences.md). +> > - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -18,19 +19,19 @@ import storage from '@system.storage'; get(Object): void -Reads the stored content. +Obtains the stored data. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| key | string | Yes | Content index. | -| default | string | No | Default value returned when the **key** does not exist. | -| success | Function | No | Called when the stored content is successfully read. | -| fail | Function | No | Called when the stored content fails to be read. | -| complete | Function | No | Called when the execution is complete. | +| key | string | Yes| Index of the data to obtain.| +| default | string | No| Default value returned when the **key** does not exist.| +| success | Function | No| Called when the stored data is successfully obtained.| +| fail | Function | No| Called when the stored data failed to be obtained.| +| complete | Function | No| Called when the execution is complete.| **Example** @@ -58,19 +59,19 @@ export default { set(Object): void -Modifies the stored content. +Modifies the stored data. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| key | string | Yes | Index of the stored content to be modified. | -| value | string | No | Target storage content. The maximum number of characters allowed is 128. | -| success | Function | No | Called when the stored content is modified successfully. | -| fail | Function | No | Called when the stored content fails to be modified. | -| complete | Function | No | Called when the execution is complete. | +| key | string | Yes| Index of the data to modify.| +| value | string | No| New value to set. The maximum length is 128 bytes.| +| success | Function | No| Called when the data is successfully modified.| +| fail | Function | No| Called when the data failed to be modified.| +| complete | Function | No| Called when the execution is complete.| **Example** @@ -96,17 +97,17 @@ export default { clear(Object): void -Clears the stored content. +Clears the stored data. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| success | Function | No | Called when the stored content is cleared successfully | -| fail | Function | No | Called when the stored content fails to be cleared | -| complete | Function | No | Called when the execution is complete | +| success | Function | No| Called when the data is successfully cleared.| +| fail | Function | No| Called when the data failed to be cleared.| +| complete | Function | No| Called when the execution is complete.| **Example** @@ -130,18 +131,18 @@ export default { delete(Object): void -Deletes the stored content. +Deletes the stored data. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| key | string | Yes | Content index. | -| success | Function | No | Called when the stored content is deleted successfully. | -| fail | Function | No | Called when the stored content fails to be deleted. | -| complete | Function | No | Called when the execution is complete. | +| key | string | Yes| Index of the data to delete.| +| success | Function | No| Called when the data is deleted.| +| fail | Function | No| Called when the data failed to be deleted.| +| complete | Function | No| Called when the execution is complete.| **Example** @@ -159,4 +160,4 @@ export default { }); } } -``` \ No newline at end of file +``` -- GitLab