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