• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 短时任务(C/C++)
2
3## 场景介绍
4
5应用退至后台一小段时间后，应用进程会被挂起，无法执行对应的任务。如果应用在后台仍需要执行耗时不长的任务，如状态保存等，可以通过本文申请短时任务，扩展应用在后台的运行时间。
6
7## 接口说明
8
9常用接口如下表所示，具体API说明详见[API参考](../reference/apis-backgroundtasks-kit/capi-transient-task-api-h.md#函数)。
10
11
12| 接口名 | 描述 |
13| -------- | -------- |
14| int32_t OH_BackgroundTaskManager_RequestSuspendDelay(const char *reason, TransientTask_Callback callback, TransientTask_DelaySuspendInfo *info); | 申请短时任务。 |
15| int32_t OH_BackgroundTaskManager_GetRemainingDelayTime(int32_t requestId, int32_t *delayTime); | 获取对应短时任务的剩余时间。 |
16| int32_t OH_BackgroundTaskManager_CancelSuspendDelay(int32_t requestId); | 取消短时任务。 |
17| int32_t OH_BackgroundTaskManager_GetTransientTaskInfo(TransientTask_TransientTaskInfo  *transientTaskInfo); | 获取所有短时任务信息，如当日剩余总配额等。 |
18
19## 开发步骤
20
21### 在napi_init.cpp文件中封装接口并注册模块
22
231. 封装函数
24
25   ```C
26   #include "napi/native_api.h"
27   #include "transient_task/transient_task_api.h"
28
29   TransientTask_DelaySuspendInfo delaySuspendInfo;
30
31   static void callback(void)
32   {
33      // 短时任务即将结束，业务在这里取消短时任务
34      OH_BackgroundTaskManager_CancelSuspendDelay(delaySuspendInfo.requestId);
35   }
36
37   // 申请短时任务
38   static napi_value RequestSuspendDelay(napi_env env, napi_callback_info info)
39   {
40         napi_value result;
41         int32_t res = OH_BackgroundTaskManager_RequestSuspendDelay("test", callback, &delaySuspendInfo);
42         if (res == 0) {
43            napi_create_int32(env, delaySuspendInfo.requestId, &result);
44         } else {
45            napi_create_int32(env, -1, &result);
46         }
47         return result;
48   }
49
50   // 获取剩余时间
51   static napi_value GetRemainingDelayTime(napi_env env, napi_callback_info info)
52   {
53         napi_value result;
54         int32_t delayTime = 0;
55         int32_t res = OH_BackgroundTaskManager_GetRemainingDelayTime(delaySuspendInfo.requestId, &delayTime);
56         if (res == 0) {
57            napi_create_int32(env, delayTime, &result);
58         } else {
59            napi_create_int32(env, -1, &result);
60         }
61         return result;
62   }
63
64   // 取消短时任务
65   static napi_value CancelSuspendDelay(napi_env env, napi_callback_info info)
66   {
67         napi_value result;
68         int32_t res = OH_BackgroundTaskManager_CancelSuspendDelay(delaySuspendInfo.requestId);
69         napi_create_int32(env, res, &result);
70         return result;
71   }
72
73   // 获取所有短时任务信息
74   TransientTask_TransientTaskInfo transientTaskInfo;
75
76   static napi_value GetTransientTaskInfo(napi_env env, napi_callback_info info)
77   {
78      napi_value result;
79      napi_create_object(env, &result);
80      int32_t res = OH_BackgroundTaskManager_GetTransientTaskInfo(&transientTaskInfo);
81      napi_value napiRemainingQuota = nullptr;
82      // 获取成功，格式化数据并返回给接口
83      if (res == 0) {
84         napi_create_int32(env, transientTaskInfo.remainingQuota, &napiRemainingQuota);
85         napi_set_named_property(env, result, "remainingQuota", napiRemainingQuota); // 格式化当日总配额
86
87         napi_value info {nullptr};
88         napi_create_array(env, &info);
89         uint32_t count = 0;
90         // 格式化所有已申请的短时任务信息
91         for (int index = 0; index < 3; index++) {
92            if (transientTaskInfo.transientTasks[index].requestId == 0) {
93                continue;
94            }
95
96            napi_value napiWork = nullptr;
97            napi_create_object(env, &napiWork);
98
99            napi_value napiRequestId = nullptr;
100            napi_create_int32(env, transientTaskInfo.transientTasks[index].requestId, &napiRequestId);
101            napi_set_named_property(env, napiWork, "requestId", napiRequestId);
102
103            napi_value napiActualDelayTime = nullptr;
104            napi_create_int32(env, transientTaskInfo.transientTasks[index].actualDelayTime, &napiActualDelayTime);
105            napi_set_named_property(env, napiWork, "actualDelayTime", napiActualDelayTime);
106
107            napi_set_element(env, info, count, napiWork);
108            count++;
109         }
110         napi_set_named_property(env, result, "transientTasks", info);
111      } else {
112         napi_create_int32(env, 0, &napiRemainingQuota);
113         napi_set_named_property(env, result, "remainingQuota", napiRemainingQuota);
114         napi_value info {nullptr};
115         napi_create_array(env, &info);
116         napi_set_named_property(env, result, "transientTasks", info);
117      }
118      return result;
119   }
120   ```
121
1222. 注册函数
123
124   ```C
125   EXTERN_C_START
126   static napi_value Init(napi_env env, napi_value exports)
127   {
128       napi_property_descriptor desc[] = {
129           {"RequestSuspendDelay", nullptr, RequestSuspendDelay, nullptr, nullptr, nullptr, napi_default, nullptr},
130           {"GetRemainingDelayTime", nullptr, GetRemainingDelayTime, nullptr, nullptr, nullptr, napi_default, nullptr},
131           {"CancelSuspendDelay", nullptr, CancelSuspendDelay, nullptr, nullptr, nullptr, napi_default, nullptr},
132           {"GetTransientTaskInfo", nullptr, GetTransientTaskInfo, nullptr, nullptr, nullptr, napi_default, nullptr },
133       };
134       napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
135       return exports;
136   }
137   EXTERN_C_END
138   ```
139
1403. 注册模块
141
142   ```C
143   static napi_module demoModule = {
144       .nm_version = 1,
145       .nm_flags = 0,
146       .nm_filename = nullptr,
147       .nm_register_func = Init,
148       .nm_modname = "entry",
149       .nm_priv = ((void*)0),
150       .reserved = { 0 },
151   };
152
153   extern "C" __attribute__((constructor)) void RegisterEntryModule(void)
154   {
155       napi_module_register(&demoModule);
156   }
157   ```
158
159### 在index.d.ts文件中声明函数
160
161   ```ts
162   import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
163
164   export const RequestSuspendDelay: () => number;
165   export const GetRemainingDelayTime: () => number;
166   export const CancelSuspendDelay: () => number;
167   export const GetTransientTaskInfo: () => backgroundTaskManager.TransientTaskInfo;
168   ```
169
170### 在index.ets文件中调用函数
171
172   ```ts
173   import testTransientTask from 'libentry.so';
174
175   @Entry
176   @Component
177   struct Index {
178     @State message: string = '';
179
180     build() {
181       Row() {
182         Column() {
183           Text(this.message)
184             .fontSize(50)
185             .fontWeight(FontWeight.Bold)
186           Button('申请短时任务').onClick(event => {
187             this.RequestSuspendDelay();
188           })
189           Button('获取剩余时间').onClick(event =>{
190             this.GetRemainingDelayTime();
191           })
192           Button('取消短时任务').onClick(event =>{
193             this.CancelSuspendDelay();
194           })
195           Button('获取所有短时任务信息').onClick(event =>{
196             this.GetTransientTaskInfo();
197           })
198         }
199         .width('100%')
200        }
201       .height('100%')
202     }
203
204     RequestSuspendDelay() {
205       let requestId = testTransientTask.RequestSuspendDelay();
206       console.log("The return requestId is " + requestId);
207     }
208
209     GetRemainingDelayTime() {
210       let time = testTransientTask.GetRemainingDelayTime();
211       console.log("The time is " + time);
212     }
213
214     CancelSuspendDelay() {
215       let ret = testTransientTask.CancelSuspendDelay();
216       console.log("The ret is " + ret);
217     }
218
219     GetTransientTaskInfo() {
220       let ret = testTransientTask.GetTransientTaskInfo();
221       console.log("The ret is " + JSON.stringify(ret));
222     }
223   }
224
225   ```
226
227### 配置库依赖
228
229配置`CMakeLists.txt`，本模块需要用到的共享库是`libtransient_task.so`，在工程自动生成的`CMakeLists.txt`中的`target_link_libraries`中添加此共享库。
230
231   ```txt
232   target_link_libraries(entry PUBLIC libace_napi.z.so libtransient_task.so)
233   ```
234
235## 测试步骤
236
2371. 连接设备并运行程序。
238
2392. 点击 `申请短时任务` 按钮，控制台会打印日志，示例如下：
240
241   ```
242   The return requestId is 1
243   ```
244
2453. 点击 `获取剩余时间` 按钮，控制台会打印日志，示例如下：
246
247   ```
248   The return requestId is 18000
249   ```
2504. 点击 `取消短时任务` 按钮，控制台会打印日志，示例如下：
251
252   ```
253   The ret is 0
254   ```
2555. 点击 `获取所有短时任务信息` 按钮，控制台会打印日志，示例如下：
256
257   ```
258   The ret is {"remainingQuota":600000,"transientTasks":[]}
259   ```
260> **说明**
261>
262>申请短时任务的按钮，不可连续点击超过3次，否则会报错。使用过程中更多的约束与限制请参考[短时任务(ArkTS)](transient-task.md#约束与限制)。
263