@ohos.resourceschedule.backgroundTaskManager (后台任务管理)(系统接口)

本模块提供申请后台任务的接口。当应用退至后台时，开发者可以通过本模块接口为应用申请短时、长时任务，避免应用进程被终止或挂起。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

当前页面仅包含本模块的系统接口，其他公开接口请参见@ohos.resourceschedule.backgroundTaskManager (后台任务管理)。

导入模块

import { backgroundTaskManager } from '@kit.BackgroundTasksKit';

backgroundTaskManager.applyEfficiencyResources

applyEfficiencyResources(request: EfficiencyResourcesRequest): void

申请能效资源。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply

系统API: 此接口为系统接口。

参数：

参数名	类型	必填	说明
request	EfficiencyResourcesRequest	是	请求的必要信息，包括资源类型、超时时间等。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID	错误信息
201	Permission denied.
202	Not System App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.
9800001	Memory operation failed.
9800002	Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003	Internal transaction failed.
9800004	System service operation failed.
18700001	Caller information verification failed for an energy resource request.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let request: backgroundTaskManager.EfficiencyResourcesRequest = {
    resourceTypes: backgroundTaskManager.ResourceType.CPU,
    isApply: true,
    timeOut: 0,
    reason: "apply",
    isPersist: true,
    isProcess: false,
};
try {
    backgroundTaskManager.applyEfficiencyResources(request);
    console.info("applyEfficiencyResources success. ");
} catch (error) {
    console.error(`applyEfficiencyResources failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
}

backgroundTaskManager.resetAllEfficiencyResources

resetAllEfficiencyResources(): void

释放已申请的全部能效资源。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply

系统API: 此接口为系统接口。

错误码：

以下错误码的详细介绍请参见通用错误码和backgroundTaskManager错误码。

错误码ID	错误信息
201	Permission denied.
202	Not System App.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.
9800001	Memory operation failed.
9800002	Failed to write data into parcel. Possible reasons: 1. Invalid parameters; 2. Failed to apply for memory.
9800003	Internal transaction failed.
9800004	System service operation failed.
18700001	Caller information verification failed for an energy resource request.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

try {
    backgroundTaskManager.resetAllEfficiencyResources();
} catch (error) {
    console.error(`resetAllEfficiencyResources failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
}

BackgroundMode

长时任务模式。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

名称	值	说明
WIFI_INTERACTION	7	WLAN相关。系统API: 此接口为系统接口。

EfficiencyResourcesRequest

能效资源申请参数。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply

系统API: 此接口为系统接口。

名称	类型	只读	可选	说明
resourceTypes	number	否	否	申请的资源类型。
isApply	boolean	否	否	申请或释放资源。 - true表示申请资源。 - false表示释放部分资源。
timeOut	number	否	否	资源使用时间，单位为毫秒。
isPersist	boolean	否	是	是否永久持有资源，默认为false。 - true表示永久持有。 - false表示有限时间内持有。
isProcess	boolean	否	是	进程或应用申请，默认为false。 - true表示进程申请。 - false表示应用申请。
reason	string	否	否	申请资源原因。

ResourceType

能效资源类型。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply

系统API: 此接口为系统接口。

名称	值	说明
CPU	1	CPU资源，申请后应用进程不被挂起。
COMMON_EVENT	2	公共事件资源，申请后应用进程被挂起后，可以收到公共事件。
TIMER	4	计时器，申请后应用进程被挂起后，Timer仍然可以唤醒应用。
WORK_SCHEDULER	8	延迟任务资源，申请后延迟任务管控变宽松。
BLUETOOTH	16	蓝牙资源，申请后应用进程被挂起后，蓝牙相关事件仍然可以唤醒应用。
GPS	32	GPS资源，申请后应用进程被挂起后，GPS相关事件可以唤醒应用。
AUDIO	64	音频资源，有音频播放时对应的应用进程不被挂起。
RUNNING_LOCK¹⁰⁺	128	RUNNING_LOCK资源，申请后挂起状态不会代理RUNNING_BACKGROUND锁。
SENSOR¹⁰⁺	256	申请后不拦截Sensor回调。