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

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

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

导入模块

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回调。

func getValue()

public func getValue(): Int32

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

返回值：

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

示例：

  • import ohos.background_task_mgr.*

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

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

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

posted @ 2024-12-25 20:54  BisonLiu  阅读(79)  评论(0)    收藏  举报