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 16/** 17 * @file 18 * @kit PerformanceAnalysisKit 19 */ 20 21import { AsyncCallback } from './@ohos.base'; 22 23/** 24 * Provides the system event logging function for applications to log the fault, statistical, security, 25 * and user behavior events reported during running. Based on event information, 26 * you will be able to analyze the running status of applications. 27 * 28 * @namespace hiSysEvent 29 * @syscap SystemCapability.HiviewDFX.HiSysEvent 30 * @systemapi hide for inner use 31 * @since 9 32 */ 33declare namespace hiSysEvent { 34 /** 35 * Enumerate system event types. 36 * 37 * @enum {number} 38 * @syscap SystemCapability.HiviewDFX.HiSysEvent 39 * @systemapi hide for inner use 40 * @since 9 41 */ 42 enum EventType { 43 /** 44 * Fault event 45 * 46 * @syscap SystemCapability.HiviewDFX.HiSysEvent 47 * @systemapi hide for inner use 48 * @since 9 49 */ 50 FAULT = 1, 51 52 /** 53 * Statistic event 54 * 55 * @syscap SystemCapability.HiviewDFX.HiSysEvent 56 * @systemapi hide for inner use 57 * @since 9 58 */ 59 STATISTIC = 2, 60 61 /** 62 * Security event 63 * 64 * @syscap SystemCapability.HiviewDFX.HiSysEvent 65 * @systemapi hide for inner use 66 * @since 9 67 */ 68 SECURITY = 3, 69 70 /** 71 * System behavior event 72 * 73 * @syscap SystemCapability.HiviewDFX.HiSysEvent 74 * @systemapi hide for inner use 75 * @since 9 76 */ 77 BEHAVIOR = 4 78 } 79 80 /** 81 * Definition of written system event information. 82 * 83 * @interface SysEventInfo 84 * @syscap SystemCapability.HiviewDFX.HiSysEvent 85 * @systemapi hide for inner use 86 * @since 9 87 */ 88 interface SysEventInfo { 89 /** 90 * The domain of the event. 91 * 92 * @type { string } 93 * @syscap SystemCapability.HiviewDFX.HiSysEvent 94 * @systemapi hide for inner use 95 * @since 9 96 */ 97 domain: string; 98 99 /** 100 * The name of the event. 101 * 102 * @type { string } 103 * @syscap SystemCapability.HiviewDFX.HiSysEvent 104 * @systemapi hide for inner use 105 * @since 9 106 */ 107 name: string; 108 109 /** 110 * The type of the event. 111 * 112 * @type { EventType } 113 * @syscap SystemCapability.HiviewDFX.HiSysEvent 114 * @systemapi hide for inner use 115 * @since 9 116 */ 117 eventType: EventType; 118 119 /** 120 * The params of the event. 121 * 122 * @type { object } 123 * @syscap SystemCapability.HiviewDFX.HiSysEvent 124 * @systemapi hide for inner use 125 * @since 9 126 */ 127 params: object; 128 } 129 130 /** 131 * Write system event. 132 * 133 * @param {SysEventInfo} info - system event information to be written. 134 * @returns {Promise<void>} - Return Promise 135 * @throws {BusinessError} 401 - Invalid argument. 136 * @throws {BusinessError} 11200001 - Invalid event domain. 137 * @throws {BusinessError} 11200002 - Invalid event name. 138 * @throws {BusinessError} 11200003 - Abnormal environment. 139 * @throws {BusinessError} 11200004 - Length of the event is over limit. 140 * @throws {BusinessError} 11200051 - Invalid event parameter. 141 * @throws {BusinessError} 11200052 - Size of the event parameter of the string type is over limit. 142 * @throws {BusinessError} 11200053 - Count of event parameters is over limit. 143 * @throws {BusinessError} 11200054 - Count of event parameter of the array type is over limit. 144 * @syscap SystemCapability.HiviewDFX.HiSysEvent 145 * @systemapi hide for inner use 146 * @since 9 147 */ 148 function write(info: SysEventInfo): Promise<void>; 149 150 /** 151 * Write system event. 152 * 153 * @param {SysEventInfo} info - system event information to be written. 154 * @param {AsyncCallback<void>} callback - callback function. 155 * @throws {BusinessError} 401 - Invalid argument. 156 * @throws {BusinessError} 11200001 - Invalid event domain. 157 * @throws {BusinessError} 11200002 - Invalid event name. 158 * @throws {BusinessError} 11200003 - Abnormal environment. 159 * @throws {BusinessError} 11200004 - Length of the event is over limit. 160 * @throws {BusinessError} 11200051 - Invalid event parameter. 161 * @throws {BusinessError} 11200052 - Size of the event parameter of the string type is over limit. 162 * @throws {BusinessError} 11200053 - Count of event parameters is over limit. 163 * @throws {BusinessError} 11200054 - Count of event parameter of the array type is over limit. 164 * @syscap SystemCapability.HiviewDFX.HiSysEvent 165 * @systemapi hide for inner use 166 * @since 9 167 */ 168 function write(info: SysEventInfo, callback: AsyncCallback<void>): void; 169 170 /** 171 * Enumerate search system event rule type. 172 * 173 * @enum {number} 174 * @syscap SystemCapability.HiviewDFX.HiSysEvent 175 * @systemapi hide for inner use 176 * @since 9 177 */ 178 enum RuleType { 179 /** 180 * Whole word match 181 * 182 * @syscap SystemCapability.HiviewDFX.HiSysEvent 183 * @systemapi hide for inner use 184 * @since 9 185 */ 186 WHOLE_WORD = 1, 187 188 /** 189 * Prefix match 190 * 191 * @syscap SystemCapability.HiviewDFX.HiSysEvent 192 * @systemapi hide for inner use 193 * @since 9 194 */ 195 PREFIX = 2, 196 197 /** 198 * Regular match 199 * 200 * @syscap SystemCapability.HiviewDFX.HiSysEvent 201 * @systemapi hide for inner use 202 * @since 9 203 */ 204 REGULAR = 3 205 } 206 207 /** 208 * Definition listener rule for system event information. 209 * 210 * @interface WatchRule 211 * @syscap SystemCapability.HiviewDFX.HiSysEvent 212 * @systemapi hide for inner use 213 * @since 9 214 */ 215 interface WatchRule { 216 /** 217 * The domain of the event. 218 * 219 * @type { string } 220 * @syscap SystemCapability.HiviewDFX.HiSysEvent 221 * @systemapi hide for inner use 222 * @since 9 223 */ 224 domain: string; 225 226 /** 227 * The name of the event. 228 * 229 * @type { string } 230 * @syscap SystemCapability.HiviewDFX.HiSysEvent 231 * @systemapi hide for inner use 232 * @since 9 233 */ 234 name: string; 235 236 /** 237 * The tag of the event. 238 * 239 * @type { string } 240 * @syscap SystemCapability.HiviewDFX.HiSysEvent 241 * @systemapi hide for inner use 242 * @since 9 243 */ 244 tag: string; 245 246 /** 247 * The rule of match system event 248 * 249 * @type { RuleType } 250 * @syscap SystemCapability.HiviewDFX.HiSysEvent 251 * @systemapi hide for inner use 252 * @since 9 253 */ 254 ruleType: RuleType; 255 } 256 257 /** 258 * Definition watcher for system event information. 259 * 260 * @interface Watcher 261 * @syscap SystemCapability.HiviewDFX.HiSysEvent 262 * @systemapi hide for inner use 263 * @since 9 264 */ 265 interface Watcher { 266 /** 267 * Rule of filter system event 268 * 269 * @syscap SystemCapability.HiviewDFX.HiSysEvent 270 * @systemapi hide for inner use 271 * @since 9 272 */ 273 rules: WatchRule[]; 274 275 /** 276 * Receive system event. 277 * 278 * @syscap SystemCapability.HiviewDFX.HiSysEvent 279 * @systemapi hide for inner use 280 * @since 9 281 */ 282 onEvent: (info: SysEventInfo) => void; 283 284 /** 285 * Hisysevent service shutdown. 286 * 287 * @syscap SystemCapability.HiviewDFX.HiSysEvent 288 * @systemapi hide for inner use 289 * @since 9 290 */ 291 onServiceDied: () => void; 292 } 293 294 /** 295 * Definition arguments for query system event information. 296 * 297 * @interface QueryArg 298 * @syscap SystemCapability.HiviewDFX.HiSysEvent 299 * @systemapi hide for inner use 300 * @since 9 301 */ 302 interface QueryArg { 303 /** 304 * Begin time 305 * 306 * @type { number } 307 * @syscap SystemCapability.HiviewDFX.HiSysEvent 308 * @systemapi hide for inner use 309 * @since 9 310 */ 311 beginTime: number; 312 313 /** 314 * End time 315 * 316 * @type { number } 317 * @syscap SystemCapability.HiviewDFX.HiSysEvent 318 * @systemapi hide for inner use 319 * @since 9 320 */ 321 endTime: number; 322 323 /** 324 * Max number of receive system event 325 * 326 * @type { number } 327 * @syscap SystemCapability.HiviewDFX.HiSysEvent 328 * @systemapi hide for inner use 329 * @since 9 330 */ 331 maxEvents: number; 332 333 /** 334 * Begin sequence 335 * 336 * @type { ?number } 337 * @syscap SystemCapability.HiviewDFX.HiSysEvent 338 * @systemapi hide for inner use 339 * @since 10 340 */ 341 fromSeq?: number; 342 343 /** 344 * End sequence 345 * 346 * @type { ?number } 347 * @syscap SystemCapability.HiviewDFX.HiSysEvent 348 * @systemapi hide for inner use 349 * @since 10 350 */ 351 toSeq?: number; 352 } 353 354 /** 355 * Definition event for query system event information 356 * 357 * @interface QueryRule 358 * @syscap SystemCapability.HiviewDFX.HiSysEvent 359 * @systemapi hide for inner use 360 * @since 9 361 */ 362 interface QueryRule { 363 /** 364 * The domain of the event 365 * 366 * @type { string } 367 * @syscap SystemCapability.HiviewDFX.HiSysEvent 368 * @systemapi hide for inner use 369 * @since 9 370 */ 371 domain: string; 372 373 /** 374 * List of event name 375 * 376 * @type { string[] } 377 * @syscap SystemCapability.HiviewDFX.HiSysEvent 378 * @systemapi hide for inner use 379 * @since 9 380 */ 381 names: string[]; 382 383 /** 384 * Extra parameter condition of event 385 * 386 * @type { ?string } 387 * @syscap SystemCapability.HiviewDFX.HiSysEvent 388 * @systemapi hide for inner use 389 * @since 10 390 */ 391 condition?: string; 392 } 393 394 /** 395 * Definition query result handler 396 * 397 * @interface Querier 398 * @syscap SystemCapability.HiviewDFX.HiSysEvent 399 * @systemapi hide for inner use 400 * @since 9 401 */ 402 interface Querier { 403 /** 404 * Handle query result, the query result will be send in several times. 405 * 406 * @syscap SystemCapability.HiviewDFX.HiSysEvent 407 * @systemapi hide for inner use 408 * @since 9 409 */ 410 onQuery: (infos: SysEventInfo[]) => void; 411 412 /** 413 * Notify querier execute query has finished. 414 * 415 * @syscap SystemCapability.HiviewDFX.HiSysEvent 416 * @systemapi hide for inner use 417 * @since 9 418 */ 419 onComplete: (reason: number, total: number) => void; 420 } 421 422 /** 423 * Add watcher to watch system event 424 * 425 * @permission ohos.permission.READ_DFX_SYSEVENT 426 * @param {Watcher} watcher watch system event 427 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 428 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 429 * @throws {BusinessError} 401 - Invalid argument. 430 * @throws {BusinessError} 11200101 - Count of watchers is over limit. 431 * @throws {BusinessError} 11200102 - Count of watch rules is over limit. 432 * @syscap SystemCapability.HiviewDFX.HiSysEvent 433 * @systemapi hide for inner use 434 * @since 9 435 */ 436 function addWatcher(watcher: Watcher): void; 437 438 /** 439 * Remove watcher 440 * 441 * @permission ohos.permission.READ_DFX_SYSEVENT 442 * @param {Watcher} watcher watch system event 443 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 444 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 445 * @throws {BusinessError} 401 - Invalid argument. 446 * @throws {BusinessError} 11200201 - The watcher does not exist. 447 * @syscap SystemCapability.HiviewDFX.HiSysEvent 448 * @systemapi hide for inner use 449 * @since 9 450 */ 451 function removeWatcher(watcher: Watcher): void; 452 453 /** 454 * Query system event 455 * 456 * @permission ohos.permission.READ_DFX_SYSEVENT 457 * @param {QueryArg} queryArg common arguments of query system event 458 * @param {QueryRule[]} rules rule of query system event 459 * @param {Querier} querier receive query result 460 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 461 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 462 * @throws {BusinessError} 401 - Invalid argument. 463 * @throws {BusinessError} 11200301 - Count of query rules is over limit. 464 * @throws {BusinessError} 11200302 - Invalid query rule. 465 * @throws {BusinessError} 11200303 - Count of concurrent queriers is over limit. 466 * @throws {BusinessError} 11200304 - Query frequency is over limit. 467 * @syscap SystemCapability.HiviewDFX.HiSysEvent 468 * @systemapi hide for inner use 469 * @since 9 470 */ 471 function query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void; 472 473 /** 474 * Export system event 475 * 476 * @permission ohos.permission.READ_DFX_SYSEVENT 477 * @param {QueryArg} queryArg common arguments of query system event 478 * @param {QueryRule[]} rules rule of query system event 479 * @returns {number} return hiview receive task time. 480 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 481 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 482 * @throws {BusinessError} 401 - Invalid argument. 483 * @throws {BusinessError} 11200301 - Count of query rules is over limit. 484 * @throws {BusinessError} 11200302 - Invalid query rule. 485 * @throws {BusinessError} 11200304 – Export frequency is over limit. 486 * @syscap SystemCapability.HiviewDFX.HiSysEvent 487 * @systemapi hide for inner use 488 * @since 10 489 */ 490 function exportSysEvents(queryArg: QueryArg, rules: QueryRule[]): number; 491 492 /** 493 * Subscribe system event 494 * 495 * @permission ohos.permission.READ_DFX_SYSEVENT 496 * @param {QueryRule[]} rules rule of subscribe system event 497 * @returns {number} return hiview receive task time. 498 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 499 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 500 * @throws {BusinessError} 401 - Invalid argument. 501 * @throws {BusinessError} 11200301 - Count of query rules is over limit. 502 * @throws {BusinessError} 11200302 - Invalid query rule. 503 * @syscap SystemCapability.HiviewDFX.HiSysEvent 504 * @systemapi hide for inner use 505 * @since 10 506 */ 507 function subscribe(rules: QueryRule[]): number; 508 509 /** 510 * Unsubscribe system event 511 * 512 * @permission ohos.permission.READ_DFX_SYSEVENT 513 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 514 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 515 * @throws {BusinessError} 401 - Invalid argument. 516 * @throws {BusinessError} 11200305 – unsubscribe failed. 517 * @syscap SystemCapability.HiviewDFX.HiSysEvent 518 * @systemapi hide for inner use 519 * @since 10 520 */ 521 function unsubscribe(): void; 522} 523 524export default hiSysEvent; 525