From 634ae1b38c6d4fbf2c8e37eaa62b48c0cc4a66b9 Mon Sep 17 00:00:00 2001 From: shawn_he Date: Mon, 20 Feb 2023 15:30:35 +0800 Subject: [PATCH] update doc Signed-off-by: shawn_he --- .../device/pointerstyle-guidelines.md | 8 +-- en/application-dev/dfx/hilog-guidelines.md | 47 ++++++++++++----- .../reference/apis/js-apis-battery-info.md | 51 ++++++++++--------- 3 files changed, 65 insertions(+), 41 deletions(-) diff --git a/en/application-dev/device/pointerstyle-guidelines.md b/en/application-dev/device/pointerstyle-guidelines.md index 06a904a5c5..cecab92b28 100644 --- a/en/application-dev/device/pointerstyle-guidelines.md +++ b/en/application-dev/device/pointerstyle-guidelines.md @@ -15,11 +15,11 @@ import pointer from '@ohos.multimodalInput.pointer'; The following table lists the common APIs for mouse pointer management. For details about the APIs, see [ohos.multimodalInput.pointer](../reference/apis/js-apis-pointer.md). | Instance | API | Description | -| ------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| pointer | function isPointerVisible(callback: AsyncCallback\): void; | Checks the visible status of the mouse pointer. | -| pointer | function setPointerVisible(visible: boolean, callback: AsyncCallback\): void; | Sets the visible status of the mouse pointer. This setting takes effect for the mouse pointer globally.| +| ------- | ------------------------------------------------------------ | --------------------------------------------------------------- | +| pointer | function isPointerVisible(callback: AsyncCallback\): void; | Checks the visible status of the mouse pointer. | +| pointer | function setPointerVisible(visible: boolean, callback: AsyncCallback\): void; | Sets the visible status of the mouse pointer. This setting takes effect for the mouse pointer globally. | | pointer | function setPointerStyle(windowId: number, pointerStyle: PointerStyle, callback: AsyncCallback\): void; | Sets the mouse pointer style. This setting takes effect for the mouse pointer style of a specified window. | -| pointer | function getPointerStyle(windowId: number, callback: AsyncCallback\): void; | Obtains the mouse pointer style. | +| pointer | function getPointerStyle(windowId: number, callback: AsyncCallback\): void; | Obtains the mouse pointer style. | ## Hiding the Mouse Pointer diff --git a/en/application-dev/dfx/hilog-guidelines.md b/en/application-dev/dfx/hilog-guidelines.md index f2a2fc7deb..79c0077592 100644 --- a/en/application-dev/dfx/hilog-guidelines.md +++ b/en/application-dev/dfx/hilog-guidelines.md @@ -1,37 +1,60 @@ -# HiLog Development -## Introduction +# HiLog Development +## Overview HiLog is the log system of OpenHarmony that provides logging for the system framework, services, and applications to record information on user operations and system running status. > **NOTE** -> This development guide is applicable only when you use Native APIs for application development. For details about the APIs, see [HiLog Native API Reference](https://gitee.com/openharmony-sig/interface_native_header/blob/master/en/native_sdk/dfx/log.h). +> This development guide is applicable only when you use Native APIs for application development. For details about the APIs, see [HiLog Native API Reference](../reference/native-apis/_hi_log.md). ## Available APIs | API/Macro| Description| | -------- | -------- | -| int OH_LOG_Print(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, ...) | Outputs logs based on the specified log type, log level, service domain, log tag, and variable parameters determined by the format specifier and privacy identifier in the printf format.| +| int OH_LOG_Print(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, ...) | Outputs logs based on the specified log type, log level, service domain, log tag, and variable parameters determined by the format specifier and privacy identifier in the printf format.
Input parameters: See [Parameter Description](#parameter-description).
Output parameters: None
Return value: total number of bytes if log printing is successful; **-1** otherwise.| | #define OH_LOG_DEBUG(type, ...) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, \_*VA*ARGS__))| Outputs DEBUG logs. This is a function-like macro.| | #define OH_LOG_INFO(type, ...) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, \_*VA*ARGS__)) | Outputs INFO logs. This is a function-like macro.| | #define OH_LOG_WARN(type, ...) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, \_*VA*ARGS__)) | Outputs WARN logs. This is a function-like macro.| | #define OH_LOG_ERROR(type, ...) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, \_*VA*ARGS__)) | Outputs ERROR logs. This is a function-like macro.| | #define OH_LOG_FATAL(type, ...) ((void)OH_LOG_Print((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, \_*VA*ARGS__)) | Outputs FATAL logs. This is a function-like macro.| -| bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level) | Checks whether logs of the specified service domain, tag, and level can be printed.
Input arguments:
- **domain**: service domain.
- **tag**: log tag.
- **level**: log level.
Output arguments: none
Return value: Returns **true** if the specified logs can be printed; returns **false** otherwise.| +| bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level) | Checks whether logs of the specified service domain, tag, and level can be printed.
Input parameters: See [Parameter Description](#parameter-description).
Output arguments: none
Return value: **true** if the specified logs can be printed; **false** otherwise.| +## Parameter Description +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| type | enum | Yes | Enum of log printing types. The default value is **LOG_APP** for application logs.| +| level | enum | Yes | Log printing level. For details, see [Log Level](#loglevel).| +| domain | number | Yes | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.
You can define the value as required. | +| tag | string | Yes | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method.| +| fmt | string | Yes | Format string used to output logs in a specified format. It can contain several parameters, where the parameter type and privacy identifier are mandatory.
Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\**.| +| args | any[] | Yes | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.| +## LogLevel +Log level. + +| Name | Value | Description | +| ----- | ------ | ------------------------------------------------------------ | +| DEBUG | 3 | Log level used to record more detailed process information than INFO logs to help developers analyze service processes and locate faults.| +| INFO | 4 | Log level used to record key service process nodes and exceptions that occur during service running,
Log level used to record information about unexpected exceptions, such as network signal loss and login failure.
These logs should be recorded by the dominant module in the service to avoid repeated logging conducted by multiple invoked modules or low-level functions.| +| WARN | 5 | Log level used to record severe, unexpected faults that have little impact on users and can be rectified by the programs themselves or through simple operations.| +| ERROR | 6 | Log level used to record program or functional errors that affect the normal running or use of the functionality and can be fixed at a high cost, for example, by resetting data.| +| FATAL | 7 | Log level used to record program or functionality crashes that cannot be rectified. ## Development Examples -1. Include the **hilog** header file in the source file. +1. Add the link of **libhilog_ndk.z.so** to **CMakeLists.txt**: +``` +target_link_libraries(entry PUBLIC libhilog_ndk.z.so) +``` +2. Include the **hilog** header file in the source file, and define the **domain** and **tag** macros. ```c++ #include "hilog/log.h" ``` -2. Define the **domain** and **tag** macros. + ```c++ #undef LOG_DOMAIN #undef LOG_TAG -#define LOG_DOMAIN 0x3200 // Service domain. The value ranges from 0xD0000 to 0xDFFFF. -#define LOG_TAG "MY_TAG" +#define LOG_DOMAIN 0x3200 // Global domain, which identifies the service domain. +#define LOG_TAG "MY_TAG" // Global tag, which identifies the module log tag. ``` -3. Print logs. For example, to print INFO logs, use the following code: +3. Print logs. For example, to print ERROR logs, use the following code: ```c++ -OH_LOG_INFO(LOG_APP, "Failed to visit %{private}s, reason:%{public}d.", url, errno); +OH_LOG_ERROR(LOG_APP, "Failed to visit %{private}s, reason:%{public}d.", url, errno); ``` 4. View the output log information. ``` -12-11 12:21:47.579 2695 2695 I A03200/MY_TAG: Failed to visit , reason:11. +12-11 12:21:47.579 2695 2695 E A03200/MY_TAG: Failed to visit , reason:11. ``` diff --git a/en/application-dev/reference/apis/js-apis-battery-info.md b/en/application-dev/reference/apis/js-apis-battery-info.md index 41d13ba574..6231cab500 100644 --- a/en/application-dev/reference/apis/js-apis-battery-info.md +++ b/en/application-dev/reference/apis/js-apis-battery-info.md @@ -2,9 +2,11 @@ The **batteryInfo** module provides APIs for querying the charger type, battery health status, and battery charging status. -> **NOTE**
+> **NOTE** +> > 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 ```js @@ -20,18 +22,18 @@ Describes battery information. | Name | Type | Readable| Writable| Description | | --------------- | ------------------- | ---- | ---- | ---------------------| | batterySOC | number | Yes | No | Battery state of charge (SoC) of the device, in unit of percentage. | -| chargingStatus | [BatteryChargeState](#batterychargestate) | Yes | No | Battery charging state of the device. | -| healthStatus | [BatteryHealthState](#batteryhealthstate) | Yes | No | Battery health state of the device. | +| chargingStatus | [BatteryChargeState](#batterychargestate) | Yes | No | Battery charging status of the device. | +| healthStatus | [BatteryHealthState](#batteryhealthstate) | Yes | No | Battery health status of the device. | | pluggedType | [BatteryPluggedType](#batterypluggedtype) | Yes | No | Charger type of the device. | | voltage | number | Yes | No | Battery voltage of the device, in unit of microvolt. | | technology | string | Yes | No | Battery technology of the device. | | batteryTemperature | number | Yes | No | Battery temperature of the device, in unit of 0.1°C. | | isBatteryPresent7+ | boolean | Yes | No | Whether the battery is supported or present. | | batteryCapacityLevel9+ | [BatteryCapacityLevel](#batterycapacitylevel9) | Yes | No | Battery level of the device. | -| estimatedRemainingChargeTime9+ | number | Yes | No | Estimated time for fully charging the current device, in unit of milliseconds. | -| totalEnergy9+ | number | Yes | No | Total battery capacity of the device, in unit of mAh. This is a system API. | -| nowCurrent9+ | number | Yes | No | Battery current of the device, in unit of mA. This is a system API. | -| remainingEnergy9+ | number | Yes | No | Remaining battery capacity of the device, in unit of mAh. This is a system API.| +| estimatedRemainingChargeTime9+ | number | Yes | No | Estimated time for fully charging the current device, in unit of milliseconds. **System API**: This is a system API. | +| totalEnergy9+ | number | Yes | No | Total battery capacity of the device, in unit of mAh. **System API**: This is a system API. | +| nowCurrent9+ | number | Yes | No | Battery current of the device, in unit of mA. **System API**: This is a system API. | +| remainingEnergy9+ | number | Yes | No | Remaining battery capacity of the device, in unit of mAh. **System API**: This is a system API.| ## BatteryPluggedType @@ -41,10 +43,10 @@ Enumerates charger types. | Name | Value | Description | | -------- | ---- | ----------------- | -| NONE | 0 | Unknown type | -| AC | 1 | AC charger| -| USB | 2 | USB charger | -| WIRELESS | 3 | Wireless charger| +| NONE | 0 | Unknown charger type. | +| AC | 1 | AC charger.| +| USB | 2 | USB charger. | +| WIRELESS | 3 | Wireless charger.| ## BatteryChargeState @@ -82,14 +84,15 @@ Enumerates battery levels. | Name | Value| Description | | -------------- | ------ | ---------------------------- | -| LEVEL_NONE | 0 | Unknown battery level. | | LEVEL_FULL | 1 | Full battery level. | | LEVEL_HIGH | 2 | High battery level. | | LEVEL_NORMAL | 3 | Normal battery level.| | LEVEL_LOW | 4 | Low battery level. | -| LEVEL_CRITICAL | 5 | Ultra-low battery level.| +| LEVEL_WARNING | 5 | Alarm battery level.| +| LEVEL_CRITICAL | 6 | Ultra-low battery level.| +| LEVEL_SHUTDOWN | 7 | Power-down battery level.| -## CommonEventBatteryChangedCode9+ +## CommonEventBatteryChangedKey9+ Enumerates keys for querying the additional information about the **COMMON_EVENT_BATTERY_CHANGED** event. @@ -97,14 +100,12 @@ Enumerates keys for querying the additional information about the **COMMON_EVENT | Name | Value| Description | | -------------------- | ------ | -------------------------------------------------- | -| EXTRA_SOC | 0 | Remaining battery level in percentage. | -| EXTRA_VOLTAGE | 1 | Battery voltage of the device. | -| EXTRA_TEMPERATURE | 2 | Battery temperature of the device. | -| EXTRA_HEALTH_STATE | 3 | Battery health status of the device. | -| EXTRA_PLUGGED_TYPE | 4 | Type of the charger connected to the device. | -| EXTRA_MAX_CURRENT | 5 | Maximum battery current of the device. | -| EXTRA_MAX_VOLTAGE | 6 | Maximum battery voltage of the device. | -| EXTRA_CHARGE_STATE | 7 | Battery charging status of the device. | -| EXTRA_CHARGE_COUNTER | 8 | Number of battery charging times of the device. | -| EXTRA_PRESENT | 9 | Whether the battery is supported by the device or installed.| -| EXTRA_TECHNOLOGY | 10 | Battery technology of the device. | +| EXTRA_SOC | "soc" | Remaining battery level in percentage. | +| EXTRA_CHARGE_STATE | "chargeState" | Battery charging status of the device. | +| EXTRA_HEALTH_STATE | "healthState" | Battery health status of the device. | +| EXTRA_PLUGGED_TYPE | "pluggedType" | Type of the charger connected to the device. | +| EXTRA_VOLTAGE | "voltage" | Battery voltage of the device. | +| EXTRA_TECHNOLOGY | "technology" | Battery technology of the device. | +| EXTRA_TEMPERATURE | "temperature" | Battery temperature of the device. | +| EXTRA_PRESENT | "present" | Whether the battery is supported by the device or installed.| +| EXTRA_CAPACITY_LEVEL | "capacityLevel" | Battery level of the device. | -- GitLab