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

BisonLiu
333 阅读4分钟

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

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

导入模块

import ohos.background_task_mgr.*

func requestSuspendDelay(String, ()->Unit)

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

申请短时任务。

说明

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

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

参数：

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

返回值：

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

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9900001Caller information verification failed.
9900002Background 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

参数：

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

返回值：

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

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
9900001Caller information verification failed.
9900002Background 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      messageis{e.code}             message is {e.message}")

  • }

func cancelSuspendDelay(Int32)

public func cancelSuspendDelay(requestId: Int32): Unit

取消短时任务。

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

参数：

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

错误码：

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

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

示例：

  • import ohos.background_task_mgr.*

  • let id = 1

  • try {

  •    cancelSuspendDelay(id)

  • } catch (e: BusinessException) {

  •    AppLog.info("cancelSuspendDelay failed. code is e.codemessageis{e.code} message is {e.message}")

  • }

func stopBackgroundRunning(StageContext)

public func stopBackgroundRunning(context: StageContext): Unit

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

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

参数：

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

示例：

  • 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.codemessageis{e.code} message is {e.message}")

  • }

func applyEfficiencyResources(EfficiencyResourcesRequest)

public func applyEfficiencyResources(request: EfficiencyResourcesRequest): Unit

申请能效资源。

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

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

参数：

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

错误码：

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

错误码ID错误信息
9800001Memory operation failed.
9800002Parcel operation failed.
9800003Inner transact failed.
9800004System service operation failed.
18700001Caller 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.codemessageis{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

名称类型必填说明
requestIdInt32是短时任务的请求ID。
actualDelayTimeInt32是应用实际申请的短时任务时间，单位为毫秒。短时任务申请时间最长为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: 此接口为系统接口。

名称类型必填说明
resourceTypesUInt32是申请的资源类型。
isApplyBool是申请或释放资源。- true表示申请资源。- false表示释放部分资源。
timeOutUInt32是资源使用时间，单位为毫秒。
isPersistBool否是否永久持有资源，默认为false。- true表示永久持有。- false表示有限时间内持有。
isProcessBool否进程或应用申请，默认为false。- true表示进程申请。- false表示应用申请。
reasonString是申请资源原因。

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_INTERACTIONWLAN相关。系统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: 此接口为系统接口。

名称值说明
CPU1CPU资源，申请后应用进程不被挂起。
COMMON_EVENT2公共事件资源，申请后应用进程被挂起后，可以收到公共事件。
TIMER4计时器，申请后应用进程被挂起后，Timer仍然可以唤醒应用。
WORK_SCHEDULER8延迟任务资源，申请后延迟任务管控变宽松。
BLUETOOTH16蓝牙资源，申请后应用进程被挂起后，蓝牙相关事件仍然可以唤醒应用。
GPS32GPS资源，申请后应用进程被挂起后，GPS相关事件可以唤醒应用。
AUDIO64音频资源，有音频播放时对应的应用进程不被挂起。
RUNNING_LOCK128RUNNING_LOCK资源，申请后挂起状态不会代理RUNNING_BACKGROUND锁。
SENSOR256申请后不拦截Sensor回调。

func getValue()

public func getValue(): Int32

获取ResourceType枚举类型对应的整数值。

返回值：

类型说明
Int32ResourceType枚举类型对应的整数值。

示例：

  • import ohos.background_task_mgr.*

  • let value: Int32 = ResourceType.CPU.getValue()

如对您有帮助，帮忙点个“在看 、关注” 让更多的人受益~！

技术交流群可加wx“LB-9191”备注cangjie

avatar
文章
阅读
粉丝