diff --git a/en/application-dev/reference/apis/js-apis-WorkSchedulerExtensionAbility.md b/en/application-dev/reference/apis/js-apis-WorkSchedulerExtensionAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..8e0c427520a549e74f6b9e8dec02ac219d734054 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-WorkSchedulerExtensionAbility.md @@ -0,0 +1,51 @@ +# Work Scheduler Callbacks + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **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. + + +## Modules to Import + +``` +import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility' +``` + +## WorkSchedulerExtensionAbility.onWorkStart +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +onWorkStart(workInfo: WorkInfo); + +- **Description** +Triggered when the Work Scheduler task starts. + +- **Example** + + ``` + export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility { + onWorkStart(workInfo) { + console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo)); + } + } + ``` + +## WorkSchedulerExtensionAbility.onWorkStop +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +onWorkStop(workInfo: WorkInfo); + +- **Description** +Triggered when the Work Scheduler task stops. + +- **Example** + + ``` + export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility { + onWorkStop(workInfo) { + console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo)); + } + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-workScheduler.md b/en/application-dev/reference/apis/js-apis-workScheduler.md new file mode 100644 index 0000000000000000000000000000000000000000..bc4e6f32cd9b9258f6b5ef18f0ae0c91797e6613 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-workScheduler.md @@ -0,0 +1,375 @@ +# Work Scheduler + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **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. + + +## Modules to Import + +``` +import workScheduler from '@ohos.workScheduler' +``` + +## workScheduler.startWork +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +workScheduler.startWork(work: WorkInfo): boolean + +- **Description** +Instructs the **WorkSchedulerService** to add the specified task to the execution queue. + +- **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, + batteryLevel:50, + batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, + isRepeat: false, + isPersisted: true, + bundleName: "com.example.myapplication", + abilityName: "MyExtension" + } + var res = workScheduler.startWork(workInfo); + console.info("workschedulerLog res:" + res); + ``` + +## workScheduler.stopWork +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +stopWork(work: WorkInfo, needCancel?: boolean): boolean + +- **Description** +Instructs the **WorkSchedulerService** to stop the specified task. + +- **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, + batteryLevel:50, + batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, + isRepeat: false, + isPersisted: true, + bundleName: "com.example.myapplication", + abilityName: "MyExtension" + } + var res = workScheduler.stopWork(workInfo, false); + console.info("workschedulerLog res:" + res); + ``` + +## workScheduler.getWorkStatus +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +getWorkStatus(workId: number, callback : AsyncCallback): void + +- **Description** +Obtains the latest task status. This method uses an asynchronous callback to return the result. + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | workId | number | Yes| Task ID.| + |callback|AsyncCallback| 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.data); + } else { + for (let item in res) { + console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]); + } + } + }); + ``` + +## workScheduler.getWorkStatus +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +getWorkStatus(workID: number): Promise + +- **Description** +Obtains the latest task status. This method uses a promise to return the result. + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | workId | number | Yes| Task ID.| + +- **Return value** + + | Type| Description| + | -------- | -------- | + | Promise | 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.data); + }) + ``` + +## workScheduler.obtainAllWorks +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +obtainAllWorks(callback : AsyncCallback): Array + +- **Description** +Obtains all tasks associated with this application. This method uses an asynchronous callback to return the result. + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + |callback|AsyncCallback| Yes| Callback used to return all tasks associated with the current application.| + + +- **Return value** + + | Type| Description| + | -------- | -------- | + | Array | All tasks associated with the current application.| + +- **Example** + + ``` + workScheduler.obtainAllWorks((err, res) =>{ + if (err) { + console.info('workschedulerLog obtainAllWorks failed, because:' + err.data); + } else { + console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); + } + }); + ``` + +## workScheduler.obtainAllWorks +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +obtainAllWorks(): Promise> + +- **Description** +Obtains all tasks associated with this application. This method uses a promise to return the result. + +- **Return value** + + | Type| Description| + | -------- | -------- | + | Promise> | 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.data); + }) + ``` + +## workScheduler.stopAndClearWorks +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +stopAndClearWorks(): boolean + +- **Description** +Stops and cancels all tasks associated with the current application. + +- **Example** + + ``` + let res = workScheduler.stopAndClearWorks(); + console.info("workschedulerLog res:" + res); + ``` + +## workScheduler.isLastWorkTimeOut +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +isLastWorkTimeOut(workId: number, callback : AsyncCallback): boolean + +- **Description** +Checks whether the last execution of the specified task timed out. This method uses an asynchronous callback to return the result. + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | workId | number | Yes| Task ID.| + |callback|AsyncCallback| Yes| Callback used to return the result.| + +- **Return value** + + | Type| Description| + | -------- | -------- | + | boolean | 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.data); + } else { + console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); + } + }); + ``` + +## workScheduler.isLastWorkTimeOut +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +- **API** +isLastWorkTimeOut(workId: number): Promise + +- **Description** +Checks whether the last execution of the specified task timed out. This method uses a promise to return the result. + +- **Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | workId | number | Yes| Task ID.| + +- **Return value** + + | Type| Description| + | -------- | -------- | + | Promise | 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.data); + }); + }) + ``` + +## workScheduler.WorkInfo +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +Provides detailed information about the task. + +| 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 | bool| 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.| + +## workScheduler.NetworkType +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +Enumerates the network types that can trigger the task. + +|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.| + +## workScheduler.ChargingType +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +Enumerates the charging types that can trigger the task. + +|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.| + +## workScheduler.BatteryStatus +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +Enumerates the battery status that can trigger the task. + +|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.| + +## workScheduler.StorageRequest +- **System capability** +SystemCapability.ResourceSchedule.WorkScheduler + +Enumerates the storage status that can trigger the task. + + |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. \ No newline at end of file diff --git a/en/application-dev/work-scheduler/Readme.md b/en/application-dev/work-scheduler/Readme.md new file mode 100644 index 0000000000000000000000000000000000000000..13c70babfe8971b1d22739d569461caac4850847 --- /dev/null +++ b/en/application-dev/work-scheduler/Readme.md @@ -0,0 +1,5 @@ +# Work Scheduler + +- Background Tasks + - [Work Scheduler Overview](work-scheduler-overview.md) + - [Work Scheduler Development](work-scheduler-dev-guide.md) diff --git a/en/application-dev/work-scheduler/work-scheduler-dev-guide.md b/en/application-dev/work-scheduler/work-scheduler-dev-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..d4c21ca52b96f2c0b770621be8acb75ce82c337e --- /dev/null +++ b/en/application-dev/work-scheduler/work-scheduler-dev-guide.md @@ -0,0 +1,182 @@ +# Work Scheduler Development + +## When to Use + +If your application needs to execute a non-real-time task, for example, data learning, you can harness the Work Scheduler mechanism, which will schedule the task based on the storage space, power consumption, temperature, and more when the preset conditions are met. + + +## Available APIs +Import the **workScheduler** package to implement registration: +```js +import workScheduler from '@ohos.workScheduler'; +``` + +Import the **WorkSchedulerExtensionAbility** package to implement callback: +```js +import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; +``` + +### Work Scheduler + +**Table 1** Major workScheduler APIs + + API | Description + ------------------------------------------------------------ | ------------------------------------------------------------ + function startWork(work: WorkInfo): boolean; | Starts a Work Scheduler task. + function stopWork(work: WorkInfo, needCancel?: boolean): boolean; | Stops a Work Scheduler task. + function getWorkStatus(workId: number, callback: AsyncCallback): void; | Obtains the status of a Work Scheduler task. This method uses an asynchronous callback to return the result. + function getWorkStatus(workId: number): Promise; | Obtains the status of a Work Scheduler task. This method uses a promise to return the result. + function obtainAllWorks(callback: AsyncCallback): Array; | Obtains Work Scheduler tasks. This method uses an asynchronous callback to return the result. + function obtainAllWorks(): Promise>; | Obtains Work Scheduler tasks. This method uses a promise to return the result. + function stopAndClearWorks(): boolean; | Stops and clears Work Scheduler tasks. + function isLastWorkTimeOut(workId: number, callback: AsyncCallback): boolean; | Checks whether the last execution of the specified task has timed out. This method uses an asynchronous callback to return the result. It is applicable to repeated tasks. + function isLastWorkTimeOut(workId: number): Promise; | Checks whether the last execution of the specified task has timed out. This method uses a promise to return the result. It is applicable to repeated tasks. + +**Table 2** WorkInfo parameters + +API|Description|Type +---------------------------------------------------------|-----------------------------------------|--------------------------------------------------------- +workId | Work ID. Mandatory.|number +bundleName | Name of the Work Scheduler task bundle. Mandatory.|string +abilityName | Name of the component to be notified by a Work Scheduler callback.|string +networkType | Network type.| NetworkType +isCharging | Whether the device is charging.| bool +chargerType | Charging type.| ChargingType +batteryLevel | Battery level.| number +batteryStatus| Battery status.| BatteryStatus +storageRequest|Storage status.| StorageRequest +isRepeat|Whether the task is repeated.| boolean +repeatCycleTime |Repeat interval.| number +repeatCount |Number of repeat times.| number + +**Table 3** Work Scheduler callbacks + +API | Description +---------------------------------------------------------|----------------------------------------- +function onWorkStart(work: WorkInfo): void; | Triggered when the Work Scheduler task starts. +function onWorkStop(work: WorkInfo): void; | Triggered when the Work Scheduler task stops. + +### How to Develop + +**Implementing WorkSchedulerExtensionAbility** + + import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; + + export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility { + onWorkStart(workInfo) { + console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo)); + } + onWorkStop(workInfo) { + console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo)); + } + } + + +**Registering a Work Scheduler Task** + + import workScheduler from '@ohos.workScheduler'; + + let workInfo = { + workId: 1, + batteryLevel:50, + batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, + isRepeat: false, + isPersisted: true, + bundleName: "com.example.myapplication", + abilityName: "MyExtension" + } + var res = workScheduler.startWork(workInfo); + console.info("workschedulerLog res:" + res); + + +**Canceling the Work Scheduler Task** + + + import workScheduler from '@ohos.workScheduler'; + + let workInfo = { + workId: 1, + batteryLevel:50, + batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, + isRepeat: false, + isPersisted: true, + bundleName: "com.example.myapplication", + abilityName: "MyExtension" + } + var res = workScheduler.stopWork(workInfo, false); + console.info("workschedulerLog res:" + res); + + +**Obtaining a Specified Work Scheduler Task** + +1. Callback syntax + + workScheduler.getWorkStatus(50, (err, res) => { + if (err) { + console.info('workschedulerLog getWorkStatus failed, because:' + err.data); + } else { + for (let item in res) { + console.info('workschedulerLog getWorkStatuscallback success,' + item + ' is:' + res[item]); + } + } + }); + + +2. Promise syntax + + 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.data); + }) + + +**Obtaining All Work Scheduler Tasks** + +1. Callback syntax + + workScheduler.obtainAllWorks((err, res) =>{ + if (err) { + console.info('workschedulerLog obtainAllWorks failed, because:' + err.data); + } else { + console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); + } + }); + +2. Promise syntax + + workScheduler.obtainAllWorks().then((res) => { + console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); + }).catch((err) => { + console.info('workschedulerLog obtainAllWorks failed, because:' + err.data); + }) + +**Stopping and Clearing Work Scheduler Tasks** + + let res = workScheduler.stopAndClearWorks(); + console.info("workschedulerLog res:" + res); + +**Checking Whether the Last Execution Has Timed Out** + +1. Callback syntax + + workScheduler.isLastWorkTimeOut(500, (err, res) =>{ + if (err) { + console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data); + } else { + console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); + } + }); + +2. Promise syntax + + workScheduler.isLastWorkTimeOut(500) + .then(res => { + console.info('workschedulerLog isLastWorkTimeOut success, data is:' + res); + }) + .catch(err => { + console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.data); + }); + }) diff --git a/en/application-dev/work-scheduler/work-scheduler-overview.md b/en/application-dev/work-scheduler/work-scheduler-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..b6c2fec6ec66b369832930fd5dc520603209788f --- /dev/null +++ b/en/application-dev/work-scheduler/work-scheduler-overview.md @@ -0,0 +1,20 @@ +# Work Scheduler Overview + +The Work Scheduler provides a mechanism for applications to execute non-real-time tasks when the system is idle. If the preset conditions are met, the tasks will be placed in the execution queue and scheduled when the system is idle. + +## Usage + +If your application needs to execute a non-real-time task, for example, data learning, you can harness the Work Scheduler mechanism, which will schedule the task based on the storage space, power consumption, temperature, and more when the preset conditions are met. + +## Constraints + +The use of the Work Scheduler must comply with the following restrictions and rules: + +- **Timeout**: The Work Scheduler callback can run only within the specified period of time. After the timeout, the callback automatically stops. +- **WorkInfo setting** + +(1) **workId**, **bundleName**, and **abilityName** are mandatory. **bundleName** must be set to the name of the current application. Otherwise, the verification will fail. + +(2) At least one condition must be set. + +(3) The repeat interval must be at least 20 minutes and must work with the Always repeat pattern or repeat times.