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