1# Hiview Development 2 3 4## Introduction 5 6 7### Function Overview 8 9Hiview is a module that provides toolkits for device maintenance across different platforms. It consists of the plugin management platform and the service plugins running on the platform. Hiview works in event-driven mode. The core of Hiview is a collection of HiSysEvent stubs distributed in the system. Formatted events are reported to Hiview through the HiSysEvent API for processing. The following figure shows the data interaction process. 10 11**Figure 1** Data interaction between Hiview modules 12 13 14 151. The service process calls the event logging API to report logged event information and writes the information to the node file. 162. SysEventSource of the Hiview process asynchronously reads event information from the node file and distributes the event to SysEventPipeline for processing. 17 - The SysEventService plugin verifies events and flushes them to disks. 18 - The Faultlogger plugin processes fault-related events. 19 - The EventLogger plugin collects event-related log information. 203. On completion of event processing, SysEventPipeline sends the events to the event subscription queue and then dispatches the events to the subscription plugin for processing. 21 - FreezeDetector processes screen freezing events. 22 - HiCollieCollector processes suspension events. 23 24### Basic Concepts 25 26Before you get started, familiarize yourself with the following concepts: 27 28- Plug-in 29 30 An independent module running in the Hiview process. A plugin is delivered with the Hiview binary file to implement maintenance and fault management functions independently. Plug-ins can be disassembled independently during compilation, and can be hosted on the platform during running and dynamically configured. 31 32- Pipeline 33 34 An ordered set of event processing plugins. Events entering the pipeline are processed by plugins on the pipeline in sequence. 35 36- Event source 37 38 A special plugin that can produce events. Different from common plugins, a special plugin can be bound to a pipeline, and can produce events and distribute them to the pipeline. 39 40- Pipeline group 41 42 A group of pipelines configured on the same event source. 43 44### Working Principles 45 46Hiview supports plugin development on the plugin management platform and provides the required plugin development capabilities. You can add plugins to the Hiview platform to implement HiSysEvent event processing. Before you get started, you're expected to have a basic understanding of plugin working principles. 47 48#### Plug-in Registration 49 50A plugin can be registered in any of the following modes. 51 52| Mode | Description | 53| ------------------ | ------------------------------------------------------------ | 54| Static registration | Use the **REGISTER(xxx);** macro to register the plugin. Such a plugin cannot be unloaded.| 55| Proxy registration | Use the **REGISTER_PROXY(xxx);** macro to register the plugin. Such a plugin is not loaded upon startup and can be loaded and unloaded dynamically during system running.| 56| Proxy registration and loading upon startup| Use the **REGISTER_PROXY_WITH_LOADED(xxx);** macro to register the plugin. Such a plugin is loaded upon startup and can be unloaded and loaded dynamically during system running.| 57 58#### Plug-in Event-Driven Modes 59 60There are two event-driven modes available for plugins: pipeline-driven and subscription-driven. The differences are as follows: 61 62- Pipeline-driven plugins need to be configured on the pipeline. After an event is distributed from an event source to the pipeline, the event traverses the plugins configured on the pipeline in sequence for processing. 63- Subscription-driven plugins do not need to be configured on the pipeline. However, a listener needs to be registered with the Hiview platform upon plugin startup, and the plugin needs to implement the event listener function. 64 65#### Plug-in Loading 66 67Depending on your service demand, you can compile all or some plugins into the Hiview binary file. 68 69Multiple plugins can be built into an independent plugin package and preset in the system as an independent **.so** file. One **.so** file corresponds to one **plugin_config** file. For example, **libxxx.z.so** corresponds to the** xxx_plugin_config** file. When the Hiview process starts, it scans for the plugin package (**.so** file) and the corresponding configuration file and loads the plugins in the plugin package. 70 71The plugin package is described as follows: 72 731. The plugin package runs on the plugin management platform as an independent entity. The plugins, pipelines, or event sources in it provide the same functions as the plugins in the Hiview binary. 74 752. Plug-ins in the plugin package can be inserted into the Hiview binary pipeline. 76 77 783. Subscribers, wherever they are located, can receive events sent by the platform based on the subscription rules. 79 80 81## Plug-in Development Guide 82 83 84### When to Use 85 86You can deploy a plugin on the Hiview platform if you want to perform specific service processing on the HiSysEvent events distributed from the event source. The following table describes the APIs used for plugin development. 87 88### Available APIs 89 90The following table lists the APIs related to plugin development. For details about the APIs, see the API Reference. 91 92Table 1 Description of Plugin APIs 93 94| API | Description | 95| ------------------------------------------------------------ | ------------------------------------------------------------ | 96| virtual void OnLoad() | Loads plugins. After plugins are loaded, you can call this API to initialize data.| 97| virtual void OnUnload() | Unloads plugins. Before plugins are unloaded, you can call this API to reclaim data. | 98| virtual bool ReadyToLoad() | Checks whether the current plugin can be loaded when the Hiview starts plugin loading. | 99| virtual bool OnEvent(std::shared_ptr\<Event\>& event) | Implements event processing. You can call this API to receive events distributed by the pipeline or platform perform service processing.| 100| virtual bool CanProcessEvent(std::shared_ptr\<Event\> event) | Checks whether an event can traverse backward throughout the entire pipeline. This function takes effect only when the plugin is the first one in the pipeline.| 101| HiviewContext* GetHiviewContext() | Obtains the context of the Hiview plugin management platform. | 102 103**Table 2** Description of Event APIs 104 105| API | Description | 106| ---------------------- | ---------------------------- | 107| domain_ | Event domain. | 108| eventName_ | Event name. | 109| happenTime_ | Time when an event occurs. | 110| jsonExtraInfo_ | Event data in JSON format. | 111| bool IsPipelineEvent() | Whether an event is a pipeline event. | 112| bool HasFinish() | Whether an event can continue to traverse backward.| 113 114### How to Develop 115 1161. Define a service plugin class, namely, **PluginExample**, which inherits from the **Plugin** class. 117 118 ```c++ 119 #include "event.h" 120 #include "plugin.h" 121 122 class PluginExample : public Plugin { 123 public: 124 bool OnEvent(std::shared_ptr<Event>& event) override; 125 void OnLoad() override; 126 void OnUnload() override; 127 }; 128 ``` 129 1302. In the plugin class implementation code, register the plugin and overwrite the corresponding functions based on the service requirements. 131 132 ```c++ 133 #include "plugin_factory.h" 134 135 // Register the plugin in static registration mode. 136 REGISTER(PluginExample); 137 138 void PluginExample::OnLoad() 139 { 140 ... // Initialize plugin resources while the plugin is loaded. 141 printf("PluginExample OnLoad \n"); 142 } 143 144 void PluginExample::OnUnload() 145 { 146 ... // Release plugin resources while the plugin is unloaded. 147 printf("PluginExample OnUnload \n"); 148 } 149 150 bool PluginExample::OnEvent(std::shared_ptr<Event>& event) 151 { 152 ... // Perform specific service processing on the event using the event processing function. 153 printf("PluginExample OnEvent \n"); 154 155 // If the plugin focuses only on events of a certain domain, log only the events of this domain. 156 if (event->domain_ == "TEST_DOMAIN") { 157 printf("The event data received is %s \n", event->jsonExtraInfo_); 158 return true; 159 } 160 161 return false; 162 } 163 ``` 164 1653. Configure the plugin in the **plugin_build.json** file and compile the plugin with the Hiview binary file. 166 167 ```json 168 { 169 "plugins": { 170 "PluginExample": { 171 "path": "plugins/PluginExample", 172 "name": "PluginExample" 173 } 174 }, 175 "rules": [ 176 { 177 "info": { 178 "loadorder": { 179 "PluginExample": { 180 "loadtime": 0 181 } 182 }, 183 "pipelines": { 184 "SysEventPipeline": [ 185 PluginExample 186 ] 187 } 188 } 189 } 190 ] 191 } 192 ``` 193 194 195## Reference 196 197For more information about the source code and usage of HiSysEvent, access the Hiview code repository(https://gitee.com/openharmony/hiviewdfx_hiview). 198
