提交 f3409fe0 编写于 作者: G Gloria

Update docs against 14743+15098+14761+14524+15298+15329

Signed-off-by: wusongqing<wusongqing@huawei.com>
上级 2db0ad1e
...@@ -16,6 +16,14 @@ When developing an application, you can override the APIs of this module and add ...@@ -16,6 +16,14 @@ When developing an application, you can override the APIs of this module and add
import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility' import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'
``` ```
## Attributes
**System capability**: SystemCapability.ResourceSchedule.WorkScheduler
| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
| context | [WorkSchedulerExtensionContext](js-apis-inner-application-WorkSchedulerExtensionContext.md) | Yes| No| Context of the **WorkSchedulerExtension**. This context is inherited from **ExtensionContext**.|
## WorkSchedulerExtensionAbility.onWorkStart ## WorkSchedulerExtensionAbility.onWorkStart
onWorkStart(work: workScheduler.WorkInfo): void onWorkStart(work: workScheduler.WorkInfo): void
......
# WorkSchedulerExtensionContext
The **WorkSchedulerExtensionContext** module, inherited from [ExtensionContext](js-apis-inner-application-extensionContext.md), is the context environment of the WorkSchedulerExtensionAbility.
This module provides APIs for accessing the resources of a WorkSchedulerExtensionAbility.
> **NOTE**
>
> The initial APIs of this module are supported since API version 10. 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.
## Usage
The context is obtained through a WorkSchedulerExtensionAbility child class instance.
```ts
import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility';
class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility {
onWorkStart(workInfo) {
let WorkSchedulerExtensionContext = this.context; // Obtain the WorkSchedulerExtensionContext.
}
}
```
...@@ -430,7 +430,7 @@ Provides detailed information about the task. For details about the constraints ...@@ -430,7 +430,7 @@ Provides detailed information about the task. For details about the constraints
| isPersisted | boolean | No | Whether to enable persistent storage for the task. | | isPersisted | boolean | No | Whether to enable persistent storage for the task. |
| isDeepIdle | boolean | No | Whether the device needs to enter the idle state. | | isDeepIdle | boolean | No | Whether the device needs to enter the idle state. |
| idleWaitTime | number | No | Time to wait in the idle state. | | idleWaitTime | number | No | Time to wait in the idle state. |
| parameters | {[key: string]: any} | No | Carried parameters. | | parameters | {[key: string]: number | string | boolean} | No | Carried parameters. |
## NetworkType ## NetworkType
Enumerates the network types that can trigger the task. Enumerates the network types that can trigger the task.
......
# Task Management # Background Task Management
- Background Task - Background Task
- [Background Task Management Overview](background-task-overview.md) - [Background Task Management Overview](background-task-overview.md)
...@@ -8,6 +8,6 @@ ...@@ -8,6 +8,6 @@
- [WorkSchedulerExtensionAbility Development](workscheduler-extensionability.md) - [WorkSchedulerExtensionAbility Development](workscheduler-extensionability.md)
- [Efficiency Resource Request Development](efficiency-resources-apply-dev-guide.md) - [Efficiency Resource Request Development](efficiency-resources-apply-dev-guide.md)
- Agent-Powered Scheduled Reminder - Agent-Powered Reminder
- [Agent-Powered Reminder Overview](reminder-agent-overview.md) - [Agent-Powered Reminder Overview](reminder-agent-overview.md)
- [Agent-Powered Reminder Development](reminder-agent-development.md) - [Agent-Powered Reminder Development](reminder-agent-development.md)
\ No newline at end of file
...@@ -41,7 +41,7 @@ Adhere to the following constraints and rules when using transient tasks: ...@@ -41,7 +41,7 @@ Adhere to the following constraints and rules when using transient tasks:
- **When to cancel**: The application shall proactively cancel the request when the transient task is complete, rather than waiting for a system callback. Otherwise, the time frame allowed for the application to run in the background will be affected. - **When to cancel**: The application shall proactively cancel the request when the transient task is complete, rather than waiting for a system callback. Otherwise, the time frame allowed for the application to run in the background will be affected.
- **Quota mechanism**: To prevent abuse of the keepalive, each application has a certain quota every day (dynamically adjusted based on user habits). After using up the quota, an application cannot request transient tasks. Therefore, applications should cancel their request immediately after the transient tasks are complete, to avoid quota consumption. (Note: The quota refers to the requested duration and does not include the time when the application runs in the background.) - **Quota mechanism**: To prevent abuse of the keepalive, each application has a certain quota every day (dynamically adjusted based on user habits). The default quota for a single day is 10 minutes, and the maximum quota for each request is 3 minutes. After using up the quota, an application cannot request transient tasks. Therefore, applications should cancel their request immediately after the transient tasks are complete, to avoid quota consumption. (Note: The quota refers to the requested duration and does not include the time when the application runs in the background.)
## Continuous Tasks ## Continuous Tasks
Continuous tasks provide background running lifecycle support for services that can be directly perceived by users and need to run in the background. For example, if a service needs to play audio or continue with navigation and positioning in the background, which can be perceived by users, it can execute a continuous task in the respective background mode. Continuous tasks provide background running lifecycle support for services that can be directly perceived by users and need to run in the background. For example, if a service needs to play audio or continue with navigation and positioning in the background, which can be perceived by users, it can execute a continuous task in the respective background mode.
...@@ -58,7 +58,7 @@ OpenHarmony provides 9 background modes for services that require continuous tas ...@@ -58,7 +58,7 @@ OpenHarmony provides 9 background modes for services that require continuous tas
| audioRecording | Audio input | A recording task is running. | - | | audioRecording | Audio input | A recording task is running. | - |
| location | Positioning and navigation | A positioning task is running. | - | | location | Positioning and navigation | A positioning task is running. | - |
| bluetoothInteraction | Bluetooth transmission | A Bluetooth-related task is running. | - | | bluetoothInteraction | Bluetooth transmission | A Bluetooth-related task is running. | - |
| multiDeviceConnection | Distributed interconnection | A distributed task is running. | - | | multiDeviceConnection | Multi-device application collaboration | A distributed task is running. | - |
| wifiInteraction | WLAN transmission | A WLAN-related task is running.| System API, which is available only to system applications| | wifiInteraction | WLAN transmission | A WLAN-related task is running.| System API, which is available only to system applications|
| voip | Voice and video calls over VoIP | A call-related task is running. | System API, which is available only to system applications| | voip | Voice and video calls over VoIP | A call-related task is running. | System API, which is available only to system applications|
| taskKeeping | Computing task | A computing task is running | Effective only for specific devices | | taskKeeping | Computing task | A computing task is running | Effective only for specific devices |
......
...@@ -6,6 +6,9 @@ To further balance power consumption overhead of the system, privileged system a ...@@ -6,6 +6,9 @@ To further balance power consumption overhead of the system, privileged system a
To upgrade your application as a privileged application, you must evaluate your service requirements and submit a request to the application center. The application center will determine whether to accept the request based on the conditions. To upgrade your application as a privileged application, you must evaluate your service requirements and submit a request to the application center. The application center will determine whether to accept the request based on the conditions.
## Constraints
Only system applications can request efficiency resources.
## Available APIs ## Available APIs
**Table 1** Main APIs for efficiency resources **Table 1** Main APIs for efficiency resources
...@@ -22,48 +25,48 @@ To upgrade your application as a privileged application, you must evaluate your ...@@ -22,48 +25,48 @@ To upgrade your application as a privileged application, you must evaluate your
2. When the task is complete, release the resources in time. You can choose whether to release some or all resources. 2. When the task is complete, release the resources in time. You can choose whether to release some or all resources.
```js ```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager'; import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
// Request efficiency resources. // Request efficiency resources.
let request = { let request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT | resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT |
backgroundTaskManager.ResourceType.TIMER, backgroundTaskManager.ResourceType.TIMER,
isApply: true, isApply: true,
timeOut: 0, timeOut: 0,
reason: "apply", reason: "apply",
isPersist: true, isPersist: true,
isProcess: true, isProcess: true,
}; };
let res; let res;
try { try {
res = backgroundTaskManager.applyEfficiencyResources(request); res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res); console.info("the result of request is: " + res);
} catch (error) { } catch (error) {
console.error(`Operation applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`); console.error(`Operation applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
} }
// Release some efficiency resources. // Release some efficiency resources.
request = { request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT, resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT,
isApply: false, isApply: false,
timeOut: 0, timeOut: 0,
reason: "reset", reason: "reset",
isPersist: true, isPersist: true,
isProcess: true, isProcess: true,
}; };
try { try {
res = backgroundTaskManager.applyEfficiencyResources(request); res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res); console.info("the result of request is: " + res);
} catch (error) { } catch (error) {
console.error(`Operation applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`); console.error(`Operation applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
} }
// Release all efficiency resources. // Release all efficiency resources.
try { try {
backgroundTaskManager.resetAllEfficiencyResources(); backgroundTaskManager.resetAllEfficiencyResources();
} catch (error) { } catch (error) {
console.error(`Operation resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`); console.error(`Operation resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
} }
``` ```
\ No newline at end of file
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
## When to Use ## When to Use
If your application needs to execute a non-real-time task or a persistent 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. Your application must implement the callbacks provided by [WorkSchedulerExtensionAbility](./workscheduler-extensionability.md) for Work Scheduler tasks. For details about the restrictions, see [Restrictions on Using Work Scheduler](./background-task-overview.md#restrictions-on-using-work-scheduler). If your application needs to execute a non-real-time task or a persistent 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. Your application must implement the callbacks provided by [WorkSchedulerExtensionAbility](./workscheduler-extensionability.md) for Work Scheduler tasks.
For details about the restrictions, see [Restrictions on Using Work Scheduler](./background-task-overview.md#restrictions-on-using-work-scheduler).
## Available APIs ## Available APIs
...@@ -38,7 +39,7 @@ storageRequest| [StorageRequest](../reference/apis/js-apis-resourceschedule-work ...@@ -38,7 +39,7 @@ storageRequest| [StorageRequest](../reference/apis/js-apis-resourceschedule-work
isRepeat| boolean |Whether the task is repeated. isRepeat| boolean |Whether the task is repeated.
repeatCycleTime| number |Repeat interval. repeatCycleTime| number |Repeat interval.
repeatCount | number|Number of repeat times. repeatCount | number|Number of repeat times.
parameters | {[key: string]: any} |Carried parameters. parameters | {[key: string]: number | string | boolean} |Carried parameters.
**Table 3** Work Scheduler callbacks **Table 3** Work Scheduler callbacks
...@@ -64,135 +65,134 @@ onWorkStop(work: WorkInfo): void | Called when the Work Scheduler task stops. ...@@ -64,135 +65,134 @@ onWorkStop(work: WorkInfo): void | Called when the Work Scheduler task stops.
2. Develop an ExtensionAbility to execute a Work Scheduler task. For details about the ExtensionAbility, see [ExtensionAbility Component Overview](../application-models/extensionability-overview.md) and [WorkSchedulerExtensionAbility Development](./workscheduler-extensionability.md). 2. Develop an ExtensionAbility to execute a Work Scheduler task. For details about the ExtensionAbility, see [ExtensionAbility Component Overview](../application-models/extensionability-overview.md) and [WorkSchedulerExtensionAbility Development](./workscheduler-extensionability.md).
```ts ```ts
import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility';
export default class MyExtension extends WorkSchedulerExtensionAbility { export default class MyExtension extends WorkSchedulerExtensionAbility {
onWorkStart(workInfo) { onWorkStart(workInfo) {
console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo)); console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo));
} }
onWorkStop(workInfo) { onWorkStop(workInfo) {
console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo)); console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo));
} }
} }
``` ```
3. Start a Work Scheduler task. 3. Start a Work Scheduler task.
```ts ```ts
import workScheduler from '@ohos.resourceschedule.workScheduler'; import workScheduler from '@ohos.resourceschedule.workScheduler';
let workInfo = { let workInfo = {
workId: 1, workId: 1,
batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
isRepeat: false, isRepeat: false,
isPersisted: true, isPersisted: true,
bundleName: "com.example.myapplication", bundleName: "com.example.myapplication",
abilityName: "MyExtension", abilityName: "MyExtension",
parameters: { parameters: {
mykey0: 1, mykey0: 1,
mykey1: "string value", mykey1: "string value",
mykey2: true, mykey2: true,
mykey3: 1.5 mykey3: 1.5
} }
} }
try{ try{
workScheduler.startWork(workInfo); workScheduler.startWork(workInfo);
console.info('workschedulerLog startWork success'); console.info('workschedulerLog startWork success');
} catch (error) { } catch (error) {
console.error(`workschedulerLog startwork failed. code is ${error.code} message is ${error.message}`); console.error(`workschedulerLog startwork failed. code is ${error.code} message is ${error.message}`);
} }
``` ```
4. Stop the Work Scheduler task. 4. Stop the Work Scheduler task.
```ts ```ts
import workScheduler from '@ohos.resourceschedule.workScheduler'; import workScheduler from '@ohos.resourceschedule.workScheduler';
let workInfo = { let workInfo = {
workId: 1, workId: 1,
batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW, batteryStatus:workScheduler.BatteryStatus.BATTERY_STATUS_LOW,
isRepeat: false, isRepeat: false,
isPersisted: true, isPersisted: true,
bundleName: "com.example.myapplication", bundleName: "com.example.myapplication",
abilityName: "MyExtension", abilityName: "MyExtension",
parameters: { parameters: {
mykey0: 1, mykey0: 1,
mykey1: "string value", mykey1: "string value",
mykey2: true, mykey2: true,
mykey3: 1.5 mykey3: 1.5
} }
} }
try{ try{
workScheduler.stopWork(workInfo, false); workScheduler.stopWork(workInfo, false);
console.info('workschedulerLog stopWork success'); console.info('workschedulerLog stopWork success');
} catch (error) { } catch (error) {
console.error(`workschedulerLog stopWork failed. code is ${error.code} message is ${error.message}`); console.error(`workschedulerLog stopWork failed. code is ${error.code} message is ${error.message}`);
} }
```
```
5. Obtain a specified Work Scheduler task. 5. Obtain a specified Work Scheduler task.
```ts ```ts
try{ try{
workScheduler.getWorkStatus(50, (error, res) => { workScheduler.getWorkStatus(50, (error, res) => {
if (error) { if (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`); console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
} else { } else {
for (let item in res) { for (let item in res) {
console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`); console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
} }
} }
}); });
} catch (error) { } catch (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`); console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
} }
``` ```
6. Obtain all the Work Scheduler tasks. 6. Obtain all the Work Scheduler tasks.
```ts ```ts
try{ try{
workScheduler.obtainAllWorks((error, res) =>{ workScheduler.obtainAllWorks((error, res) =>{
if (error) { if (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`); console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
} else { } else {
console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`); console.info(`workschedulerLog obtainAllWorks success, data is: ${JSON.stringify(res)}`);
} }
}); });
} catch (error) { } catch (error) {
console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`); console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
} }
``` ```
7. Stop and clear all the Work Scheduler tasks. 7. Stop and clear all the Work Scheduler tasks.
```ts ```ts
try{ try{
workScheduler.stopAndClearWorks(); workScheduler.stopAndClearWorks();
console.info(`workschedulerLog stopAndClearWorks success`); console.info(`workschedulerLog stopAndClearWorks success`);
} catch (error) { } catch (error) {
console.error(`workschedulerLog stopAndClearWorks failed. code is ${error.code} message is ${error.message}`); console.error(`workschedulerLog stopAndClearWorks failed. code is ${error.code} message is ${error.message}`);
} }
``` ```
8. Check whether the last execution of a specified Work Scheduler task has timed out. 8. Check whether the last execution of a specified Work Scheduler task has timed out.
```ts ```ts
try{ try{
workScheduler.isLastWorkTimeOut(500, (error, res) =>{ workScheduler.isLastWorkTimeOut(500, (error, res) =>{
if (error) { if (error) {
onsole.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`); onsole.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
} else { } else {
console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`); console.info(`workschedulerLog isLastWorkTimeOut success, data is: ${res}`);
} }
}); });
} catch (error) { } catch (error) {
console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`); console.error(`workschedulerLog isLastWorkTimeOut failed. code is ${error.code} message is ${error.message}`);
} }
``` ```
# Resource Scheduler Subsystem Changelog
## cl.resourceschedule.workScheduler
The data type of the **parameters** attribute value is changed. Specifically, the number, string, and boolean types are supported, but the any type is not.
**Change Impact**
For applications developed based on OpenHarmony3.2.10.7 and later SDK versions, the **parameters** attribute value can use the number, string, and boolean types only. If it uses the any type, a compilation error is reported.
**Key API/Component Changes**
The **parameters** attribute in @ohos.resourceschedule.workScheduler.d.ts is changed.
| Class| API Type| Statement Before the Change| Statement After the Change|
| -- | -- | -- | -- |
| workScheduler.WorkInfo | field | parameters?: {[key: string]: any} | parameters?: {[key: string]: number | string | boolean} |
**Adaptation Guide**
The **parameters** attribute uses the {[key: string]: number | string | boolean} data type.
# Resource Scheduler Subsystem Changelog
## cl.resourceschedule.workScheduler
The WorkSchedulerExtensionAbility provides a default WorkSchedulerExtensionContext.
**Change Impact**
Applications developed based on OpenHarmony4.0.5.1 and later SDK versions can use the default context attribute as the context environment of a WorkSchedulerExtension.
**Key API/Component Changes**
The context attribute is added to **@ohos.WorkSchedulerExtensionAbility.d.ts**. The **application/WorkSchedulerExtensionContext.d.ts** file is added, which is inherited from ExtensionContext.
| Module| Class| Method/Attribute/Enum/Constant| Change Type|
| -- | -- | -- | -- |
| @ohos.WorkSchedulerExtensionAbility.d.ts | WorkSchedulerExtensionAbility | context: WorkSchedulerExtensionContext; | Added|
| application/WorkSchedulerExtensionContext.d.ts | WorkSchedulerExtensionContext | - | Added|
**Adaptation Guide**
The context is obtained through a WorkSchedulerExtensionAbility child class instance.
```ts
import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility';
class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility {
onWorkStart(workInfo) {
let WorkSchedulerExtensionContext = this.context; // Obtain the WorkSchedulerExtensionContext.
}
}
```
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册