Work Scheduler

The workScheduler module provides the APIs for registering, canceling, and querying Work Scheduler tasks, which do not have real-time constraints.

The system executes Work Scheduler tasks at an appropriate time, subject to the storage space, power consumption, temperature, and more.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs of this module can be used only in the stage model.

For details about the constraints on the Work Scheduler usage, see Work Scheduler Overview.

Modules to Import

import workScheduler from '@ohos.workScheduler';

workScheduler.startWork

startWork(work: WorkInfo): boolean

Instructs the WorkSchedulerService to add the specified task to the execution queue.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Parameters

Name	Type	Mandatory	Description
work	WorkInfo	Yes	Task to be added to the execution queue.

Return value

Type	Description
boolean	Returns true if the task is added to the execution queue; returns false otherwise.

Example

  let workInfo = {
      workId: 1,
      batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
      isRepeat: false,
      isPersisted: true,
      bundleName: "com.example.myapplication",
      abilityName: "MyExtension",
      parameters: {
          mykey0: 1,
          mykey1: "string value",
          mykey2: true,
          mykey3: 1.5
      }
  }
  var res = workScheduler.startWork(workInfo);
  console.info(`workschedulerLog res: ${res}`);

workScheduler.stopWork

stopWork(work: WorkInfo, needCancel?: boolean): boolean

Instructs the WorkSchedulerService to stop the specified task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Parameters

Name	Type	Mandatory	Description
work	WorkInfo	Yes	Task to stop.
needCancel	boolean	Yes	Whether to cancel the task.

Return value

Type	Description
boolean	Returns true if the operation is successful; returns false otherwise.

Example

  let workInfo = {
      workId: 1,
      batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
      isRepeat: false,
      isPersisted: true,
      bundleName: "com.example.myapplication",
      abilityName: "MyExtension",
      parameters: {
          mykey0: 1,
          mykey1: "string value",
          mykey2: true,
          mykey3: 1.5
      }
     }
  var res = workScheduler.stopWork(workInfo, false);
  console.info(`workschedulerLog res: ${res}`);

workScheduler.getWorkStatus

getWorkStatus(workId: number, callback : AsyncCallback<WorkInfo>): void

Obtains the latest task status. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Parameters

Name	Type	Mandatory	Description
workId	number	Yes	Task ID.
callback	AsyncCallback<WorkInfo>	Yes	Callback used to return the result. Returns the task status obtained from the WorkSchedulerService if the specified task ID is valid; returns null otherwise.

Example

  workScheduler.getWorkStatus(50, (err, res) => {
    if (err) {
      console.info(`workschedulerLog getWorkStatus failed, because: ${err.code}`);
    } else {
      for (let item in res) {
        console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
      }
    }
  });

workScheduler.getWorkStatus

getWorkStatus(workId: number): Promise<WorkInfo>

Obtains the latest task status. This API uses a promise to return the result.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Parameters

Name	Type	Mandatory	Description
workId	number	Yes	Task ID.

Return value

Type	Description
Promise<WorkInfo>	Promise used to return the result. Returns the task status obtained from the WorkSchedulerService if the specified task ID is valid; returns null otherwise.

Example

  workScheduler.getWorkStatus(50).then((res) => {
    for (let item in res) {
      console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
    }
  }).catch((err) => {
    console.info(`workschedulerLog getWorkStatus failed, because: ${err.code}`);
  })

workScheduler.obtainAllWorks

obtainAllWorks(callback : AsyncCallback<void>): Array<WorkInfo>

Obtains all tasks associated with this application. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return all tasks associated with the current application.

Return value

Type	Description
Array<WorkInfo>	All tasks associated with the current application.

Example

  workScheduler.obtainAllWorks((err, res) =>{
    if (err) {
      console.info(`workschedulerLog obtainAllWorks failed, because: ${err.code}`);
    } else {
      console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
    }
  });

workScheduler.obtainAllWorks

obtainAllWorks(): Promise<Array<WorkInfo>>

Obtains all tasks associated with this application. This API uses a promise to return the result.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Return value

Type	Description
Promise<Array<WorkInfo>>	Promise used to return all tasks associated with the current application.

Example

  workScheduler.obtainAllWorks().then((res) => {
    console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
  }).catch((err) => {
    console.info(`workschedulerLog obtainAllWorks failed, because: ${err.code}`);
  })

workScheduler.stopAndClearWorks

stopAndClearWorks(): boolean

Stops and cancels all tasks associated with the current application.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Example

  let res = workScheduler.stopAndClearWorks();
  console.info(`workschedulerLog res: ${res}`);

workScheduler.isLastWorkTimeOut

isLastWorkTimeOut(workId: number, callback : AsyncCallback<void>): boolean

Checks whether the last execution of the specified task timed out. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Parameters

Name	Type	Mandatory	Description
workId	number	Yes	Task ID.
callback	AsyncCallback<void>	Yes	Callback used to return the result. Returns true if the last execution of the specified task timed out; returns false otherwise.

Return value

Type	Description
boolean	Callback used to return the result. Returns true if the last execution of the specified task timed out; returns false otherwise.

Example

  workScheduler.isLastWorkTimeOut(500, (err, res) =>{
    if (err) {
      console.info(`workschedulerLog isLastWorkTimeOut failed, because: ${err.code}`);
    } else {
      console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
    }
  });

workScheduler.isLastWorkTimeOut

isLastWorkTimeOut(workId: number): Promise<boolean>

Checks whether the last execution of the specified task timed out. This API uses a promise to return the result.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Parameters

Name	Type	Mandatory	Description
workId	number	Yes	Task ID.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. Returns true if the last execution of the specified task timed out; returns false otherwise.

Example

  workScheduler.isLastWorkTimeOut(500)
    .then(res => {
      console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
    })
    .catch(err =>  {
      console.info(`workschedulerLog isLastWorkTimeOut failed, because: ${err.code}`);
    });

WorkInfo

Provides detailed information about the task. For details about the constraints on configuring WorkInfo, see Work Scheduler Overview.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Name	Type	Mandatory	Description
workId	number	Yes	Task ID.
bundleName	string	Yes	Name of the Work Scheduler task bundle.
abilityName	string	Yes	Name of the component to be notified by a Work Scheduler callback.
networkType	NetworkType	No	Network type.
isCharging	boolean	No	Whether the device is charging.
chargerType	ChargingType	No	Charging type.
batteryLevel	number	No	Battery level.
batteryStatus	BatteryStatus	No	Battery status.
storageRequest	StorageRequest	No	Storage status.
isRepeat	boolean	No	Whether the task is repeated.
repeatCycleTime	number	No	Repeat interval.
repeatCount	number	No	Number of repeat times.
isPersisted	boolean	No	Whether to enable persistent storage for the task.
isDeepIdle	boolean	No	Whether the device needs to enter the idle state.
idleWaitTime	number	No	Time to wait in the idle state.
parameters	{[key: string]: any}	No	Carried parameters.

NetworkType

Enumerates the network types that can trigger the task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Name	Default Value	Description
NETWORK_TYPE_ANY	0	Any network type.
NETWORK_TYPE_MOBILE	1	Mobile network.
NETWORK_TYPE_WIFI	2	Wi-Fi network.
NETWORK_TYPE_BLUETOOTH	3	Bluetooth network.
NETWORK_TYPE_WIFI_P2P	4	Wi-Fi P2P network.
NETWORK_TYPE_ETHERNET	5	Ethernet.

ChargingType

Enumerates the charging types that can trigger the task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Name	Default Value	Description
CHARGING_PLUGGED_ANY	0	Any charging type.
CHARGING_PLUGGED_AC	1	DC charging.
CHARGING_PLUGGED_USB	2	USB charging.
CHARGING_PLUGGED_WIRELESS	3	Wireless charging.

BatteryStatus

Enumerates the battery states that can trigger the task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Name	Default Value	Description
BATTERY_STATUS_LOW	0	A low battery alert is displayed.
BATTERY_STATUS_OKAY	1	The battery level is restored from low to normal.
BATTERY_STATUS_LOW_OR_OKAY	2	The battery level is restored from low to normal, or a low battery alert is displayed.

StorageRequest

Enumerates the storage states that can trigger the task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Name	Default Value	Description
STORAGE_LEVEL_LOW	0	The storage space is insufficient.
STORAGE_LEVEL_OKAY	1	The storage space is restored from insufficient to normal.
STORAGE_LEVEL_LOW_OR_OKAY	2	The storage space is restored from insufficient to normal, or the storage space is insufficient.