1# @ohos.resourceschedule.backgroundTaskManager (后台任务管理)(系统接口) 2 3<!--Kit: Background Tasks Kit--> 4<!--Subsystem: ResourceSchedule--> 5<!--Owner: @cheng-shichang--> 6<!--Designer: @zhouben25--> 7<!--Tester: @fenglili18--> 8<!--Adviser: @Brilliantry_Rui--> 9 10本模块提供申请后台任务的接口。当应用退至后台时，开发者可以通过本模块接口为应用申请短时、长时任务，避免应用进程被终止或挂起。 11 12> **说明：** 13> 14> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 16> - 当前页面仅包含本模块的系统接口，其他公开接口请参见[@ohos.resourceschedule.backgroundTaskManager (后台任务管理)](js-apis-resourceschedule-backgroundTaskManager.md)。 17 18## 导入模块 19 20```ts 21import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 22``` 23 24## backgroundTaskManager.applyEfficiencyResources 25 26applyEfficiencyResources(request: EfficiencyResourcesRequest): void 27 28申请能效资源。 29 30**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 31 32**系统API**: 此接口为系统接口。 33 34**参数**： 35 36| 参数名 | 类型 | 必填 | 说明 | 37| ------- | ------- | ---- | ---------------------------------------- | 38| request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest) | 是 | 请求的必要信息，包括资源类型、超时时间等。 | 39 40 41**错误码**： 42 43以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 44 45| 错误码ID | 错误信息 | 46| ---- | --------------------- | 47| 201 | Permission denied. | 48| 202 | Not System App. | 49| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 50| 9800001 | Memory operation failed. | 51| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 52| 9800003 | Internal transaction failed. | 53| 9800004 | System service operation failed. | 54| 18700001 | Caller information verification failed for an energy resource request. | 55 56**示例**： 57 58```js 59import { BusinessError } from '@kit.BasicServicesKit'; 60 61let request: backgroundTaskManager.EfficiencyResourcesRequest = { 62 resourceTypes: backgroundTaskManager.ResourceType.CPU, 63 isApply: true, 64 timeOut: 0, 65 reason: "apply", 66 isPersist: true, 67 isProcess: false, 68}; 69try { 70 backgroundTaskManager.applyEfficiencyResources(request); 71 console.info("applyEfficiencyResources success. "); 72} catch (error) { 73 console.error(`applyEfficiencyResources failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 74} 75``` 76 77## backgroundTaskManager.resetAllEfficiencyResources 78 79resetAllEfficiencyResources(): void 80 81释放已申请的全部能效资源。 82 83**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 84 85**系统API**: 此接口为系统接口。 86 87**错误码**： 88 89以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 90 91| 错误码ID | 错误信息 | 92| ---- | --------------------- | 93| 201 | Permission denied. | 94| 202 | Not System App. | 95| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 96| 9800001 | Memory operation failed. | 97| 9800002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 98| 9800003 | Internal transaction failed. | 99| 9800004 | System service operation failed. | 100| 18700001 | Caller information verification failed for an energy resource request. | 101 102**示例**： 103 104```js 105import { BusinessError } from '@kit.BasicServicesKit'; 106 107try { 108 backgroundTaskManager.resetAllEfficiencyResources(); 109} catch (error) { 110 console.error(`resetAllEfficiencyResources failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 111} 112``` 113 114## backgroundTaskManager.getAllEfficiencyResources<sup>20+</sup> 115 116getAllEfficiencyResources(): Promise<EfficiencyResourcesInfo[]> 117 118获取已申请的所有能效资源信息，如能效资源类型等，使用Promise异步回调。 119 120**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 121 122**系统API**: 此接口为系统接口。 123 124**返回值**： 125 126| 类型 | 说明 | 127|-----------------------------------------------|-------------| 128| Promise<[EfficiencyResourcesInfo](#efficiencyresourcesinfo20)[]> | Promise对象，返回所有能效资源信息。 | 129 130**错误码**： 131 132以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[backgroundTaskManager错误码](errorcode-backgroundTaskMgr.md)。 133 134| 错误码ID | 错误信息 | 135| ---- | --------------------- | 136| 202 | Not System App. | 137| 18700001 | Caller information verification failed for an energy resource request. | 138| 18700002 | Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory. | 139| 18700004 | System service operation failed. | 140 141**示例**： 142 143```js 144import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 145import { BusinessError } from '@kit.BasicServicesKit'; 146 147try { 148 backgroundTaskManager.getAllEfficiencyResources().then((res: backgroundTaskManager.EfficiencyResourcesInfo[]) => { 149 console.info(`Operation getAllEfficiencyResources succeeded. data: ` + JSON.stringify(res)); 150 }).catch((error : BusinessError) => { 151 console.error(`Operation getAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`); 152 }); 153} catch (error) { 154 console.error(`Operation getAllEfficiencyResources failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 155} 156``` 157 158## BackgroundMode 159 160长时任务模式。 161 162**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 163 164| 名称 | 值 | 说明 | 165| ----------------------- | ---- | --------------------- | 166| WIFI_INTERACTION | 7 | WLAN相关。<br>**系统API**: 此接口为系统接口。 | 167 168## EfficiencyResourcesRequest 169 170能效资源申请参数。 171 172**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 173 174**系统API**: 此接口为系统接口。 175 176| 名称 | 类型 | 只读 | 可选 | 说明 | 177| --------------- | ------ | ---- | ---- | ---------------------------------------- | 178| resourceTypes | number | 否 | 否 | 申请的资源类型。 | 179| isApply | boolean | 否 | 否 | 申请或释放资源。<br>- true表示申请资源。<br>- false表示释放部分资源。 | 180| timeOut | number | 否 | 否 | 资源使用时间，单位为毫秒。 | 181| isPersist | boolean | 否 | 是 | 是否永久持有资源，默认为false。<br>- true表示永久持有。<br>- false表示有限时间内持有。| 182| isProcess | boolean | 否 | 是 | 进程或应用申请，默认为false。<br>- true表示进程申请。<br>- false表示应用申请。 | 183| reason | string | 否 | 否 | 申请资源原因。 | 184 185## ResourceType 186 187能效资源类型。 188 189**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 190 191**系统API**: 此接口为系统接口。 192 193| 名称 | 值 | 说明 | 194| ----------------------- | ---- | --------------------- | 195| CPU | 1 | CPU资源，申请后应用进程不被挂起。 | 196| COMMON_EVENT | 2 | 公共事件资源，申请后应用进程被挂起后，可以收到公共事件。 | 197| TIMER | 4 | 计时器，申请后应用进程被挂起后，Timer仍然可以唤醒应用。 | 198| WORK_SCHEDULER | 8 | 延迟任务资源，申请后延迟任务管控变宽松。 | 199| BLUETOOTH | 16 | 蓝牙资源，申请后应用进程被挂起后，蓝牙相关事件仍然可以唤醒应用。 | 200| GPS | 32 | GPS资源，申请后应用进程被挂起后，GPS相关事件可以唤醒应用。 | 201| AUDIO | 64 | 音频资源，有音频播放时对应的应用进程不被挂起。 | 202| RUNNING_LOCK<sup>10+</sup> | 128 | RUNNING_LOCK资源，申请后挂起状态不会代理RUNNING_BACKGROUND锁。 | 203| SENSOR<sup>10+</sup> | 256 | 申请后不拦截Sensor回调。 | 204 205## EfficiencyResourcesInfo<sup>20+</sup> 206 207能效资源信息。 208 209**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply 210 211**系统API**: 此接口为系统接口。 212 213| 名称 | 类型 | 只读 | 可选 | 说明 | 214|--------------------------------|---------| ---- | ---- |-------------| 215| [resourceTypes](#resourcetype) | number | 否 | 否 | 能效资源类型。 | 216| timeout | number | 否 | 否 | 超时时间，单位：ms。 | 217| isPersistent | boolean | 否 | 否 | 是否永久持有资源，默认为false。取值为true表示永久持有。取值为false表示有限时间内持有。 | 218| isForProcess | boolean | 否 | 否 | 进程或应用申请，取值为true表示进程申请。取值为false表示应用申请。 | 219| reason | string | 否 | 否 | 申请资源原因。 | 220| uid | number | 否 | 否 | 应用的UID。 | 221| pid | number | 否 | 否 | 应用进程的PID。 |