@ohos.notificationSubscribe (NotificationSubscribe)

The notificationSubscribe module provides APIs for notification subscription, notification unsubscription, subscription removal, and more. In general cases, only system applications can call these APIs.

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.

The APIs provided by this module are system APIs.

Modules to Import

import notificationSubscribe from '@ohos.notificationSubscribe';

notificationSubscribe.subscribe

subscribe(subscriber: NotificationSubscriber, info: NotificationSubscribeInfo, callback: AsyncCallback<void>): void

Subscribes to a notification with the subscription information specified. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
subscriber NotificationSubscriber Yes Notification subscriber.
info NotificationSubscribeInfo No Notification subscription information.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
1600012 No memory space.

Example

import Base from '@ohos.base';

// subscribe callback
let subscribeCallback = (err: Base.BusinessError) => {
  if (err) {
    console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info("subscribe success");
  }
}
let onConsumeCallback = (data: notificationSubscribe.SubscribeCallbackData) => {
  console.info("Consume callback: " + JSON.stringify(data));
}
let subscriber: notificationSubscribe.NotificationSubscriber = {
  onConsume: onConsumeCallback
};
// Bundle names are not verified. You need to determine the target bundle names.
let info: notificationSubscribe.NotificationSubscribeInfo = {
  bundleNames: ["bundleName1","bundleName2"]
};
notificationSubscribe.subscribe(subscriber, info, subscribeCallback);

notificationSubscribe.subscribe

subscribe(subscriber: NotificationSubscriber, callback: AsyncCallback<void>): void

Subscribes to notifications of all applications under this user. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
subscriber NotificationSubscriber Yes Notification subscriber.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
1600012 No memory space.

Example

import Base from '@ohos.base';

let subscribeCallback = (err: Base.BusinessError) => {
  if (err) {
    console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info("subscribe success");
  }
}
let onConsumeCallback = (data: notificationSubscribe.SubscribeCallbackData) => {
  console.info("Consume callback: " + JSON.stringify(data));
}
let subscriber: notificationSubscribe.NotificationSubscriber = {
  onConsume: onConsumeCallback
};
notificationSubscribe.subscribe(subscriber, subscribeCallback);

notificationSubscribe.subscribe

subscribe(subscriber: NotificationSubscriber, info?: NotificationSubscribeInfo): Promise<void>

Subscribes to a notification with the subscription information specified. This API uses a promise to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
subscriber NotificationSubscriber Yes Notification subscriber.
info NotificationSubscribeInfo No Notification subscription information. By default, this parameter is left empty, which means to subscribe to notifications of all applications under this user.

Return value

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

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
1600012 No memory space.

Example

import Base from '@ohos.base';

let onConsumeCallback = (data: notificationSubscribe.SubscribeCallbackData) => {
  console.info("Consume callback: " + JSON.stringify(data));
}
let subscriber: notificationSubscribe.NotificationSubscriber = {
  onConsume: onConsumeCallback
};
notificationSubscribe.subscribe(subscriber).then(() => {
  console.info("subscribe success");
}).catch((err: Base.BusinessError) => {
  console.error("subscribe fail: " + JSON.stringify(err));
});

notificationSubscribe.unsubscribe

unsubscribe(subscriber: NotificationSubscriber, callback: AsyncCallback<void>): void

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

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
subscriber NotificationSubscriber Yes Notification subscriber.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.

Example

import Base from '@ohos.base';

let unsubscribeCallback = (err: Base.BusinessError) => {
  if (err) {
    console.error(`unsubscribe failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info("unsubscribe success");
  }
}
let onDisconnectCallback = () => {
  console.info("subscribe disconnect");
}
let subscriber: notificationSubscribe.NotificationSubscriber = {
  onDisconnect: onDisconnectCallback
};
notificationSubscribe.unsubscribe(subscriber, unsubscribeCallback);

notificationSubscribe.unsubscribe

unsubscribe(subscriber: NotificationSubscriber): Promise<void>

Unsubscribes from a notification. This API uses a promise to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
subscriber NotificationSubscriber Yes Notification subscriber.

Return value

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

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.

Example

import Base from '@ohos.base';

let onDisconnectCallback = () => {
  console.info("subscribe disconnect");
}
let subscriber: notificationSubscribe.NotificationSubscriber = {
  onDisconnect: onDisconnectCallback
};
notificationSubscribe.unsubscribe(subscriber).then(() => {
  console.info("unsubscribe success");
}).catch((err: Base.BusinessError) => {
  console.error("unsubscribe fail: " + JSON.stringify(err));
});

notificationSubscribe.remove

remove(bundle: BundleOption, notificationKey: NotificationKey, reason: RemoveReason, callback: AsyncCallback<void>): void

Removes a notification based on the bundle information and notification key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
bundle BundleOption Yes Bundle information of the application.
notificationKey NotificationKey Yes Notification key.
reason RemoveReason Yes Reason for removing the notification.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
1600007 The notification is not exist.
17700001 The specified bundle name was not found.

Example

import Base from '@ohos.base';
import NotificationManager from '@ohos.notificationManager';

let removeCallback = (err: Base.BusinessError) => {
  if (err) {
    console.error(`remove failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info("remove success");
  }
}
let bundle: NotificationManager.BundleOption = {
  bundle: "bundleName1",
};
let notificationKey: notificationSubscribe.NotificationKey = {
  id: 0,
  label: "label",
};
let reason: notificationSubscribe.RemoveReason = notificationSubscribe.RemoveReason.CLICK_REASON_REMOVE;
notificationSubscribe.remove(bundle, notificationKey, reason, removeCallback);

notificationSubscribe.remove

remove(bundle: BundleOption, notificationKey: NotificationKey, reason: RemoveReason): Promise<void>

Removes a notification based on the specified bundle information and notification key. This API uses a promise to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
bundle BundleOption Yes Bundle information of the application.
notificationKey NotificationKey Yes Notification key.
reason RemoveReason Yes Reason for removing the notification.

Return value

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

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
1600007 The notification is not exist.
17700001 The specified bundle name was not found.

Example

import Base from '@ohos.base';
import NotificationManager from '@ohos.notificationManager';

let bundle: NotificationManager.BundleOption = {
  bundle: "bundleName1",
};
let notificationKey: notificationSubscribe.NotificationKey = {
  id: 0,
  label: "label",
};
let reason: notificationSubscribe.RemoveReason = notificationSubscribe.RemoveReason.CLICK_REASON_REMOVE;
notificationSubscribe.remove(bundle, notificationKey, reason).then(() => {
  console.info("remove success");
}).catch((err: Base.BusinessError) => {
  console.error("remove fail: " + JSON.stringify(err));
});

notificationSubscribe.remove

remove(hashCode: string, reason: RemoveReason, callback: AsyncCallback<void>): void

Removes a notification based on the specified unique notification ID. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
hashCode string Yes Unique notification ID. It is the hashCode in the NotificationRequest object of SubscribeCallbackData of the onConsume callback.
reason RemoveReason Yes Reason for removing the notification.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
1600007 The notification is not exist.

Example

import Base from '@ohos.base';

let hashCode: string = 'hashCode';
let removeCallback = (err: Base.BusinessError) => {
  if (err) {
    console.error(`remove failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info("remove success");
  }
}
let reason: notificationSubscribe.RemoveReason = notificationSubscribe.RemoveReason.CANCEL_REASON_REMOVE;
notificationSubscribe.remove(hashCode, reason, removeCallback);

notificationSubscribe.remove

remove(hashCode: string, reason: RemoveReason): Promise<void>

Removes a notification based on the specified unique notification ID. This API uses a promise to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
hashCode string Yes Unique notification ID.
reason RemoveReason Yes Reason for removing the notification.

Return value

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

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
1600007 The notification is not exist.

Example

import Base from '@ohos.base';

let hashCode: string = 'hashCode';
let reason: notificationSubscribe.RemoveReason = notificationSubscribe.RemoveReason.CLICK_REASON_REMOVE;
notificationSubscribe.remove(hashCode, reason).then(() => {
	console.info("remove success");
}).catch((err: Base.BusinessError) => {
  console.error("remove fail: " + JSON.stringify(err));
});

notificationSubscribe.remove10+

remove(hashCodes: Array<String>, reason: RemoveReason, callback: AsyncCallback<void>): void

Removes specified notifications. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
hashCodes Array<String> Yes Array of unique notification IDs. It is the hashCode in the NotificationRequest object of SubscribeCallbackData of the onConsume callback.
reason RemoveReason Yes Reason for removing the notification.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.

Example

import Base from '@ohos.base';

let hashCodes: string[] = ['hashCode1', 'hashCode2'];
let removeCallback = (err: Base.BusinessError) => {
  if (err) {
    console.error(`remove failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info("remove success");
  }
}
let reason: notificationSubscribe.RemoveReason = notificationSubscribe.RemoveReason.CANCEL_REASON_REMOVE;
notificationSubscribe.remove(hashCodes, reason, removeCallback);

notificationSubscribe.remove10+

remove(hashCodes: Array<String>, reason: RemoveReason): Promise<void>

Removes specified notifications. This API uses a promise to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
hashCodes Array<String> Yes Array of unique notification IDs.
reason RemoveReason Yes Reason for removing the notification.

Return value

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

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.

Example

import Base from '@ohos.base';

let hashCodes: string[] = ['hashCode1','hashCode2'];
let reason: notificationSubscribe.RemoveReason = notificationSubscribe.RemoveReason.CLICK_REASON_REMOVE;
notificationSubscribe.remove(hashCodes, reason).then(() => {
  console.info("remove success");
}).catch((err: Base.BusinessError) => {
  console.error("remove fail: " + JSON.stringify(err));
});

notificationSubscribe.removeAll

removeAll(bundle: BundleOption, callback: AsyncCallback<void>): void

Removes all notifications for a specified application. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.Notification

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

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

Parameters

Name Type Mandatory Description
bundle BundleOption Yes Bundle information of the application.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
17700001 The specified bundle name was not found.

Example

import Base from '@ohos.base';

let removeAllCallback = (err: Base.BusinessError) => {
  if (err) {
    console.error(`removeAll failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info("removeAll success");
  }
}
let bundle: notificationSubscribe.BundleOption = {
  bundle: "bundleName1",
};
notificationSubscribe.removeAll(bundle, removeAllCallback);

notificationSubscribe.removeAll

removeAll(callback: AsyncCallback<void>): void

Removes all notifications. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.

Example

import Base from '@ohos.base';

let removeAllCallback = (err: Base.BusinessError) => {
    if (err) {
        console.error(`removeAll failed, code is ${err.code}, message is ${err.message}`);
    } else {
        console.info("removeAll success");
    }
}
notificationSubscribe.removeAll(removeAllCallback);

notificationSubscribe.removeAll

removeAll(bundle?: BundleOption): Promise<void>

Removes all notifications for a specified application. This API uses a promise to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
bundle BundleOption No Bundle information of the application. By default, this parameter is left empty, indicating that all notifications will be removed.

Return value

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

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
17700001 The specified bundle name was not found.

Example

import Base from '@ohos.base';

// If no application is specified, notifications of all applications are deleted.
notificationSubscribe.removeAll().then(() => {
	console.info("removeAll success");
}).catch((err: Base.BusinessError) => {
  console.error("removeAll fail: " + JSON.stringify(err));
});

notificationSubscribe.removeAll

removeAll(userId: number, callback: AsyncCallback<void>): void

Removes all notifications for a specified user. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

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

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
1600008 The user is not exist.

Example

import Base from '@ohos.base';

let removeAllCallback = (err: Base.BusinessError) => {
  if (err) {
    console.error(`removeAll failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info("removeAll success");
  }
}
let userId: number = 1;
notificationSubscribe.removeAll(userId, removeAllCallback);

notificationSubscribe.removeAll

removeAll(userId: number): Promise<void>

Removes all notifications for a specified user. This API uses a promise to return the result.

System capability: SystemCapability.Notification.Notification

Required permissions: ohos.permission.NOTIFICATION_CONTROLLER

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

Parameters

Name Type Mandatory Description
userId number Yes User ID.

Error codes

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

ID Error Message
1600001 Internal error.
1600002 Marshalling or unmarshalling error.
1600003 Failed to connect service.
1600008 The user is not exist.

Example

import Base from '@ohos.base';

let userId: number = 1;
notificationSubscribe.removeAll(userId).then(() => {
	console.info("removeAll success");
}).catch((err: Base.BusinessError) => {
  console.error("removeAll fail: " + JSON.stringify(err));
});

NotificationKey

System capability: SystemCapability.Notification.Notification

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

Name Type Mandatory Description
id number Yes Notification ID.
label string No Notification label. This parameter is left empty by default.

RemoveReason

System capability: SystemCapability.Notification.Notification

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

Name Value Description
CLICK_REASON_REMOVE 1 The notification is removed after a click on it.
CANCEL_REASON_REMOVE 2 The notification is removed by the user.