!9072 增加能效资源申请的api说明

Merge pull request !9072 from ZhaoPengfei/master

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

@@ -8,6 +8,8 @@
 
 应用中存在用户能够直观感受到的且需要一直在后台运行的业务时（如，后台播放音乐），可以使用长时任务机制。
 
+对于系统特权应用，提供独立的能效资源申请接口。系统特权应用如果需要使用特定的系统资源，例如在被挂起期间仍然能够收到系统公共事件，可以使用能效资源申请接口。
+
 >  **说明：**
 > 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
 
@@ -201,7 +203,7 @@ startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: Want
 | bgMode    | [BackgroundMode](#backgroundmode8) | 是    | 向系统申请的后台模式。                              |
 | wantAgent | [WantAgent](js-apis-wantAgent.md)  | 是    | 通知参数，用于指定长时任务通知点击跳转的界面。                  |
 
-**返回值**
+**返回值**：
 | 类型             | 说明               |
 | -------------- | ---------------- |
 | Promise\<void> | 使用Promise形式返回结果。 |
@@ -279,7 +281,7 @@ stopBackgroundRunning(context: Context): Promise&lt;void&gt;
 | ------- | ------- | ---- | ---------------------------------------- |
 | context | Context | 是    | 应用运行的上下文。<br>FA模型的应用Context定义见[Context](js-apis-Context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 |
 
-**返回值**
+**返回值**：
 | 类型             | 说明               |
 | -------------- | ---------------- |
 | Promise\<void> | 使用Promise形式返回结果。 |
@@ -297,6 +299,64 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(()
 
 ```
 
+## backgroundTaskManager.applyEfficiencyResources<sup>9+</sup>
+
+applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): boolean
+
+向系统申请能效资源，使用boolean形式返回结果。
+进程和它所属的应用可以同时申请某一类资源，例如CPU资源，但是应用释放资源的时候会将进程的资源一起释放。
+
+**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
+
+**系统API**: 此接口为系统接口。
+
+**参数**：
+
+| 参数名     | 类型      | 必填   | 说明                                       |
+| ------- | ------- | ---- | ---------------------------------------- |
+| request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest9) | 是    | 请求的必要信息。包括资源类型，超时时间等信息。详见[EfficiencyResourcesRequest](#efficiencyresourcesrequest9)。 |
+
+**返回值**：
+| 类型             | 说明               |
+| -------------- | ---------------- |
+| boolean | true代表申请成功，false代表申请失败。 |
+
+**示例**：
+
+```js
+import backgroundTaskManager from '@ohos.backgroundTaskManager';
+
+let request = {
+    resourceTypes: backgroundTaskManager.ResourceType.CPU,
+    isApply: true,
+    timeOut: 0,
+    reason: "apply",
+    isPersist: true,
+    isProcess: false,
+};
+let res = backgroundTaskManager.applyEfficiencyResources(request);
+console.info("result of applyEfficiencyResources is: " + res)
+```
+
+## backgroundTaskManager.resetAllEfficiencyResources<sup>9+</sup>
+
+resetAllEfficiencyResources(): void
+
+释放所有已经申请的资源。
+
+**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
+
+**系统API**: 此接口为系统接口。
+
+**示例**：
+
+```js
+import backgroundTaskManager from '@ohos.backgroundTaskManager';
+
+backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
+
+```
+
 ## DelaySuspendInfo
 
 延迟挂起信息。
@@ -315,12 +375,47 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(()
 
 | 参数名                     | 参数值  | 描述                    |
 | ----------------------- | ---- | --------------------- |
-| DATA_TRANSFER           | 1    | 数据传输                  |
-| AUDIO_PLAYBACK          | 2    | 音频播放                  |
-| AUDIO_RECORDING         | 3    | 录音                    |
-| LOCATION                | 4    | 定位导航                  |
-| BLUETOOTH_INTERACTION   | 5    | 蓝牙相关                  |
-| MULTI_DEVICE_CONNECTION | 6    | 多设备互联                 |
+| DATA_TRANSFER           | 1    | 数据传输。                  |
+| AUDIO_PLAYBACK          | 2    | 音频播放。                  |
+| AUDIO_RECORDING         | 3    | 录音。                    |
+| LOCATION                | 4    | 定位导航。                  |
+| BLUETOOTH_INTERACTION   | 5    | 蓝牙相关。                  |
+| MULTI_DEVICE_CONNECTION | 6    | 多设备互联。                 |
 | WIFI_INTERACTION        | 7    | WLAN相关<br />此接口为系统接口。 |
 | VOIP                    | 8    | 音视频通话<br />此接口为系统接口。  |
-| TASK_KEEPING            | 9    | 计算任务（仅在特定设备生效）        |
+| TASK_KEEPING            | 9    | 计算任务（仅在特定设备生效）。        |
\ No newline at end of file
+
+## EfficiencyResourcesRequest<sup>9+</sup>
+
+能效资源申请参数。
+
+**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
+
+**系统API**: 此接口为系统接口。
+
+| 参数名             | 类型     | 必填   | 说明                                       |
+| --------------- | ------ | ---- | ---------------------------------------- |
+| resourceTypes   | number  | 是    | 申请的资源类型。                               |
+| isApply         | boolean | 是    | 申请资源或者是释放资源。          |
+| timeOut         | number  | 是    | 资源的使用时间，以毫秒为单位。                |
+| isPersist       | boolean | 否    | 是否永久持有资源，如果是true，那么timeOut就无效。    |
+| isProcess       | boolean | 否    | 应用申请或者是进程申请。          |
+| reason          | string  | 是    | 申请资源的原因。                |
+
+## ResourceType<sup>9+</sup>
+
+能效资源类型。
+
+**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
+
+**系统API**: 此接口为系统接口。
+
+| 参数名                     | 参数值  | 描述                    |
+| ----------------------- | ---- | --------------------- |
+| CPU                     | 1    | CPU资源，申请后不被挂起。             |
+| COMMON_EVENT            | 2    | 公共事件，申请后挂起状态下不被代理掉。  |
+| TIMER                   | 4    | 计时器，申请后挂起状态下不被代理掉。    |
+| WORK_SCHEDULER          | 8    | 延迟任务，申请后有更长的执行时间。      |
+| BLUETOOTH               | 16   | 蓝牙相关，申请后挂起状态下不被代理掉。  |
+| GPS                     | 32   | GPS相关，申请后挂起状态下不被代理掉。  |
+| AUDIO                   | 64   | 音频资源，申请后挂起状态下不被代理掉。 |
\ No newline at end of file

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

@@ -2,7 +2,9 @@
 
 ## 场景介绍
 
-应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。
+应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。如果应用需要更加灵活的配置，可以申请能效资源。常见的使用能效资源的场景有：1.应用保证自己在一个时间段内不被挂起，直到任务完成；2.应用处于挂起状态时仍然需要系统的资源，例如闹钟需要计时器资源；3.延时任务需要不受到执行频率的限制，并且拥有更长的执行时间。
+
+在挂起时如果需要单独的某种资源不被代理或者需要更长的延时任务执行时间，可以申请所需的能效资源。
 
 ## 短时任务
 
@@ -486,6 +488,93 @@ export default class BgTaskAbility extends Ability {
 };
 ```
 
+## 能效资源申请
+
+### 接口说明
+
+**表1** 能效资源申请主要接口
+
+| 接口名                                      | 描述                                       |
+| ---------------------------------------- | ---------------------------------------- |
+| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): boolean | 申请能效资源。 |
+| resetAllEfficiencyResources():void | 释放申请的能效资源。   |
+
+
+### 开发步骤
+
+
+1. 申请能效资源
+
+```js
+import backgroundTaskManager from '@ohos.backgroundTaskManager';
+
+let request = {
+    resourceTypes: backgroundTaskManager.ResourceType.CPU,
+    isApply: true,
+    timeOut: 0,
+    reason: "apply",
+    isPersist: true,
+    isProcess: true,
+};
+let res = backgroundTaskManager.applyEfficiencyResources(request);
+console.info("the result of request is: " + res);
+```
+
+2. 释放申请的部分资源
+
+```js
+import backgroundTaskManager from '@ohos.backgroundTaskManager';
+
+let request = {
+    resourceTypes: backgroundTaskManager.ResourceType.CPU,
+    isApply: false,
+    timeOut: 0,
+    reason: "reset",
+};
+let res = backgroundTaskManager.applyEfficiencyResources(request);
+console.info("the result of request is: " + res);
+```
+
+3. 释放申请的所有资源
+
+```js
+import backgroundTaskManager from '@ohos.backgroundTaskManager';
+
+backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
+```
+
+### 开发实例
+
+```js
+import backgroundTaskManager from '@ohos.backgroundTaskManager';
+
+// 申请能效资源
+let request = {
+    resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT |
+        backgroundTaskManager.ResourceType.TIMER,
+    isApply: true,
+    timeOut: 0,
+    reason: "apply",
+    isPersist: true,
+    isProcess: true,
+};
+let res = backgroundTaskManager.applyEfficiencyResources(request);
+console.info("the result of request is: " + res);
+
+// 释放部分资源
+request = {
+    resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT,
+    isApply: false,
+    timeOut: 0,
+    reason: "reset",
+};
+res = backgroundTaskManager.applyEfficiencyResources(request);
+console.info("the result of request is: " + res);
+
+// 释放全部资源
+backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
+```
+
 ## 相关实例
 
 基于后台任务管理，有以下相关实例可供参考：

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

 # 后台任务概述
 
-后台应用频繁活动，会造成用户设备耗电快、卡顿等现象。因此，为了支撑性能、功耗诉求，系统仅允许应用在后台执行规范内的活动，规范外的活动默认会被挂起，当资源不足时会被回收。
+后台应用频繁活动，会造成用户设备耗电快、卡顿等现象。因此，为了支撑性能、功耗诉求，系统仅允许应用在后台执行规范内的活动，规范外的活动默认会被挂起，当资源不足时会被回收。同时，应用可以申请能效资源，保证自己在一段时间内不会被挂起，或者在挂起状态能够正常使用一些资源，例如公共事件、计时器等。
 
 
 ## 后台任务类型
@@ -13,6 +13,8 @@
 
  **3. 长时任务** ：如果是用户发起的可感知业务需要长时间后台运行，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。
 
+ **4. 能效资源** ：能效资源包括CPU资源、WORK_SCHEDULER资源、软件资源(COMMON_EVENT, TIMER)、硬件资源(GPS, BLUETOOTH)。如果应用或者进程申请了能效资源，那么根据能效资源的类型会拥有相应的特权，例如申请了CPU资源的可以不被挂起，申请了WORK_SCHEDULER后延时任务可以拥有更长的执行时间。
+
 
 ## 短时任务
 
@@ -59,4 +61,26 @@ OpenHarmony提供了九种后台模式，供需要在后台做长时任务的业
 - 如果任务结束，应用应主动退出后台模式。若在后台运行期间，系统检测到应用并未使用对应后台模式的资源，则会被挂起（Suspend）。
 - 避免不合理地申请后台长时任务，长时任务类型要与应用的业务类型匹配。如果执行的任务和申请的类型不匹配，也会被系统检测到并被挂起（Suspend）。
 - 长时任务是为了真正在后台长时间执行某个任务，如果一个应用申请了长时任务，但在实际运行过程中，并未真正运行或执行此类任务时，也会被系统检测到并被挂起（Suspend）。
-- 一个Ability同一时刻只能申请运行一个长时任务。
+- 一个Ability同一时刻只能申请运行一个长时任务。
\ No newline at end of file
+
+## 能效资源申请
+能效资源可以分为四种，CPU资源，WORK_SCHEDULER资源，软件资源(COMMON_EVENT，TIMER)，硬件资源(GPS,BLOOTOOTH,AUDIO)。
+应用或进程申请能效资源后能够获得相应特权，例如：申请CPU资源后可以不被挂起；申请WORK_SCHEDULER资源后不受延迟任务执行频率约束，且任务执行时间增加；申请软件、硬件资源后，相关资源在挂起状态下不被代理。
+
+
+**表1** 能效资源种类
+
+| 参数名                     | 参数值  | 描述                    |
+| ----------------------- | ---- | --------------------- |
+| CPU                     | 1    | CPU资源，申请后不被挂起             |
+| COMMON_EVENT            | 2    | 公共事件，申请后挂起状态下不被代理掉  |
+| TIMER                   | 4    | 计时器，申请后挂起状态下不被代理掉    |
+| WORK_SCHEDULER          | 8    | 延迟任务，申请后有更长的执行时间      |
+| BLUETOOTH               | 16   | 蓝牙相关，申请后挂起状态下不被代理掉  |
+| GPS                     | 32   | GPS相关，申请后挂起状态下不被代理掉  |
+| AUDIO                   | 64   | 音频资源，申请后挂起状态下不被代理掉 |
+
+### 能效资源使用约束
+- 能效资源申请或者释放可以由进程或者应用发起，由应用发起的资源释放会释放属于它的同类型的所有资源，包括进程申请的资源。例如应用申请了CPU资源,进程申请了CPU和WORK_SCHEDULER资源，当应用释放CPU资源的时候，会将进程的CPU资源一同释放，同时不同类型的WORK_SCHEDULER资源不受影响。由进程发起的资源释放对应用申请的资源没有影响，例如当应用和进程同时申请了CPU，进程发起了CPU资源释放，应用的CPU资源不会被释放。
+- 同时申请同一类持久资源和非持久资源，持久资源会覆盖非持久资源，在超时时不会释放资源。例如应用首先申请了10s的CPU资源，然后在第5s的时候申请了持久的CPU资源，那么资源会变成持久的，非持久的CPU资源记录会被持久化的CPU资源记录覆盖，到了第10s的时候资源不会被释放，如果在第8s的时候提前释放了资源，那么会将CPU资源释放，无法单独释放其中非持久的或者持久的CPU资源。
+- WORK_SCHEDULER资源只能由应用申请和释放，不能由进程申请和释放。

zh-cn/application-dev/task-management/work-scheduler-overview.md

@@ -10,8 +10,8 @@
 
 延迟调度任务的使用需要遵从如下约束和规则：
 
-- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。
-- **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。
+- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。默认的超时限制为2分钟，对于系统应用，可以通过[能效资源申请接口](background-task-overview.md#能效资源申请)获取更长的执行时间（充电状态20分钟，非充电状态10分钟）。
+- **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。对于通过能效资源接口申请了WORK_SCHEDULER资源的应用，在资源的有效期内，它的延迟任务执行频率不受限制。
 
 应用分组             |     延迟任务执行频率约束                            
 --------------------|-------------------------
@@ -21,6 +21,7 @@
 不经常使用 | 最小间隔48小时 
 受限分组 | 禁止 
 未使用分组 | 禁止 
+[能效资源豁免分组](../reference/apis/js-apis-backgroundTaskManager.md#resourcetype9)  | 执行频率不受限制
 
 - **WorkInfo设置参数约束**