1/* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16import { AsyncCallback } from './basic'; 17 18/** 19 * Provides the system event logging function for applications to log the fault, statistical, security, 20 * and user behavior events reported during running. Based on event information, 21 * you will be able to analyze the running status of applications. 22 * 23 * @syscap SystemCapability.HiviewDFX.HiSysEvent 24 * @systemapi hide for inner use 25 * @since 9 26 */ 27declare namespace hiSysEvent { 28 /** 29 * Enumerate system event types. 30 * 31 * @enum {number} 32 * @readonly 33 * @syscap SystemCapability.HiviewDFX.HiSysEvent 34 * @systemapi hide for inner use 35 * @since 9 36 */ 37 enum EventType { 38 /** 39 * Fault event 40 * 41 * @syscap SystemCapability.HiviewDFX.HiSysEvent 42 * @systemapi hide for inner use 43 * @since 9 44 */ 45 FAULT = 1, 46 47 /** 48 * Statistic event 49 * 50 * @syscap SystemCapability.HiviewDFX.HiSysEvent 51 * @systemapi hide for inner use 52 * @since 9 53 */ 54 STATISTIC = 2, 55 56 /** 57 * Security event 58 * 59 * @syscap SystemCapability.HiviewDFX.HiSysEvent 60 * @systemapi hide for inner use 61 * @since 9 62 */ 63 SECURITY = 3, 64 65 /** 66 * System behavior event 67 * 68 * @syscap SystemCapability.HiviewDFX.HiSysEvent 69 * @systemapi hide for inner use 70 * @since 9 71 */ 72 BEHAVIOR = 4 73 } 74 75 /** 76 * Definition of written system event information. 77 * 78 * @syscap SystemCapability.HiviewDFX.HiSysEvent 79 * @systemapi hide for inner use 80 * @since 9 81 */ 82 interface SysEventInfo { 83 /** 84 * The domain of the event. 85 */ 86 domain: string; 87 88 /** 89 * The name of the event. 90 */ 91 name: string; 92 93 /** 94 * The type of the event. 95 */ 96 eventType: EventType; 97 98 /** 99 * The params of the event. 100 */ 101 params: object; 102 } 103 104 /** 105 * Write system event. 106 * 107 * @syscap SystemCapability.HiviewDFX.HiSysEvent 108 * @systemapi hide for inner use 109 * @static 110 * @param {SysEventInfo} info system event information to be written. 111 * @param {AsyncCallback} [callback] callback function. 112 * @throws {BusinessError} 401 - Invalid argument. 113 * @throws {BusinessError} 11200001 - Invalid event domain. 114 * @throws {BusinessError} 11200002 - Invalid event name. 115 * @throws {BusinessError} 11200003 - Abnormal environment. 116 * @throws {BusinessError} 11200004 - Length of the event is over limit. 117 * @throws {BusinessError} 11200051 - Invalid event parameter. 118 * @throws {BusinessError} 11200052 - Size of the event parameter of the string type is over limit. 119 * @throws {BusinessError} 11200053 - Count of event parameters is over limit. 120 * @throws {BusinessError} 11200054 - Count of event parameter of the array type is over limit. 121 * @returns {void | Promise<void>} no callback return Promise otherwise return void. 122 * @since 9 123 */ 124 function write(info: SysEventInfo): Promise<void>; 125 function write(info: SysEventInfo, callback: AsyncCallback<void>): void; 126 127 /** 128 * Enumerate search system event rule type. 129 * 130 * @enum {number} 131 * @readonly 132 * @syscap SystemCapability.HiviewDFX.HiSysEvent 133 * @systemapi hide for inner use 134 * @since 9 135 */ 136 enum RuleType { 137 /** 138 * Whole word match 139 * 140 * @syscap SystemCapability.HiviewDFX.HiSysEvent 141 * @systemapi hide for inner use 142 * @since 9 143 */ 144 WHOLE_WORD = 1, 145 146 /** 147 * Prefix match 148 * 149 * @syscap SystemCapability.HiviewDFX.HiSysEvent 150 * @systemapi hide for inner use 151 * @since 9 152 */ 153 PREFIX = 2, 154 155 /** 156 * Regular match 157 * 158 * @syscap SystemCapability.HiviewDFX.HiSysEvent 159 * @systemapi hide for inner use 160 * @since 9 161 */ 162 REGULAR = 3 163 } 164 165 /** 166 * Definition listener rule for system event information. 167 * 168 * @syscap SystemCapability.HiviewDFX.HiSysEvent 169 * @systemapi hide for inner use 170 * @since 9 171 */ 172 interface WatchRule { 173 /** 174 * The domain of the event. 175 */ 176 domain: string; 177 178 /** 179 * The name of the event. 180 */ 181 name: string; 182 183 /** 184 * The name of the event. 185 */ 186 tag: string; 187 188 /** 189 * The rule of match system event 190 */ 191 ruleType: RuleType; 192 } 193 194 /** 195 * Definition watcher for system event information. 196 * 197 * @syscap SystemCapability.HiviewDFX.HiSysEvent 198 * @systemapi hide for inner use 199 * @since 9 200 */ 201 interface Watcher { 202 /** 203 * Rule of filter system event 204 */ 205 rules: WatchRule[]; 206 207 /** 208 * Receive system event. 209 * 210 * @syscap SystemCapability.HiviewDFX.HiSysEvent 211 * @systemapi hide for inner use 212 * @param {SysEventInfo} info system event information of receive. 213 * @returns {void} return void. 214 * @since 9 215 */ 216 onEvent: (info: SysEventInfo) => void; 217 218 /** 219 * Hisysevent service shutdown. 220 * 221 * @syscap SystemCapability.HiviewDFX.HiSysEvent 222 * @systemapi hide for inner use 223 * @returns {void} return void. 224 * @since 9 225 */ 226 onServiceDied: () => void; 227 } 228 229 /** 230 * Definition arguments for query system event information. 231 * 232 * @enum {number} 233 * @readonly 234 * @syscap SystemCapability.HiviewDFX.HiSysEvent 235 * @systemapi hide for inner use 236 * @since 9 237 */ 238 interface QueryArg { 239 /** 240 * Begin time 241 */ 242 beginTime: number; 243 244 /** 245 * End time 246 */ 247 endTime: number; 248 249 /** 250 * Max number of receive system event 251 */ 252 maxEvents: number; 253 } 254 255 /** 256 * Definition event for query system event information 257 * 258 * @syscap SystemCapability.HiviewDFX.HiSysEvent 259 * @systemapi hide for inner use 260 * @since 9 261 */ 262 interface QueryRule { 263 /** 264 * The domain of the event 265 */ 266 domain: string; 267 268 /** 269 * List of event name 270 */ 271 names: string[]; 272 } 273 274 /** 275 * Definition query result handler 276 * 277 * @syscap SystemCapability.HiviewDFX.HiSysEvent 278 * @systemapi hide for inner use 279 * @since 9 280 */ 281 interface Querier { 282 /** 283 * Handle query result, the query result will be send in several times. 284 * 285 * @syscap SystemCapability.HiviewDFX.HiSysEvent 286 * @systemapi hide for inner use 287 * @param {SysEventInfo[]} infos system event information of query result. 288 * @returns {void} return void. 289 * @since 9 290 */ 291 onQuery: (infos: SysEventInfo[]) => void; 292 293 /** 294 * Notify querier execute query has finished. 295 * 296 * @syscap SystemCapability.HiviewDFX.HiSysEvent 297 * @systemapi hide for inner use 298 * @param {number} reason 0 success, 1 fail. 299 * @param {number} total the total number of query result. 300 * @returns {void} return void. 301 * @since 9 302 */ 303 onComplete: (reason: number, total: number) => void; 304 } 305 306 /** 307 * Add watcher to watch system event 308 * 309 * @syscap SystemCapability.HiviewDFX.HiSysEvent 310 * @systemapi hide for inner use 311 * @permission ohos.permission.READ_DFX_SYSEVENT 312 * @param {Watcher} watcher watch system event 313 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 314 * @throws {BusinessError} 401 - Invalid argument. 315 * @throws {BusinessError} 11200101 - Count of watchers is over limit. 316 * @throws {BusinessError} 11200102 - Count of watch rules is over limit. 317 * @returns {void} return void. 318 * @since 9 319 */ 320 function addWatcher(watcher: Watcher): void; 321 322 /** 323 * Remove watcher 324 * 325 * @syscap SystemCapability.HiviewDFX.HiSysEvent 326 * @systemapi hide for inner use 327 * @permission ohos.permission.READ_DFX_SYSEVENT 328 * @param {Watcher} watcher watch system event 329 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 330 * @throws {BusinessError} 401 - Invalid argument. 331 * @throws {BusinessError} 11200201 - The watcher does not exist. 332 * @returns {void} return void. 333 * @since 9 334 */ 335 function removeWatcher(watcher: Watcher): void; 336 337 /** 338 * Query system event 339 * 340 * @syscap SystemCapability.HiviewDFX.HiSysEvent 341 * @systemapi hide for inner use 342 * @permission ohos.permission.READ_DFX_SYSEVENT 343 * @param {QueryArg} queryArg common arguments of query system event 344 * @param {QueryRule[]} rules rule of query system event 345 * @param {Querier} querier receive query result 346 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 347 * @throws {BusinessError} 401 - Invalid argument. 348 * @throws {BusinessError} 11200301 - Count of query rules is over limit. 349 * @throws {BusinessError} 11200302 - Invalid query rule. 350 * @throws {BusinessError} 11200303 - Count of concurrent queriers is over limit. 351 * @throws {BusinessError} 11200304 - Query frequency is over limit. 352 * @returns {void} return void. 353 * @since 9 354 */ 355 function query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void; 356} 357 358export default hiSysEvent; 359