华为仓颉鸿蒙NEXT原生后台任务管理

原创

Bison丶 2024-12-25 20:54:37 ©著作权

©著作权归作者所有：来自51CTO博客作者Bison丶的原创作品，请联系作者获取转载授权，否则将追究法律责任

当应用退至后台时，开发者可以通过本模块接口为应用申请短时、长时任务，避免应用进程被终止或挂起。

👇🏻👇🏻👇🏻求关注👇🏻👇🏻👇🏻

导入模块

import ohos.background_task_mgr.*

func requestSuspendDelay(String, ()->Unit)

public func requestSuspendDelay(reason: String, callback: () -> Unit): DelaySuspendInfo

申请短时任务。

说明

短时任务的申请时间最长为3分钟，低电量时最长为1分钟。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

参数：

参数名	类型	必填	说明
reason	String	是	申请短时任务的原因。
callback	()->Unit	是	短时任务即将超时的回调函数，一般在超时前6秒，通过此回调通知应用。

返回值：

类型	说明
DelaySuspendInfo	返回短时任务信息。

错误码：

以下错误码的详细介绍请参见backgroundTaskManager错误码。

错误码ID	错误信息
9800001	Memory operation failed.
9800002	Parcel operation failed.
9800003	Inner transact failed.
9800004	System service operation failed.
9900001	Caller information verification failed.
9900002	Background task verification failed.

示例：

import ohos.background_task_mgr.*
let myReason = "test requestSuspendDelay"
try {
let delayInfo = requestSuspendDelay(myReason, { =>
AppLog.info("Request suspension delay will time out.")
})
let id = delayInfo.requestId
let time = delayInfo.actualDelayTime
AppLog.info("The requestId is: ${id}")
AppLog.info("The actualDelayTime is: ${time}")
} catch (e: BusinessException) {
AppLog.info(`requestSuspendDelay failed. code is ${e.code} mes sage is ${e.message}`)
}

func getRemainingDelayTime(Int32)

public func getRemainingDelayTime(requestId: Int32): Int32

获取本次短时任务的剩余时间。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

参数：

参数名	类型	必填	说明
requestId	Int32	是	短时任务的请求ID。

返回值：

类型	说明
Int32	返回本次短时任务的剩余时间，单位为毫秒。

错误码：

以下错误码的详细介绍请参见backgroundTaskManager错误码。

错误码ID	错误信息
9800001	Memory operation failed.
9800002	Parcel operation failed.
9800003	Inner transact failed.
9800004	System service operation failed.
9900001	Caller information verification failed.
9900002	Background task verification failed.

示例：

import ohos.background_task_mgr.*
let id = 1
try {
let time = getRemainingDelayTime(id)
AppLog.info("getRemainingDelayTime succeeded. Data: ${time}")
} catch (e: BusinessException) {
AppLog.info("getRemainingDelayTime failed. code is ${e.code} message is ${e.message}")
}

func cancelSuspendDelay(Int32)

public func cancelSuspendDelay(requestId: Int32): Unit

取消短时任务。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

参数：

参数名	类型	必填	说明
requestId	Int32	是	短时任务的请求ID。

错误码：

以下错误码的详细介绍请参见backgroundTaskManager错误码。

错误码ID	错误信息
9800001	Memory operation failed.
9800002	Parcel operation failed.
9800003	Inner transact failed.
9800004	System service operation failed.
9900001	Caller information verification failed.
9900002	Background task verification failed.

示例：

import ohos.background_task_mgr.*
let id = 1
try {
cancelSuspendDelay(id)
} catch (e: BusinessException) {
AppLog.info("cancelSuspendDelay failed. code is ${e.code} message is ${e.message}")
}

func stopBackgroundRunning(StageContext)

public func stopBackgroundRunning(context: StageContext): Unit

向系统申请取消长时任务。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

参数：

参数名	类型	必填	说明
context	StageContext	是	应用运行的上下文。

示例：

import ohos.base.*
import ohos.ability.*
import ohos.background_task_mgr.*
try {
let stageContext = getStageContext(getContext())
stopBackgroundRunning(stageContext)
} catch (e: BusinessException) {
AppLog.info("cancelSuspendDelay failed. code is ${e.code} message is ${e.message}")
}

func applyEfficiencyResources(EfficiencyResourcesRequest)

public func applyEfficiencyResources(request: EfficiencyResourcesRequest): Unit

申请能效资源。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply

系统API: 此接口为系统接口。

参数：

参数名	类型	必填	说明
request	EfficiencyResourcesRequest	是	请求的必要信息，包括资源类型、超时时间等。

错误码：

以下错误码的详细介绍请参见backgroundTaskManager错误码。

错误码ID	错误信息
9800001	Memory operation failed.
9800002	Parcel operation failed.
9800003	Inner transact failed.
9800004	System service operation failed.
18700001	Caller information verification failed.

示例：

import ohos.background_task_mgr.*
try {
let req = EfficiencyResourcesRequest(UInt32(ResourceType.CPU.getValue()), true, 0, "apply", isPersist: true)
applyEfficiencyResources(req)
} catch (e: BusinessException) {
AppLog.info("cancelSuspendDelay failed. code is ${e.code} message is ${e.message}")
}

class DelaySuspendInfo

public class DelaySuspendInfo {
public DelaySuspendInfo(
public let requestId: Int32,
public let actualDelayTime: Int32
) {}
}

短时任务信息。

系统能力:SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask

名称	类型	必填	说明
requestId	Int32	是	短时任务的请求ID。
actualDelayTime	Int32	是	应用实际申请的短时任务时间，单位为毫秒。短时任务申请时间最长为3分钟，低电量时最长为1分钟。

class EfficiencyResourcesRequest

public class EfficiencyResourcesRequest {
public EfficiencyResourcesRequest(
public let resourceTypes: UInt32,
public let isApply: Bool,
public let timeOut: UInt32,
public let reason: String,
public let isPersist!: Bool = false,
public let isProcess!: Bool = false
) {}
}

能效资源申请参数。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply

系统API: 此接口为系统接口。

名称	类型	必填	说明
resourceTypes	UInt32	是	申请的资源类型。
isApply	Bool	是	申请或释放资源。 - true表示申请资源。 - false表示释放部分资源。
timeOut	UInt32	是	资源使用时间，单位为毫秒。
isPersist	Bool	否	是否永久持有资源，默认为false。 - true表示永久持有。 - false表示有限时间内持有。
isProcess	Bool	否	进程或应用申请，默认为false。 - true表示进程申请。 - false表示应用申请。
reason	String	是	申请资源原因。

enum BackgroundMode

public enum BackgroundMode {
| DATA_TRANSFER
| AUDIO_PLAYBACK
| AUDIO_RECORDING
| LOCATION
| BLUETOOTH_INTERACTION
| MULTI_DEVICE_CONNECTION
| WIFI_INTERACTION
| VOIP
| TASK_KEEPING
}

长时任务模式。

系统能力:SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask

名称	说明
DATA_TRANSFER	数据传输。
AUDIO_PLAYBACK	音频播放。
AUDIO_RECORDING	录音。
LOCATION	定位导航。
BLUETOOTH_INTERACTION	蓝牙相关。
MULTI_DEVICE_CONNECTION	多设备互联。
WIFI_INTERACTION	WLAN相关。系统API:此接口为系统接口。
VOIP	音视频通话。系统API:此接口为系统接口。
TASK_KEEPING	计算任务（仅对特定设备开放）。

enum ResourceType

public enum ResourceType {
| CPU
| COMMON_EVENT
| TIMER
| WORK_SCHEDULER
| BLUETOOTH
| GPS
| AUDIO
| RUNNING_LOCK
| SENSOR
}

能效资源类型。

系统能力: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply

系统API: 此接口为系统接口。

名称	值	说明
CPU	1	CPU资源，申请后应用进程不被挂起。
COMMON_EVENT	2	公共事件资源，申请后应用进程被挂起后，可以收到公共事件。
TIMER	4	计时器，申请后应用进程被挂起后，Timer仍然可以唤醒应用。
WORK_SCHEDULER	8	延迟任务资源，申请后延迟任务管控变宽松。
BLUETOOTH	16	蓝牙资源，申请后应用进程被挂起后，蓝牙相关事件仍然可以唤醒应用。
GPS	32	GPS资源，申请后应用进程被挂起后，GPS相关事件可以唤醒应用。
AUDIO	64	音频资源，有音频播放时对应的应用进程不被挂起。
RUNNING_LOCK	128	RUNNING_LOCK资源，申请后挂起状态不会代理RUNNING_BACKGROUND锁。
SENSOR	256	申请后不拦截Sensor回调。