未验证 提交 386a0b46 编写于 作者: O openharmony_ci 提交者: Gitee

!2378 Done! 2082:后台任务管理模块doc修改

Merge pull request !2378 from wusongqing/TR2082
上级 55f7cb37 dfe334ac
master E0523 OpenHarmony-3.1-API8-SDK-Public OpenHarmony-3.2-Beta1 OpenHarmony-3.2-Beta2 OpenHarmony-3.2-Beta3 OpenHarmony-3.2-Beta4 OpenHarmony-3.2-Beta5 OpenHarmony-3.2-Release OpenHarmony-4.0-Beta1 OpenHarmony-4.0-Beta2 OpenHarmony_filemanager_develop_20220505 OpenHarmony_filemanager_develop_20220614 TR4270 bak_OpenHarmony-4.0-Beta1_20230529 docs-modify feature_IDL_20220811 monthly_20220614 monthly_20220816 monthly_20221018 monthly_20230815 revert-merge-17651-master revert-merge-19334-OpenHarmony-4.0-Beta1 revert-merge-19586-master revert-merge-20613-master revert-merge-21757-OpenHarmony-4.0-Beta2 revert-merge-21765-OpenHarmony-4.0-Beta2 revert-merge-23766-master revert-merge-5580-master weekly_20220406 weekly_20220412 weekly_20220419 weekly_20220426 weekly_20220503 weekly_20220510 weekly_20220524 weekly_20220531 weekly_20220607 weekly_20220614 weekly_20220621 weekly_20220628 weekly_20220705 weekly_20220712 weekly_20220719 weekly_20220726 weekly_20220802 weekly_20220809 weekly_20220816 weekly_20220823 weekly_20220830 weekly_20220906 weekly_20220913 weekly_20220920 weekly_20220927 weekly_20221004 weekly_20221011 weekly_20221018 weekly_20221025 weekly_20221101 weekly_20221108 weekly_20221115 weekly_20221122 weekly_20221129 weekly_20221206 weekly_20221213 weekly_20221220 weekly_20221227 weekly_20230103 weekly_20230110 weekly_20230117 weekly_20230124 weekly_20230131 weekly_20230207 weekly_20230214 weekly_20230221 weekly_20230228 weekly_20230307 weekly_20230314 weekly_20230321 weekly_20230328 weekly_20230404 weekly_20230411 weekly_20230418 weekly_20230425 weekly_20230502 weekly_20230509 weekly_20230516 weekly_20230523 weekly_20230530 weekly_20230606 weekly_20230613 weekly_20230619 weekly_20230626 weekly_20230627 weekly_20230704 weekly_20230712 weekly_20230725 weekly_20230801 weekly_20230808 weekly_20230815 weekly_20230822 weekly_20230829 weekly_20230905 OpenHarmony-v4.0-Beta2 OpenHarmony-v4.0-Beta1 OpenHarmony-v3.2.3-Release OpenHarmony-v3.2.2-Release OpenHarmony-v3.2.1-Release OpenHarmony-v3.2-Release OpenHarmony-v3.2-Beta5 OpenHarmony-v3.2-Beta4 OpenHarmony-v3.2-Beta3 OpenHarmony-v3.2-Beta2 OpenHarmony-v3.2-Beta1 OpenHarmony-v3.1.7-Release OpenHarmony-v3.1.6-Release OpenHarmony-v3.1.5-Release OpenHarmony-v3.1.4-Release OpenHarmony-v3.1.3-Release OpenHarmony-v3.1.2-Release OpenHarmony-v3.1.1-Release OpenHarmony-v3.1-Release
无相关合并请求
# Background Task 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.
Frequent activities of background applications cause user devices to consume power quickly and respond slowly. To meet performance and power consumption requirements, the system allows applications to execute only activities within the specifications in the background. Activities beyond the specifications are suspended by default, and resources allocated to them will be reclaimed when the available resources are insufficient.
## Background Task Types
......@@ -11,14 +11,14 @@ Background tasks described in this document refer to the services that need to b
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.
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, 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:**
> ![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.
......@@ -44,7 +44,7 @@ OpenHarmony provides 9 background modes for services that require continuous tas
| Background Mode| Description| Hint in Notification Panel| Remarks|
| -------- | -------- | -------- | -------- |
| dataTransfer | Data transfer through the network or peer device, such as upload, download, backup, and restore| A data transfer task is running.| |
| dataTransfer | Data transfer through the network or peer device, such as download, backup, share, and transfer| A data transfer task is running.| |
| audioPlayback | Audio output| An audio playback task is running.| |
| audioRecording | Audio input| A recording task is running.| |
| location | Positioning and navigation| A positioning task is running.| |
......@@ -55,7 +55,7 @@ OpenHarmony provides 9 background modes for services that require continuous tas
| taskKeeping | Computing task| A computing task is running| PC-specific, valid only on PCs|
### Restrictions on Using Continuous Tasks
- If a user triggers a perceivable task, such as broadcasting, navigation, upload, and download, the corresponding background mode is triggered. When the task is started, the system forcibly displays a notification to the user.
- If a user triggers a perceivable task, such as broadcasting and navigation, the corresponding background mode is triggered. When the task is started, the system forcibly displays a notification to the user.
- If the task is complete, the application should exit the background mode. If the system detects that an application is not using the resources in the corresponding background mode when the application is running in the background, the application is suspended.
- Ensure that the requested continuous task background mode matches the application type. If the background mode does not match the application type, the system will suspend the task once it detects the issue.
- If a requested continuous task is not actually executed, the system will suspend the task once it detects the issue.
......
......@@ -10,12 +10,6 @@
import backgroundTaskManager from '@ohos.backgroundTaskManager';
```
## Required Permissions
Declare the following permissions for continuous tasks:
ohos.permission.KEEP_BACKGROUND_RUNNING
## backgroundTaskManager.requestSuspendDelay
......@@ -27,19 +21,19 @@ The default duration of delayed suspension is 180000 when the battery level is h
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
- **Parameters**
**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**
**Return value**
| Type| Description|
| -------- | -------- |
| [DelaySuspendInfo](#delaysuspendinfo) | Information about the suspension delay.|
- **Example**
```
**Example**
```js
let myReason = 'test requestSuspendDelay';
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
......@@ -55,14 +49,14 @@ Obtains the remaining duration before the application is suspended. This API use
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
- **Parameters**
**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**
```
**Example**
```js
let id = 1;
backgroundTaskManager.getRemainingDelayTime(id, (err, res) => {
if(err.data === 0) {
......@@ -82,18 +76,18 @@ Obtains the remaining duration before the application is suspended. This API use
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
- **Parameters**
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| requestId | number | Yes| ID of the suspension delay request.|
- **Return value**
**Return value**
| Type| Description|
| -------- | -------- |
| Promise<number> | Promise used to return the remaining duration before the application is suspended, in milliseconds.|
- **Example**
```
**Example**
```js
let id = 1;
backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res));
......@@ -111,45 +105,36 @@ Cancels the suspension delay.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
- **Parameters**
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| requestId | number | Yes| ID of the suspension delay request.|
- **Example**
```
**Example**
```js
backgroundTaskManager.cancelSuspendDelay(id);
```
#### DelaySuspendInfo
Provides the information about the suspension delay.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
| 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.|
## backgroundTaskManager.startBackgroundRunning
## backgroundTaskManager.startBackgroundRunning<sup>8+</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void; <sup>8+</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void
Requests a continuous task from the system. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
- **Parameters**
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| context | Context | Yes| Application context.|
| bgMode | BackgroundMode | Yes| Background mode requested.|
| context | [Context](js-apis-Context.md) | Yes| Application context.|
| bgMode | [BackgroundMode](#backgroundmode8) | Yes| Background mode requested.|
| wantAgent | [WantAgent](js-apis-notification.md#WantAgent)| Yes| Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
- **Example**
**Example**
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
......@@ -182,28 +167,30 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
```
## backgroundTaskManager.startBackgroundRunning
## backgroundTaskManager.startBackgroundRunning<sup>8+</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;; <sup>8+</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;
Requests a continuous task from the system. This API uses a promise to return the result.
**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
- **Parameters**
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| context | Context | Yes| Application context.|
| bgMode | BackgroundMode | Yes| Background mode requested.|
| wantAgent | [WantAgent](js-apis-notification.md#WantAgent)| Yes| Notification parameter, which is used to specify the target page when a continuous task notification is clicked.|
| context | [Context](js-apis-Context.md) | Yes| Application context.|
| bgMode | [BackgroundMode](#backgroundmode8) | Yes| Background mode requested.|
| wantAgent | [WantAgent](js-apis-notification.md#WantAgent)| Yes| Notification parameter, which is used to specify the target page when a continuous task notification is clicked.|
- **Return value**
**Return value**
| Type | Description |
| -------------- | ------------------------- |
| Promise\<void> | Promise used to return the result.|
- **Example**
**Example**
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
......@@ -232,21 +219,23 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
```
## backgroundTaskManager.stopBackgroundRunning
## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup>
stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void; <sup>8+</sup>
stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void
Requests to cancel a continuous task. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
- **Parameters**
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| context | Context | Yes| Application context.|
| context | [Context](js-apis-Context.md) | Yes| Application context.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
- **Example**
**Example**
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
......@@ -263,25 +252,27 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callbac
```
## backgroundTaskManager.stopBackgroundRunning
## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup>
stopBackgroundRunning(context: Context): Promise&lt;void&gt;; <sup>8+</sup>
stopBackgroundRunning(context: Context): Promise&lt;void&gt;
Requests to cancel a continuous task. This API uses a promise to return the result.
**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
- **Parameters**
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| context | Context | Yes| Application context.|
| context | [Context](js-apis-Context.md) | Yes| Application context.|
- **Return value**
**Return value**
| Type | Description |
| -------------- | ------------------------- |
| Promise\<void> | Promise used to return the result.|
- **Example**
**Example**
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
......@@ -294,9 +285,21 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(()
```
## DelaySuspendInfo
Provides the information about the suspension delay.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
| 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.|
## BackgroundMode<sup>8+</sup>
**System capability:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
| Name | Value| Description|
| ----------------------- | -------- | -------- |
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册
反馈
建议
客服 返回
顶部