1# HiSysEvent Listening<a name="EN-US_TOPIC_0000001185655868"></a> 2 3## Overview<a name="section315316685112"></a> 4 5### Introduction<a name="section123181433335224"></a> 6 7HiSysEvent 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. 8 9### Constraints<a name="section123181433375224"></a> 10 11Before subscribing to system events, you need to configure HiSysEvent logging. For details, see [HiSysEvent Logging Configuration](subsys-dfx-hisysevent-logging-config.md). 12 13## Development Guidelines<a name="section315316685113"></a> 14 15### Available APIs<a name="section0342191810519"></a> 16 17**Table 1** Description of EventListener APIs 18 19| Name| Description | 20| -------- | --------- | 21|bool 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**: Repeated registration is successful. </li><li>**1**: Initial registration is successful. </li><li>Other values: Registration has failed.</li></ul>| 22|bool 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:<br>None.| 23 24**Table 2** Description of ListenerRule 25 26| API| Description | 27| -------- | --------- | 28|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>| 29|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>| 30|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>| 31 32**Table 3** Description of RuleType 33 34| Value | Description | 35| ------------ | ------------- | 36| WHOLE_WORD | Whole word matching | 37| PREFIX | Prefix matching | 38| REGULAR | Regular expression matching | 39 40**Table 4** Description of HiSysEventSubscribeCallBack 41 42| API| Description | 43| -------- | --------- | 44|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.| 45 46### Development Example<a name="section123181432175110"></a> 47 48C++ 49 501. Develop the source code. 51 52 Import the **DemoListener.h** header file, which contains the **DemoListener** class for implementing the custom event callback. 53 54 ``` 55 #ifndef DEMO_LISTENER_H 56 #define DEMO_LISTENER_H 57 58 #include "hisysevent_subscribe_callback.h" 59 60 #include <string> 61 62 class DemoListener : public OHOS::HiviewDFX::HiSysEventSubscribeCallBack { 63 public: 64 explicit DemoListener() : HiSysEventSubscribeCallBack() {} 65 void OnHandle(const std::string& domain, const std::string& eventName, const int eventType, 66 const std::string& eventDetail); 67 virtual ~DemoListener() {} 68 void OnServiceDied(); 69 }; 70 71 #endif // DEMO_LISTENER_H 72 ``` 73 74 Create the **DemoListener.cpp** file, and add the implementation logic of the custom event callback API in the **DemoListener** class. 75 76 ``` 77 #include "demo_listener.h" 78 79 #include <iostream> 80 81 void DemoListener::OnHandle(const std::string& domain, const std::string& eventName, 82 const int eventType, const std::string& eventDetail) 83 { 84 std::cout << eventDetail << std::endl; 85 } 86 87 void DemoListener::OnServiceDied() 88 { 89 std::cout << std::string("service disconnect, exit") << std::endl; 90 exit(0); 91 } 92 ``` 93 94 Call the **AddEventListener** API of the **HiSysEventManager** class to add a listener for system events. 95 96 ``` 97 std::shared_ptr<DemoListener> demoListener = nullptr; 98 try { 99 demoListener = std::make_shared<DemoListener>(); 100 } catch(...) { 101 // Catch exception thrown by make_shared 102 } 103 if (demoListener != nullptr) { 104 // Add a ListenerRule object based on the event tag, with RuleType left unspecified (in this case, ruleType is defaulted to WHOLE_WORD). 105 ListenerRule tagRule("dfx"); 106 // Add a ListenerRule object based on the event tag, with RuleType set as REGULAR. 107 ListenerRule regRule("dfx.*", RuleType::REGULAR); 108 // Add a ListenerRule object based on the event domain and event name, with RuleType set as PREFIX. 109 ListenerRule domainNameRule("HIVIEWDFX", "APP_USAGE", RuleType::PREFIX); 110 std::vector<ListenerRule> sysRules; 111 sysRules.push_back(tagRule); 112 sysRules.push_back(regRule); 113 sysRules.push_back(domainNameRule); 114 HiSysEventManager::AddEventListener(demoListener, sysRules); 115 } 116 ``` 117 1182. Configure the **BUILD.gn** file. 119 120 In the **BUILD.gn** file, add the **libhisyseventmanager** library that depends on the **hisysevent\_native** component. 121 122 ``` 123 external_deps = [ "hisysevent_native:libhisyseventmanager", ] 124 ``` 125