@ohos.resourceschedule.workScheduler (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 restrictions, see Restrictions on Using Work Scheduler Tasks.

Modules to Import

import workScheduler from '@ohos.resourceschedule.workScheduler';

workScheduler.startWork

startWork(work: WorkInfo): void

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

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Parameters

Error codes

For details about the error codes, see workScheduler Error Codes.

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
      }
  }
  try{
    workScheduler.startWork(workInfo);
    console.info('workschedulerLog startWork success');
  } catch (error) {
    console.error(`workschedulerLog startwork failed. code is ${error.code} message is ${error.message}`);
  }

workScheduler.stopWork

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

Instructs the WorkSchedulerService to stop the specified task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Parameters

Error codes

For details about the error codes, see workScheduler Error Codes.

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
      }
     }
  try{
    workScheduler.stopWork(workInfo, false);
    console.info('workschedulerLog stopWork success');
  } catch (error) {
    console.error(`workschedulerLog stopWork failed. code is ${error.code} message is ${error.message}`);
  }

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

Error codes

For details about the error codes, see workScheduler Error Codes.

Example

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

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

Return value

Error codes

For details about the error codes, see workScheduler Error Codes.

Example

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

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

Return value

Error codes

For details about the error codes, see workScheduler Error Codes.

Example

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

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

Error codes

For details about the error codes, see workScheduler Error Codes.

Example

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

workScheduler.stopAndClearWorks

stopAndClearWorks(): void

Stops and cancels all tasks associated with the current application.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

Error codes

For details about the error codes, see workScheduler Error Codes.

Example

  try{
    workScheduler.stopAndClearWorks();
    console.info(`workschedulerLog stopAndClearWorks success`);
  } catch (error) {
    console.error(`workschedulerLog stopAndClearWorks failed. code is ${error.code} message is ${error.message}`);
  }

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

Return value

Error codes

For details about the error codes, see workScheduler Error Codes.

Example

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

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

Return value

Error codes

For details about the error codes, see workScheduler Error Codes.

Example

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

WorkInfo

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

System capability: SystemCapability.ResourceSchedule.WorkScheduler

NetworkType

Enumerates the network types that can trigger the task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

ChargingType

Enumerates the charging types that can trigger the task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

BatteryStatus

Enumerates the battery states that can trigger the task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler

StorageRequest

Enumerates the storage states that can trigger the task.

System capability: SystemCapability.ResourceSchedule.WorkScheduler