1# @ohos.commonEvent (Common Event)
2
3The **CommonEvent** module provides common event capabilities, including the capabilities to publish, subscribe to, and unsubscribe from common events, as well obtaining and setting the common event result code and result data.
4
5> **NOTE**
6> - The APIs provided by this module are no longer maintained since API version 9. You are advised to use [@ohos.commonEventManager](js-apis-commonEventManager.md).
7>
8> - 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.
9
10## Modules to Import
11
12```ts
13import CommonEvent from '@ohos.commonEvent';
14```
15
16## Support
17
18A 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.
19
20For details about the definitions of all system common events, see [System Common Events](./common_event/commonEvent-definitions.md).
21
22## CommonEvent.publish<sup>(deprecated)</sup>
23
24publish(event: string, callback: AsyncCallback\<void>): void
25
26Publishes a common event. This API uses an asynchronous callback to return the result.
27
28> **NOTE**<br>
29> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [commonEventManager.publish](js-apis-commonEventManager.md#commoneventmanagerpublish) instead.
30
31**System capability**: SystemCapability.Notification.CommonEvent
32
33**Parameters**
34
35| Name    | Type                | Mandatory| Description                  |
36| -------- | -------------------- | ---- | ---------------------- |
37| event    | string               | Yes  | Name of the common event to publish.|
38| callback | AsyncCallback\<void> | Yes  | Callback used to return the result.|
39
40**Example**
41
42```ts
43import Base from '@ohos.base';
44
45// Callback for common event publication
46function publishCB(err:Base.BusinessError) {
47	if (err.code) {
48        console.error(`publish failed, code is ${err.code}`);
49    } else {
50        console.info("publish");
51    }
52}
53
54// Publish a common event.
55CommonEvent.publish("event", publishCB);
56```
57
58## CommonEvent.publish<sup>(deprecated)</sup>
59
60publish(event: string, options: CommonEventPublishData, callback: AsyncCallback\<void>): void
61
62Publishes a common event with given attributes. This API uses an asynchronous callback to return the result.
63
64> **NOTE**<br>
65> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [commonEventManager.publish](js-apis-commonEventManager.md#commoneventmanagerpublish-1) instead.
66
67**System capability**: SystemCapability.Notification.CommonEvent
68
69**Parameters**
70
71| Name    | Type                  | Mandatory| Description                  |
72| -------- | ---------------------- | ---- | ---------------------- |
73| event    | string                 | Yes  | Name of the common event to publish. |
74| options  | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | Yes  | Attributes of the common event to publish.|
75| callback | AsyncCallback\<void>   | Yes  | Callback used to return the result. |
76
77**Example**
78
79
80```ts
81import Base from '@ohos.base';
82import CommonEventManager from '@ohos.commonEventManager';
83
84// Attributes of a common event.
85let options:CommonEventManager.CommonEventPublishData = {
86	code: 0,			 // Result code of the common event.
87	data: "initial data";// Result data of the common event.
88	isOrdered: true	 // The common event is an ordered one.
89}
90
91// Callback for common event publication
92function publishCB(err:Base.BusinessError) {
93	if (err.code) {
94        console.error(`publish failed, code is ${err.code}`);
95    } else {
96        console.info("publish");
97    }
98}
99
100// Publish a common event.
101CommonEvent.publish("event", options, publishCB);
102```
103
104## CommonEvent.createSubscriber<sup>(deprecated)</sup>
105
106createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback\<CommonEventSubscriber>): void
107
108Creates a subscriber. This API uses an asynchronous callback to return the result.
109
110> **NOTE**<br>
111>This API is supported since API version 7 and deprecated since API version 9. You are advised to use [commonEventManager.createSubscriber](js-apis-commonEventManager.md#commoneventmanagercreatesubscriber) instead.
112
113**System capability**: SystemCapability.Notification.CommonEvent
114
115**Parameters**
116
117| Name         | Type                                                        | Mandatory| Description                      |
118| ------------- | ------------------------------------------------------------ | ---- | -------------------------- |
119| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)        | Yes  | Subscriber information.            |
120| callback      | AsyncCallback\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | Yes  | Callback used to return the result.|
121
122**Example**
123
124
125```ts
126import Base from '@ohos.base';
127import CommonEventManager from '@ohos.commonEventManager';
128
129let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.
130
131// Subscriber information.
132let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
133    events: ["event"]
134};
135
136// Callback for subscriber creation.
137function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
138    if (err.code) {
139        console.error(`createSubscriber failed, code is ${err.code}`);
140    } else {
141        console.info("createSubscriber");
142        subscriber = commonEventSubscriber;
143    }
144}
145
146// Create a subscriber.
147CommonEvent.createSubscriber(subscribeInfo, createCB);
148```
149
150## CommonEvent.createSubscriber<sup>(deprecated)</sup>
151
152createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise\<CommonEventSubscriber>
153
154Creates a subscriber. This API uses a promise to return the result.
155
156> **NOTE**<br>
157>This API is supported since API version 7 and deprecated since API version 9. You are advised to use [commonEventManager.createSubscriber](js-apis-commonEventManager.md#commoneventmanagercreatesubscriber-1) instead.
158
159**System capability**: SystemCapability.Notification.CommonEvent
160
161**Parameters**
162
163| Name         | Type                                                 | Mandatory| Description          |
164| ------------- | ----------------------------------------------------- | ---- | -------------- |
165| subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes  | Subscriber information.|
166
167**Return value**
168| Type                                                     | Description            |
169| --------------------------------------------------------- | ---------------- |
170| Promise\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)> | Promise used to return the subscriber object.|
171
172**Example**
173
174```ts
175import Base from '@ohos.base';
176import CommonEventManager from '@ohos.commonEventManager';
177
178let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.
179
180// Subscriber information.
181let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
182    events: ["event"]
183};
184
185// Create a subscriber.
186CommonEvent.createSubscriber(subscribeInfo).then((commonEventSubscriber:CommonEventManager.CommonEventSubscriber) => {
187    console.info("createSubscriber");
188    subscriber = commonEventSubscriber;
189}).catch((err:Base.BusinessError) => {
190    console.error(`createSubscriber failed, code is ${err.code}`);
191});
192```
193
194## CommonEvent.subscribe<sup>(deprecated)</sup>
195
196subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback\<CommonEventData>): void
197
198Subscribes to common events. This API uses an asynchronous callback to return the result.
199
200> **NOTE**<br>
201>This API is supported since API version 7 and deprecated since API version 9. You are advised to use [commonEventManager.subscribe](js-apis-commonEventManager.md#commoneventmanagersubscribe) instead.
202
203**System capability**: SystemCapability.Notification.CommonEvent
204
205**Parameters**
206
207| Name      | Type                                               | Mandatory| Description                            |
208| ---------- | ---------------------------------------------------- | ---- | -------------------------------- |
209| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md)     | Yes  | Subscriber object.                |
210| callback   | AsyncCallback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | Yes  | Callback used to return the result.|
211
212**Example**
213
214```ts
215import Base from '@ohos.base';
216import CommonEventManager from '@ohos.commonEventManager';
217
218let subscriber:CommonEventManager.CommonEventSubscriber;// Used to save the created subscriber object for subsequent subscription and unsubscription.
219
220// Subscriber information.
221let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
222    events: ["event"]
223};
224
225// Callback for common event subscription.
226function subscribeCB(err:Base.BusinessError, data:CommonEventManager.CommonEventData) {
227    if (err.code) {
228        console.error(`subscribe failed, code is ${err.code}`);
229    } else {
230        console.info("subscribe " + JSON.stringify(data));
231    }
232}
233
234// Callback for subscriber creation.
235function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
236    if (err.code) {
237        console.error(`createSubscriber failed, code is ${err.code}`);
238    } else {
239        console.info("createSubscriber");
240        subscriber = commonEventSubscriber;
241        // Subscribe to a common event.
242        CommonEvent.subscribe(subscriber, subscribeCB);
243    }
244}
245
246// Create a subscriber.
247CommonEvent.createSubscriber(subscribeInfo, createCB);
248```
249
250## CommonEvent.unsubscribe<sup>(deprecated)</sup>
251
252unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\<void>): void
253
254Unsubscribes from common events. This API uses an asynchronous callback to return the result.
255
256> **NOTE**<br>
257>This API is supported since API version 7 and deprecated since API version 9. You are advised to use [commonEventManager.subscribe](js-apis-commonEventManager.md#commoneventmanagerunsubscribe) instead.
258
259**System capability**: SystemCapability.Notification.CommonEvent
260
261**Parameters**
262
263| Name      | Type                                            | Mandatory| Description                    |
264| ---------- | ----------------------------------------------- | ---- | ------------------------ |
265| subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md) | Yes  | Subscriber object.        |
266| callback   | AsyncCallback\<void>                            | No  | Callback used to return the result.|
267
268**Example**
269
270```ts
271import Base from '@ohos.base';
272import CommonEventManager from '@ohos.commonEventManager';
273
274let subscriber:CommonEventManager.CommonEventSubscriber;	// Used to save the created subscriber object for subsequent subscription and unsubscription.
275
276// Subscriber information.
277let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
278    events: ["event"]
279};
280
281// Callback for common event subscription.
282function subscribeCB(err:Base.BusinessError, data:CommonEventManager.CommonEventData) {
283    if (err.code) {
284        console.error(`subscribe failed, code is ${err.code}`);
285    } else {
286        console.info("subscribe " + JSON.stringify(data));
287    }
288}
289
290// Callback for subscriber creation.
291function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
292    if (err.code) {
293        console.error(`createSubscriber failed, code is ${err.code}`);
294    } else {
295        console.info("createSubscriber");
296        subscriber = commonEventSubscriber;
297        // Subscribe to a common event.
298        CommonEvent.subscribe(subscriber, subscribeCB);
299    }
300}
301
302// Callback for common event unsubscription.
303function unsubscribeCB(err:Base.BusinessError) {
304    if (err.code) {
305        console.error(`unsubscribe failed, code is ${err.code}`);
306    } else {
307        console.info("unsubscribe");
308    }
309}
310
311// Create a subscriber.
312CommonEvent.createSubscriber(subscribeInfo, createCB);
313
314// Unsubscribe from the common event.
315CommonEvent.unsubscribe(subscriber, unsubscribeCB);
316```
317