1# @ohos.commonEventManager (Common Event) 2 3The **CommonEventManager** module provides common event capabilities, including the capabilities to publish, subscribe to, and unsubscribe from common events. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import CommonEventManager from '@ohos.commonEventManager'; 13``` 14 15## Support 16 17A system common event is an event that is published by a system service or system application and requires specific permissions to subscribe to. To publish or subscribe to this type of event, you must follow the event-specific definitions. 18 19For details about the definitions of all system common events, see [System Common Events](./commonEventManager-definitions.md). 20 21## CommonEventManager.publish 22 23publish(event: string, callback: AsyncCallback\<void>): void 24 25Publishes a common event and executes an asynchronous callback after the event is published. 26 27**System capability**: SystemCapability.Notification.CommonEvent 28 29**Parameters** 30 31| Name | Type | Mandatory| Description | 32| -------- | -------------------- | ---- | ---------------------- | 33| event | string | Yes | Name of the common event to publish.| 34| callback | AsyncCallback\<void> | Yes | Callback to execute after the event is published.| 35 36**Error codes** 37 38For details about the error codes, see [Event Error Codes](./errorcode-CommonEventService.md). 39 40| ID| Error Message | 41| -------- | ----------------------------------- | 42| 1500004 | not System services. | 43| 1500007 | error sending message to Common Event Service. | 44| 1500008 | Common Event Service does not complete initialization. | 45| 1500009 | error obtaining system parameters. | 46 47**Example** 48 49```ts 50import Base from '@ohos.base'; 51 52// Callback for common event publication 53function publishCB(err:Base.BusinessError) { 54 if (err) { 55 console.error(`publish failed, code is ${err.code}, message is ${err.message}`); 56 } else { 57 console.info("publish"); 58 } 59} 60 61// Publish a common event. 62try { 63 CommonEventManager.publish("event", publishCB); 64} catch (error) { 65 let err:Base.BusinessError = error as Base.BusinessError; 66 console.error(`publish failed, code is ${err.code}, message is ${err.message}`); 67} 68``` 69 70## CommonEventManager.publish 71 72publish(event: string, options: CommonEventPublishData, callback: AsyncCallback\<void>): void 73 74Publishes a common event with given attributes. This API uses an asynchronous callback to return the result. 75 76**System capability**: SystemCapability.Notification.CommonEvent 77 78**Parameters** 79 80| Name | Type | Mandatory| Description | 81| -------- | ---------------------- | ---- | ---------------------- | 82| event | string | Yes | Name of the common event to publish. | 83| options | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | Yes | Attributes of the common event to publish.| 84| callback | syncCallback\<void> | Yes | Callback used to return the result. | 85 86**Error codes** 87 88For details about the error codes, see [Event Error Codes](./errorcode-CommonEventService.md). 89 90| ID| Error Message | 91| -------- | ----------------------------------- | 92| 1500004 | not System services. | 93| 1500007 | error sending message to Common Event Service. | 94| 1500008 | Common Event Service does not complete initialization. | 95| 1500009 | error obtaining system parameters. | 96 97**Example** 98 99```ts 100import Base from '@ohos.base'; 101 102// Attributes of a common event. 103let options:CommonEventManager.CommonEventPublishData = { 104 code: 0, // Result code of the common event. 105 data: "initial data",// Result data of the common event. 106 isOrdered: true // The common event is an ordered one. 107} 108 109// Callback for common event publication 110function publishCB(err:Base.BusinessError) { 111 if (err) { 112 console.error(`publish failed, code is ${err.code}, message is ${err.message}`); 113 } else { 114 console.info("publish"); 115 } 116} 117 118// Publish a common event. 119try { 120 CommonEventManager.publish("event", options, publishCB); 121} catch (error) { 122 let err:Base.BusinessError = error as Base.BusinessError; 123 console.error(`publish failed, code is ${err.code}, message is ${err.message}`); 124} 125``` 126 127## CommonEventManager.createSubscriber 128 129createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback\<CommonEventSubscriber>): void 130 131Creates a subscriber. This API uses an asynchronous callback to return the result. 132 133**System capability**: SystemCapability.Notification.CommonEvent 134 135**Parameters** 136 137| Name | Type | Mandatory| Description | 138| ------------- | ------------------------------------------------------------ | ---- | -------------------------- | 139| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes | Subscriber information. | 140| callback | AsyncCallback\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | Yes | Callback used to return the result.| 141 142**Example** 143 144```ts 145import Base from '@ohos.base'; 146 147let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. 148 149// Subscriber information. 150let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = { 151 events: ["event"] 152}; 153 154// Callback for subscriber creation. 155function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) { 156 if(!err) { 157 console.info("createSubscriber"); 158 subscriber = commonEventSubscriber; 159 } else { 160 console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`); 161 } 162} 163 164// Create a subscriber. 165try { 166 CommonEventManager.createSubscriber(subscribeInfo, createCB); 167} catch (error) { 168 let err:Base.BusinessError = error as Base.BusinessError; 169 console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`); 170} 171``` 172 173## CommonEventManager.createSubscriber 174 175createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise\<CommonEventSubscriber> 176 177Creates a subscriber. This API uses a promise to return the result. 178 179**System capability**: SystemCapability.Notification.CommonEvent 180 181**Parameters** 182 183| Name | Type | Mandatory| Description | 184| ------------- | ----------------------------------------------------- | ---- | -------------- | 185| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes | Subscriber information.| 186 187**Return value** 188| Type | Description | 189| --------------------------------------------------------- | ---------------- | 190| Promise\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | Promise used to return the subscriber object.| 191 192**Example** 193 194```ts 195import Base from '@ohos.base'; 196 197let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. 198 199// Subscriber information. 200let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = { 201 events: ["event"] 202}; 203 204// Create a subscriber. 205CommonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber:CommonEventManager.CommonEventSubscriber) => { 206 console.info("createSubscriber"); 207 subscriber = commonEventSubscriber; 208}).catch((err:Base.BusinessError) => { 209 console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`); 210}); 211 212``` 213 214## CommonEventManager.createSubscriberSync<sup>10+</sup> 215 216createSubscriberSync(subscribeInfo: CommonEventSubscribeInfo): CommonEventSubscriber 217 218Creates a subscriber. The API returns the result synchronously. 219 220**System capability**: SystemCapability.Notification.CommonEvent 221 222**Parameters** 223 224| Name | Type | Mandatory| Description | 225| ------------- | ----------------------------------------------------- | ---- | -------------- | 226| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes | Subscriber information.| 227 228**Return value** 229| Type | Description | 230| --------------------------------------------------------- | ---------------- | 231| [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | Promise used to return the subscriber object.| 232 233**Example** 234 235```ts 236import Base from '@ohos.base'; 237 238let subscriber: CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. 239 240// Subscriber information. 241let subscribeInfo: CommonEventManager.CommonEventSubscribeInfo = { 242 events: ["event"] 243}; 244 245// Create a subscriber. 246try { 247 subscriber = CommonEventManager.createSubscriberSync(subscribeInfo); 248} catch (error) { 249 let err:Base.BusinessError = error as Base.BusinessError; 250 console.error(`createSubscriberSync failed, code is ${err.code}, message is ${err.message}`); 251} 252 253``` 254 255## CommonEventManager.subscribe 256 257subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback\<CommonEventData>): void 258 259Subscribes to common events. This API uses an asynchronous callback to return the result. 260 261**System capability**: SystemCapability.Notification.CommonEvent 262 263**Parameters** 264 265| Name | Type | Mandatory| Description | 266| ---------- | ---------------------------------------------------- | ---- | -------------------------------- | 267| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | Yes | Subscriber object. | 268| callback | AsyncCallback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | Yes | Callback used to return the result.| 269 270**Error codes** 271 272For details about the error codes, see [Event Error Codes](./errorcode-CommonEventService.md). 273 274| ID| Error Message | 275| -------- | ----------------------------------- | 276| 801 | capability not supported. | 277| 1500007 | error sending message to Common Event Service. | 278| 1500008 | Common Event Service does not complete initialization. | 279 280**Example** 281 282```ts 283import Base from '@ohos.base'; 284 285let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. 286 287// Subscriber information. 288let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = { 289 events: ["event"] 290}; 291 292// Callback for common event subscription. 293function SubscribeCB(err:Base.BusinessError, data:CommonEventManager.CommonEventData) { 294 if (err) { 295 console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`); 296 } else { 297 console.info("subscribe "); 298 } 299} 300 301// Callback for subscriber creation. 302function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) { 303 if(!err) { 304 console.info("createSubscriber"); 305 subscriber = commonEventSubscriber; 306 // Subscribe to a common event. 307 try { 308 CommonEventManager.subscribe(subscriber, SubscribeCB); 309 } catch (error) { 310 let err:Base.BusinessError = error as Base.BusinessError; 311 console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`); 312 } 313 } else { 314 console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`); 315 } 316} 317 318// Create a subscriber. 319try { 320 CommonEventManager.createSubscriber(subscribeInfo, createCB); 321} catch (error) { 322 let err:Base.BusinessError = error as Base.BusinessError; 323 console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`); 324} 325``` 326 327## CommonEventManager.unsubscribe 328 329unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\<void>): void 330 331Unsubscribes from common events. This API uses an asynchronous callback to return the result. 332 333**System capability**: SystemCapability.Notification.CommonEvent 334 335**Parameters** 336 337| Name | Type | Mandatory| Description | 338| ---------- | ----------------------------------------------- | ---- | ------------------------ | 339| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | Yes | Subscriber object. | 340| callback | AsyncCallback\<void> | No | Callback used to return the result.| 341 342**Error codes** 343 344For details about the error codes, see [Event Error Codes](./errorcode-CommonEventService.md). 345 346| ID| Error Message | 347| -------- | ----------------------------------- | 348| 801 | capability not supported. | 349| 1500007 | error sending message to Common Event Service. | 350| 1500008 | Common Event Service does not complete initialization. | 351 352**Example** 353 354```ts 355import Base from '@ohos.base'; 356 357let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. 358// Subscriber information. 359let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = { 360 events: ["event"] 361}; 362// Callback for common event subscription. 363function subscribeCB(err:Base.BusinessError, data:CommonEventManager.CommonEventData) { 364 if (err) { 365 console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`); 366 } else { 367 console.info("subscribe"); 368 } 369} 370// Callback for subscriber creation. 371function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) { 372 if (err) { 373 console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`); 374 } else { 375 console.info("createSubscriber"); 376 subscriber = commonEventSubscriber; 377 // Subscribe to a common event. 378 try { 379 CommonEventManager.subscribe(subscriber, subscribeCB); 380 } catch (error) { 381 let err:Base.BusinessError = error as Base.BusinessError; 382 console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`); 383 } 384 } 385} 386// Callback for common event unsubscription. 387function unsubscribeCB(err:Base.BusinessError) { 388 if (err) { 389 console.error(`unsubscribe failed, code is ${err.code}, message is ${err.message}`); 390 } else { 391 console.info("unsubscribe"); 392 } 393} 394// Create a subscriber. 395try { 396 CommonEventManager.createSubscriber(subscribeInfo, createCB); 397} catch (error) { 398 let err:Base.BusinessError = error as Base.BusinessError; 399 console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`); 400} 401 402// Unsubscribe from the common event. 403// Wait until execution of the asynchronous API subscribe is completed. Add setTimeout when necessary. 404setTimeout(() => { 405 try { 406 CommonEventManager.unsubscribe(subscriber, unsubscribeCB); 407 } catch (error) { 408 let err:Base.BusinessError = error as Base.BusinessError; 409 console.error(`unsubscribe failed, code is ${err.code}, message is ${err.message}`); 410 } 411}, 500); 412``` 413