@@ -7,139 +7,33 @@ You can set your application to call the **ReminderRequest** class to create sch
## Available APIs
**reminderAgent** encapsulates the methods for publishing and canceling reminders.
**reminderAgent** encapsulates the APIs for publishing and canceling reminders.
**Table 1** Major APIs in reminderAgent
| Name| Description|
| -------- | -------- |
| function publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void;<br>function publishReminder(reminderReq: ReminderRequest): Promise<number>; | Publishes a scheduled reminder.<br>The maximum number of valid notifications (excluding expired ones that will not pop up again) is 30 for one application and 2000 for the entire system. |
| function cancelReminder(reminderId: number, callback: AsyncCallback<void>): void;<br>function cancelReminder(reminderId: number): Promise<void>; | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.)|
| function getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void;<br>function getValidReminders(): Promise<Array<ReminderRequest>>; | Obtains all valid reminders set by the current application.|
| function cancelAllReminders(callback: AsyncCallback<void>): void;<br>function cancelAllReminders(): Promise<void>; | Cancels all reminders set by the current application.|
| function addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void;<br>function addNotificationSlot(slot: NotificationSlot): Promise<void>; | Registers a **NotificationSlot** instance to be used by the reminder. |
| function removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void;<br>function removeNotificationSlot(slotType: notification.SlotType): Promise<void>; | Removes a **NotificationSlot** instance of a specified type. |
For details about the APIs, see [reminderAgent](../reference/apis/js-apis-reminderAgent.md).
**ActionButtonType** enumerates types of buttons displayed in a reminder notification.
**Table 2** ActionButtonType enums
| Name| Description|
| -------- | -------- |
| ACTION_BUTTON_TYPE_CLOSE | Close button, which can stop the reminder alert tone, close the reminder notification, and cancel the reminder snoozing.|
| ACTION_BUTTON_TYPE_SNOOZE | Snooze button, which can snooze the reminder.|
**ReminderType** enumerates the reminder types.
**Table 3** ReminderType enums
**Table 1** Major APIs in reminderAgent
| Name| Description|
| -------- | -------- |
| REMINDER_TYPE_TIMER | Countdown reminder.|
| REMINDER_TYPE_CALENDAR | Calendar reminder.|
| REMINDER_TYPE_ALARM | Alarm reminder.|
**ActionButton** defines a button displayed in the reminder notification.
**Table 4** ActionButton
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| title | string | Yes| Text on the button.|
| type | ActionButtonType | Yes| Button type.|
**WantAgent** sets the package and ability that are redirected to when the reminder notification is clicked.
**Table 5** WantAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| pkgName | string | Yes| Name of the package redirected to when the reminder notification is clicked.|
| abilityName | string | Yes| Name of the ability redirected to when the reminder notification is clicked.|
**MaxScreenWantAgent** sets the name of the target package and ability to start automatically when the reminder arrives and the device is not in use. If the device is in use, a notification will be displayed.
**Table 6** MaxScreenWantAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| pkgName | string | Yes| Name of the package that is automatically started when the reminder arrives and the device is not in use.|
| abilityName | string | Yes| Name of the ability that is automatically started when the reminder arrives and the device is not in use.|
**ReminderRequest** defines the reminder to publish.
**Table 7** ReminderRequest
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| reminderType | ReminderType | Yes| Type of the reminder.|
| actionButton | [ActionButton?,ActionButton?] | No| Action button displayed in the reminder notification.|
| wantAgent | WantAgent | No| Information about the ability that is redirected to when the notification is clicked.|
| maxScreenWantAgent | MaxScreenWantAgent | No| Information about the ability that is automatically started when the reminder arrives. If the device is in use, a notification will be displayed.|
| ringDuration | number | No| Ring duration.|
| snoozeTimes | number | No| Number of reminder snooze times.|
| timeInterval | number | No| Reminder snooze interval.|
| title | string | No| Reminder title.|
| content | string | No| Reminder content.|
| expiredContent | string | No| Extended content to be displayed when the reminder expires.|
| snoozeContent | string | No| Extended content to be displayed when the reminder is snoozing.|
| notificationId | number | No| Notification ID used by the reminder. For details, see **NotificationRequest::SetNotificationId(int32_t id)**.|
| slotType | SlotType | No| Type of the slot used by the reminder. |
**ReminderRequestCalendar** extends **ReminderRequest** and defines a reminder for a calendar event.
For the application to run properly, if both **repeatMonths** and **repeatDays** are not specified, the earliest reminder time must be later than the current time.
**Table 8** ReminderRequestCalendar
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| dateTime | LocalDateTime | Yes| Reminder time, accurate to the minute.|
| repeatMonths | Array<number> | No| Months in which the reminder repeats. The value range is 1 to 12.|
| repeatDays | Array<number> | No| Date on which the reminder repeats. The value range is 1 to 31.|
**ReminderRequestAlarm** extends **ReminderRequest** and defines a reminder for the alarm clock.
**Table 9** ReminderRequestAlarm
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| hour | number | Yes| Hour portion of the reminder time. The value range is 0 to 23.|
| minute | number | Yes| Minute portion of the reminder time. The value range is 0 to 59.|
| daysOfWeek | Array<number> | No| Days of a week when the reminder repeats. The value range is 1 to 7.|
**ReminderRequestTimer** extends **ReminderRequest** and defines a reminder for a scheduled timer.
**Table 10** ReminderRequestTimer
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| triggerTimeInSeconds | number | Yes| Number of seconds in the countdown timer.|
**LocalDateTime** defines a **LocalDateTime** instance.
**Table 11** LocalDateTime
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| year | number | Yes| Year.|
| month | number | Yes| Month.|
| day | number | Yes| Date.|
| hour | number | Yes| Hour.|
| minute | number | Yes| Minute.|
| second | number | No| Second.|
| publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void<br>publishReminder(reminderReq: ReminderRequest): Promise<number> | Publishes a scheduled reminder.<br>The maximum number of valid notifications (excluding expired ones that will not pop up again) is 30 for one application and 2000 for the entire system. |
| cancelReminder(reminderId: number, callback: AsyncCallback<void>): void<br>cancelReminder(reminderId: number): Promise<void> | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.)|
| getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void<br>getValidReminders(): Promise<Array<ReminderRequest>> | Obtains all valid reminders set by the current application.|
| cancelAllReminders(callback: AsyncCallback<void>): void<br>cancelAllReminders(): Promise<void> | Cancels all reminders set by the current application.|
| addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void<br>addNotificationSlot(slot: NotificationSlot): Promise<void> | Registers a **NotificationSlot** instance to be used by the reminder.|
| removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void<br>removeNotificationSlot(slotType: notification.SlotType): Promise<void> | Removes a **NotificationSlot** instance of a specified type.|
## How to Develop
> **NOTE**
>
> To publish a reminder, your application needs to apply for the **ohos.permission.PUBLISH_AGENT_REMINDER** permission.
> 1. To publish a reminder through the reminder agent, your application needs to apply for the **ohos.permission.PUBLISH_AGENT_REMINDER** permission.
>
> 2. Your application must have notification enabled. For details, see [Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8).
Publish a 10-second countdown reminder.
1. Define a reminder agent.
1. Define a countdown timer instance.
```
Sample code for defining a reminder agent for a countdown timer:
```js
importreminderAgentfrom'@ohos.reminderAgent';
importnotificationfrom'@ohos.notification';
exportdefault{
...
...
@@ -172,8 +66,97 @@ Publish a 10-second countdown reminder.
}
```
2. Publish the reminder.
```
Sample code for defining a reminder agent for a calendar event:
```js
// For a JS project:
// calendar: {
// For an eTS project:
let calendar : reminderAgent.ReminderRequestCalendar = {
Publishes an agent-powered reminder. This API uses an asynchronous callback to return the result.
Publishes a reminder through the reminder agent. This API uses an asynchronous callback to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8).
Publishes an agent-powered reminder. This API uses a promise callback to return the result.
Publishes a reminder through the reminder agent. This API uses a promise to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8).
@@ -435,7 +435,7 @@ Sets the package and ability that are redirected to when the reminder notificati
## MaxScreenWantAgent
Sets the name of the target package and ability to start automatically when the reminder arrives and the device is not in use. If the device is in use, a notification will be displayed.
Provides the information about the target package and ability to start automatically when the reminder is displayed in full-screen mode. This API is reserved.
@@ -454,7 +454,7 @@ Defines the reminder to publish.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| reminderType | ReminderType | Yes| Type of the reminder.|
| actionButton | [ActionButton?, ActionButton?] | No| Action button displayed in the reminder notification. (The parameter is optional. Up to two buttons are supported.)|
| actionButton | [ActionButton?, ActionButton?] | No| Button displayed in the reminder notification. (The parameter is optional. Up to two buttons are supported.)|
| wantAgent | WantAgent | No| Information about the ability that is redirected to when the notification is clicked.|
| maxScreenWantAgent | MaxScreenWantAgent | No| Information about the ability that is automatically started when the reminder arrives. If the device is in use, a notification will be displayed.|
