Background Task Management

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import backgroundTaskManager from '@ohos.backgroundTaskManager';  

backgroundTaskManager.requestSuspendDelay

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

Requests delayed suspension after the application switches to the background.

The default duration of delayed suspension is 180000 when the battery level is higher than or equal to the broadcast low battery level and 60000 when the battery level is lower than the broadcast low battery level.

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

Parameters

Return value

Example

let myReason = 'test requestSuspendDelay';
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
    console.info("Request suspension delay will time out.");
})

var id = delayInfo.requestId;
var time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);

backgroundTaskManager.getRemainingDelayTime

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

Obtains the remaining duration before the application is suspended. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

Parameters

Example

let id = 1;
backgroundTaskManager.getRemainingDelayTime(id, (err, res) => {
    if(err.data === 0) {
        console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
    } else {
        console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.data);
    }
})

backgroundTaskManager.getRemainingDelayTime

getRemainingDelayTime(requestId: number): Promise<number>

Obtains the remaining duration before the application is suspended. This API uses a promise to return the result.

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

Parameters

Return value

Example

let id = 1;
backgroundTaskManager.getRemainingDelayTime(id).then( res => {
    console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( err => {
    console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.data);
})

backgroundTaskManager.cancelSuspendDelay

cancelSuspendDelay(requestId: number): void

Cancels the suspension delay.

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

Parameters

Example

backgroundTaskManager.cancelSuspendDelay(id);

backgroundTaskManager.startBackgroundRunning⁸⁺

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

Requests a continuous task from the system. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.KEEP_BACKGROUND_RUNNING

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

Parameters

Example

import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';

function callback(err, data) {
    if (err) {
        console.error("Operation startBackgroundRunning failed Cause: " + err);
    } else {
        console.info("Operation startBackgroundRunning succeeded");
    }
}

let wantAgentInfo = {
    wants: [
        {
            bundleName: "com.example.myapplication",
            abilityName: "com.example.myapplication.MainAbility"
        }
    ],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};

wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
    backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
        backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback)
});

backgroundTaskManager.startBackgroundRunning⁸⁺

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

Requests a continuous task from the system. This API uses a promise to return the result.

Required permissions: ohos.permission.KEEP_BACKGROUND_RUNNING

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

Parameters

Return value

Example

import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';

let wantAgentInfo = {
    wants: [
        {
            bundleName: "com.example.myapplication",
            abilityName: "com.example.myapplication.MainAbility"
        }
    ],
    operationType: wantAgent.OperationType.START_ABILITY,
    requestCode: 0,
    wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};

wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
    backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
        backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
        console.info("Operation startBackgroundRunning succeeded");
    }).catch((err) => {
        console.error("Operation startBackgroundRunning failed Cause: " + err);
    });
});

backgroundTaskManager.stopBackgroundRunning⁸⁺

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

Requests to cancel a continuous task. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

Parameters

Example

import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';

function callback(err, data) {
    if (err) {
        console.error("Operation stopBackgroundRunning failed Cause: " + err);
    } else {
        console.info("Operation stopBackgroundRunning succeeded");
    }
}

backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callback);

backgroundTaskManager.stopBackgroundRunning⁸⁺

stopBackgroundRunning(context: Context): Promise<void>

Requests to cancel a continuous task. This API uses a promise to return the result.

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

Parameters

Return value

Example

import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';

backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
    console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
    console.error("Operation stopBackgroundRunning failed Cause: " + err);
});

DelaySuspendInfo

Provides the information about the suspension delay.

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

BackgroundMode⁸⁺

System capability: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask