长待机开发文档补充

Signed-off-by: N xufanghan <xufanghan@huawei.com>

长待机开发文档补充
Signed-off-by: N xufanghan <xufanghan@huawei.com>
644b42df · geraltxu · 4e9296cc · 644b42df · 644b42df
2 changed file
--- a/zh-cn/application-dev/device_standby/device-standby-use-guide.md
+++ b/zh-cn/application-dev/device_standby/device-standby-use-guide.md
+# 设备待机空闲部件开发指南
+## 场景介绍
+当前设备在待机状态及睡眠状态，应用不会被冻结、任务不会被延迟、时钟时间不会变慢、CPU锁不会释放、网络不会停止，导致灭屏功耗大。
+设备灭屏/锁屏情况下，保持一段时间后进入待机空闲模式，限制后台应用使用资源，降低功耗。<br>
+解决以下场景<br>
+一、采集系统设备进入待机空闲特征<br>
+二、检测设备进入浅睡眠状态和深睡眠状态<br>
+三、设备每隔一段时间暂停睡眠，进入维护状态<br>
+四、检测到设备进入待机空闲状态，触发资源管控
+
+本文档旨在帮助开发者理解设备待机空闲下的相关功能和资源使用规范。
+## 待机低续航模式介绍
+待机低续航模式会延迟应用后台cpu和网络活动，从而延长电池续航时间。
+<br>包括：
+<br>1.应用限网：限制访问网络
+<br>2.work待机任务：延迟应用的work任务响应
+<br>3.running_lock锁：释放应用的锁
+<br>4.Timer响应：延迟应用的timer响应
+## 接口说明
+### 一、返回当前是否进入待机功耗续航模式
+isDeviceInStandby()
+<br>
+功能描述：返回当前是否进入待机低功耗续航模式。
+<br>
+举例：push客户端应用获取待机状态管控消息推送缓存
+### 二、获取豁免信息
+getExemptionListApps()
+<br>
+功能描述：获取豁免信息
+<br>
+举例：push客户端应用获取push限网豁免名单
+### 三、更新调用者豁免信息
+applyExemptionAppResource()、unapplyExemptionAppResource()
+<br>
+功能描述：更新调用者豁免信息
+<br>
+举例：针对系统应用可以申请临时豁免，临时放行待机状态管控该应用使用资源限制
--- a/zh-cn/application-dev/reference/apis/js-apis-resourceschedule-deviceStandby.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-resourceschedule-deviceStandby.md
+# @ohos.resourceschedule.deviceStandby（设备待机空闲部件功能）
+本模块提供设备待机空闲部件管理功能
+<br>
+API使用场景：
+<br>
+如果用户长时间没有主动使用设备，且屏幕已关闭，则系统会使设备进入待机低功耗续航模式。待机续航模式会延迟应用后台CPU和网络活动，从而延长电池续航时间。 包括：
+<br>
+1、应用限网：通过iptable防火墙限制后台应用访问网络
+<br>
+2、Work待机任务：延迟应用的work任务响应
+<br>
+3、running_lock锁：临时释放应用的background running_lock锁
+<br>
+4、Timer响应：延迟应用的timer响应
+<br>
+5、待规划：停止wifi扫描、停止蓝牙扫描、云同步账户等
+
+>  **说明：**
+> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+
+## 导入模块
+```js
+import deviceStandby from '@ohos.resourceschedule.deviceStandby';
+```
+## deviceStandby.isDeviceInStandby
+function isDeviceInStandby(callback: AsyncCallback<boolean>): void;
+<br>
+当前设备是否进入待机低功耗续航模式
+<br>
+**系统能力:** SystemCapability.ResourceSchedule.DeviceStandby.Idle
+
+**参数**：
+
+| 参数名      | 类型                   | 必填   | 说明                             |
+| -------- | -------------------- | ---- | ------------------------------ |
+| callback | Callback&lt;void&gt; | 是    | 延迟即将超时的回调函数，一般在超时前6秒通过此回调通知应用。 |
+
+**错误码**：
+
+以下错误码的详细介绍请参见[@ohos.resourceschedule.backgroundTaskManager (后台任务管理)](../errorcodes/errorcode-backgroundTaskMgr.md)错误码。
+
+| 错误码ID  | 错误信息             |
+| ---- | --------------------- |
+| 201 | Permission denied. |
+| 401 | Parameter error. |
+| 9800001 | Memory operation failed. |
+| 9800002 | Parcel operation failed. |
+| 9800003 | IPC failed. | |
+| 9800004 | System service operation failed. |
+| 18700001 | Caller information verification failed when applying for efficiency resources. |
+
+## deviceStandby.isDeviceInStandby
+function isDeviceInStandby(): Promise&lt;boolean&gt;
+<br>
+当前设备是否进入待机低功耗续航模式
+<br>
+**系统能力:** SystemCapability.ResourceSchedule.DeviceStandby.Idle
+
+**返回值**：
+
+| 类型                    | 说明                                       |
+| --------------------- | ---------------------------------------- |
+| Promise&lt;boolean&gt; | 指定的Promise回调方法。返回是否进入待机低功耗续航模式。|
+
+**错误码**：
+以下错误码的详细介绍请参见[@ohos.resourceschedule.backgroundTaskManager (后台任务管理)](../errorcodes/errorcode-backgroundTaskMgr.md)错误码。
+
+| 错误码ID  | 错误信息             |
+| ---- | --------------------- |
+| 201 | Permission denied. |
+| 401 | Parameter error. |
+| 9800001 | Memory operation failed. |
+| 9800002 | Parcel operation failed. |
+| 9800003 | IPC failed. | |
+| 9800004 | System service operation failed. |
+| 18700001 | Caller information verification failed when applying for efficiency resources. |
+
+## deviceStandby.getExemptionListApps
+function getExemptionListApps(resourceTypes: number, callback: AsyncCallback<Array&lt;ExemptionAppInfo&gt;>): void;
+<br>
+返回豁免应用名单
+<br>
+**系统能力:** SystemCapability.ResourceSchedule.DeviceStandby.Exemption
+<br>
+**系统API:** 此接口为系统接口。
+
+**参数**：
+
+| 参数名      | 类型                   | 必填   | 说明                             |
+| -------- | -------------------- | ---- | ------------------------------ |
+| resourceTypes |number | 是    | 资源类型，具体结构见文末枚举 |
+| callback | AsyncCallback<Array&lt;ExemptionAppInfo&gt;> | 是    | 回调函数，具体结构见文末 |
+
+**错误码**：
+
+以下错误码的详细介绍请参见[@ohos.resourceschedule.backgroundTaskManager (后台任务管理)](../errorcodes/errorcode-backgroundTaskMgr.md)错误码。
+
+| 错误码ID  | 错误信息             |
+| ---- | --------------------- |
+| 201 | Permission denied. |
+| 202 | Not System App. |
+| 401 | Parameter error. |
+| 9800001 | Memory operation failed. |
+| 9800002 | Parcel operation failed. |
+| 9800003 | IPC failed. | |
+| 9800004 | System service operation failed. |
+| 18700001 | Caller information verification failed when applying for efficiency resources. |
+## deviceStandby.getExemptionListApps
+function getExemptionListApps(resourceTypes: number): Promise<Array&lt;ExemptionAppInfo&gt;>;
+<br>
+返回豁免应用名单
+<br>
+**系统能力:** SystemCapability.ResourceSchedule.DeviceStandby.Exemption
+<br>
+**系统API:** 此接口为系统接口。
+
+**参数**：
+
+| 参数名      | 类型                   | 必填   | 说明                             |
+| -------- | -------------------- | ---- | ------------------------------ |
+| resourceTypes |number | 是    | 资源类型。 |
+
+**返回值**：
+
+| 类型                    | 说明                                       |
+| --------------------- | ---------------------------------------- |
+| Promise<Array&lt;ExemptionAppInfo&gt;> | 指定的Promise回调方法。返回豁免应用名单，具体结构见文末|
+
+**错误码**：
+
+以下错误码的详细介绍请参见[@ohos.resourceschedule.backgroundTaskManager (后台任务管理)](../errorcodes/errorcode-backgroundTaskMgr.md)错误码。
+
+| 错误码ID  | 错误信息             |
+| ---- | --------------------- |
+| 201 | Permission denied. |
+| 202 | Not System App. |
+| 401 | Parameter error. |
+| 9800001 | Memory operation failed. |
+| 9800002 | Parcel operation failed. |
+| 9800003 | IPC failed. | |
+| 9800004 | System service operation failed. |
+| 18700001 | Caller information verification failed when applying for efficiency resources. |
+
+## deviceStandby.applyExemptionAppResource
+function applyExemptionAppResource(request: ResourceRequest): void;
+<br>
+订阅申请豁免
+<br>
+**系统能力:** SystemCapability.ResourceSchedule.DeviceStandby.Exemption
+<br>
+**系统API:** 此接口为系统接口。
+
+**参数**：
+
+| 参数名      | 类型                   | 必填   | 说明                             |
+| -------- | -------------------- | ---- | ------------------------------ |
+| request |ResourceRequest | 是    | 请求豁免应用信息数据结构，具体结构见文末请求体 |
+
+**错误码**：
+
+以下错误码的详细介绍请参见[@ohos.resourceschedule.backgroundTaskManager (后台任务管理)](../errorcodes/errorcode-backgroundTaskMgr.md)错误码。
+
+| 错误码ID  | 错误信息             |
+| ---- | --------------------- |
+| 201 | Permission denied. |
+| 202 | Not System App. |
+| 401 | Parameter error. |
+| 9800001 | Memory operation failed. |
+| 9800002 | Parcel operation failed. |
+| 9800003 | IPC failed. | |
+| 9800004 | System service operation failed. |
+| 18700001 | Caller information verification failed when applying for efficiency resources. |
+
+## deviceStandby.unapplyExemptionAppResource
+function unapplyExemptionAppResource(request: ResourceRequest): void;
+<br>
+去除订阅申请豁免
+<br>
+**系统能力:** SystemCapability.ResourceSchedule.DeviceStandby.Exemption
+<br>
+**系统API:** 此接口为系统接口。
+
+**参数**：
+
+| 参数名      | 类型                   | 必填   | 说明                             |
+| -------- | -------------------- | ---- | ------------------------------ |
+| request |ResourceRequest | 是    | 请求豁免应用信息数据结构，具体结构见文末请求体 |
+
+**错误码**：
+
+以下错误码的详细介绍请参见[@ohos.resourceschedule.backgroundTaskManager (后台任务管理)](../errorcodes/errorcode-backgroundTaskMgr.md)错误码。
+
+| 错误码ID  | 错误信息             |
+| ---- | --------------------- |
+| 201 | Permission denied. |
+| 202 | Not System App. |
+| 401 | Parameter error. |
+| 9800001 | Memory operation failed. |
+| 9800002 | Parcel operation failed. |
+| 9800003 | IPC failed. | |
+| 9800004 | System service operation failed. |
+| 18700001 | Caller information verification failed when applying for efficiency resources. |
+
+## 枚举类和请求体
+### ResourceType
+The resource type of exemption application.
+<br>
+
+|名称   |枚举值   |说明|
+| ------------ | ------------ |--------------|
+|NETWORK    |1   |The resource for non-standby network access.|
+|RUNNING_LOCK    |1 << 1   |The resource for non-standby cpu-runninglock.|
+|TIMER     |1 << 2   |The resource for non-standby timer.|
+|WORK_SCHEDULER     |1 << 3   |The resource for non-standby workscheduler.|
+|AUTO_SYNC      |1 << 4   |The resource for non-standby Automatic synchronization.|
+|PUSH     |1 << 5   |The resource for non-standby pushkit.|
+|FREEZE       |1 << 6   |The resource for non-standby freezing application.|
+
+### ExemptionAppInfo
+The information of exemption application.
+<br>
+
+|对象名   |类型   |说明   |
+| ------------ | ------------ | ------------ |
+|resourceTypes   | number  |The set of resource types that app wants to apply.   |
+|name   |string   |  The app name.  |
+|duration   | number  | The exemption duration. |
+
+### ResourceRequest
+The request of standby resources.
+<br>
+
+|对象名   |类型   |说明   |
+| ------------ | ------------ | ------------ |
+|resourceTypes   | number  |The set of resource types that app wants to apply.   |
+|uid   | number  |The app uid.   |
+|name   |string   |  The app name.  |
+|duration   | number  | The exemption duration. |
+|reason   |string   |  The apply reason.  |
\ No newline at end of file