@ohos.commonEventManager (Common Event)

The CommonEventManager module provides common event 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 '@kit.BasicServicesKit';

Support

System common events refer to events released by system services or system applications. Subscribing to these common events requires specific permissions and values. For details, 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.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.CommonEvent

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Name of the common event to publish. For details, see System Common Events.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Event Error Codes.

ID	Error Message
1500003	The common event sending frequency too high.
1500007	Failed to send the message to the common event service.
1500008	Failed to initialize the common event service.
1500009	Failed to obtain system parameters.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Publish a common event.
try {
  commonEventManager.publish('event', (err: BusinessError) => {
    if (err) {
      console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`);
      return;
    }
    console.info(`Succeeded in publishing common event.`);
  });
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`);
}

commonEventManager.publish

publish(event: string, options: CommonEventPublishData, callback: AsyncCallback<void>): void

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

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.CommonEvent

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Name of the common event to publish. For details, see System Common Events.
options	CommonEventPublishData	Yes	Properties of the common event to publish.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Event Error Codes.

ID	Error Message
1500003	The common event sending frequency too high.
1500007	Failed to send the message to the common event service.
1500008	Failed to initialize the common event service.
1500009	Failed to obtain system parameters.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Common event information. The following uses an ordered common event as an example.
let options: commonEventManager.CommonEventPublishData = {
  code: 0,
  data: 'initial data',
  isOrdered: true // The common event is an ordered one.
}

// Publish a common event.
try {
  commonEventManager.publish('event', options, (err: BusinessError) => {
    if (err) {
      console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`);
      return;
    }
    console.info(`Succeeded in publishing common event.`);
  });
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to publish common event. 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.

Atomic service API: This API can be used in atomic services since API version 11.

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. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription.
let subscriber: commonEventManager.CommonEventSubscriber | null = null;
// Subscriber information.
let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
  events: ['event']
};

// Create a subscriber.
try {
  commonEventManager.createSubscriber(subscribeInfo,
    (err: BusinessError, commonEventSubscriber: commonEventManager.CommonEventSubscriber) => {
      if(!err) {
        console.info(`Succeeded in creating subscriber.`);
        subscriber = commonEventSubscriber;
        return;
      }
      console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
    });
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to create subscriber. 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.

Atomic service API: This API can be used in atomic services since API version 11.

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 created subscriber object.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription.
let subscriber: commonEventManager.CommonEventSubscriber | null = null;
// Subscriber information.
let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
  events: ['event']
};
// Create a subscriber.
commonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber: commonEventManager.CommonEventSubscriber) => {
  console.info(`Succeeded in creating subscriber.`);
  subscriber = commonEventSubscriber;
}).catch((err: BusinessError) => {
  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
});

commonEventManager.createSubscriberSync¹⁰⁺

createSubscriberSync(subscribeInfo: CommonEventSubscribeInfo): CommonEventSubscriber

Creates a subscriber. The API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 11.

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.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription.
let subscriber: commonEventManager.CommonEventSubscriber | null = null;
// Subscriber information.
let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
  events: ['event']
};
// Create a subscriber.
try {
  subscriber = commonEventManager.createSubscriberSync(subscribeInfo);
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
}

commonEventManager.subscribe

subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback<CommonEventData>): void

Subscribes to a common event. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.CommonEvent

Parameters

Name	Type	Mandatory	Description
subscriber	CommonEventSubscriber	Yes	Subscriber object.
callback	AsyncCallback<CommonEventData>	Yes	Callback triggered if the operation is successful; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Event Error Codes.

ID	Error Message
801	capability not supported.
1500007	Failed to send the message to the common event service.
1500008	Failed to initialize the common event service.
1500010	The count of subscriber exceed system specification.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription.
let subscriber: commonEventManager.CommonEventSubscriber | null = null;
// Subscriber information.
let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
  events: ['event']
};

// Create a subscriber.
try {
  commonEventManager.createSubscriber(subscribeInfo,
    (err: BusinessError, commonEventSubscriber: commonEventManager.CommonEventSubscriber) => {
      if(!err) {
        console.info(`Succeeded in creating subscriber.`);
        subscriber = commonEventSubscriber;
        // Subscribe to a common event.
        try {
          commonEventManager.subscribe(subscriber, (err: BusinessError, data: commonEventManager.CommonEventData) => {
            if (err) {
              console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
              return;
            }
            console.info(`Succeeded in subscribing, data is ${JSON.stringify(data)}`);
          });
        } catch (error) {
          let err: BusinessError = error as BusinessError;
          console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
        }
        return;
      }
      console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
    });
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
}

commonEventManager.unsubscribe

unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback<void>): void

Unsubscribes from a common event. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.CommonEvent

Parameters

Name	Type	Mandatory	Description
subscriber	CommonEventSubscriber	Yes	Subscriber object.
callback	AsyncCallback<void>	No	Callback to unregister. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Event Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	capability not supported.
1500007	Failed to send the message to the common event service.
1500008	Failed to initialize the common event service.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription.
let subscriber: commonEventManager.CommonEventSubscriber | null = null;
// Subscriber information.
let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
  events: ['event']
};

// Create a subscriber.
try {
  commonEventManager.createSubscriber(subscribeInfo,
    (err: BusinessError, commonEventSubscriber: commonEventManager.CommonEventSubscriber) => {
      if(!err) {
        console.info(`Succeeded in creating subscriber.`);
        subscriber = commonEventSubscriber;
        // Subscribe to a common event.
        try {
          commonEventManager.subscribe(subscriber, (err: BusinessError, data: commonEventManager.CommonEventData) => {
            if (err) {
              console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
              return;
            }
            console.info(`Succeeded in subscribing, data is ${JSON.stringify(data)}`);
          });
        } catch (error) {
          let err: BusinessError = error as BusinessError;
          console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
        }
        return;
      }
      console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
    });
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to create subscriber. 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, (err: BusinessError) => {
      if (err) {
        console.error(`Failed to unsubscribe. Code is ${err.code}, message is ${err.message}`);
        return;
      }
      // If the subscriber is no longer used, set it to null to avoid memory leakage.
      subscriber = null;
      console.info(`Succeeded in unsubscribing.`);
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`Failed to unsubscribe. Code is ${err.code}, message is ${err.message}`);
  }
}, 500);

commonEventManager.subscribeToEvent²⁰⁺

subscribeToEvent(subscriber: CommonEventSubscriber, callback: Callback<CommonEventData>): Promise<void>

Subscribes to a common event. This API uses a promise to return the result, indicating subscription success or failure.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Notification.CommonEvent

Parameters

Name	Type	Mandatory	Description
subscriber	CommonEventSubscriber	Yes	Subscriber object.
callback	Callback<CommonEventData>	Yes	Callback to be invoked when a common event is subscribed to.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Event Error Codes.

ID	Error Message
801	Capability not supported.
1500007	Failed to send the message to the common event service.
1500008	Failed to initialize the common event service.
1500010	The count of subscriber exceed system specification.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription.
let subscriber: commonEventManager.CommonEventSubscriber | null = null;
// Subscriber information.
let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = {
  events: ["event"]
};

// Create a subscriber.
try {
  commonEventManager.createSubscriber(subscribeInfo,
    (err: BusinessError, commonEventSubscriber: commonEventManager.CommonEventSubscriber) => {
      if (err) {
        console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
      } else {
        console.info(`Succeeded in creating subscriber.`);
        subscriber = commonEventSubscriber;
        // Subscribe to a common event.
        try {
          commonEventManager.subscribeToEvent(subscriber, (data: commonEventManager.CommonEventData) => {
            console.info(`Succeeded to receive common event, data is ` + JSON.stringify(data));
          }).then(() => {
            console.info(`Succeeded to subscribe.`);
          }).catch((err: BusinessError) => {
            console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
          });
        } catch (error) {
          let err: BusinessError = error as BusinessError;
          console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`);
        }
      }
    });
} catch (error) {
  let err: BusinessError = error as BusinessError;
  console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`);
}

CommonEventData¹⁰⁺

type CommonEventData = _CommonEventData

Describes the data of a common event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.CommonEvent

Type	Description
_CommonEventData	Data of a common event.

CommonEventSubscriber¹⁰⁺

type CommonEventSubscriber = _CommonEventSubscriber

Describes the subscriber of a common event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.CommonEvent

Type	Description
_CommonEventSubscriber	Subscriber of a common event.

CommonEventSubscribeInfo¹⁰⁺

type CommonEventSubscribeInfo = _CommonEventSubscribeInfo

Describes the information about a subscriber.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.CommonEvent

Type	Description
_CommonEventSubscribeInfo	Information about a subscriber.

CommonEventPublishData¹⁰⁺

type CommonEventPublishData = _CommonEventPublishData

Describes the content and properties of a common event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Notification.CommonEvent

Type	Description
_CommonEventPublishData	Content and properties of a common event.

@ohos.commonEventManager (Common Event)

Modules to Import

Support

commonEventManager.publish

commonEventManager.publish

commonEventManager.createSubscriber

commonEventManager.createSubscriber

commonEventManager.createSubscriberSync10+

commonEventManager.subscribe

commonEventManager.unsubscribe

commonEventManager.subscribeToEvent20+

CommonEventData10+

CommonEventSubscriber10+

CommonEventSubscribeInfo10+

CommonEventPublishData10+

commonEventManager.createSubscriberSync¹⁰⁺

commonEventManager.subscribeToEvent²⁰⁺

CommonEventData¹⁰⁺

CommonEventSubscriber¹⁰⁺

CommonEventSubscribeInfo¹⁰⁺

CommonEventPublishData¹⁰⁺