README.md
1# Background Task Manager
2
3- [Introduction](#section11660541593)
4- [Directory Structure](#section161941989596)
5- [Transient Tasks](#section1312121216216)
6 - [Available APIs](#section114564657874)
7 - [Usage Guidelines](#section129654513264)
8 - [Restrictions on Using Transient Tasks](#section1551164914237)
9- [Continuous Tasks](#section18532577761)
10 - [Available APIs](#section19389218787)
11 - [Usage Guidelines](#section17228995140)
12 - [Restrictions on Using Continuous Tasks](#section18958419455)
13
14- [Repositories Involved](#section1371113476307)
15
16## Introduction<a name="section11660541593"></a>
17
18In the resource scheduling subsystem, the background task management is responsible for managing background tasks, and provides interfaces for application, cancellation and query of background tasks.
19
20
21
22## Directory Structure<a name="section161941989596"></a>
23
24```
25/foundation/resourceschedule/background_task_mgr
26├── frameworks # Frameworks
27├── interfaces
28│ ├── innerkits # Internal APIs
29│ └── kits # External APIs
30├── sa_profile # SA profile
31├── services # Services
32└── utils # Utilities
33
34```
35## Transient Tasks<a name="section1312121216216"></a>
36
37### Available APIs<a name="section114564657874"></a>
38
39| API | Description |
40|------------------------------------------------------------------------------------------|-------------------|
41| function requestSuspendDelay(reason:string, callback:Callback\<void>): DelaySuspendInfo; | Request a suspend delay |
42| function cancelSuspendDelay(requestId:number): void; | Cancel the suspend delay |
43| function getRemainingDelayTime(requestId:number, callback:AsyncCallback\<number>):void; | Get remaining delay time(callback) |
44| function getRemainingDelayTime(requestId:number): Promise\<number>; | Get remaining delay time(Promise) |
45
46### Usage Guidelines<a name="section129654513264"></a>
47
48As mentioned above, applications and service modules with transient tasks have their suspension delayed so that their running is not affected by background lifecycle management within the specified time frame.
49
50- Note: Applications and service modules can request transient tasks only for temporary tasks. The time quota is 3 minutes per time and 10 minutes per day. The system allocates the time frame based on the application scenario and system status.
51
52#### Restrictions on Using Transient Tasks<a name="section1551164914237"></a>
53
54- **When to request**：An application can request a transient task only when it is running in the foreground or before it is suspended in the background. Otherwise, the application may be suspended, resulting in request failure. By default, an application has 6–12 seconds of running time (subject to the application scenario) before it is suspended in the background.
55- **Timeout**：The system notifies the application of the suspension delay which is about to timeout by using a callback. The application must then cancel the delayed suspension if timeout . Otherwise, the application will be forcibly killed.
56- **When to cancel**：The requesting application shall cancel the suspension delay when the transient task is complete. Do not wait for the request is forcibly canceled by the system.Otherwise,the time frame allowed for the application to run in the background will be affected.
57- **Quota mechanism**：To prevent abuse of the keepalive, each application has a certain quota every day (dynamically adjusted based on user habits). After using up the quota, an application cannot request transient tasks. Therefore, applications should cancel their suspension delay immediately after the transient tasks are complete, to avoid quota consumption. (Note: The quota refers to the requested duration and does not include the time when the application runs in the background.)
58
59## Continuous Tasks<a name="section18532577761"></a>
60
61### Available APIs<a name="section19389218787"></a>
62
63| API | Description |
64|------------------------------------------------------------------------------------------|-------------|
65| function startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void; | When the service is started, apply to the system for continuousterm tasks so that the service keeps running in the background (callback). |
66| function startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void>; | When the service is started, apply to the system for continuous tasks so that the service keeps running in the background (promise). |
67| function stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void; | Stopping continuous tasks running in background（callback） |
68| function stopBackgroundRunning(context: Context): Promise<void>; | Stopping continuous tasks running in background（promise） |
69
70### Usage Guidelines<a name="section17228995140"></a>
71
72Continuous tasks guarantee the life cycle of services that users can intuitively feel and need to run in the background. For example, services need to play sound and continuously navigate in the background. Users can intuitively perceive the background service behaviors and use the background mode corresponding to continuous tasks to ensure the running of services in the background and support applications to complete operation in the background.
73
74OpenHarmony offers 9 kinds of background modes for businesses that need to do continuous tasks in the background
75
76| BackgroundMode | interface parameters | Instructions | The prompt in notification bar | note |
77| -------- | ------- | -------- | -------- | -------- |
78| dataTransfer | DATA_TRANSFER | Download, back up, share, and transfer data through the network or peer device etc | Running data transfer task | |
79| audioPlayback | AUDIO_PLAYBACK | Audio output | Running audio playback task | |
80| audioRecording | AUDIO_RECORDING | Audio input | Running recording task | |
81| location | LOCATION | Positioning and navigation | Running location task | |
82| bluetoothInteraction | BLUETOOTH_INTERACTION | Bluetooth transmission | Running bluetooth related task | |
83| multiDeviceConnection | MULTI_DEVICE_CONNECTION | Distributed interconnection task | Running distributed task | |
84| wifiInteraction | WIFI_INTERACTION | WLAN transmission | Running WLAN related task | SystemApi，only supported for system app |
85| voip | VOIP | Voice over Internet Phone | Running voip task | SystemApi，only supported for system app |
86| taskKeeping | TASK_KEEPING | Computing tasks | Running computing task | only supported in particular device |
87
88#### Restrictions on Using Continuous Tasks<a name="section18958419455"></a>
89
90- If user selects aware services (such as broadcasting, navigation, and uploading and downloading), the background mode is triggered. When a task is started, the system forcibly displays a notification to remind the user.
91- If the task ends, the application should actively exit background mode. If the system detects that an application does not use resources in the corresponding background mode during background running, it suspends.
92- Do not apply for continuous tasks improperly. The type of the continuous tasks must match the service type of the application. If a task is executed that does not match the requested type, the system detects it and suspends it.
93- A continuous task is intended to be executed in the background for a long time. If an application applies for a continuous task but does not actually run or execute such a task, the system detects and suspends it.
94- A ability can only apply to run one continuous task at a time.
95
96## Repositories Involved<a name="section1371113476307"></a>
97
98Resource Schedule subsystem
99
100**background\_task\_mgr**
101
102notification_ans_standard
103
104notification_common_event_service
105
106appexecfwk_standard
107
108account_os_account
README_ZH.md
1# 后台任务管理
2
3- [简介](#section11660541593)
4- [目录](#section161941989596)
5- [短时任务](#section1312121216216)
6 - [接口说明](#section114564657874)
7 - [使用说明](#section129654513264)
8 - [短时任务使用约束](#section1551164914237)
9- [长时任务](#section18532577761)
10 - [接口说明](#section19389218787)
11 - [使用说明](#section17228995140)
12 - [长时任务使用约束](#section18958419455)
13- [能效资源](#section18532577850)
14 - [接口说明](#section19389218896)
15 - [使用说明](#section17228995230)
16 - [能效资源使用约束](#section18958419327)
17
18- [相关仓](#section1371113476307)
19
20## 简介<a name="section11660541593"></a>
21
22在资源调度子系统中后台任务管理负责管理后台任务，并提供后台任务的申请、取消和查询等接口。
23
24
25
26## 目录<a name="section161941989596"></a>
27
28```
29/foundation/resourceschedule/background_task_mgr
30├── frameworks # 接口实现
31├── interfaces
32│ ├── innerkits # 对内接口目录
33│ └── kits # 对外接口目录
34├── sa_profile # 组件服务配置
35├── services # 组件服务实现
36└── utils # 组件工具实现
37
38```
39## 短时任务<a name="section1312121216216"></a>
40
41### 接口说明<a name="section114564657874"></a>
42
43| 接口名 | 接口描述 |
44|------------------------------------------------------------------------------------------|-------------|
45| function requestSuspendDelay(reason:string, callback:Callback\<void>): DelaySuspendInfo; | 申请延迟挂起 |
46| function cancelSuspendDelay(requestId:number): void; | 取消延迟挂起 |
47| function getRemainingDelayTime(requestId:number, callback:AsyncCallback\<number>):void; | 获取延迟挂起剩余时间（callback形式） |
48| function getRemainingDelayTime(requestId:number): Promise\<number>; | 获取延迟挂起剩余时间（Promise形式） |
49
50### 使用说明<a name="section129654513264"></a>
51
52退到后台的应用有不可中断且短时间能完成的任务时，可以使用短时任务机制，该机制允许应用在后台短时间内完成任务，保障应用业务运行不受后台生命周期管理的影响。
53
54- 注意：短时任务仅针对应用的临时任务提供资源使用生命周期保障，限制单次最大使用时长为3分钟，全天使用配额默认为10分钟（具体时长系统根据应用场景和系统状态智能调整）。
55
56#### 短时任务使用约束<a name="section1551164914237"></a>
57
58- **申请时机**：允许应用在前台时，或退后台在被挂起之前（应用退到后台默认有6~12秒的运行时长，具体时长由系统根据具体场景决定）申请延迟挂起，否则可能被挂起（Suspend），导致申请失败。
59- **超时**：延迟挂起即将超时（Timeout），系统通过回调知会应用，应用需要取消对应的延迟挂起。如果超时不取消，该应用会被强制杀掉。
60- **取消时机**：任务完成后申请方应用应该主动取消延迟挂起，不要等到系统回调后再取消，否则会影响该应用的后台允许运行时长配额。
61- **配额机制**：为了防止应用滥用保活，或者申请后不取消，每个应用每天都会有一定配额（会根据用户的使用习惯动态调整），配额消耗完就不再允许申请短时任务，所以应用完成短时任务后立刻取消延迟挂起，避免消耗配额。（注，这个配额指的是申请的时长，系统默认应用在后台运行的时间不计算在内。）
62
63## 长时任务<a name="section18532577761"></a>
64
65### 接口说明<a name="section19389218787"></a>
66
67| 接口名 | 接口描述 |
68|------------------------------------------------------------------------------------------|-------------|
69| function startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void; | 服务启动后，向系统申请长时任务，使服务一直保持后台运行（callback形式） |
70| function startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void>; | 服务启动后，向系统申请长时任务，使服务一直保持后台运行（promise形式） |
71| function stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void; | 停止后台长时任务的运行（callback形式） |
72| function stopBackgroundRunning(context: Context): Promise<void>; | 停止后台长时任务的运行（promise形式） |
73
74### 使用说明<a name="section17228995140"></a>
75
76长时任务给用户能够直观感受到的且需要一直在后台运行的业务提供后台运行生命周期的保障。比如：业务需要在后台播放声音、需要在后台持续导航定位等。此类用户可以直观感知到的后台业务行为，可以通过使用长时任务对应的后台模式保障业务在后台的运行，支撑应用完成在后台的业务。
77
78OpenHarmony提供了九种后台模式，供需要在后台做长时任务的业务使用
79
80| BackgroundMode | 接口参数 | 说明 | 通知栏显示提示 | 备注 |
81| -------- | -------- | -------- | -------- | -------- |
82| dataTransfer | DATA_TRANSFER | 通过网络/对端设备进行数据下载、备份、分享、传输等 | 正在运行数据传输任务 | |
83| audioPlayback | AUDIO_PLAYBACK | 音频输出 | 正在运行音频播放任务 | |
84| audioRecording | AUDIO_RECORDING | 音频输入 | 正在运行录音任务 | |
85| location | LOCATION | 定位、导航 | 正在运行定位任务 | |
86| bluetoothInteraction | BLUETOOTH_INTERACTION | 蓝牙传输 | 正在运行蓝牙相关任务 | |
87| multiDeviceConnection | MULTI_DEVICE_CONNECTION | 分布式互联任务 | 正在运行分布式任务 | |
88| wifiInteraction | WIFI_INTERACTION | WLAN传输 | 正在运行WLAN相关任务 | SystemApi，仅对System权限应用开放 |
89| voip | VOIP | 音视频电话、VOIP | 正在运行通话相关任务 | SystemApi，仅对System权限应用开放 |
90| taskKeeping | TASK_KEEPING | 计算任务 | 正在运行计算任务 | 仅在特定设备生效 |
91
92#### 长时任务使用约束<a name="section18958419455"></a>
93
94- 如果用户选择可感知业务（如播音、导航、上传下载等），触发对应后台模式，在任务启动时，系统会强制弹出通知提醒用户。
95- 如果任务结束，应用应主动退出后台模式。若在后台运行期间，系统检测到应用并未使用对应后台模式的资源，则会被挂起（Suspend）。
96- 避免不合理地申请后台长时任务，长时任务类型要与应用的业务类型匹配。如果执行的任务和申请的类型不匹配，也会被系统检测到并被挂起（Suspend）。
97- 长时任务是为了真正在后台长时间执行某个任务，如果一个应用申请了长时任务，但在实际运行过程中，并未真正运行或执行此类任务时，也会被系统检测到并被挂起（Suspend）。
98- 每个Ability同一时刻只能申请运行一个长时任务。
99
100## 能效资源<a name="section18532577850"></a>
101
102### 接口说明<a name="section19389218896"></a>
103
104| 接口名 | 接口描述 |
105| ---------------------------------------- | ---------------------------------------- |
106| applyEfficiencyResources(request: EfficiencyResourcesRequest): boolean | 申请能效资源。 |
107| resetAllEfficiencyResources():void | 释放申请的能效资源 |
108
109### 使用说明<a name="section17228995230"></a>
110
111能效资源可以分为四种：CPU资源；WORK_SCHEDULER资源；软件资源(COMMON_EVENT, TIMER)；硬件资源(GPS, BLOOTOOTH, AUDIO)。
112应用或进程申请能效资源后能够获得相应特权，例如：申请CPU资源后可以不被挂起；申请WORK_SCHEDULER资源后不受延迟任务执行频率约束，且任务执行时间增加；申请软件、硬件资源后，相关资源在挂起状态下不被代理。
113
114| 参数名 | 参数值 | 描述 |
115| ----------------------- | ---- | --------------------- |
116| CPU | 1 | CPU资源，申请后不被挂起 |
117| COMMON_EVENT | 2 | 公共事件，申请后挂起状态下不被代理掉 |
118| TIMER | 4 | 计时器，申请后挂起状态下不被代理掉 |
119| WORK_SCHEDULER | 8 | 延迟任务，申请后有更长的执行时间 |
120| BLUETOOTH | 16 | 蓝牙相关，申请后挂起状态下不被代理掉 |
121| GPS | 32 | GPS相关，申请后挂起状态下不被代理掉 |
122| AUDIO | 64 | 音频资源，申请后挂起状态下不被代理掉 |
123
124#### 能效使用约束<a name="section18958419327"></a>
125
126- 能效资源申请或者释放可以由进程或者应用发起，由应用发起的释放在释放的时候会释放所有资源，包括进程申请的资源。由进程发起的资源释放对应用申请的资源没有影响。
127- 同时申请同一类持久资源和非持久资源，持久资源会覆盖非持久资源。在超时时不会释放资源。
128- WORK_SCHEDULER资源的申请和释放都必须由应用来进行，不能以进程的身份申请。
129- 在应用死亡时，会清空除了WORK_SCHEDULER之外的所有资源申请记录；在应用被卸载时，会清空所有的资源申请记录。
130
131## 相关仓<a name="section1371113476307"></a>
132
133资源调度子系统
134
135**[resourceschedule_background_task_mgr](https://gitee.com/openharmony/resourceschedule_background_task_mgr)**
136
137[notification_ans_standard](https://gitee.com/openharmony/notification_ans_standard)
138
139[notification_ces_standard](https://gitee.com/openharmony/notification_ces_standard)
140
141[appexecfwk_standard](https://gitee.com/openharmony/appexecfwk_standard)
142
143[account_os_account](https://gitee.com/openharmony/account_os_account)
144
145[resourceschedule_work_scheduler](https://gitee.com/openharmony/resourceschedule_work_scheduler)
