This module provides system-related or enhanced I18N capabilities, such as locale management, phone number formatting, and calendar, through supplementary I18N APIs that are not defined in ECMA 402.
The [Intl](js-apis-intl.md) module provides basic I18N capabilities through the standard I18N APIs defined in ECMA 402. It works with the I18N module to provide a complete suite of I18N capabilities.
> **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.
>
> - This module provides system-related or enhanced I18N capabilities, such as locale management, phone number formatting, and calendar, through supplementary I18N interfaces that are not defined in ECMA 402. For details about the basic I18N capabilities, see [Intl](js-apis-intl.md).
> 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 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.
>
> - This module provides basic I18N capabilities, such as time and date formatting, number formatting, and string sorting, through the standard I18N interfaces defined in ECMA 402. For details about the enhanced I18N capabilities, see [I18N](js-apis-i18n.md).
This module provides basic I18N capabilities, such as time and date formatting, number formatting, and string sorting, through the standard I18N APIs defined in ECMA 402.
The [I18N](js-apis-i18n.md) module provides enhanced I18N capabilities through supplementary APIs that are not defined in ECMA 402. It works with the Intl module to provide a complete suite of I18N capabilities.
> **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.
HiSysEvent supports listening for events across processes. You can register a listener to listen for concerned events on a real-time basis. For example, you can enable the battery module to listen for power consumption events for power usage analysis.
Before subscribing to system events, you need to configure HiSysEvent logging. For details, see [HiSysEvent Logging Configuration](subsys-dfx-hisysevent-logging-config.md).
## Development Guidelines<a name="section315316685113"></a>
### Available APIs<a name="section0342191810519"></a>
**Table 1** Description of EventListener APIs
| Name| Description |
| -------- | --------- |
|int32_t HiSysEventManager::AddEventListener(std::shared_ptr<HiSysEventSubscribeCallBack> listener, std::vector<ListenerRule>& rules)|Registers a listener for system events. You can listen for certain events by specifying rules.<br><br>Input arguments: <ul><li>**listener**: callback object for system events. </li><li>**rules**: rules for event listening. </li></ul>Return value:<ul><li>**0**: registration is successful. </li><li>Other values: Registration has failed.</li></ul>|
|int32_t HiSysEventManager::RemoveListener(std::shared_ptr<HiSysEventSubscribeCallBack> listener)|Removes the listener for system events.<br><br>Input arguments: <ul><li>**listener**: callback object for system events. </ul>Return value:<ul><li>**0**: Cancel registration is successful. </li><li>Other values: Cancel registration has failed.</li></ul>|
### Introduction
**Table 2** Description of ListenerRule
| API| Description |
| -------- | --------- |
|ListenerRule(const std::string& tag, RuleType ruleType = RuleType::WHOLE_WORD)|Constructor used to create a **ListenerRule** object based on the event tag.<br><br>Input arguments:<ul><li>**tag**: indicates the event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits. </li><li>**ruleType**: indicates the type of the **ListenerRule** object. The value is an enum defined by **RuleType**.</li></ul>|
|ListenerRule(const std::string& domain, const std::string& eventName, RuleType ruleType = RuleType::WHOLE_WORD)|Constructor used to create a **ListenerRule** object based on the event domain and event name.<br><br>Input arguments: <ul><li>**domain**: indicates the event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores (_). </li><li>**eventName**: indicates the event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores (_). </li><li>**ruleType**: indicates the type of the **ListenerRule** object. The value is an enum defined by **RuleType**.</li></ul>|
|ListenerRule(const std::string& domain, const std::string& eventName, const std::string& tag, RuleType ruleType = RuleType::WHOLE_WORD)|Constructor used to create a **ListenerRule** object based on the event domain, event name, and event tag.<br><br>Input arguments:<ul><li>**tag**: indicates the event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits. </li><li>**domain**: indicates the event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores (_). </li><li>**eventName**: indicates the event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores (_). </li><li>**ruleType**: indicates the type of the **ListenerRule** object. The value is an enum defined by **RuleType**.</li></ul>|
**Table 3** Description of RuleType
| Value | Description |
| ------------ | ------------- |
| WHOLE_WORD | Whole word matching |
| PREFIX | Prefix matching |
| REGULAR | Regular expression matching |
**Table 4** Description of HiSysEventSubscribeCallBack
| API| Description |
| -------- | --------- |
|void HiSysEventSubscribeCallBack::OnHandle(const std::string& domain, const std::string& eventName, const int eventType, const std::string& eventDetail)|Provides the callback of system events.<br><br>Input arguments: <ul><li>**domain**: indicates the domain to which the event belongs. </li><li>**eventName**: indicates the event name. </li><li>**eventType**: indicates the event type. </li><li>**eventDetail**: indicates the event information, in JSON format. </li></ul>Return value:<br>None.|
HiSysEvent supports listening for events across processes. You can register a listener to listen for concerned events on a real-time basis. For example, you can enable the battery module to listen for power consumption events for power usage analysis.
### Development Example<a name="section123181432175110"></a>
C++
### Constraints
1. Develop the source code.
Before subscribing to system events, you need to configure HiSysEvent logging. For details, see [HiSysEvent Logging Configuration](../subsystems/subsys-dfx-hisysevent-logging-config.md).
Import the **DemoListener.h** header file, which contains the **DemoListener** class for implementing the custom event callback.
```
#ifndef DEMO_LISTENER_H
#define DEMO_LISTENER_H
## Development Guidelines
#include "hisysevent_subscribe_callback.h"
#include <string>
### Available APIs
class DemoListener : public OHOS::HiviewDFX::HiSysEventSubscribeCallBack {
void OnHandle(const std::string& domain, const std::string& eventName, const int eventType,
const std::string& eventDetail);
virtual ~DemoListener() {}
void OnServiceDied();
};
**Table 1** Description of HiSysEventListener APIs
#endif // DEMO_LISTENER_H
```
| API| Description|
| -------- | -------- |
| int32_t HiSysEventManager::AddListener(std::shared_ptr<HiSysEventListener> listener, std::vector<ListenerRule>& rules) | Registers a listener for system events. You can listen for certain events by specifying rules.<br>Input arguments:<br>- **listener**: callback object for system events.<br>- **rules**: rules for event listening.<br>Return value:<br>- **0**: Registration is successful.<br>- A negative value: Registration has failed.|
| int32_t HiSysEventManager::RemoveListener(std::shared_ptr<HiSysEventListener> listener) | Removes the listener for system events.<br>Input arguments:<br>- **listener**: callback object for system events.<br>Return value:<br>- **0**: Canceling registration is successful.<br>- A negative value: Canceling registration has failed. |
Create the **DemoListener.cpp** file, and add the implementation logic of the custom event callback API in the **DemoListener** class.
**Table 2** Description of ListenerRule
```
#include "demo_listener.h"
| API| Description|
| -------- | -------- |
| ListenerRule(const std::string& tag, RuleType ruleType = RuleType::WHOLE_WORD) | Constructor used to create a **ListenerRule** object based on the event tag.<br>Input arguments:<br>- **tag**: event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits.<br>- **ruleType**: type of the **ListenerRule** object. The value is an enum defined by **RuleType**.|
| ListenerRule(const std::string& domain, const std::string& eventName, RuleType ruleType = RuleType::WHOLE_WORD) | Constructor used to create a **ListenerRule** object based on the event domain and event name.<br>Input arguments:<br>- **domain**: event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores.<br>- **eventName**: event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores.<br>- **ruleType**: type of the **ListenerRule** object. The value is an enum defined by **RuleType**.|
| ListenerRule(const std::string& domain, const std::string& eventName, const std::string& tag, RuleType ruleType = RuleType::WHOLE_WORD) | Constructor used to create a **ListenerRule** object based on the event domain, event name, and event tag.<br>Input arguments:<br>- **tag**: event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits.<br>- **domain**: event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores.<br>- **eventName**: event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores.<br>- **ruleType**: type of the **ListenerRule** object. The value is an enum defined by **RuleType**.|
|std::string HiSysEventRecord::AsJson()|Obtains the content of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Content of the system event.|
|std::string HiSysEventRecord::GetDomain()|Obtains the domain name of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Domain name of the system event.|
|std::string HiSysEventRecord::GetEventName()|Obtains the name of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Name of the system event.|
|HiSysEvent::EventType HiSysEventRecord::GetEventType()|Obtains the type of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Type of the system event.|
|std::string HiSysEventRecord::GetLevel()|Obtains the level of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Level of the system event.|
|std::string HiSysEventRecord::GetTag()|Obtains the tag of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Tag of the system event.|
|std::string HiSysEventRecord::GetTimeZone()|Obtains the time zone of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Time zone, in the format of **+0800**.|
|int HiSysEventRecord::GetTraceFlag()|Obtains the distributed call chain tracing flag of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Distributed call chain tracing flag.|
|int64_t HiSysEventRecord::GetPid()|Obtains the ID of the process that flushes a system event to the disk.<br>Input arguments:<br>None.<br>Return value:<br>Process ID.|
|int64_t HiSysEventRecord::GetTid()|Obtains the thread ID of the process that flushes a system event to the disk.<br>Input arguments:<br>None.<br>Return value:<br>Thread ID.|
|int64_t HiSysEventRecord::GetUid()|Obtains the user ID of the process that flushes a system event to the disk.<br>Input arguments:<br>None.<br>Return value:<br>User ID.|
|uint64_t HiSysEventRecord::GetPspanId()|Obtains the parent span ID of the distributed call chain tracing task.<br>Input arguments:<br>None.<br>Return value:<br>Parent span ID of the distributed call chain tracing task.|
|uint64_t HiSysEventRecord::GetSpandId()|Obtains the span ID of the distributed call chain tracing task.<br>Input arguments:<br>None.<br>Return value:<br>Span ID of the distributed call chain tracing task.|
|uint64_t HiSysEventRecord::GetTime()|Obtains the timestamp of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Timestamp of the system event.|
|uint64_t HiSysEventRecord::GetTraceId()|Obtains the ID of the distributed call chain tracing task.<br>Input arguments:<br>None.<br>Return value:<br>ID of the distributed call chain tracing task.|
|void HiSysEventRecord::GetParamNames(std::vector<std::string>& params)|Obtains all key names of a system event.<br>Input arguments:<br>- **params**: key name array reference.<br>Return value:<br>None.|
|int HiSysEventRecord::GetParamValue(const std::string& param, int64_t& value)|Parses the value of the **param** key in a system event into an int64\_t value.<br>Input arguments:<br>- **param**: key name.<br>- **value**: int64\_t reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, uint64_t& value)|Parses the value of the **param** key in a system event into a uint64\_t value.<br>Input arguments:<br>- **param**: key name.<br>- **value**: uint64\_t reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, double& value)|Parses the value of the **param** key in a system event into a double value.<br>Input arguments:<br>- **param**: key name.<br>- **value**: double reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::string& value)|Parses the value of the **param** key in a system event into a string value.<br>Input arguments:<br>- **param**: key name.<br>- **value**: std::string reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<int64_t>& value)|Parses the value of the **param** key in a system event into an int64\_t array.<br>Input arguments:<br>- **param**: key name.<br>- **value**: int64\_t array reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<uint64_t>& value)|Parses the value of the **param** key in a system event into a uint64\_t array.<br>Input arguments:<br>- **param**: key name.<br>- **value**: uint64\_t array reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<double>& value)|Parses the value of the **param** key in a system event into a double array.<br>Input arguments:<br>- **param**: key name.<br>- **value**: double array reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.|
|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<std::string>& value)|Parses the value of the **param** key in a system event into a string array.<br>Input arguments:<br>- **param**: key name.<br>- **value**: std::string array reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.|
## How to Develop
### **C++**
The following provides an example of how to use C++ APIs of **HiSysEvent**.
1. Develop the source code.
Import the **DemoListener.h** header file, which contains the **DemoListener** class for implementing the custom event callback.
```
#ifndef DEMO_LISTENER_H
#define DEMO_LISTENER_H
#include "hisysevent_listener.h"
#include <string>
class DemoListener : public OHOS::HiviewDFX::HiSysEventListener {
HiSysEvent provides an API for you to query system events. You can query concerned events by specifying search criteria. For example, for a power consumption module, you can query required system events for analysis.
## Overview
## Development Guidelines<a name="section315316761113"></a>
HiSysEvent allows you to query system events by specifying search criteria. For example, for a power consumption module, you can query required system events for analysis.
### Available APIs<a name="section03869128521"></a>
**Table 1** Description of the HiSysEvent query API
## Development Guidelines
| Name| Description |
| -------- | --------- |
| int32_t HiSysEventManager::QueryHiSysEvent(struct QueryArg& queryArg, std::vector<QueryRule>& queryRules, std::shared_ptr<HiSysEventQueryCallBack> queryCallBack) | Queries system events by specifying search criteria such as the time segment, event domain, and event name.<br><br>Input arguments:<ul><li>**queryArg**: event query parameter. </li><li>**queryRules**: event filtering rules. </li><li>**queryRules**: callback object for query results. </li></ul>Return value:<ul><li>**0**: The query is successful. </li><li>Other values: The query has failed.</li></ul> |
> For details about the **HiSysEventRecord** argument in the **OnQuery()** method of **HiSysEventQueryCallback**, see Table 5 in [HiSysEvent Listening](subsys-dfx-hisysevent-listening.md).
| Attribute| Description |
| -------- | --------- |
| beginTime | Start time, in the **long long int** format.|
| endTime | End time, in the **long long int** format.|
| maxEvents | Maximum number of returned events, in the **int** format.|
**Table 3** Description of QueryRule
| API| Description |
| -------- | --------- |
| QueryRule(const std::string& domain, const std::vector<std::string>& eventList) | Constructor used to create a **QueryRule** object.<br><br>Input arguments:<ul><li>**domain: domain to which the event of the **QueryRule** object belongs, in the **string** format. By default, an empty string indicates that the domain is successfully matched. </li><li>**eventList**: event name list, in the **std::vector<std::string>** format. By default, an empty string indicates that the event names on the list are successfully matched.</li></ul> |
**Table 4** Description of HiSysEventQueryCallBack
| void HiSysEventQueryCallBack::OnComplete(int32_t reason, int32_t total) | Callback object for completion of event query.<br><br>Input arguments:<ul><li>**reason**: reason for completion of event query. The default value is **0**. </li><li>**total**: total number of events returned in this query. </li></ul>Return value:<br>None.|
### Development Example<a name="section14286111855212"></a>
C++
1. Develop the source code.
- Import the corresponding header file:
**Table 1** Description of the HiSysEvent query API
hisysevent\_manager.h
| API| Description|
| -------- | -------- |
| int32_t HiSysEventManager::Query(struct QueryArg& arg, std::vector<QueryRule>& rules, std::shared_ptr<HiSysEventQueryCallback> callback) | Queries system events by specifying search criteria such as the time segment, event domain, and event name.<br>Input arguments:<br>- **arg**: event query parameter.<br>- **rules**: rules for event filtering.<br>- **callback**: callback object for event query.<br>Return value:<br>- **0**: Query is successful.<br>- A negative value: Query has failed.|
| QueryRule(const std::string& domain, const std::vector<std::string>& eventList) | Constructor used to create a **QueryRule** object.<br>Input arguments:<br>- **domain**: domain to which the event of the **QueryRule** object belongs, in the string format. By default, an empty string indicates that the domain is successfully matched.<br>- **eventList**: event name list, in the **std::vector<std::string>** format. By default, an empty string indicates that the event names on the list are successfully matched.|
**Table 4** Description of HiSysEventQueryCallback
| void HiSysEventQueryCallback::OnComplete(int32_t reason, int32_t total) | Callback object for completion of event query.<br>Input arguments:<br>- **reason**: reason for completion of event query. The default value is **0**.<br>- **total**: total number of events returned in this query.<br>Return value:<br>None.|
@@ -17,7 +17,7 @@ The HiSysEvent tool is a command line tool preconfigured in the **/system/bin**
| Option| Description|
| -------- | -------- |
| -r | Subscribes to real-time system events based on the default settings. When this option is specified, any real-time system event will be printed on the console.|
| -r | Subscription to real-time system events based on the default settings. When this option is specified, any real-time system event will be printed on the console.|
- Command for enabling the debugging mode:
...
...
@@ -29,7 +29,7 @@ The HiSysEvent tool is a command line tool preconfigured in the **/system/bin**
| Option| Description|
| -------- | -------- |
| -d | Subscribes to real-time system events in debugging mode.|
| -d | Subscription to real-time system events in debugging mode.|
- Command for subscribing to real-time system events by event tag:
...
...
@@ -96,7 +96,7 @@ The HiSysEvent tool is a command line tool preconfigured in the **/system/bin**
| Option| Description|
| -------- | -------- |
| -l | Queries historical system events based on the default settings. A maximum of 1,000 latest system events will be returned.|
| -l | Query of historical system events based on the default settings. A maximum of 10,000 system events will be returned.|
- Command for querying historical system events within the specified period of time:
...
...
@@ -130,7 +130,7 @@ The HiSysEvent tool is a command line tool preconfigured in the **/system/bin**
| Option| Description|
| -------- | -------- |
| -m | Maximum number of historical system events that can be queried. The value ranges from **0** to **1000**. The number of returned system events is not more than the value of this parameter.|
| -m | Maximum number of historical system events that can be queried. The number of returned system events is not more than the value of this parameter.|
Example:
...
...
@@ -151,7 +151,7 @@ The HiSysEvent tool is a command line tool preconfigured in the **/system/bin**
| Option| Description|
| -------- | -------- |
| -v | Used with the subscription command **-r** and query command **-l**. If system event validity check is enabled, invalid content contained in system events will be highlighted in red.|
| -v | Used with the **-r** and **-l** commands. If system event validity check is enabled, invalid content contained in system events will be highlighted in red.|
