@ohos.commonEventManager (Common Event)
The CommonEventManager module provides common event capabilities, including the capabilities to publish, subscribe to, and unsubscribe from common events.
NOTE
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.
Modules to Import
import CommonEventManager from '@ohos.commonEventManager';
Support
A 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.
For details about the definitions of all system common events, see System Common Events.
CommonEventManager.publish
publish(event: string, callback: AsyncCallback<void>): void
Publishes a common event and executes an asynchronous callback after the event is published.
System capability: SystemCapability.Notification.CommonEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Name of the common event to publish. |
callback | AsyncCallback<void> | Yes | Callback to execute after the event is published. |
Error codes
For details about the error codes, see Event Error Codes.
ID | Error Message |
---|---|
1500004 | not System services. |
1500007 | error sending message to Common Event Service. |
1500008 | Common Event Service does not complete initialization. |
1500009 | error obtaining system parameters. |
Example
import Base from '@ohos.base';
// Callback for common event publication
function publishCB(err:Base.BusinessError) {
if (err) {
console.error(`publish failed, code is ${err.code}, message is ${err.message}`);
} else {
console.info("publish");
}
}
// Publish a common event.
try {
CommonEventManager.publish("event", publishCB);
} catch (error) {
let err:Base.BusinessError = error as Base.BusinessError;
console.error(`publish failed, code is ${err.code}, message is ${err.message}`);
}
CommonEventManager.publish
publish(event: string, options: CommonEventPublishData, callback: AsyncCallback<void>): void
Publishes a common event with given attributes. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Notification.CommonEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
event | string | Yes | Name of the common event to publish. |
options | CommonEventPublishData | Yes | Attributes of the common event to publish. |
callback | syncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Event Error Codes.
ID | Error Message |
---|---|
1500004 | not System services. |
1500007 | error sending message to Common Event Service. |
1500008 | Common Event Service does not complete initialization. |
1500009 | error obtaining system parameters. |
Example
import Base from '@ohos.base';
// Attributes of a common event.
let options:CommonEventManager.CommonEventPublishData = {
code: 0, // Result code of the common event.
data: "initial data",// Result data of the common event.
isOrdered: true // The common event is an ordered one.
}
// Callback for common event publication
function publishCB(err:Base.BusinessError) {
if (err) {
console.error(`publish failed, code is ${err.code}, message is ${err.message}`);
} else {
console.info("publish");
}
}
// Publish a common event.
try {
CommonEventManager.publish("event", options, publishCB);
} catch (error) {
let err:Base.BusinessError = error as Base.BusinessError;
console.error(`publish failed, code is ${err.code}, message is ${err.message}`);
}
CommonEventManager.createSubscriber
createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback<CommonEventSubscriber>): void
Creates a subscriber. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Notification.CommonEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
subscribeInfo | CommonEventSubscribeInfo | Yes | Subscriber information. |
callback | AsyncCallback<CommonEventSubscriber> | Yes | Callback used to return the result. |
Example
import Base from '@ohos.base';
let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.
// Subscriber information.
let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
events: ["event"]
};
// Callback for subscriber creation.
function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
if(!err) {
console.info("createSubscriber");
subscriber = commonEventSubscriber;
} else {
console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
}
}
// Create a subscriber.
try {
CommonEventManager.createSubscriber(subscribeInfo, createCB);
} catch (error) {
let err:Base.BusinessError = error as Base.BusinessError;
console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
}
CommonEventManager.createSubscriber
createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise<CommonEventSubscriber>
Creates a subscriber. This API uses a promise to return the result.
System capability: SystemCapability.Notification.CommonEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
subscribeInfo | CommonEventSubscribeInfo | Yes | Subscriber information. |
Return value
Type | Description |
---|---|
Promise<CommonEventSubscriber> | Promise used to return the subscriber object. |
Example
import Base from '@ohos.base';
let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.
// Subscriber information.
let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
events: ["event"]
};
// Create a subscriber.
CommonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber:CommonEventManager.CommonEventSubscriber) => {
console.info("createSubscriber");
subscriber = commonEventSubscriber;
}).catch((err:Base.BusinessError) => {
console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
});
CommonEventManager.createSubscriberSync10+
createSubscriberSync(subscribeInfo: CommonEventSubscribeInfo): CommonEventSubscriber
Creates a subscriber. The API returns the result synchronously.
System capability: SystemCapability.Notification.CommonEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
subscribeInfo | CommonEventSubscribeInfo | Yes | Subscriber information. |
Return value
Type | Description |
---|---|
CommonEventSubscriber | Promise used to return the subscriber object. |
Example
import Base from '@ohos.base';
let subscriber: CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.
// Subscriber information.
let subscribeInfo: CommonEventManager.CommonEventSubscribeInfo = {
events: ["event"]
};
// Create a subscriber.
try {
subscriber = CommonEventManager.createSubscriberSync(subscribeInfo);
} catch (error) {
let err:Base.BusinessError = error as Base.BusinessError;
console.error(`createSubscriberSync failed, code is ${err.code}, message is ${err.message}`);
}
CommonEventManager.subscribe
subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback<CommonEventData>): void
Subscribes to common events. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Notification.CommonEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
subscriber | CommonEventSubscriber | Yes | Subscriber object. |
callback | AsyncCallback<CommonEventData> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Event Error Codes.
ID | Error Message |
---|---|
801 | capability not supported. |
1500007 | error sending message to Common Event Service. |
1500008 | Common Event Service does not complete initialization. |
Example
import Base from '@ohos.base';
let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.
// Subscriber information.
let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
events: ["event"]
};
// Callback for common event subscription.
function SubscribeCB(err:Base.BusinessError, data:CommonEventManager.CommonEventData) {
if (err) {
console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
} else {
console.info("subscribe ");
}
}
// Callback for subscriber creation.
function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
if(!err) {
console.info("createSubscriber");
subscriber = commonEventSubscriber;
// Subscribe to a common event.
try {
CommonEventManager.subscribe(subscriber, SubscribeCB);
} catch (error) {
let err:Base.BusinessError = error as Base.BusinessError;
console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
}
} else {
console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
}
}
// Create a subscriber.
try {
CommonEventManager.createSubscriber(subscribeInfo, createCB);
} catch (error) {
let err:Base.BusinessError = error as Base.BusinessError;
console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
}
CommonEventManager.unsubscribe
unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback<void>): void
Unsubscribes from common events. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Notification.CommonEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
subscriber | CommonEventSubscriber | Yes | Subscriber object. |
callback | AsyncCallback<void> | No | Callback used to return the result. |
Error codes
For details about the error codes, see Event Error Codes.
ID | Error Message |
---|---|
801 | capability not supported. |
1500007 | error sending message to Common Event Service. |
1500008 | Common Event Service does not complete initialization. |
Example
import Base from '@ohos.base';
let subscriber:CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.
// Subscriber information.
let subscribeInfo:CommonEventManager.CommonEventSubscribeInfo = {
events: ["event"]
};
// Callback for common event subscription.
function subscribeCB(err:Base.BusinessError, data:CommonEventManager.CommonEventData) {
if (err) {
console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
} else {
console.info("subscribe");
}
}
// Callback for subscriber creation.
function createCB(err:Base.BusinessError, commonEventSubscriber:CommonEventManager.CommonEventSubscriber) {
if (err) {
console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
} else {
console.info("createSubscriber");
subscriber = commonEventSubscriber;
// Subscribe to a common event.
try {
CommonEventManager.subscribe(subscriber, subscribeCB);
} catch (error) {
let err:Base.BusinessError = error as Base.BusinessError;
console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
}
}
}
// Callback for common event unsubscription.
function unsubscribeCB(err:Base.BusinessError) {
if (err) {
console.error(`unsubscribe failed, code is ${err.code}, message is ${err.message}`);
} else {
console.info("unsubscribe");
}
}
// Create a subscriber.
try {
CommonEventManager.createSubscriber(subscribeInfo, createCB);
} catch (error) {
let err:Base.BusinessError = error as Base.BusinessError;
console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`);
}
// Unsubscribe from the common event.
// Wait until execution of the asynchronous API subscribe is completed. Add setTimeout when necessary.
setTimeout(() => {
try {
CommonEventManager.unsubscribe(subscriber, unsubscribeCB);
} catch (error) {
let err:Base.BusinessError = error as Base.BusinessError;
console.error(`unsubscribe failed, code is ${err.code}, message is ${err.message}`);
}
}, 500);