An application is suspended after it runs in the background for a short period of time. If the application needs to execute a short-time task in the background, for example, saving the status, it can request a transient task to extend the running time in the background.
The button for requesting a transient task cannot be clicked more than three times consecutively; otherwise, the limit on the number of transient tasks is exceeded and an error is reported. For more constraints and limitations during use, see constraints and limitations of transient tasks (ArkTS).
The following table lists the commonly used APIs. For details about the APIs, see transient_task_api.h.
| Name | Description |
|---|---|
| int32_t OH_BackgroundTaskManager_RequestSuspendDelay(const char *reason, TransientTask_Callback callback, TransientTask_DelaySuspendInfo *info) | Requests a transient task. |
| int32_t OH_BackgroundTaskManager_GetRemainingDelayTime(int32_t requestId, int32_t *delayTime) | Obtains the remaining time of a transient task. |
| int32_t OH_BackgroundTaskManager_CancelSuspendDelay(int32_t requestId) | Cancels a transient task. |
| int32_t OH_BackgroundTaskManager_GetTransientTaskInfo(TransientTask_TransientTaskInfo *transientTaskInfo) | Obtains all information about a transient task, including the remaining quota of the current day. |
Encapsulate the functions.
#include "napi/native_api.h"
#include "transient_task/transient_task_api.h"
TransientTask_DelaySuspendInfo delaySuspendInfo;
const int32_t TransientTask_TIMER = 3;
static void Callback(void)
{
// The transient task is about to end. The service cancels the transient task here.
OH_BackgroundTaskManager_CancelSuspendDelay(delaySuspendInfo.requestId);
}
// Request a transient task.
static napi_value RequestSuspendDelay(napi_env env, napi_callback_info info)
{
napi_value result;
int32_t res = OH_BackgroundTaskManager_RequestSuspendDelay("test", Callback, &delaySuspendInfo);
if (res == 0) {
napi_create_int32(env, delaySuspendInfo.requestId, &result);
} else {
napi_create_int32(env, -1, &result);
}
return result;
}
// Obtain the remaining time.
static napi_value GetRemainingDelayTime(napi_env env, napi_callback_info info)
{
napi_value result;
int32_t delayTime = 0;
int32_t res = OH_BackgroundTaskManager_GetRemainingDelayTime(delaySuspendInfo.requestId, &delayTime);
if (res == 0) {
napi_create_int32(env, delayTime, &result);
} else {
napi_create_int32(env, -1, &result);
}
return result;
}
// Cancel the transient task.
static napi_value CancelSuspendDelay(napi_env env, napi_callback_info info)
{
napi_value result;
int32_t res = OH_BackgroundTaskManager_CancelSuspendDelay(delaySuspendInfo.requestId);
napi_create_int32(env, res, &result);
return result;
}
// Obtain all transient task information.
TransientTask_TransientTaskInfo transientTaskInfo;
static napi_value GetTransientTaskInfo(napi_env env, napi_callback_info info)
{
napi_value result;
napi_create_object(env, &result);
int32_t res = OH_BackgroundTaskManager_GetTransientTaskInfo(&transientTaskInfo);
napi_value napiRemainingQuota = nullptr;
// The data is successfully obtained. The data is formatted and returned to the API.
if (res == 0) {
napi_create_int32(env, transientTaskInfo.remainingQuota, &napiRemainingQuota);
napi_set_named_property(env, result, "remainingQuota", napiRemainingQuota); // Format the total quota of the current day.
napi_value info {nullptr};
napi_create_array(env, &info);
uint32_t count = 0;
// Format all requested transient task information.
for (int index = 0; index < TransientTask_TIMER; index++) {
if (transientTaskInfo.transientTasks[index].requestId == 0) {
continue;
}
napi_value napiWork = nullptr;
napi_create_object(env, &napiWork);
napi_value napiRequestId = nullptr;
napi_create_int32(env, transientTaskInfo.transientTasks[index].requestId, &napiRequestId);
napi_set_named_property(env, napiWork, "requestId", napiRequestId);
napi_value napiActualDelayTime = nullptr;
napi_create_int32(env, transientTaskInfo.transientTasks[index].actualDelayTime, &napiActualDelayTime);
napi_set_named_property(env, napiWork, "actualDelayTime", napiActualDelayTime);
napi_set_element(env, info, count, napiWork);
count++;
}
napi_set_named_property(env, result, "transientTasks", info);
} else {
napi_create_int32(env, 0, &napiRemainingQuota);
napi_set_named_property(env, result, "remainingQuota", napiRemainingQuota);
napi_value info {nullptr};
napi_create_array(env, &info);
napi_set_named_property(env, result, "transientTasks", info);
}
return result;
} Register the functions.
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
napi_property_descriptor desc[] = {
{"RequestSuspendDelay", nullptr, RequestSuspendDelay, nullptr, nullptr, nullptr, napi_default, nullptr},
{"GetRemainingDelayTime", nullptr, GetRemainingDelayTime, nullptr, nullptr, nullptr, napi_default, nullptr},
{"CancelSuspendDelay", nullptr, CancelSuspendDelay, nullptr, nullptr, nullptr, napi_default, nullptr},
{"GetTransientTaskInfo", nullptr, GetTransientTaskInfo, nullptr, nullptr, nullptr, napi_default, nullptr },
};
napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
return exports;
}
EXTERN_C_END Register the module.
static napi_module demoModule = {
.nm_version = 1,
.nm_flags = 0,
.nm_filename = nullptr,
.nm_register_func = Init,
.nm_modname = "entry",
.nm_priv = ((void*)0),
.reserved = { 0 },
};
extern "C" __attribute__((constructor)) void RegisterEntryModule(void)
{
napi_module_register(&demoModule);
} import backgroundTaskManager from '@kit.BackgroundTasksKit'; export const RequestSuspendDelay: () => number; export const GetRemainingDelayTime: () => number; export const CancelSuspendDelay: () => number; export const GetTransientTaskInfo: () => backgroundTaskManager.TransientTaskInfo;
import testTransientTask from 'libentry.so';
@Entry
@Component
struct Index {
@State message: string = '';
// ...
build() {
Row() {
Column() {
// ...
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
Button() {
Text("RequestSuspendDelay").fontSize(20)
}
.id('request_suspend_delay')
.margin({ top: 10, bottom: 10 })
.width(250)
.height(40)
.backgroundColor('#0D9FFB')
.onClick(() => {
this.RequestSuspendDelay();
})
Button(){
Text('GetRemainingDelayTime').fontSize(20)
}
.id('get_remaining_delay_time')
.margin({ top: 10, bottom: 10 })
.width(250)
.height(40)
.backgroundColor('#0D9FFB')
.onClick(() => {
this.GetRemainingDelayTime();
})
Button(){
Text('CancelSuspendDelay').fontSize(20)
}
.id('cancel_suspend_delay')
.margin({ top: 10, bottom: 10 })
.width(250)
.height(40)
.backgroundColor('#0D9FFB')
.onClick(() => {
this.CancelSuspendDelay();
})
Button(){
Text('GetTransientTaskInfo').fontSize(20)
}
.id('get_transient_task_info')
.margin({ top: 10, bottom: 10 })
.width(250)
.height(40)
.backgroundColor('#0D9FFB')
.onClick(() => {
this.GetTransientTaskInfo();
})
}
.width('100%')
}
.height('100%')
}
RequestSuspendDelay() {
let requestId = testTransientTask.RequestSuspendDelay();
// ...
console.info('The returned requestId is ' + requestId);
}
GetRemainingDelayTime() {
let time = testTransientTask.GetRemainingDelayTime();
console.info('The time is ' + time);
}
CancelSuspendDelay() {
let result = testTransientTask.CancelSuspendDelay();
console.info('The return value is ' + result);
}
GetTransientTaskInfo() {
let info = testTransientTask.GetTransientTaskInfo();
console.info('The transientTaskInfo is ' + JSON.stringify(info));
}
} Configure the CMakeLists.txt file. Add the required shared library, that is, libtransient_task.so, to target_link_libraries in the CMakeLists.txt file automatically generated by the project.
target_link_libraries(entry PUBLIC libace_napi.z.so libtransient_task.so)
Connect to the device and run the program.
Tap the Request transient task button. The console prints a log. The following is an example:
The returned requestId is 1
Tap the Obtain remaining time button. The console prints a log. The following is an example:
The time is 18000
Tap the Cancel transient task button. The console prints a log. The following is an example:
The return value is 0
Tap the Obtain all transient task information button. The console prints a log. The following is an example:
The transientTaskInfo is {"remainingQuota":600000,"transientTasks":[]}