harmony 鸿蒙@ohos.resourceschedule.backgroundTaskManager (后台任务管理)

2022-10-28 浏览 (1263)

@ohos.resourceschedule.backgroundTaskManager (后台任务管理)

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

说明：

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

导入模块

import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';

backgroundTaskManager.requestSuspendDelay

requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo

申请短时任务。

说明：

短时任务的申请时间最长为3分钟，低电量时最长为1分钟。

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

参数：

参数名类型必填说明
reasonstring是申请短时任务的原因。
callbackCallback<void>是短时任务即将超时的回调函数，一般在超时前6秒，通过此回调通知应用。

返回值：

类型说明
DelaySuspendInfo返回短时任务信息。

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9900001Caller information verification failed.
9900002Background task verification failed.

示例：

import { BusinessError } from '@ohos.base';

let myReason = 'test requestSuspendDelay';
try {
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
    console.info("Request suspension delay will time out.");
})
let id = delayInfo.requestId;
let time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);
} catch (error) {
console.error(`requestSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
}

backgroundTaskManager.getRemainingDelayTime

getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void

获取本次短时任务的剩余时间。使用callback异步回调。

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

参数：

参数名类型必填说明
requestIdnumber是短时任务的请求ID。
callbackAsyncCallback<number>是回调函数，返回本次短时任务的剩余时间，单位为毫秒。

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9900001Caller information verification failed.
9900002Background task verification failed.

示例：

import { BusinessError } from '@ohos.base';

let id = 1;
backgroundTaskManager.getRemainingDelayTime(id, (error: BusinessError, res: number) => {
    if(error) {
        console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
    } else {
        console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
    }
})

backgroundTaskManager.getRemainingDelayTime

getRemainingDelayTime(requestId: number): Promise<number>

获取本次短时任务的剩余时间。使用promise异步回调。

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

参数：

参数名类型必填说明
requestIdnumber是短时任务的请求ID。

返回值：

类型说明
Promise<number>Promise对象，返回本次短时任务的剩余时间，单位为毫秒。

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9900001Caller information verification failed.
9900002Background task verification failed.

示例：

import { BusinessError } from '@ohos.base';

let id = 1;
backgroundTaskManager.getRemainingDelayTime(id).then((res: number) => {
    console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch((error: BusinessError) => {
    console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
})

backgroundTaskManager.cancelSuspendDelay

cancelSuspendDelay(requestId: number): void

取消短时任务。

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

参数：

参数名类型必填说明
requestIdnumber是短时任务的请求ID。

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9900001Caller information verification failed.
9900002Background task verification failed.

示例：

import { BusinessError } from '@ohos.base';

let id = 1;
try {
  backgroundTaskManager.cancelSuspendDelay(id);
} catch (error) {
  console.error(`cancelSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
}

backgroundTaskManager.startBackgroundRunning

startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void

申请长时任务。使用callback异步回调。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
FA模型的应用Context定义见Context。
Stage模型的应用Context定义见Context。
bgModeBackgroundMode是长时任务模式。
wantAgentWantAgent是通知参数，用于指定点击长时任务通知后跳转的界面。
callbackAsyncCallback<void>是回调函数，申请长时任务成功时，err为undefined，否则为错误对象。

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9800005Background task verification failed.
9800006Notification verification failed.
9800007Task storage failed.

示例：

import UIAbility from '@ohos.app.ability.UIAbility';
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';  
import wantAgent, { WantAgent } from '@ohos.app.ability.wantAgent';
import Want from '@ohos.app.ability.Want';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import { BusinessError } from '@ohos.base';

function callback(error: BusinessError, data: void) {
    if (error) {
        console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
    } else {
        console.info("Operation startBackgroundRunning succeeded");
    }
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        let wantAgentInfo: wantAgent.WantAgentInfo = {
            // 点击通知后，将要执行的动作列表
            wants: [
                {
                    bundleName: "com.example.myapplication",
                    abilityName: "EntryAbility"
                }
            ],
            // 点击通知后，动作类型
            operationType: wantAgent.OperationType.START_ABILITY,
            // 使用者自定义的一个私有值
            requestCode: 0,
            // 点击通知后，动作执行属性
            wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
        };

        try {
            // 通过wantAgent模块下getWantAgent方法获取WantAgent对象
            wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => {
                try {
                    backgroundTaskManager.startBackgroundRunning(this.context,
                        backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback)
                } catch (error) {
                    console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
                }
            });
        } catch (error) {
            console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.startBackgroundRunning

startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void>

申请长时任务，使用promise异步回调。

需要权限: ohos.permission.KEEP_BACKGROUND_RUNNING

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
FA模型的应用Context定义见Context。
Stage模型的应用Context定义见Context。
bgModeBackgroundMode是长时任务模式。
wantAgentWantAgent是通知参数，用于指定点击长时任务通知后跳转的界面。

返回值：

类型说明
Promise<void>无返回结果的Promise对象。

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9800005Background task verification failed.
9800006Notification verification failed.
9800007Task storage failed.

示例：

import UIAbility from '@ohos.app.ability.UIAbility';
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; 
import wantAgent, { WantAgent } from '@ohos.app.ability.wantAgent';
import Want from '@ohos.app.ability.Want';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import { BusinessError } from '@ohos.base';

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        let wantAgentInfo: wantAgent.WantAgentInfo = {
            // 点击通知后，将要执行的动作列表
            wants: [
                {
                    bundleName: "com.example.myapplication",
                    abilityName: "EntryAbility"
                }
            ],
            // 点击通知后，动作类型
            operationType: wantAgent.OperationType.START_ABILITY,
            // 使用者自定义的一个私有值
            requestCode: 0,
            // 点击通知后，动作执行属性
            wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
        };

        try {
            // 通过wantAgent模块下getWantAgent方法获取WantAgent对象
            wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => {
                try {
                    backgroundTaskManager.startBackgroundRunning(this.context,
                        backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => {
                        console.info("Operation startBackgroundRunning succeeded");
                    }).catch((error: BusinessError) => {
                        console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
                    });
                } catch (error) {
                    console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
                }
            });
        } catch (error) {
            console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.stopBackgroundRunning

stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void

取消长时任务。使用callback异步回调。

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
FA模型的应用Context定义见Context。
Stage模型的应用Context定义见Context。
callbackAsyncCallback<void>是回调函数，取消长时任务成功时，err为undefined，否则为错误对象。

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9800005Background task verification failed.
9800006Notification verification failed.
9800007Task storage failed.

示例：

import UIAbility from '@ohos.app.ability.UIAbility';
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';  
import Want from '@ohos.app.ability.Want';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import { BusinessError } from '@ohos.base';

function callback(error: BusinessError, data: void) {
    if (error) {
        console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
    } else {
        console.info("Operation stopBackgroundRunning succeeded");
    }
}

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.stopBackgroundRunning(this.context, callback);
        } catch (error) {
            console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.stopBackgroundRunning

stopBackgroundRunning(context: Context): Promise<void>

取消长时任务，使用promise异步回调。

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

参数：

参数名类型必填说明
contextContext是应用运行的上下文。
FA模型的应用Context定义见Context。
Stage模型的应用Context定义见Context。

返回值：

类型说明
Promise<void>无返回结果的Promise对象。

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9800005Background task verification failed.
9800006Notification verification failed.
9800007Task storage failed.

示例：

import UIAbility from '@ohos.app.ability.UIAbility';
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';  
import Want from '@ohos.app.ability.Want';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import { BusinessError } from '@ohos.base';

export default class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        try {
            backgroundTaskManager.stopBackgroundRunning(this.context).then(() => {
                console.info("Operation stopBackgroundRunning succeeded");
            }).catch((error: BusinessError) => {
                console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
            });
        } catch (error) {
            console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`);
        }
    }
};

backgroundTaskManager.applyEfficiencyResources

applyEfficiencyResources(request: EfficiencyResourcesRequest): void

申请能效资源。

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

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

参数：

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

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
18700001Caller information verification failed.

示例：

import { BusinessError } from '@ohos.base';

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错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
18700001Caller information verification failed.

示例：

import { BusinessError } from '@ohos.base';

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

DelaySuspendInfo

短时任务信息。

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

名称类型必填说明
requestIdnumber是短时任务的请求ID。
actualDelayTimenumber是应用实际申请的短时任务时间，单位为毫秒。
短时任务申请时间最长为3分钟，低电量时最长为1分钟。

BackgroundMode

长时任务模式。

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

名称值说明
DATA_TRANSFER1数据传输。
AUDIO_PLAYBACK2音频播放。
AUDIO_RECORDING3录音。
LOCATION4定位导航。
BLUETOOTH_INTERACTION5蓝牙相关。
MULTI_DEVICE_CONNECTION6多设备互联。
WIFI_INTERACTION7WLAN相关。
系统API: 此接口为系统接口。
VOIP8音视频通话。
系统API: 此接口为系统接口。
TASK_KEEPING9计算任务（仅对特定设备开放）。

EfficiencyResourcesRequest

能效资源申请参数。

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

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

名称类型必填说明
resourceTypesnumber是申请的资源类型。
isApplyboolean是申请或释放资源。
- true表示申请资源，false表示释放部分资源。
timeOutnumber是资源使用时间，单位为毫秒。
isPersistboolean否是否永久持有资源，默认为false。
- true表示永久持有，false表示有限时间内持有。
isProcessboolean否进程或应用申请，默认为false。
- true表示进程申请，false表示应用申请。
reasonstring是申请资源原因。

ResourceType

能效资源类型。

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

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

名称值说明
CPU1CPU资源，申请后应用进程不被挂起。
COMMON_EVENT2公共事件资源，申请后应用进程被挂起后，可以收到公共事件。
TIMER4计时器，申请后应用进程被挂起后，Timer仍然可以唤醒应用。
WORK_SCHEDULER8延迟任务资源，申请后延迟任务管控变宽松。
BLUETOOTH16蓝牙资源，申请后应用进程被挂起后，蓝牙相关事件仍然可以唤醒应用。
GPS32GPS资源，申请后应用进程被挂起后，GPS相关事件可以唤醒应用。
AUDIO64音频资源，有音频播放时对应的应用进程不被挂起。
RUNNING_LOCK10+128RUNNING_LOCK资源，申请后挂起状态不会代理RUNNING_BACKGROUND锁。
SENSOR10+256申请后不拦截Sensor回调。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述（仅对系统应用开放）

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/0f4ca2bbfd0c4453802fda7814efd7be