diff --git a/en/application-dev/notification/background-agent-scheduled-reminder-guide.md b/en/application-dev/notification/background-agent-scheduled-reminder-guide.md deleted file mode 100644 index 71ffeb0b07acfb088988163a68f72882d267f49b..0000000000000000000000000000000000000000 --- a/en/application-dev/notification/background-agent-scheduled-reminder-guide.md +++ /dev/null @@ -1,167 +0,0 @@ -# Agent-Powered Scheduled Reminder Development - -## When to Use - -You can set your application to call the **ReminderRequest** class to create scheduled reminders for countdown timers, calendar events, and alarm clocks. When the created reminders are published, the timing and pop-up notification functions of your application will be taken over by the reminder agent in the background, even when your application is frozen or exits. - - -## Available APIs - -**reminderAgent** encapsulates the APIs for publishing and canceling reminders. - -For details about the APIs, see [reminderAgent](../reference/apis/js-apis-reminderAgent.md). - -**Table 1** Major APIs in reminderAgent - -| Name| Description| -| -------- | -------- | -| publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void
publishReminder(reminderReq: ReminderRequest): Promise<number> | Publishes a scheduled reminder.
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
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
getValidReminders(): Promise<Array<ReminderRequest>> | Obtains all valid reminders set by the current application.| -| cancelAllReminders(callback: AsyncCallback<void>): void
cancelAllReminders(): Promise<void> | Cancels all reminders set by the current application.| -| addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void
addNotificationSlot(slot: NotificationSlot): Promise<void> | Registers a **NotificationSlot** instance to be used by the reminder.| -| removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void
removeNotificationSlot(slotType: notification.SlotType): Promise<void> | Removes a **NotificationSlot** instance of a specified type.| - -## How to Develop - -> **NOTE** -> -> 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). - -1. Define a reminder agent. - - Sample code for defining a reminder agent for a countdown timer: - ```js - import reminderAgent from '@ohos.reminderAgent'; - import notification from '@ohos.notification'; - export default { - // ArkTS project: - let timer : reminderAgent.ReminderRequestTimer = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER, - triggerTimeInSeconds: 10, - actionButton: [ - { - title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - } - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION - } - } - ``` - - Sample code for defining a reminder agent for a calendar event: - - ```js - // ArkTS project: - let calendar : reminderAgent.ReminderRequestCalendar = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR, - dateTime: { - year: 2050, - month: 7, - day: 30, - hour: 11, - minute: 14, - second: 30 - }, - repeatMonths: [1], - repeatDays: [1], - actionButton: [ - { - title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION - } - ``` - - Sample code for defining a reminder agent for an alarm: - - ```js - // ArkTS project: - let alarm : reminderAgent.ReminderRequestAlarm = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, - hour: 11, - minute: 14, - daysOfWeek: [0], - actionButton: [ - { - title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION - } - ``` - -2. Publish a countdown reminder. - ```js - startTimer() { - reminderAgent.publishReminder(this.timer, (err, reminderId) =>{ - this.printInfo(JSON.stringify(err)); - this.printInfo("reminderId:" + reminderId); - }); - } - ``` - - HML page code: - ```html -
- -
- ``` diff --git a/en/application-dev/notification/background-agent-scheduled-reminder-overview.md b/en/application-dev/notification/background-agent-scheduled-reminder-overview.md deleted file mode 100644 index a9eccc77a9fecd9d1044eead091bfe9ffb097310..0000000000000000000000000000000000000000 --- a/en/application-dev/notification/background-agent-scheduled-reminder-overview.md +++ /dev/null @@ -1,4 +0,0 @@ -# Agent-Powered Scheduled Reminder Overview - -Your application can call the **ReminderRequest** class to create scheduled reminders for countdown timers, calendar events, and alarm clocks. When the created reminders are published, the timing and pop-up notification functions of your application will be taken over by the reminder agent in the background, even when your application is frozen or exits. - diff --git a/en/application-dev/task-management/Readme-EN.md b/en/application-dev/task-management/Readme-EN.md index efc153e1b229c56a83c630a98aee1cecf5c72cac..f4b1d6d548e5e739daf352ddf16a8df310a47d05 100644 --- a/en/application-dev/task-management/Readme-EN.md +++ b/en/application-dev/task-management/Readme-EN.md @@ -8,6 +8,6 @@ - [Efficiency Resource Request Development](efficiency-resources-apply-dev-guide.md) - Agent-Powered Scheduled Reminder - - [Agent-Powered Scheduled Reminder Overview](background-agent-scheduled-reminder-overview.md) - - [Agent-Powered Scheduled Reminder Development](background-agent-scheduled-reminder-guide.md) + - [Agent-Powered Reminder Overview](reminder-agent-overview.md) + - [Agent-Powered Reminder Development](reminder-agent-development.md) diff --git a/en/application-dev/task-management/background-agent-scheduled-reminder-guide.md b/en/application-dev/task-management/background-agent-scheduled-reminder-guide.md deleted file mode 100644 index ed220944dd102466ec190ca09d6066a8818acd3e..0000000000000000000000000000000000000000 --- a/en/application-dev/task-management/background-agent-scheduled-reminder-guide.md +++ /dev/null @@ -1,180 +0,0 @@ -# Agent-Powered Scheduled Reminder Development - -## When to Use - -You can set your application to call the **ReminderRequest** class to create scheduled reminders for countdown timers, calendar events, and alarm clocks. When the created reminders are published, the timing and pop-up notification functions of your application will be taken over by the reminder agent in the background, even when your application is frozen or exits. - - -## Available APIs - -**reminderAgentManager** encapsulates the APIs for publishing and canceling reminders. - -For details about the APIs, see [reminderAgentManager](../reference/apis/js-apis-reminderAgentManager.md). - -**Table 1** Major APIs in reminderAgentManager - -| Name| Description| -| -------- | -------- | -| publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void
publishReminder(reminderReq: ReminderRequest): Promise<number> | Publishes a scheduled reminder.
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
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
getValidReminders(): Promise<Array<ReminderRequest>> | Obtains all valid reminders set by the current application.| -| cancelAllReminders(callback: AsyncCallback<void>): void
cancelAllReminders(): Promise<void> | Cancels all reminders set by the current application.| -| addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void
addNotificationSlot(slot: NotificationSlot): Promise<void> | Registers a **NotificationSlot** instance to be used by the reminder.| -| removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void
removeNotificationSlot(slotType: notification.SlotType): Promise<void> | Removes a **NotificationSlot** instance of a specified type.| - -## How to Develop - -> **NOTE** -> -> 1. To publish a reminder through the reminder agent, your application must 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). -> 3. The reminder agent can be used only after being authorized by the user. - -1. Define a reminder agent. - -2. Publish the reminder agent. - -```ts -import reminderAgentManager from '@ohos.reminderAgentManager'; -import notification from '@ohos.notification'; - -// Sample code for defining a reminder agent for a countdown timer: -let timer : reminderAgentManager.ReminderRequestTimer = { - reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, - triggerTimeInSeconds: 10, - actionButton: [ - { - title: "close", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - } - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION -} - -// Sample code for defining a reminder agent for a calendar event: -let calendar : reminderAgentManager.ReminderRequestCalendar = { - reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR, - dateTime: { - year: 2050, - month: 7, - day: 30, - hour: 11, - minute: 14, - second: 30 - }, - repeatMonths: [1], - repeatDays: [1], - actionButton: [ - { - title: "close", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION -} - -// Sample code for defining a reminder agent for an alarm: -let alarm : reminderAgentManager.ReminderRequestAlarm = { - reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM, - hour: 11, - minute: 14, - daysOfWeek: [0], - actionButton: [ - { - title: "close", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE - }, - { - title: "snooze", - type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE - }, - ], - wantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - maxScreenWantAgent: { - pkgName: "com.example.device", - abilityName: "com.example.device.MainAbility" - }, - ringDuration: 5, - snoozeTimes: 2, - timeInterval: 5, - title: "this is title", - content: "this is content", - expiredContent: "this reminder has expired", - snoozeContent: "remind later", - notificationId: 100, - slotType: notification.SlotType.SOCIAL_COMMUNICATION -} - -@Entry -@Component -struct Index { - @State message: string = 'test' - - publishReminder() { - try { - reminderAgentManager.publishReminder(timer).then(res => { - console.log("publishReminder promise reminderId:" + res); - }).catch(err => { - console.log("publishReminder err code:" + err.code + " message:" + err.message); - }) - } catch (error) { - console.log("publishReminder code:" + error.code + " message:" + error.message); - }; - } - - build() { - Row() { - Column() { - Text("Index") - .fontSize(50) - .fontWeight(FontWeight.Bold) - - Button() { Text('Countdown reminder agent').fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule) - .margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40) - .onClick(() => { - // Sample code for publishing the reminder agent. - this.publishReminder(); - }) - - } - .width('100%') - } - .height('100%') - } -} -``` diff --git a/en/application-dev/task-management/background-agent-scheduled-reminder-overview.md b/en/application-dev/task-management/background-agent-scheduled-reminder-overview.md deleted file mode 100644 index 22c530571ad2770a279b9c94df998b6d773a5f1f..0000000000000000000000000000000000000000 --- a/en/application-dev/task-management/background-agent-scheduled-reminder-overview.md +++ /dev/null @@ -1,12 +0,0 @@ -# Agent-Powered Scheduled Reminder Overview - -According to the OpenHarmony background activity specifications, a third-party application will be suspended if it does not execute background tasks after switching to the background. In practice, an application may need to process certain work at specified moments, no matter what state it is in. For example, a shopping application needs to remind users of flash sale activities at some time points. Generally, a timer is used to achieve the preceding scenario. When the timer expires, the system starts the application to execute the task. However, some applications abuse the timer mechanism so they can be frequently waken up when running in the background. To avoid malicious background activities and meet service requirements of applications, OpenHarmony introduces the agent-powered scheduled reminder. -With the agent-powered scheduled reminder, the timing and pop-up notification functions of an application will be taken over by the reminder agent in the background, even when the application is suspended or exits. This prevents an application from being frequently woken up and helps reduce power consumption. - -## Notification Instance Types - -- **Countdown timers**: Applications can use this type to implement short-time timing notification services. - -- **Calendar events**: Applications can use this type to implement long-time notification services. - -- **Alarm clocks**: Applications can use this type to implement alarm-related services. diff --git a/en/application-dev/task-management/efficiency-resources-apply-dev-guide.md b/en/application-dev/task-management/efficiency-resources-apply-dev-guide.md index 0b8ea31ca804f848d1e931b65a7e5f5812e656c2..61f1431ea4d26eb8579246b8ecec1f58fab56327 100644 --- a/en/application-dev/task-management/efficiency-resources-apply-dev-guide.md +++ b/en/application-dev/task-management/efficiency-resources-apply-dev-guide.md @@ -1,22 +1,22 @@ -## Efficiency Resource Request Development +# Efficiency Resource Request Development -### When to Use +## When to Use To further balance power consumption overhead of the system, privileged system applications can be suspended in the background as other applications. To ensure normal provisioning of important functions, efficiency resource APIs are provided for these applications so that they can execute special tasks and use specific system resources in the background. For example, if they want to receive common events when suspended, they can use the APIs to request the common event resources. To upgrade your application as a privileged application, you must evaluate your service requirements and submit a request to the application center. The application center will determine whether to accept the request based on the conditions. -### Available APIs +## Available APIs **Table 1** Main APIs for efficiency resources -| API | Description | -| ---------------------------------------- | ---------------------------------------- | -| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): boolean | Requests efficiency resources.| -| resetAllEfficiencyResources():void | Releases efficiency resources. | +| API | Description | +| ---------------------------------------- | ---------- | +| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-resourceschedule-backgroundTaskManager.md#efficiencyresourcesrequest)): boolean | Requests efficiency resources. | +| resetAllEfficiencyResources():void | Releases efficiency resources.| -### How to Develop +## How to Develop 1. When a privileged application in the background needs to use special resources, request the target resources from the system. @@ -51,5 +51,3 @@ console.info("the result of request is: " + res); // Release all efficiency resources. backgroundTaskManager.resetAllEfficiencyResources(); ``` - - \ No newline at end of file diff --git a/en/application-dev/task-management/figures/en-us_image_0000001416585578.png b/en/application-dev/task-management/figures/en-us_image_0000001416585578.png new file mode 100644 index 0000000000000000000000000000000000000000..7603dfb263fe088c0a71a99be541838566b53268 Binary files /dev/null and b/en/application-dev/task-management/figures/en-us_image_0000001416585578.png differ diff --git a/en/application-dev/task-management/reminder-agent-development.md b/en/application-dev/task-management/reminder-agent-development.md new file mode 100644 index 0000000000000000000000000000000000000000..c749a9f4cc9615e836e2163632390b8821e55072 --- /dev/null +++ b/en/application-dev/task-management/reminder-agent-development.md @@ -0,0 +1,181 @@ +# Agent-Powered Reminder Development + + +## Available APIs + +The agent-powered reminder feature provides APIs for publishing background reminders. You can call these APIs to create scheduled reminders for countdown timers, calendar events, and alarm clocks. The APIs are encapsulated in the [reminderAgentManager](../reference/apis/js-apis-reminderAgentManager.md) class. + +**Table 1** Major APIs in reminderAgentManager + +| API | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void
publishReminder(reminderReq: ReminderRequest): Promise<number> | Publishes a scheduled reminder.
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
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
getValidReminders(): Promise<Array<ReminderRequest>> | Obtains all valid reminders set by the current application. | +| cancelAllReminders(callback: AsyncCallback<void>): void
cancelAllReminders(): Promise<void> | Cancels all reminders set by the current application. | +| addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void
addNotificationSlot(slot: NotificationSlot): Promise<void> | Registers a **NotificationSlot** instance to be used by the reminder. | +| removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void
removeNotificationSlot(slotType: notification.SlotType): Promise<void> | Removes a **NotificationSlot** instance of a specified type. | + + +## How to Develop + +1. Request the **ohos.permission.PUBLISH_AGENT_REMINDER** permission. For details, see [Permission Application Guide](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file). + +2. [Enable the notification feature](../notification/notification-enable.md). + +3. Import the modules. + + ```js + import reminderAgentManager from '@ohos.reminderAgentManager'; + import notificationManager from '@ohos.notificationManager'; + ``` + +4. Define a reminder agent. You can define the following types of reminder agents based on project requirements. + - Countdown timer + + ```js + let targetReminderAgent: reminderAgentManager.ReminderRequestTimer = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, // The reminder type is countdown timer. + triggerTimeInSeconds: 10, + actionButton: [ // Set the button type and title displayed in the reminder notification. The Close and Snooze types are supported, and the Snooze type must be used together with the snoozeTimes and timeInterval parameters. + { + title: 'close', + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + } + ], + wantAgent: {// Information about the target UIAbility that is displayed after the reminder notification is touched. + pkgName: 'com.example.myapplication', + abilityName: 'EntryAbility' + }, + maxScreenWantAgent: {// Information about the target ability that is automatically started when the specified reminder time arrives is displayed in full screen. + pkgName: 'com.example.myapplication', + abilityName: 'EntryAbility' + }, + title:'this is title', // Reminder title. + content:'this is content', // Reminder content. + expiredContent:'This reminder has expired', // Content to be displayed after the reminder expires. + notificationId: 100, // Notification ID used by the reminder. If there are reminders with the same notification ID, the later one will overwrite the earlier one. + slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // Type of the slot used by the reminder. + } + ``` + - Calendar event + + ```js + let targetReminderAgent: reminderAgentManager.ReminderRequestCalendar = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR, // The reminder type is calendar event. + dateTime: { // Reminder time. + year: 2023, + month: 7, + day: 30, + hour: 11, + minute: 14, + second: 30 + }, + repeatMonths: [1], // Month in which the reminder repeats. + repeatDays: [1], // Date on which the reminder repeats. + actionButton: [ // Set the button type and title displayed in the reminder notification. The Close and Snooze types are supported, and the Snooze type must be used together with the snoozeTimes and timeInterval parameters. + { + title: 'close', + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + }, + { + title: 'snooze', + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE + }, + ], + wantAgent: {// Information about the target UIAbility that is displayed after the reminder notification is touched. + pkgName: 'com.example.myapplication', + abilityName: 'EntryAbility' + }, + maxScreenWantAgent: { // Information about the target UIAbility that is displayed after the reminder notification is touched. + pkgName: 'com.example.myapplication', + abilityName: 'EntryAbility' + }, + ringDuration: 5, // Ringing duration, in seconds. + snoozeTimes: 2, // Number of reminder snooze times. + timeInterval: 5, // Reminder snooze interval, in seconds. + title:'this is title', // Reminder title. + content:'this is content', // Reminder content. + expiredContent:'This reminder has expired', // Content to be displayed after the reminder expires. + snoozeContent:'remind later', // Content to be displayed when the reminder is snoozed. + notificationId: 100, // Notification ID used by the reminder. If there are reminders with the same notification ID, the later one will overwrite the earlier one. + slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // Type of the slot used by the reminder. + } + ``` + - Alarm clock + + ```js + let targetReminderAgent: reminderAgentManager.ReminderRequestAlarm = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM, // The reminder type is alarm clock. + hour: 23, // Hour portion of the reminder time. + minute: 9, // Minute portion of the reminder time. + daysOfWeek: [2], // Days of a week when the reminder repeats.. + actionButton: [ // Set the button type and title displayed in the reminder notification. The Close and Snooze types are supported, and the Snooze type must be used together with the snoozeTimes and timeInterval parameters. + { + title: 'close', + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + }, + { + title: 'snooze', + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE + }, + ], + wantAgent: {// Information about the target UIAbility that is displayed after the reminder notification is touched. + pkgName: 'com.example.myapplication', + abilityName: 'EntryAbility' + }, + maxScreenWantAgent: { // Information about the target UIAbility that is displayed after the reminder notification is touched. + pkgName: 'com.example.myapplication', + abilityName: 'EntryAbility' + }, + ringDuration: 5, // Ringing duration, in seconds. + snoozeTimes: 2, // Number of reminder snooze times. + timeInterval: 5, // Reminder snooze interval, in seconds. + title:'this is title', // Reminder title. + content:'this is content', // Reminder content. + expiredContent:'This reminder has expired', // Content to be displayed after the reminder expires. + snoozeContent:'remind later', // Content to be displayed when the reminder is snoozed. + notificationId: 99, // Notification ID used by the reminder. If there are reminders with the same notification ID, the later one will overwrite the earlier one. + slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // Type of the slot used by the reminder. + } + ``` + +5. Publish the reminder agent. After the agent is published, your application can use the agent-powered reminder feature. + + ```js + try { + reminderAgentManager.publishReminder(targetReminderAgent).then(res => { + console.info('publishReminder promise reminderId: ' + res); + let reminderId: number = res; + // ... + }).catch(err => { + console.info('publishReminder err code: ' + err.code + ' message:' + err.message); + }) + } catch (error) { + console.info('publishReminder code: ' + error.code + ' message:' + error.message); + } + ``` + + The following figure shows the running effect of an alarm clock. + + ![en-us_image_0000001416585578](figures/en-us_image_0000001416585578.png) + +6. To delete a reminder task, call [reminderAgentManager.cancelReminder()](../reference/apis/js-apis-reminderAgentManager.md#reminderagentmanagercancelreminder). + + ```js + let reminderId = 0; // The reminderId is obtained from the callback after the agent is published. + + try { + reminderAgentManager.cancelReminder(reminderId).then(() => { + console.log("cancelReminder promise"); + }).catch(err => { + console.log("promise err code: " + err.code + ", message:" + err.message); + }); + } catch (error) { + console.log("cancelReminder code: " + error.code + ", message: " + error.message); + }; + ``` + + + + \ No newline at end of file diff --git a/en/application-dev/task-management/reminder-agent-overview.md b/en/application-dev/task-management/reminder-agent-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..6f0f4c5f99b60715e7c1a29841c9ca5aadf70cb8 --- /dev/null +++ b/en/application-dev/task-management/reminder-agent-overview.md @@ -0,0 +1,14 @@ +# Agent-Powered Reminder Overview + + +To deliver a better user experience, OpenHarmony manages background application processes in a more orderly manner. Applications cannot reside in the background randomly, and their background behavior is strictly managed to minimize malicious behavior. However, for some applications that are running in the background or have exited, notifications may need to be sent at a specified time. For example, a shopping application wants to remind users of flash sale activities at some time points. To meet these service requirements, OpenHarmony provides the agent-powered redminder feature. After an application switches to the background or exits, their timing and pop-up notification functions are taken over by the background agent. + + +OpenHarmony provides the following types of background agents: + + +- Countdown timers: Applications can use this type to implement short-time timing notification services. + +- Calendar events: Applications can use this type to implement long-time notification services. + +- Alarm clocks: Applications can use this type to implement alarm-related services. diff --git a/en/application-dev/tools/Readme-EN.md b/en/application-dev/tools/Readme-EN.md new file mode 100644 index 0000000000000000000000000000000000000000..5dfe93a6a9584920a5da457ac61964dcb183a99c --- /dev/null +++ b/en/application-dev/tools/Readme-EN.md @@ -0,0 +1,9 @@ +# Debugging Tools + +- [Ability Assistant](aa-tool.md) +- [Bundle Manager](bm-tool.md) +- Packing and Unpacking Tools + - [Packaging Tool](packing-tool.md) + - [Unpacking Tool](unpacking-tool.md) +- [Common Event Manager](cem-tool.md) +- [Advanced Notification Manager](anm-tool.md) diff --git a/en/application-dev/tools/aa-tool.md b/en/application-dev/tools/aa-tool.md new file mode 100644 index 0000000000000000000000000000000000000000..e03cdd52c6df142c13a06c918ae242c4115b323c --- /dev/null +++ b/en/application-dev/tools/aa-tool.md @@ -0,0 +1,119 @@ +# Ability Assistant + + +The Ability Assistant provides the application debugging and testing capabilities that enable you to start applications and test cases. With this tool, you can send commands (started with **aa**) in the hdc shell to perform various system operations, such as starting application components, forcibly stopping processes, and printing application component information. + + +- help + +Displays help information for the Ability Assistant. + +**Return value** + +Returns the help information. + +**Method** + + + ```bash + aa help + ``` + + +- start + +Starts an application component. The target component can be the PageAbility and ServiceAbility components of the FA model or the UIAbility and ServiceExtensionAbility components of the Stage model. The **visible** tag in the configuration file of the target component cannot be set to **false**. + + | Name| Description| + | -------- | -------- | + | -h/--help | Help information.| + | -d | Device ID. Optional.| + | -a | Ability name. Mandatory.| + | -b | Bundle name. Mandatory.| +| -D | Debugging mode. Optional.| + +**Return value** + +Returns "start ability successfully." if the ability is started; returns "error: failed to start ability." and the corresponding error information otherwise. + +**Method** + + + ```bash + aa start [-d ] -a -b [-D] +``` + +- stop-service + +Stops a ServiceAbility. + + | Name| Description| + | -------- | -------- | + | -h/--help | Help information.| + | -d | Device ID. Optional.| + | -a | Ability name. Mandatory.| +| -b | Bundle name. Mandatory.| + +**Return value** + +Returns "stop service ability successfully." if the ServiceAbility is stopped; returns "error: failed to stop service ability." otherwise. + +**Method** + + + ```bash + aa stop-service [-d ] -a -b +``` + +- dump + + Prints information about an application component. + + | Name| Level-2 Parameter| Description| + | -------- | -------- | -------- | + | -h/--help | - | Help information.| + | -a/--all | - | Application component information in all missions.| + | -l/--mission-list | type (All logs are printed if this parameter is left unspecified.)| Mission stack information.
The following values are available for **type**:
- NORMAL
- DEFAULT_STANDARD
- DEFAULT_SINGLE
- LAUNCHER | + | -e/--extension | elementName | Extended component information.| + | -u/--userId | UserId | Mission stack information of a specified user ID. This parameter must be used together with other parameters. Example commands: **aa dump -a -u 100** and **aa dump -d -u 100**.| + | -d/--data | - | DataAbility information.| +| -i/--ability | AbilityRecord ID | Detailed information about an application component.| + | -c/--client | - | Detailed information about an application component. This parameter must be used together with other parameters. Example commands: **aa dump -a -c** and **aa dump -i 21 -c**.| + + **Method** + + + ```bash +aa dump -a + ``` + + ![aa-dump-a](figures/aa-dump-a.png) + + + ```bash +aa dump -l + ``` + + ![aa-dump-l](figures/aa-dump-l.png) + + + ```bash +aa dump -i 12 + ``` + + ![aa-dump-i](figures/aa-dump-i.png) + +- force-stop + +Forcibly stops a process based on the bundle name. + +**Return value** + +Returns "force stop process successfully." if the process is forcibly stopped; returns "error: failed to force stop process." otherwise. + +**Method** + + + ```bash + aa force-stop + ``` diff --git a/en/application-dev/tools/anm-tool.md b/en/application-dev/tools/anm-tool.md new file mode 100644 index 0000000000000000000000000000000000000000..5a738bc22ff538676158bb3da32aacf9b507097c --- /dev/null +++ b/en/application-dev/tools/anm-tool.md @@ -0,0 +1,71 @@ +# Advanced Notification Manager + +The Advanced Notification Manager provides the notification debugging and testing capabilities that enable you to print notifications and set notification parameters. With this tool, you can send commands (started with **anm**) in the hdc shell to perform various system operations, such as printing notification details, setting the number of cached notifications, and enabling the notification capability. + +### help + +* **Function** + + Prints help information. + +* **Method** + + ```bash + anm help + ``` + +### dump + +* **Function** + + Prints information about notifications. + +* **Method** + + ```bash + anm dump [] + ``` + + The table below describes the available options. + + | Name | Description | + | ---------------- | ---------------------------------- | + | -A/--active | Information about all active notifications. | + | -R/--recent | Information about recent notifications. | + | -D/--distributed | Information about distributed notifications from other devices. | + | -b/--bundle | Bundle name. Optional.| + | -u/--user-id | User ID. Optional. | + | -h/--help | Help information. | + +* **Example**: Print information about active notifications. + + ```bash + anm dump -A + ``` + ![anm-dump-A](figures/anm-dump-A.png) + +### Setting + +* **Function** + + Sets notification parameters. + +* **Method** + + ```bash + anm setting [] + ``` + + The table below describes the available options. + + | Name | Description | + | ------------------------ | ------------------------------------ | + | -c/--recent-count | Maximum number of recent notifications stored in the memory.| + | -e/--enable-notification | Whether to enable the notification capability. | + | -h/--help | Help information. | + +* **Example**: Set the maximum number of recent notifications stored in the memory to 100. + + ```bash + anm setting -c 100 + ``` diff --git a/en/application-dev/tools/bm-tool.md b/en/application-dev/tools/bm-tool.md new file mode 100644 index 0000000000000000000000000000000000000000..5bd5e7b009a5694519f82294fe718b6941117598 --- /dev/null +++ b/en/application-dev/tools/bm-tool.md @@ -0,0 +1,275 @@ +# Bundle Manager + + +The Bundle Manager provides the bundle debugging and testing capabilities that enable you to install, uninstall, update, and query a bundle (application). With this tool, you can send commands (started with **bm**) in the hdc shell to perform various system operations, such as installing and uninstalling a bundle and querying bundle information. + +**Table 1** bm commands + +| Name| Description| +| -------- | -------- | +| help | Displays the commands supported by the Bundle Manager tool.| +| install | Installs a bundle.| +| uninstall | Uninstalls a bundle.| +| dump | Queries bundle information.| +| clean | Clears the cache and data of a bundle.| +| enable | Enables a bundle. A bundle can be used after being enabled.| +| disable | Disables a bundle. A bundle cannot be used after being disabled.| +| get | Obtains the UDID of a device.| +| quickfix | Performs patch-related operations, such as installing or querying a patch.| + + +## Help Command + +**Table 2** Help command + +| Name| Description| +| -------- | -------- | +| bm help | Displays the commands supported by the bm tool.| + +Example + + +```bash +# Display the help information. +bm help +``` + + +## Installation Command + +```bash +bm install [-h] [-p path] [-u userId] [-r] [-w waitting-time] +``` + +**Table 3** Installation command parameters + +| Name| Mandatory| Description| +| -------- | -------- | -------- | +| -h | No| Used to display the parameters supported by the **install** command. By default, the help information is displayed.| +| -p | Yes| Path of the HAP to install. You can specify a path to install one or more HAPs at the same time.| +| -u | No| User whose HAP is to be installed. By default, the current user's HAP is installed.| +| -r | No| Whether to install the HAP in overwrite mode. By default, the HAP is installed in overwrite mode.| +| -w | No| Time that the Bundle Manager tool waits before installing the HAP. The minimum waiting time is 5s, and the maximum waiting time is 600s. The default waiting time is 5s.| + + +Example + +```bash +bm install -p /data/app/ohosapp.hap -u 100 -w 5s -r +// The execution result is as follows: +install bundle successfully. +``` + + +## Uninstall Command + +```bash +bm uninstall [-h help] [-n bundleName] [-m moduleName] [-u userId] [-k] +``` + +**Table 4** Uninstall command parameters + +| Name| Mandatory| Description| +| -------- | -------- | -------- | +| -h | No| Used to display the parameters supported by the **uninstall** command. By default, the help information is displayed.| +| -n | Yes| Name of the bundle to uninstall.| +| -m | No| Module of the bundle to uninstall. By default, all modules are uninstalled.| +| -u | No| User whose bundle is to be uninstalled. By default, the current user's bundle is uninstalled.| +| -k | No| Whether the application data is retained when the bundle is uninstalled. By default, the application data is deleted along the uninstall.| + + +Example + +```bash +bm uninstall -n com.ohos.app -m com.ohos.app.MainAbility -u 100 -k +// The execution result is as follows: +uninstall bundle successfully. +``` + + +## Dump Command + +```bash +bm dump [-h help] [-a] [-n bundleName] [-s shortcutInfo] [-u userId] [-d deviceId] +``` + + +If **-u** is not specified, the command applies to all users. + +**Table 5** Dump command parameters + +| Name| Mandatory| Description| +| -------- | -------- | -------- | +| -h | No| Used to display the parameters supported by the **dump** command. By default, the help information is displayed.| +| -a | Yes| Used to display all bundles installed in the system.| +| -n | Yes| Used to display the details of a bundle.| +| -s | Yes| Used to display the shortcut information of a bundle.| +| -d | No| Used to display the bundle information on a given device. By default, the bundle information on the current device is queried.| +| -u | No| Used to display the bundle information for a given user. By default, the bundle information of the current user is queried.| + + +Example + +```bash +# Display the names of all bundles installed in the system. +bm dump -a +# Display the details of a bundle. +bm dump -n com.ohos.app -u 100 +# Display the shortcut information of a bundle. +bm dump -s com.ohos.app -u 100 +# Display cross-device bundle information. +bm dump -n com.ohos.app -d xxxxx +``` + + +## Clean Command + +```bash +bm clean [-h] [-c] [-n bundleName] [-d] [-u userId] +``` + + +If **-u** is not specified, the command applies to all active users. + +**Table 6** Clean command parameters + +| Name| Description| +| -------- | -------- | +| -h | Used to display the parameters supported by the **clean** command.| +| -c -n | Used to clear the cache data of a bundle.| +| -d -n | Used to clear the data directory of a bundle.| +| -u | Used to clear the cache data of a bundle for a given user.| + + +Example + +```bash +# Clear the cache data of a bundle. +bm clean -c -n com.ohos.app -u 100 +// The execution result is as follows: +clean bundle cache files successfully. +# Clear the user data of a bundle. +bm clean -d -n com.ohos.app -u 100 +// The execution result is as follows: +clean bundle data files successfully. +``` + + +## Enable Command + +```bash +bm enable [-h] [-n bundleName] [-a abilityName] [-u userId] +``` + + +If **-u** is not specified, the command applies to all active users. + +**Table 7** Enable command parameters + +| Name| Description| +| -------- | -------- | +| -h | Used to display the parameters supported by the **enable** command.| +| -n | Used to enable a bundle.| +| -a | Used to enable an ability with a specified bundle name.| +| -u | Used to enable a bundle for a given user.| + + +Example + +```bash +# Enable a bundle. +bm enable -n com.ohos.app -a com.ohos.app.MainAbility -u 100 +// The execution result is as follows: +enable bundle successfully. +``` + + +## Disable Command + +```bash +bm disable [-h] [-n bundleName] [-a abilityName] [-u userId] +``` + + +If **-u** is not specified, the command applies to all active users. + +**Table 8** Disabled command parameters + +| Name| Description| +| -------- | -------- | +| -h | Used to display the parameters supported by the **disable** command.| +| -n | Used to disable a bundle.| +| -a | Used to disable an ability with a specified bundle name.| +| -u | Used to disable a bundle for a given user.| + +Example + +```bash +# Disable a bundle. +bm disable -n com.ohos.app -a com.ohos.app.MainAbility -u 100 +// The execution result is as follows: +disable bundle successfully. +``` + + +## Obtaining UDID + +```bash +bm get [-h] [-u] +``` + +**Table 9** Parameters used in the command for obtaining the UDID + +| Name| Description| +| -------- | -------- | +| -h | Used to display the parameters supported by the **get** command.| +| -u | Used to obtain the UDID of a device.| + + +Example + +```bash +# Obtain the UDID of a device. +bm get -u +// The execution result is as follows: +udid of current device is : +23CADE0C +``` + + +## Quick Fix + +```bash +bm quickfix [-h] [-a -f filePath] [-q -b bundleName] +``` + +**Table 10** Parameters used in the command for quick fix + +| Name| Description| +| -------- | -------- | +| -h | Used to display the commands supported by **quickfix**.| +| -a -f | Used to run the quick fix patch installation command. **file-path** corresponds to the hqf file. You can pass in one or more hqf files or the directory where the hqf file is located.| +| -q -b | Used to display the patch information based on the bundle name. **bundle-name** indicates the bundle name.| + + +Example + +```bash +# Display patch package information by the bundle name. +bm quickfix -q -b com.ohos.app +// The execution result is as follows: +// Information as follows: +// ApplicationQuickFixInfo: +// bundle name: com.ohos.app +// bundle version code: xxx +// bundle version name: xxx +// patch version code: x +// patch version name: +// cpu abi: +// native library path: +// type: +# Patch installation in the quick fix: +bm quickfix -a -f /data/app/ +// The execution result is as follows: +apply quickfix succeed. +``` diff --git a/en/application-dev/tools/cem-tool.md b/en/application-dev/tools/cem-tool.md new file mode 100644 index 0000000000000000000000000000000000000000..beaf1a86e38b11508d5551a48e018cf98e7e7a6e --- /dev/null +++ b/en/application-dev/tools/cem-tool.md @@ -0,0 +1,85 @@ +# Common Event Manager + +The Common Event Manager provides the common event debugging and testing capabilities that enable you to print common event information and publish common events. With this tool, you can send commands (started with **cem**) in the hdc shell to perform various system operations, such as printing all common event subscribers, sent common events, and recipients, as well as publishing common events. + +## Commands + +### help + +* Function + + Prints help information. + +* Method + + ``` + cem help + ``` + +### publish + +* Function + + Publishes a common event. + +* Method + + ``` + cem publish [] + ``` + + The table below describes the available options. + + | Name | Description | + | ------------ | ------------------------------------------ | + | -e/--event | Name of the common event to publish. Mandatory. | + | -s/--sticky | Indicates that the common event to publish is sticky. Optional. By default, non-sticky events are published.| + | -o/--ordered | Indicates that the common event to publish is ordered. Optional. By default, non-ordered events are published. | + | -c/--code | Result code of the common event. Optional. | + | -d/--data | Data carried in the common event. Optional. | + | -h/--help | Help information. | + +* Example + + ```bash + # Publish a common event named testevent. + cem publish --event "testevent" + ``` + + ![cem-publish-event](figures/cem-publish-event.png) + + ```bash + # Publish a sticky, ordered common event named testevent. The result code of the event is 100 and the data carried is this is data. + cem publish -e "testevent" -s -o -c 100 -d "this is data" + ``` + + ![cem-publish-all](figures/cem-publish-all.png) + +### dump + +* Function + + Displays information about common events. + +* Method + + ``` + cem dump [] + ``` + + The table below describes the available options. + + | Name | Description | + | ---------- | -------------------------------------------- | + | -a/--all | Information about all common events that have been sent since system startup.| + | -e/--event | Information about a specific event. | + | -h/--help | Help information. | + +* Example + + ```bash + # Display details of a common event named testevent. + cem dump -e "testevent" + ``` + + ![cem-dump-e](figures/cem-dump-e.png) diff --git a/en/application-dev/tools/figures/aa-dump-a.png b/en/application-dev/tools/figures/aa-dump-a.png new file mode 100644 index 0000000000000000000000000000000000000000..ae8d41f65f68d73895be5bbbb539c0d220b2a9a5 Binary files /dev/null and b/en/application-dev/tools/figures/aa-dump-a.png differ diff --git a/en/application-dev/tools/figures/aa-dump-i.png b/en/application-dev/tools/figures/aa-dump-i.png new file mode 100644 index 0000000000000000000000000000000000000000..12998c5ba3e7d667d1147b6e825f8d110d5c5c5e Binary files /dev/null and b/en/application-dev/tools/figures/aa-dump-i.png differ diff --git a/en/application-dev/tools/figures/aa-dump-l.png b/en/application-dev/tools/figures/aa-dump-l.png new file mode 100644 index 0000000000000000000000000000000000000000..a6797eef284990e3fa25e71562ac8afbddf0821d Binary files /dev/null and b/en/application-dev/tools/figures/aa-dump-l.png differ diff --git a/en/application-dev/tools/figures/anm-dump-A.png b/en/application-dev/tools/figures/anm-dump-A.png new file mode 100644 index 0000000000000000000000000000000000000000..368e6f2d810976486e786a4c8f0603a87ad48540 Binary files /dev/null and b/en/application-dev/tools/figures/anm-dump-A.png differ diff --git a/en/application-dev/tools/figures/cem-dump-e.png b/en/application-dev/tools/figures/cem-dump-e.png new file mode 100644 index 0000000000000000000000000000000000000000..c2422ba0e51011174c333985ad7647f170e0f126 Binary files /dev/null and b/en/application-dev/tools/figures/cem-dump-e.png differ diff --git a/en/application-dev/tools/figures/cem-publish-all.png b/en/application-dev/tools/figures/cem-publish-all.png new file mode 100644 index 0000000000000000000000000000000000000000..99526e1f7245d101914354e2a89d5e97d710c27f Binary files /dev/null and b/en/application-dev/tools/figures/cem-publish-all.png differ diff --git a/en/application-dev/tools/figures/cem-publish-event.png b/en/application-dev/tools/figures/cem-publish-event.png new file mode 100644 index 0000000000000000000000000000000000000000..f0ca7e73093f1be72c743bd7c08467f11e2a0e05 Binary files /dev/null and b/en/application-dev/tools/figures/cem-publish-event.png differ diff --git a/en/application-dev/tools/packing-tool.md b/en/application-dev/tools/packing-tool.md new file mode 100644 index 0000000000000000000000000000000000000000..36b5c7fdc295604d7bc46db5e01300e517514ade --- /dev/null +++ b/en/application-dev/tools/packing-tool.md @@ -0,0 +1,90 @@ +# Packaging Tool + + +The packaging tool is a commissioning tool provided by OpenHarmony. It can generate HAP files in command line mode, pack multiple HAP files into an App Pack, or pack multiple HAP files and App Packs into an App Pack. App Pack is the application package format required for releasing an application on AppGallery. + + +The **app_packing_tool.jar** package can be found in the OpenHarmony SDK downloaded locally. + + +- Packing folders into an HAP file + +The command in the stage model is as follows: + + + ```bash + java -jar app_packing_tool.jar --mode