1# Transient Task (C/C++)
2
3## When to Use
4
5An 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.
6
7## Available APIs
8
9The following table lists the common APIs.
10
11
12| Name| Description|
13| -------- | -------- |
14| int32_t OH_BackgroundTaskManager_RequestSuspendDelay(const char *reason, TransientTask_Callback callback, TransientTask_DelaySuspendInfo *info); | Requests a transient task.|
15| int32_t OH_BackgroundTaskManager_GetRemainingDelayTime(int32_t requestId, int32_t *delayTime); | Obtains the remaining time of a transient task.|
16| int32_t OH_BackgroundTaskManager_CancelSuspendDelay(int32_t requestId); | Cancels a transient task.|
17
18## How to Develop
19
20### Encapsulating the Functions and Registering Modules in the napi_init.cpp File
21
221. Encapsulate the functions.
23
24   ```C
25   #include "napi/native_api.h"
26   #include "transient_task/transient_task_api.h"
27
28   TransientTask_DelaySuspendInfo delaySuspendInfo;
29
30   static void callback(void)
31   {
32      // The transient task is about to end. The service cancels the transient task here.
33      OH_BackgroundTaskManager_CancelSuspendDelay(delaySuspendInfo.requestId);
34   }
35
36   // Request a transient task.
37   static napi_value RequestSuspendDelay(napi_env env, napi_callback_info info)
38   {
39         napi_value result;
40         int32_t res = OH_BackgroundTaskManager_RequestSuspendDelay("test", callback, &delaySuspendInfo);
41         if (res == 0) {
42            napi_create_int32(env, delaySuspendInfo.requestId, &result);
43         } else {
44            napi_create_int32(env, -1, &result);
45         }
46         return result;
47   }
48
49   // Obtain the remaining time.
50   static napi_value GetRemainingDelayTime(napi_env env, napi_callback_info info)
51   {
52         napi_value result;
53         int32_t delayTime = 0;
54         int32_t res = OH_BackgroundTaskManager_GetRemainingDelayTime(delaySuspendInfo.requestId, &delayTime);
55         if (res == 0) {
56            napi_create_int32(env, delayTime, &result);
57         } else {
58            napi_create_int32(env, -1, &result);
59         }
60         return result;
61   }
62
63   // Cancel the transient task.
64   static napi_value CancelSuspendDelay(napi_env env, napi_callback_info info)
65   {
66         napi_value result;
67         int32_t res = OH_BackgroundTaskManager_CancelSuspendDelay(delaySuspendInfo.requestId);
68         napi_create_int32(env, res, &result);
69         return result;
70   }
71
72   ```
73
742. Register the functions.
75
76   ```C
77   EXTERN_C_START
78   static napi_value Init(napi_env env, napi_value exports)
79   {
80       napi_property_descriptor desc[] = {
81           {"RequestSuspendDelay", nullptr, RequestSuspendDelay, nullptr, nullptr, nullptr, napi_default, nullptr},
82           {"GetRemainingDelayTime", nullptr, GetRemainingDelayTime, nullptr, nullptr, nullptr, napi_default, nullptr},
83           {"CancelSuspendDelay", nullptr, CancelSuspendDelay, nullptr, nullptr, nullptr, napi_default, nullptr},
84       };
85       napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
86       return exports;
87   }
88   EXTERN_C_END
89   ```
90
913. Register the module.
92
93   ```C
94   static napi_module demoModule = {
95       .nm_version = 1,
96       .nm_flags = 0,
97       .nm_filename = nullptr,
98       .nm_register_func = Init,
99       .nm_modname = "entry",
100       .nm_priv = ((void*)0),
101       .reserved = { 0 },
102   };
103
104   extern "C" __attribute__((constructor)) void RegisterEntryModule(void)
105   {
106       napi_module_register(&demoModule);
107   }
108   ```
109
110### Declaring the Functions in the index.d.ts File
111
112   ```ts
113   export const RequestSuspendDelay: () => number;
114   export const GetRemainingDelayTime: () => number;
115   export const CancelSuspendDelay: () => number;
116   ```
117
118### Calling the Functions in the index.ets File
119
120   ```ts
121   import testTransientTask from 'libentry.so';
122
123   @Entry
124   @Component
125   struct Index {
126     @State message: string = '';
127
128     build() {
129       Row() {
130         Column() {
131           Text(this.message)
132             .fontSize(50)
133             .fontWeight(FontWeight.Bold)
134           Button('Request transient task').onClick(event => {
135             this.RequestSuspendDelay();
136           })
137           Button('Obtain remaining time').onClick(event =>{
138             this.GetRemainingDelayTime();
139           })
140           Button('Cancel transient task').onClick(event =>{
141             this.CancelSuspendDelay();
142           })
143         }
144         .width('100%')
145        }
146       .height('100%')
147     }
148
149     RequestSuspendDelay() {
150       let requestId = testTransientTask.RequestSuspendDelay();
151       console.log("The return requestId is " + requestId);
152     }
153
154     GetRemainingDelayTime() {
155       let time = testTransientTask.GetRemainingDelayTime();
156       console.log("The time is " + time);
157     }
158
159     CancelSuspendDelay() {
160       let ret = testTransientTask.CancelSuspendDelay();
161       console.log("The ret is " + ret);
162     }
163   }
164
165   ```
166
167### Configuring the Library Dependency
168
169Configure 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.
170
171   ```txt
172   target_link_libraries(entry PUBLIC libace_napi.z.so libtransient_task.so)
173   ```
174
175## How to Test
176
1771. Connect to the device and run the program.
178
1792. Touch the **Request transient task** button. The console prints a log. The following is an example:
180
181   ```
182   The return requestId is 1
183   ```
184
1853. Touch the **Obtain remaining time** button. The console prints a log. The following is an example:
186
187   ```
188   The return requestId is 18000
189   ```
1904. Touch the **Cancel transient task** button. The console prints a log. The following is an example:
191
192   ```
193   The ret is 0
194   ```
195> **NOTE**
196>
197>If the **Request transient task** button is touched for more than three consecutive times, an error is reported. For more constraints, see [Transient Task (ArkTS)](transient-task.md#constraints).
198