HiSysEvent Listening

Overview

Function Introduction

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 subscribe to power consumption events for power usage analysis.

Constraints

Before listening for system events, you need to configure HiSysEvent logging. For details, see HiSysEvent Logging Configuration.

How to Develop

Available APIs

C++ APIs

HiSysEvent is implemented using the APIs provided by the HiSysEventManager class. For details, see the API Header Files.

NOTE

For details about the RuleType argument in the constructor of ListenerRule, see Table 4 in HiSysEvent Query.

Table 1 Description of C++ HiSysEventManager APIs

Table 2 Description of ListenerRule

Table 3 Description of HiSysEventListener

Table 4 Description of HiSysEventRecord

C APIs

HiSysEvent listening is implemented using the API provided in the following table. For details, see the API Header Files.

NOTE

For details about the HiSysEventRecord argument in the OnEvent callback of HiSysEventWatcher, see Table 11 and Table 12 in HiSysEvent Query.

Table 5 Description of C HiSysEventManager APIs

Table 6 Description of the HiSysEventWatcher structure

Table 7 Description of the HiSysEventWatchRule structure

How to Develop

C++ HiSysEvent Listening

1. Import the corresponding header file.

   #include "hisysevent_manager.h"
   

2. Implement the callback API for the service domain.

   class TestListener : public OHOS::HiviewDFX::HiSysEventListener {
   public:
       void OnEvent(std::shared_ptr<HiSysEventRecord> record)
       {
           if (record == nullptr) {
               return;
           }
           std::cout << record->AsJson() << std::endl;
       }
   
       void OnServiceDied()
       {
           std::cout << std::string("service disconnect, exit") << std::endl;
           exit(0);
       }
   };
   

3. Call the listening API while passing in parameters such as listener and rules. When the service ends, disable event listening.

   auto testListener = std::make_shared<TestListener>();
   // Add a ListenerRule object based on the event tag, with RuleType left unspecified (in this case, ruleType is defaulted to WHOLE_WORD).
   ListenerRule tagRule("dfx");
   // Add a ListenerRule object based on the event tag, with RuleType set as REGULAR.
   ListenerRule regRule("dfx.*", RuleType::REGULAR);
   // Add a ListenerRule object based on the event domain and event name, with RuleType set as PREFIX.
   ListenerRule domainNameRule("HIVIEWDFX", "APP_USAGE", RuleType::PREFIX);
   std::vector<ListenerRule> sysRules;
   sysRules.push_back(tagRule);
   sysRules.push_back(regRule);
   sysRules.push_back(domainNameRule);
   // Start event listening.
   auto ret = HiSysEventManager::AddListener(testListener, sysRules);
   // Remove the listener when the service ends.
   if (ret == 0) {
      HiSysEventManager::RemoveListener(testListener);
   }
   

C HiSysEvent Listening

1. Import the corresponding header file.

   #include "hisysevent_manager_c.h"
   

2. Implement the callback API for the service domain.

   void OnEventTest(HiSysEventRecord record)
   {
       printf("OnEventTest: event=%s", record.jsonStr);
   }
   
   void OnServiceDiedTest()
   {
       printf("OnServiceDied");
   }
   

3. Call the listening API while passing in parameters such as watcher and rules. When the service ends, disable event listening.

   HiSysEventWatcher watcher;
   watcher.OnEvent = OnEventTest;
   watcher.OnServiceDied = OnServiceDiedTest;
   // Add a HiSysEventWatchRule object based on the event tag, with RuleType left unspecified (in this case, ruleType is defaulted to WHOLE_WORD).
   constexpr char DFX_TAG[] = "dfx";
   HiSysEventWatchRule tagRule;
   (void)strcpy_s(tagRule.tag, strlen(DFX_TAG) + 1, DFX_TAG);
   tagRule.ruleType = 1;
   tagRule.eventType = 0;
   // Add a HiSysEventWatchRule object based on the event tag, with RuleType set as REGULAR.
   constexpr char DFX_PATTERN_TAG[] = "dfx.*";
   HiSysEventWatchRule regRule;
   (void)strcpy_s(regRule.tag, strlen(DFX_PATTERN_TAG) + 1, DFX_PATTERN_TAG);
   regRule.ruleType = 3;
   regRule.eventType = 0;
   // Add a HiSysEventWatchRule object based on the event domain and event name, with RuleType set as PREFIX.
   constexpr char DOMAIN[] = "HIVIEWDFX";
   constexpr char NAME[] = "APP_USAGE";
   HiSysEventWatchRule domainNameRule;
   (void)strcpy_s(domainNameRule.domain, strlen(DOMAIN) + 1, DOMAIN);
   (void)strcpy_s(domainNameRule.name, strlen(NAME) + 1, NAME);
   domainNameRule.ruleType = 2;
   domainNameRule.eventType = 0;
   // Start event listening.
   HiSysEventWatchRule rules[] = {tagRule, regRule, domainNameRule};
   int ret = OH_HiSysEvent_Add_Watcher(&watcher, rules, sizeof(rules) / sizeof(HiSysEventWatchRule));
   // Remove the watcher when the service ends.
   if (ret == 0) {
       ret = OH_HiSysEvent_Remove_Watcher(&watcher);
   }
   

Development Examples

C++ HiSysEvent Listening

Suppose you want to enable listening for all events whose domain is HIVIEWDFX and name is PLUGIN_LOAD. The sample code is as follows:

1. Add the libhisysevent and libhisyseventmanager dependencies of the hisysevent component to the BUILD.gn file of the service module.

   external_deps = [
     "hisysevent:libhisysevent",
     "hisysevent:libhisyseventmanager",
   ]
   

2. Call the listening API in the TestEventListening() function. When the service ends, disable event listening.

   #include <iostream>
   
   #include "hisysevent_manager.h"
   
   using namespace OHOS::HiviewDFX;
   
   class TestListener : public HiSysEventQueryCallback {
   public:
       void OnEvent(std::shared_ptr<HiSysEventRecord> record)
       {
           if (record == nullptr) {
               return;
           }
           std::cout << record->AsJson() << std::endl;
       }
   
       void OnServiceDied()
       {
           std::cout << std::string("service disconnect, exit") << std::endl;
           exit(0);
       }
   };
   
   void TestEventListening()
   {
       auto testListener = std::make_shared<TestListener>();
       ListenerRule domainNameRule("HIVIEWDFX", "PLUGIN_LOAD", RuleType::WHOLE_WORD);
       std::vector<ListenerRule> sysRules;
       sysRules.push_back(domainNameRule);
       auto ret = HiSysEventManager::AddListener(testListener, sysRules);
       if (ret == 0) {
           HiSysEventManager::RemoveListener(testListener);
       }
   }
   

C HiSysEvent Listening

Suppose you want to enable listening for all events whose domain is HIVIEWDFX and name is PLUGIN_LOAD. The sample code is as follows:

1. Add the libhisysevent and libhisyseventmanager dependencies of the hisysevent component to the BUILD.gn file of the service module.

   external_deps = [ "hisysevent:libhisyseventmanager" ]
   
   // for strcpy_s
   deps = [ "//third_party/bounds_checking_function:libsec_shared" ]
   

2. Call the listening API in the TestEventListening() function. When the service ends, disable event listening.

   #include <securec.h>
   
   #include "hisysevent_manager_c.h"
   
   void OnEventTest(HiSysEventRecord record)
   {
       printf("OnEventTest: event=%s", record.jsonStr);
   }
   
   void OnServiceDiedTest()
   {
       printf("OnServiceDied");
   }
   
   void TestEventListening()
   {
       HiSysEventWatcher watcher;
       watcher.OnEvent = OnEventTest;
       watcher.OnServiceDied = OnServiceDiedTest;
       constexpr char DOMAIN[] = "HIVIEWDFX";
       constexpr char NAME[] = "PLUGIN_LOAD";
       HiSysEventWatchRule domainNameRule;
       (void)strcpy_s(domainNameRule.domain, strlen(DOMAIN) + 1, DOMAIN);
       (void)strcpy_s(domainNameRule.name, strlen(NAME) + 1, NAME);
       domainNameRule.ruleType = 1;
       domainNameRule.eventType = 0;
       HiSysEventWatchRule rules[] = {domainNameRule};
       int ret = OH_HiSysEvent_Add_Watcher(&watcher, rules, sizeof(rules) / sizeof(HiSysEventWatchRule));
       if (ret == 0) {
          ret = OH_HiSysEvent_Remove_Watcher(&watcher);
      }
   }