!1430 Done! 1144 增加后台任务管理api文档和开发指南

Merge pull request !1430 from wusongqing/TR1144

en/application-dev/background-task-management/background-task-dev-guide.md

+# Background Task Management Development
+
+## When to Use
+
+If a service needs to be continued when the application or service module is running in the background (not visible to users), the application or service module can request a transient task or continuous task for delayed suspension based on the service type.
+
+
+## Available APIs
+
+```
+import backgroundTaskManager from '@ohos.backgroundTaskManager';
+```
+
+**Table 1** Main APIs of backgroundTaskManager
+
+| API| Description|
+| -------- | -------- |
+| function&nbsp;requestSuspendDelay(reason:&nbsp;string,&nbsp;callback:&nbsp;Callback&lt;void&gt;):&nbsp;**DelaySuspendInfo**; | Requests delayed suspension after the application switches to the background. <br/>The default duration of delayed suspension is 180000 when the battery level is higher than or equal to the broadcast low battery level and 60000 when the battery level is lower than the broadcast low battery level.|
+| function&nbsp;getRemainingDelayTime(requestId:&nbsp;number,&nbsp;callback:&nbsp;AsyncCallback&lt;number&gt;):&nbsp;void;<br/>function&nbsp;getRemainingDelayTime(requestId:&nbsp;number):&nbsp;Promise&lt;number&gt;; | Obtains the remaining duration before the application is suspended. (The value of **requestId** is obtained from the return value of **requestSuspendDelay**.)<br/>Two asynchronous methods are provided: callback and promise.|
+| function&nbsp;cancelSuspendDelay(requestId:&nbsp;number):&nbsp;void; | Cancels the suspension delay. (The value of **requestId** is obtained from the return value of **requestSuspendDelay**.)|
+
+**Table 2** Parameters in DelaySuspendInfo
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| requestId | number | Yes| ID of the suspension delay request.|
+| actualDelayTime | number | Yes| Actual suspension delay duration of the application, in milliseconds.|
+
+
+## How to Develop
+
+1. Request a suspension delay.
+   ```
+   import backgroundTaskManager from '@ohos.backgroundTaskManager';
+   let myReason = 'test requestSuspendDelay';
+   let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
+       console.info("Request suspension delay will time out.");
+   });
+   var id = delayInfo.requestId;console.info("requestId is: " + id);
+   ```
+
+2. Obtain the remaining duration before the application is suspended.
+   ```
+   backgroundTaskManager.getRemainingDelayTime(id).then( res => {
+       console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res));
+   }).catch( err => {
+       console.log('promise => Operation failed. Cause: ' + err.data);
+   });
+   ```
+
+3. Cancel the suspension delay.
+   ```
+   backgroundTaskManager.cancelSuspendDelay(id);
+   ```
+
+
+## Development Examples
+
+```
+import backgroundTaskManager from '@ohos.backgroundTaskManager';
+let myReason = 'test requestSuspendDelay';
+// Request a suspension delay.
+let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
+    console.info("Request suspension delay will time out.");
+});
+// Print the suspension delay information.
+var id = delayInfo.requestId;
+var time = delayInfo.actualDelayTime;
+console.info("The requestId is: " + id);
+console.info("The actualDelayTime is: " + time);
+// Obtain the remaining duration before the application is suspended.
+backgroundTaskManager.getRemainingDelayTime(id).then( res => {
+    console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res));
+}).catch( err => {
+    console.log('promise => Operation failed. Cause: ' + err.data);
+});
+// Cancel the suspension delay.
+backgroundTaskManager.cancelSuspendDelay(id);
+```

en/application-dev/background-task-management/background-task-overview.md

+# Background Task Management Overview
+
+On an OS that allows for user interaction, resources gravitate to service processes that interact with users. In other words, apart from processes that support system running, service processes that can be perceived by users have the highest priority. Therefore, background task management is applicable to service processes that cannot be perceived by users.
+
+
+## Background Task Types
+
+Background tasks described in this document refer to the services that need to be continued when the respective applications or service modules are running in the background (not visible to the users). For more targeted management of background applications and service modules, OpenHarmony classifies applications and service modules into the following types:
+
+1. No background task: An application or service module does not need further processing when switched to the background.
+
+2. Transient task: If an application or service module has an urgent, short task that must continue in the background until it is completed, such as data compression, the application or service module can request a transient task for delayed suspension.
+
+3. Continuous task: If an application or service module has a user-initiated, perceivable task that needs to run in an extended period of time in the background, it can request a continuous task so that it will not be suspended. Examples of continuous tasks include music playback, navigation, upload and download, device connection, and VoIP.
+
+
+## Transient Tasks
+
+As mentioned above, applications and service modules with transient tasks have their suspension delayed so that their running is not affected by background lifecycle management within the specified time frame.
+
+> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:**
+> Applications and service modules can request transient tasks only for temporary tasks. The time quota is 3 minutes per time and 10 minutes per day. The system allocates the time frame based on the application scenario and system status.
+
+
+### Restrictions on Using Transient Tasks
+
+Adhere to the following constraints and rules when using transient tasks:
+
+- **When to request**: An application can request a transient task only when it is running in the foreground or before it is suspended in the background. Otherwise, the application may be suspended, resulting in request failure. By default, an application has 6–12 seconds of running time (subject to the application scenario) before it is suspended in the background.
+
+- **Timeout**: The system notifies the application of the suspension delay timeout by using a callback. The application must then cancel the delayed suspension or apply for delayed suspension again. Otherwise, the application will be forcibly suspended.
+
+- **When to cancel**: The requesting application shall cancel the request when the transient task is complete. If the request is forcibly canceled by the system, the time frame allowed for the application to run in the background will be affected.
+
+- **Quota mechanism**: To prevent abuse of the keepalive, each application has a certain quota every day (dynamically adjusted based on user habits). After using up the quota, an application cannot request transient tasks. Therefore, applications should cancel their request immediately after the transient tasks are complete, to avoid quota consumption. (Note: The quota refers to the requested duration and does not include the time when the application runs in the background.)

en/application-dev/reference/apis/js-apis-backgroundTaskManager.md

+# Background Task Management
+
+> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:**
+> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
+
+
+## Modules to Import
+
+```
+import backgroundTaskManager from '@ohos.backgroundTaskManager';  
+```
+
+
+## Required Permissions
+
+None
+
+
+## backgroundTaskManager.requestSuspendDelay
+
+requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo
+
+Requests delayed suspension after the application switches to the background.
+
+The default duration of delayed suspension is 180000 when the battery level is higher than or equal to the broadcast low battery level and 60000 when the battery level is lower than the broadcast low battery level.
+
+- **Parameters**
+  | Name| Type| Mandatory| Description|
+  | -------- | -------- | -------- | -------- |
+  | reason | string | Yes| Reason for delayed transition to the suspended state.|
+  | callback | Callback<void> | Yes| Invoked when a delay is about to time out. Generally, this callback is used to notify the application 6 seconds before the delay times out.|
+
+- **Return value**
+  | Type| Description|
+  | -------- | -------- |
+  | [DelaySuspendInfo](#delaysuspendinfo) | Information about the suspension delay.|
+
+- **Example**
+  ```
+  let myReason = 'test requestSuspendDelay';
+  let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
+      console.info("Request suspension delay will time out.");
+  })
+  ```
+
+
+## backgroundTaskManager.getRemainingDelayTime
+
+getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void
+
+Obtains the remaining duration before the application is suspended. This method uses an asynchronous callback to return the result.
+
+- **Parameters**
+  | Name| Type| Mandatory| Description|
+  | -------- | -------- | -------- | -------- |
+  | requestId | number | Yes| ID of the suspension delay request.|
+  | callback | AsyncCallback<number> | Yes| Callback used to return the remaining duration before the application is suspended, in milliseconds.|
+
+- **Example**
+  ```
+  let id = 1;
+  backgroundTaskManager.getRemainingDelayTime(id, (err, res) => {
+      if(err.data === 0) {
+          console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res));
+      } else {
+          console.log('promise => Operation failed. Cause: ' + err.data);
+      }
+  })
+  ```
+
+
+## backgroundTaskManager.getRemainingDelayTime
+
+getRemainingDelayTime(requestId: number): Promise<number>
+
+Obtains the remaining duration before the application is suspended. This method uses a promise to return the result.
+
+- **Parameters**
+  | Name| Type| Mandatory| Description|
+  | -------- | -------- | -------- | -------- |
+  | requestId | number | Yes| ID of the suspension delay request.|
+
+- **Return value**
+  | Type| Description|
+  | -------- | -------- |
+  | Promise<number> | Promise used to return the remaining duration before the application is suspended, in milliseconds.|
+
+- **Example**
+  ```
+  let id = 1;
+  backgroundTaskManager.getRemainingDelayTime(id).then( res => {
+      console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res));
+  }).catch( err => {
+      console.log('promise => Operation failed. Cause: ' + err.data);
+  })
+  ```
+
+
+## backgroundTaskManager.cancelSuspendDelay
+
+cancelSuspendDelay(requestId: number): void
+
+Cancels the suspension delay.
+
+- **Parameters**
+  | Name| Type| Mandatory| Description|
+  | -------- | -------- | -------- | -------- |
+  | requestId | number | Yes| ID of the suspension delay request.|
+
+- **Example**
+  ```
+  backgroundTaskManager.cancelSuspendDelay(id);
+  ```
+
+
+#### DelaySuspendInfo
+
+Provides the information about the suspension delay.
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| requestId | number | Yes| ID of the suspension delay request.|
+| actualDelayTime | number | Yes| Actual suspension delay duration of the application, in milliseconds. <br/>The default duration is 180000 when the battery level is higher than or equal to the broadcast low battery level and 60000 when the battery level is lower than the broadcast low battery level.|

zh-cn/application-dev/background-task-management/background-task-dev-guide.md

@@ -34,7 +34,7 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager';
    import backgroundTaskManager from '@ohos.backgroundTaskManager';
    let myReason = 'test requestSuspendDelay';
    let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
-       console.info("Request suspend delay will time out.");
+       console.info("Request suspension delay will time out.");
    });
    var id = delayInfo.requestId;console.info("requestId is: " + id);
    ```
@@ -61,7 +61,7 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager';
 let myReason = 'test requestSuspendDelay';
 // 申请延迟挂起
 let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
-    console.info("Request suspend delay will time out.");
+    console.info("Request suspension delay will time out.");
 });
 // 打印延迟挂起信息
 var id = delayInfo.requestId;

zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md

@@ -39,7 +39,7 @@ requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspen
   ```
   let myReason = 'test requestSuspendDelay';
   let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
-      console.info("Request suspend delay will time out.");
+      console.info("Request suspension delay will time out.");
   })
   ```