1# CommonEventSubscriber 2 3> **NOTE** 4> 5> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 6 7## Usage 8 9Before using the **CommonEventSubscriber** module, you must obtain a **subscriber** object by calling **CommonEvent.createSubscriber**. 10 11```ts 12import CommonEvent from '@ohos.commonEvent'; 13import CommonEventManager from '@ohos.commonEventManager'; 14import Base from '@ohos.base'; 15let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. 16 17// Subscriber information. 18let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = { 19 events: ["event"] 20}; 21 22// Callback for subscriber creation. 23function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) { 24 if (err.code !== undefined && err.code != null) { 25 console.error(`createSubscriber failed, code is ${err.code}`); 26 } else { 27 console.info("createSubscriber"); 28 subscriber = commonEventSubscriber; 29 } 30} 31 32// Create a subscriber. 33CommonEvent.createSubscriber(subscribeInfo, createCB); 34``` 35 36## getCode 37 38getCode(callback: AsyncCallback\<number>): void 39 40Obtains the code of this common event. This API uses an asynchronous callback to return the result. 41 42**System capability**: SystemCapability.Notification.CommonEvent 43 44**Parameters** 45 46| Name | Type | Mandatory| Description | 47| -------- | ---------------------- | ---- | ------------------ | 48| callback | AsyncCallback\<number\> | Yes | Common event code.| 49 50**Example** 51 52```ts 53// Callback for result code obtaining of an ordered common event. 54function getCodeCB(err:Base.BusinessError, code:number) { 55 if (err.code !== undefined && err.code != null) { 56 console.error(`getCode failed, code is ${err.code}, message is ${err.message}`); 57 } else { 58 console.info("getCode " + JSON.stringify(code)); 59 } 60} 61subscriber.getCode(getCodeCB); 62``` 63 64## getCode 65 66getCode(): Promise\<number> 67 68Obtains the code of this common event. This API uses a promise to return the result. 69 70**System capability**: SystemCapability.Notification.CommonEvent 71 72**Return value** 73 74| Type | Description | 75| ---------------- | -------------------- | 76| Promise\<number> | Common event code.| 77 78**Example** 79 80```ts 81subscriber.getCode().then((code:number) => { 82 console.info("getCode " + JSON.stringify(code)); 83}).catch((err:Base.BusinessError) => { 84 console.error(`getCode failed, code is ${err.code}, message is ${err.message}`); 85}); 86``` 87 88## setCode 89 90setCode(code: number, callback: AsyncCallback\<void>): void 91 92Sets the code for this common event. This API uses an asynchronous callback to return the result. 93 94**System capability**: SystemCapability.Notification.CommonEvent 95 96**Parameters** 97 98| Name | Type | Mandatory| Description | 99| -------- | -------------------- | ---- | ---------------------- | 100| code | number | Yes | Common event code. | 101| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 102 103**Example** 104 105```ts 106// Callback for result code setting of an ordered common event. 107function setCodeCB(err:Base.BusinessError) { 108 if (err.code !== undefined && err.code != null) { 109 console.error(`setCode failed, code is ${err.code}, message is ${err.message}`); 110 } else { 111 console.info("setCode"); 112 } 113} 114subscriber.setCode(1, setCodeCB); 115``` 116 117## setCode 118 119setCode(code: number): Promise\<void> 120 121Sets the code for this common event. This API uses a promise to return the result. 122 123**System capability**: SystemCapability.Notification.CommonEvent 124 125**Parameters** 126 127| Name| Type | Mandatory| Description | 128| ------ | ------ | ---- | ------------------ | 129| code | number | Yes | Common event code.| 130 131**Return value** 132 133| Type | Description | 134| ---------------- | -------------------- | 135| Promise\<void> | Promise used to return the result.| 136 137**Example** 138 139```ts 140subscriber.setCode(1).then(() => { 141 console.info("setCode"); 142}).catch((err:Base.BusinessError) => { 143 console.error(`setCode failed, code is ${err.code}, message is ${err.message}`); 144}); 145``` 146 147## getData 148 149getData(callback: AsyncCallback\<string>): void 150 151Obtains the data of this common event. This API uses an asynchronous callback to return the result. 152 153**System capability**: SystemCapability.Notification.CommonEvent 154 155**Parameters** 156 157| Name | Type | Mandatory| Description | 158| -------- | ---------------------- | ---- | -------------------- | 159| callback | AsyncCallback\<string> | Yes | Common event data.| 160 161**Example** 162 163```ts 164// Callback for result data obtaining of an ordered common event. 165function getDataCB(err:Base.BusinessError, data:string) { 166 if (err.code !== undefined && err.code != null) { 167 console.error(`getData failed, code is ${err.code}, message is ${err.message}`); 168 } else { 169 console.info("getData " + JSON.stringify(data)); 170 } 171} 172subscriber.getData(getDataCB); 173``` 174 175## getData 176 177getData(): Promise\<string> 178 179Obtains the data of this common event. This API uses a promise to return the result. 180 181**System capability**: SystemCapability.Notification.CommonEvent 182 183**Return value** 184 185| Type | Description | 186| ---------------- | ------------------ | 187| Promise\<string> | Common event data.| 188 189**Example** 190 191```ts 192subscriber.getData().then((data:string) => { 193 console.info("getData " + JSON.stringify(data)); 194}).catch((err:Base.BusinessError) => { 195 console.error(`getData failed, code is ${err.code}, message is ${err.message}`); 196}); 197``` 198 199## setData 200 201setData(data: string, callback: AsyncCallback\<void>): void 202 203Sets the data for this common event. This API uses an asynchronous callback to return the result. 204 205**System capability**: SystemCapability.Notification.CommonEvent 206 207**Parameters** 208 209| Name | Type | Mandatory| Description | 210| -------- | -------------------- | ---- | -------------------- | 211| data | string | Yes | Common event data. | 212| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 213 214**Example** 215 216```ts 217// Callback for result data setting of an ordered common event 218function setDataCB(err:Base.BusinessError) { 219 if (err.code !== undefined && err.code != null) { 220 console.error(`setCode failed, code is ${err.code}, message is ${err.message}`); 221 } else { 222 console.info("setData"); 223 } 224} 225subscriber.setData("publish_data_changed", setDataCB); 226``` 227 228## setData 229 230setData(data: string): Promise\<void> 231 232Sets the data for this common event. This API uses a promise to return the result. 233 234**System capability**: SystemCapability.Notification.CommonEvent 235 236**Parameters** 237 238| Name| Type | Mandatory| Description | 239| ------ | ------ | ---- | -------------------- | 240| data | string | Yes | Common event data.| 241 242**Return value** 243 244| Type | Description | 245| ---------------- | -------------------- | 246| Promise\<void> | Promise used to return the result.| 247 248**Example** 249 250```ts 251subscriber.setData("publish_data_changed").then(() => { 252 console.info("setData"); 253}).catch((err:Base.BusinessError) => { 254 console.error(`setCode failed, code is ${err.code}, message is ${err.message}`); 255}); 256``` 257 258## setCodeAndData 259 260setCodeAndData(code: number, data: string, callback:AsyncCallback\<void>): void 261 262Sets the code and data for this common event. This API uses an asynchronous callback to return the result. 263 264**System capability**: SystemCapability.Notification.CommonEvent 265 266**Parameters** 267 268| Name | Type | Mandatory| Description | 269| -------- | -------------------- | ---- | ---------------------- | 270| code | number | Yes | Common event code. | 271| data | string | Yes | Common event data. | 272| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 273 274**Example** 275 276```ts 277// Callback for code and data setting of an ordered common event. 278function setCodeDataCB(err:Base.BusinessError) { 279 if (err.code !== undefined && err.code != null) { 280 console.error(`setCodeAndData failed, code is ${err.code}, message is ${err.message}`); 281 } else { 282 console.info("setCodeDataCallback"); 283 } 284} 285subscriber.setCodeAndData(1, "publish_data_changed", setCodeDataCB); 286``` 287 288## setCodeAndData 289 290setCodeAndData(code: number, data: string): Promise\<void> 291 292Sets the code and data for this common event. This API uses a promise to return the result. 293 294**System capability**: SystemCapability.Notification.CommonEvent 295 296**Parameters** 297 298| Name| Type | Mandatory| Description | 299| ------ | ------ | ---- | -------------------- | 300| code | number | Yes | Common event code.| 301| data | string | Yes | Common event data.| 302 303**Return value** 304 305| Type | Description | 306| ---------------- | -------------------- | 307| Promise\<void> | Promise used to return the result.| 308 309**Example** 310 311```ts 312subscriber.setCodeAndData(1, "publish_data_changed").then(() => { 313 console.info("setCodeAndData"); 314}).catch((err:Base.BusinessError) => { 315 console.error(`setCodeAndData failed, code is ${err.code}, message is ${err.message}`); 316}); 317``` 318 319## isOrderedCommonEvent 320 321isOrderedCommonEvent(callback: AsyncCallback\<boolean>): void 322 323Checks whether this common event is an ordered one. This API uses an asynchronous callback to return the result. 324 325**System capability**: SystemCapability.Notification.CommonEvent 326 327**Parameters** 328 329| Name | Type | Mandatory| Description | 330| -------- | ----------------------- | ---- | ---------------------------------- | 331| callback | AsyncCallback\<boolean> | Yes | Returns **true** if the common event is an ordered one; returns **false** otherwise.| 332 333**Example** 334 335```ts 336// Callback for checking whether the current common event is an ordered one. 337function isOrderedCB(err:Base.BusinessError, isOrdered:boolean) { 338 if (err.code !== undefined && err.code != null) { 339 console.error(`isOrderedCommonEvent failed, code is ${err.code}, message is ${err.message}`); 340 } else { 341 console.info("isOrdered " + JSON.stringify(isOrdered)); 342 } 343} 344subscriber.isOrderedCommonEvent(isOrderedCB); 345``` 346 347## isOrderedCommonEvent 348 349isOrderedCommonEvent(): Promise\<boolean> 350 351Checks whether this common event is an ordered one. This API uses a promise to return the result. 352 353**System capability**: SystemCapability.Notification.CommonEvent 354 355**Return value** 356 357| Type | Description | 358| ----------------- | -------------------------------- | 359| Promise\<boolean> | Returns **true** if the common event is an ordered one; returns **false** otherwise.| 360 361**Example** 362 363```ts 364subscriber.isOrderedCommonEvent().then((isOrdered:boolean) => { 365 console.info("isOrdered " + JSON.stringify(isOrdered)); 366}).catch((err:Base.BusinessError) => { 367 console.error(`isOrdered failed, code is ${err.code}, message is ${err.message}`); 368}); 369``` 370 371## isStickyCommonEvent 372 373isStickyCommonEvent(callback: AsyncCallback\<boolean>): void 374 375Checks whether this common event is a sticky one. This API uses an asynchronous callback to return the result. 376 377**System capability**: SystemCapability.Notification.CommonEvent 378 379**Parameters** 380 381| Name | Type | Mandatory| Description | 382| -------- | ----------------------- | ---- | ---------------------------------- | 383| callback | AsyncCallback\<boolean> | Yes | Returns **true** if the common event is a sticky one; returns **false** otherwise.| 384 385**Example** 386 387```ts 388// Callback for checking whether the current common event is a sticky one. 389function isStickyCB(err:Base.BusinessError, isSticky:boolean) { 390 if (err.code !== undefined && err.code != null) { 391 console.error(`isStickyCommonEvent failed, code is ${err.code}, message is ${err.message}`); 392 } else { 393 console.info("isSticky " + JSON.stringify(isSticky)); 394 } 395} 396subscriber.isStickyCommonEvent(isStickyCB); 397``` 398 399## isStickyCommonEvent 400 401isStickyCommonEvent(): Promise\<boolean> 402 403Checks whether this common event is a sticky one. This API uses a promise to return the result. 404 405**System capability**: SystemCapability.Notification.CommonEvent 406 407**Return value** 408 409| Type | Description | 410| ----------------- | -------------------------------- | 411| Promise\<boolean> | Returns **true** if the common event is a sticky one; returns **false** otherwise.| 412 413**Example** 414 415```ts 416subscriber.isStickyCommonEvent().then((isSticky:boolean) => { 417 console.info("isSticky " + JSON.stringify(isSticky)); 418}).catch((err:Base.BusinessError) => { 419 console.error(`isSticky failed, code is ${err.code}, message is ${err.message}`); 420}); 421``` 422 423## abortCommonEvent 424 425abortCommonEvent(callback: AsyncCallback\<void>): void 426 427Aborts this common event. After the abort, the common event is not sent to the next subscriber. This API takes effect only for ordered common events. It uses an asynchronous callback to return the result. 428 429**System capability**: SystemCapability.Notification.CommonEvent 430 431**Parameters** 432 433| Name | Type | Mandatory| Description | 434| -------- | -------------------- | ---- | -------------------- | 435| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 436 437**Example** 438 439```ts 440// Callback for common event aborting. 441function abortCB(err:Base.BusinessError) { 442 if (err.code !== undefined && err.code != null) { 443 console.error(`abortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 444 } else { 445 console.info("abortCommonEvent"); 446 } 447} 448subscriber.abortCommonEvent(abortCB); 449``` 450 451## abortCommonEvent 452 453abortCommonEvent(): Promise\<void> 454 455Aborts this common event. After the abort, the common event is not sent to the next subscriber. This API takes effect only for ordered common events. It uses a promise to return the result. 456 457**System capability**: SystemCapability.Notification.CommonEvent 458 459**Return value** 460 461| Type | Description | 462| ---------------- | -------------------- | 463| Promise\<void> | Promise used to return the result.| 464 465**Example** 466 467```ts 468subscriber.abortCommonEvent().then(() => { 469 console.info("abortCommonEvent"); 470}).catch((err:Base.BusinessError) => { 471 console.error(`abortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 472}); 473``` 474 475## clearAbortCommonEvent 476 477clearAbortCommonEvent(callback: AsyncCallback\<void>): void 478 479Clears the aborted state of this common event. This API takes effect only for ordered common events. It uses an asynchronous callback to return the result. 480 481**System capability**: SystemCapability.Notification.CommonEvent 482 483**Parameters** 484 485| Name | Type | Mandatory| Description | 486| -------- | -------------------- | ---- | -------------------- | 487| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 488 489**Example** 490 491```ts 492// Callback for clearing the aborted state of the current common event. 493function clearAbortCB(err:Base.BusinessError) { 494 if (err.code !== undefined && err.code != null) { 495 console.error(`clearAbortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 496 } else { 497 console.info("clearAbortCommonEvent"); 498 } 499} 500subscriber.clearAbortCommonEvent(clearAbortCB); 501``` 502 503## clearAbortCommonEvent 504 505clearAbortCommonEvent(): Promise\<void> 506 507Clears the aborted state of this common event. This API takes effect only for ordered common events. It uses a promise to return the result. 508 509**System capability**: SystemCapability.Notification.CommonEvent 510 511**Return value** 512 513| Type | Description | 514| ---------------- | -------------------- | 515| Promise\<void> | Promise used to return the result.| 516 517**Example** 518 519```ts 520subscriber.clearAbortCommonEvent().then(() => { 521 console.info("clearAbortCommonEvent"); 522}).catch((err:Base.BusinessError) => { 523 console.error(`clearAbortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 524}); 525``` 526 527## getAbortCommonEvent 528 529getAbortCommonEvent(callback: AsyncCallback\<boolean>): void 530 531Checks whether this common event is in the aborted state. This API takes effect only for ordered common events. It uses an asynchronous callback to return the result. 532 533**System capability**: SystemCapability.Notification.CommonEvent 534 535**Parameters** 536 537| Name | Type | Mandatory| Description | 538| -------- | ----------------------- | ---- | ---------------------------------- | 539| callback | AsyncCallback\<boolean> | Yes | Returns **true** if the ordered common event is in the aborted state; returns **false** otherwise.| 540 541**Example** 542 543```ts 544// Callback for checking whether the current common event is in the aborted state. 545function getAbortCB(err:Base.BusinessError, abortEvent:boolean) { 546 if (err.code !== undefined && err.code != null) { 547 console.error(`getAbortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 548 } else { 549 console.info("abortCommonEvent " + abortEvent) 550 } 551} 552subscriber.getAbortCommonEvent(getAbortCB); 553``` 554 555## getAbortCommonEvent 556 557getAbortCommonEvent(): Promise\<boolean> 558 559Checks whether this common event is in the aborted state. This API takes effect only for ordered common events. It uses a promise to return the result. 560 561**System capability**: SystemCapability.Notification.CommonEvent 562 563**Return value** 564 565| Type | Description | 566| ----------------- | ---------------------------------- | 567| Promise\<boolean> | Returns **true** if the ordered common event is in the aborted state; returns **false** otherwise.| 568 569**Example** 570 571```ts 572subscriber.getAbortCommonEvent().then((abortEvent:boolean) => { 573 console.info("abortCommonEvent " + JSON.stringify(abortEvent)); 574}).catch((err:Base.BusinessError) => { 575 console.error(`getAbortCommonEvent failed, code is ${err.code}, message is ${err.message}`); 576}); 577``` 578 579## getSubscribeInfo 580 581getSubscribeInfo(callback: AsyncCallback\<CommonEventSubscribeInfo>): void 582 583Obtains the subscriber information. This API uses an asynchronous callback to return the result. 584 585**System capability**: SystemCapability.Notification.CommonEvent 586 587**Parameters** 588 589| Name | Type | Mandatory| Description | 590| -------- | ------------------------------------------------------------ | ---- | ---------------------- | 591| callback | AsyncCallback\<[CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)> | Yes | Callback used to return the subscriber information.| 592 593**Example** 594 595```ts 596// Callback for subscriber information obtaining. 597function getCB(err:Base.BusinessError, subscribeInfo:CommonEventManager.CommonEventSubscribeInfo) { 598 if (err.code !== undefined && err.code != null) { 599 console.error(`getSubscribeInfo failed, code is ${err.code}, message is ${err.message}`); 600 } else { 601 console.info("subscribeInfo " + JSON.stringify(subscribeInfo)); 602 } 603} 604subscriber.getSubscribeInfo(getCB); 605``` 606 607## getSubscribeInfo 608 609getSubscribeInfo(): Promise\<CommonEventSubscribeInfo> 610 611Obtains the subscriber information. This API uses a promise to return the result. 612 613**System capability**: SystemCapability.Notification.CommonEvent 614 615**Return value** 616 617| Type | Description | 618| ------------------------------------------------------------ | ---------------------- | 619| Promise\<[CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)> | Promise used to return the subscriber information.| 620 621**Example** 622 623```ts 624subscriber.getSubscribeInfo().then((subscribeInfo:CommonEventManager.CommonEventSubscribeInfo) => { 625 console.info("subscribeInfo " + JSON.stringify(subscribeInfo)); 626}).catch((err:Base.BusinessError) => { 627 console.error(`getSubscribeInfo failed, code is ${err.code}, message is ${err.message}`); 628}); 629``` 630 631## finishCommonEvent<sup>9+</sup> 632 633finishCommonEvent(callback: AsyncCallback\<void>): void 634 635Finishes this common event. This API takes effect only for ordered common events. It uses an asynchronous callback to return the result. 636 637**System capability**: SystemCapability.Notification.CommonEvent 638 639**Parameters** 640 641| Name | Type | Mandatory| Description | 642| -------- | -------------------- | ---- | -------------------------------- | 643| callback | AsyncCallback\<void> | Yes | Callback returned after the ordered common event is finished.| 644 645**Example** 646 647```ts 648// Callback for ordered common event finishing. 649function finishCB(err:Base.BusinessError) { 650 if (err.code !== undefined && err.code != null) { 651 console.error(`finishCommonEvent failed, code is ${err.code}, message is ${err.message}`); 652 } else { 653 console.info("FinishCommonEvent"); 654 } 655} 656 657subscriber.finishCommonEvent(finishCB); 658``` 659 660## finishCommonEvent<sup>9+</sup> 661 662finishCommonEvent(): Promise\<void> 663 664Finishes this common event. This API takes effect only for ordered common events. It uses a promise to return the result. 665 666**System capability**: SystemCapability.Notification.CommonEvent 667 668**Return value** 669 670| Type | Description | 671| ---------------- | -------------------- | 672| Promise\<void> | Promise used to return the result.| 673 674**Example** 675 676```ts 677subscriber.finishCommonEvent().then(() => { 678 console.info("FinishCommonEvent"); 679}).catch((err:Base.BusinessError) => { 680 console.error(`finishCommonEvent failed, code is ${err.code}, message is ${err.message}`); 681}); 682``` 683