@ohos.commonEventManager (Common Event)

The CommonEventManager 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.

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. 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.
callback AsyncCallback<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 or System app.
1500007 error sending message to Common Event Service.
1500008 Common Event Service does not complete initialization.
1500009 error obtaining system parameters.

Example

// Callback for common event publication
function publishCallBack(err) {
	if (err) {
        console.error("publish failed " + JSON.stringify(err));
    } else {
        console.info("publish");
    }
}

// Publish a common event.
try {
    CommonEventManager.publish("event", publishCallBack);
} catch(err) {
    console.error('publish failed, catch error' + JSON.stringify(err));
}

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

ID Error Message
1500004 not System services or System app.
1500007 error sending message to Common Event Service.
1500008 Common Event Service does not complete initialization.
1500009 error obtaining system parameters.

Example

// Attributes of a common event.
var options = {
	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 publishCallBack(err) {
	if (err) {
        console.error("publish failed " + JSON.stringify(err));
    } else {
        console.info("publish");
    }
}

// Publish a common event.
try {
    CommonEventManager.publish("event", options, publishCallBack);
} catch (err) {
    console.error('publish failed, catch error' + JSON.stringify(err));
}

CommonEventManager.publishAsUser

publishAsUser(event: string, userId: number, callback: AsyncCallback<void>): void

Publishes a common event to a specific user. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.CommonEvent

System API: This is a system API and cannot be called by third-party applications.

Parameters

Name Type Mandatory Description
event string Yes Name of the common event to publish.
userId number Yes User ID.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

ID Error Message
1500004 not System services or System app.
1500007 error sending message to Common Event Service.
1500008 Common Event Service does not complete initialization.
1500009 error obtaining system parameters.

Example

// Callback for common event publication
function publishAsUserCallBack(err) {
	if (err) {
        console.error("publishAsUser failed " + JSON.stringify(err));
    } else {
        console.info("publishAsUser");
    }
}

// Specify the user to whom the common event will be published.
var userId = 100;

// Publish a common event.
try {
    CommonEventManager.publishAsUser("event", userId, publishAsUserCallBack);
} catch (err) {
    console.error('publishAsUser failed, catch error' + JSON.stringify(err));
}

CommonEventManager.publishAsUser

publishAsUser(event: string, userId: number, options: CommonEventPublishData, callback: AsyncCallback<void>): void

Publishes a common event with given attributes to a specific user. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.CommonEvent

System API: This is a system API and cannot be called by third-party applications.

Parameters

Name Type Mandatory Description
event string Yes Name of the common event to publish.
userId number Yes User ID.
options CommonEventPublishData Yes Attributes of the common event to publish.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

ID Error Message
1500004 not System services or System app.
1500007 error sending message to Common Event Service.
1500008 Common Event Service does not complete initialization.
1500009 error obtaining system parameters.

Example

// Attributes of a common event.
var options = {
	code: 0,			 // Result code of the common event.
	data: "initial data",// Result data of the common event.
}

// Callback for common event publication
function publishAsUserCallBack(err) {
	if (err) {
        console.error("publishAsUser failed " + JSON.stringify(err));
    } else {
        console.info("publishAsUser");
    }
}

// Specify the user to whom the common event will be published.
var userId = 100;

// Publish a common event.
try {
    CommonEventManager.publishAsUser("event", userId, options, publishAsUserCallBack);
} catch (err) {
    console.error('publishAsUser failed, catch error' + JSON.stringify(err));
}

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

var subscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.

// Subscriber information.
var subscribeInfo = {
    events: ["event"]
};

// Callback for subscriber creation.
function createSubscriberCallBack(err, commonEventSubscriber) {
    if(!err) {
        console.info("createSubscriber");
        subscriber = commonEventSubscriber;
    } else {
        console.error("createSubscriber failed " + JSON.stringify(err));
    }
}

// Create a subscriber.
try {
    CommonEventManager.createSubscriber(subscribeInfo, createSubscriberCallBack);
} catch (err) {
    console.error('createSubscriber failed, catch error' + JSON.stringify(err));
}

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

var subscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.

// Subscriber information.
var subscribeInfo = {
	events: ["event"]
};

// Create a subscriber.
try {
    CommonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber) => {
    console.info("createSubscriber");
    subscriber = commonEventSubscriber;
}).catch((err) => {
    console.error("createSubscriber failed " + JSON.stringify(err));
});
} catch(err) {
    console.error('createSubscriber failed, catch error' + JSON.stringify(err));
}

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

// Subscriber information.
var subscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.

// Subscriber information.
var subscribeInfo = {
    events: ["event"]
};

// Callback for common event subscription.
function SubscribeCallBack(err, data) {
    if (err) {
        console.error("subscribe failed " + JSON.stringify(err));
    } else {
        console.info("subscribe ");
    }
}

// Callback for subscriber creation.
function createSubscriberCallBack(err, commonEventSubscriber) {
    if(!err) {
        console.info("createSubscriber");
        subscriber = commonEventSubscriber;
        // Subscribe to a common event.
        try {
            CommonEventManager.subscribe(subscriber, SubscribeCallBack);
        } catch (err) {
            console.error("createSubscriber failed " + JSON.stringify(err));
        }
    } else {
        console.error("createSubscriber failed " + JSON.stringify(err));
    }
}

// Create a subscriber.
try {
    CommonEventManager.createSubscriber(subscribeInfo, createSubscriberCallBack);
} catch (err) {
    console.error('createSubscriber failed, catch error' + JSON.stringify(err));
}

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

var subscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.
// Subscriber information.
var subscribeInfo = {
    events: ["event"]
};
// Callback for common event subscription.
function subscribeCallBack(err, data) {
    if (err) {
        console.info("subscribe failed " + JSON.stringify(err));
    } else {
        console.info("subscribe");
    }
}
// Callback for subscriber creation.
function createSubscriberCallBack(err, commonEventSubscriber) {
    if (err) {
        console.info("createSubscriber failed " + JSON.stringify(err));
    } else {
        console.info("createSubscriber");
        subscriber = commonEventSubscriber;
        // Subscribe to a common event.
        try {
            CommonEventManager.subscribe(subscriber, subscribeCallBack);
        } catch(err) {
            console.info("subscribe failed " + JSON.stringify(err));
        }
    }
}
// Callback for common event unsubscription.
function unsubscribeCallBack(err) {
    if (err) {
        console.info("unsubscribe failed " + JSON.stringify(err));
    } else {
        console.info("unsubscribe");
    }
}
// Create a subscriber.
try {
    CommonEventManager.createSubscriber(subscribeInfo, createSubscriberCallBack);
} catch (err) {
    console.info("createSubscriber failed " + JSON.stringify(err));
}

// Unsubscribe from the common event.
try {
    CommonEventManager.unsubscribe(subscriber, unsubscribeCallBack);
} catch (err) {
    console.info("unsubscribe failed " + JSON.stringify(err));
}

CommonEventData

System capability: SystemCapability.Notification.CommonEvent

Name Type Readable Writable Description
event string Yes No Name of the common event that is being received.
bundleName string Yes No Bundle name.
code number Yes No Result code of the common event, which is used to transfer data of the int type.
data string Yes No Custom result data of the common event, which is used to transfer data of the string type.
parameters {[key: string]: any} Yes No Additional information about the common event.

CommonEventPublishData

System capability: SystemCapability.Notification.CommonEvent

Name Type Readable Writable Description
bundleName string Yes No Bundle name.
code number Yes No Result code of the common event.
data string Yes No Custom result data of the common event.
subscriberPermissions Array<string> Yes No Permissions required for subscribers to receive the common event.
isOrdered boolean Yes No Whether the common event is an ordered one.
isSticky boolean Yes No Whether the common event is a sticky one. Only system applications and system services are allowed to send sticky events.
parameters {[key: string]: any} Yes No Additional information about the common event.

CommonEventSubscribeInfo

System capability: SystemCapability.Notification.CommonEvent

Name Type Readable Writable Description
events Array<string> Yes No Name of the common event to publish.
publisherPermission string Yes No Permissions required for publishers to publish the common event.
publisherDeviceId string Yes No Device ID. The value must be the ID of an existing device on the same network.
userId number Yes No User ID. The default value is the ID of the current user. If this parameter is specified, the value must be an existing user ID in the system.
priority number Yes No Subscriber priority. The value ranges from -100 to +1000.