Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
提交 49c181a2 编写于 作者: G Gloria
浏览文件
操作

Update docs against 10631+10688+10667+10699+10630+11124++10576+11145 

Signed-off-by: wusongqing<wusongqing@huawei.com>
上级 b0fa0e39
隐藏空白更改
内联 并排
Showing with 5662 addition and 1523 deletion
en/application-dev/device-usage-statistics/Readme-EN.md
浏览文件 @ 49c181a2
# Device Usage Statistics # Device Usage Statistics
- [Device Usage Statistics Overview](device-usage-statistics-overview.md) - [Device Usage Statistics Overview](device-usage-statistics-overview.md)
- [Device Usage Statistics Development](device-usage-statistics-dev-guide.md) - [Device Usage Statistics Development](device-usage-statistics-use-guide.md)
en/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md 已删除 100644 → 0
浏览文件 @ b0fa0e39
# Device Usage Statistics Development
## When to Use
With device usage statistics APIs, you can have a better understanding of the application, notification, and system usage. For example, in application usage statistics, you can query the application usage, event log, and bundle group.
The application records (usage history statistics and event records) cached by components are updated to the database for persistent storage within 30 minutes after an event is reported.
## Available APIs
Import the **stats** package to implement registration:
```js
import stats from '@ohos.bundleState';
```
**Table 1** Major APIs for device usage statistics
| API| Description|
| -------- | -------- |
| function queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleActiveState&gt;&gt;): void | Queries events of all applications based on the specified start time and end time.|
| function queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback&lt;BundleActiveInfoResponse&gt;): void | Queries the application usage duration statistics based on the specified start time and end time.|
| function queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleActiveState&gt;&gt;): void | Queries events of this application based on the specified start time and end time.|
| function queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleStateInfo&gt;&gt;): void | Queries the application usage duration statistics in the specified time frame at the specified interval (daily, weekly, monthly, or annually).|
| function queryAppUsagePriorityGroup(callback: AsyncCallback&lt;number&gt;): void | Queries the priority group of this application. This API uses an asynchronous callback to return the result.|
| function queryAppUsagePriorityGroup(): Promise&lt;number&gt;; | Queries the priority group of this application. This API uses a promise to return the result.|
| function isIdleState(bundleName: string, callback: AsyncCallback&lt;boolean&gt;): void | Checks whether the application specified by **bundleName** is in the idle state. |
| function getRecentlyUsedModules(callback: AsyncCallback&lt;BundleActiveModuleInfo&gt;): void | Obtains a maximum of 1000 FA usage records. |
| function getRecentlyUsedModules(maxNum: number, callback: AsyncCallback&lt;BundleActiveModuleInfo&gt;): void | Obtains the number of FA usage records specified by **maxNum**, which cannot exceed 1000.|
| function queryAppNotificationNumber(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleActiveEventState&gt;&gt;): void | Queries the number of notifications from all applications based on the specified start time and end time.|
| function queryBundleActiveEventStates(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleActiveEventState&gt;&gt;): void | Queries statistics about system events (hibernation, wakeup, unlocking, and screen locking) that occur between the specified start time and end time.|
| function queryAppUsagePriorityGroup(bundleName : string, callback: AsyncCallback&lt;number&gt;): void | Queries the priority group of the application specified by **bundleName**. This API uses an asynchronous callback to return the result.|
| function queryAppUsagePriorityGroup(bundleName? : string): Promise&lt;number&gt;; | Queries the priority group of the application specified by **bundleName**. If **bundleName** is not specified, the priority group of the current application is queried. This API uses a promise to return the result.|
| function setBundleGroup(bundleName : string, newGroup: GroupType, callback: AsyncCallback&gt;boolean&gt;): void | Sets the group for the application specified by **bundleName**. This API uses an asynchronous callback to return the result.|
| function setBundleGroup(bundleName : string, newGroup : GroupType): Promise&gt;boolean&gt;; | Sets the group for the application specified by **bundleName**. This API uses a promise to return the result.|
| function registerGroupCallBack(groupCallback: Callback&gt;BundleActiveGroupCallbackInfo&gt;, callback: AsyncCallback&gt;boolean&gt;): void | Registers a callback for application group changes. When an application group of the user changes, the change is returned to all applications that have registered the callback. This API uses an asynchronous callback to return the result.|
| function registerGroupCallBack(groupCallback: Callback&gt;BundleActiveGroupCallbackInfo&gt;): Promise&gt;boolean&gt;; | Registers a callback for application group changes. When an application group of the user changes, the change is returned to all applications that have registered the callback. This API uses a promise to return the result.|
| function unRegisterGroupCallBack(callback: AsyncCallback&gt;boolean&gt;): void | Deregisters the callback for application group changes. This API uses an asynchronous callback to return the result.|
| function unRegisterGroupCallBack(): Promise&gt;boolean&gt;; | Deregisters the callback for application group changes. This API uses a promise to return the result.|
## How to Develop
1. Configure the device usage statistics permission in the **config.json** file.
```json
"module": {
"package": "com.example.deviceUsageStatistics",
...,
"reqPermissions": [
{
"name": "ohos.permission.BUNDLE_ACTIVE_INFO"
}
]
}
```
2. Query events of all applications based on the specified start time and end time. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured in the **config.json** file.
```js
import stats from '@ohos.bundleState'
// Promise mode
stats.queryBundleActiveStates(0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryBundleActiveStates promise success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleActiveStates promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleActiveStates promise result ' + JSON.stringify(res[i]));
}
}).catch(err => {
console.log('BUNDLE_ACTIVE queryBundleActiveStates promise failed, because: ' + err.code);
});
// Asynchronous callback mode
stats.queryBundleActiveStates(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleActiveStates callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryBundleActiveStates callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleActiveStates callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleActiveStates callback result ' + JSON.stringify(res[i]));
}
}
});
```
3. Query the application usage duration statistics based on the specified start time and end time. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured in the **config.json** file.
```js
import stats from '@ohos.bundleState'
// Promise mode
stats.queryBundleStateInfos(0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryBundleStateInfos promise success.');
let i = 1;
for (let key in res){
console.log('BUNDLE_ACTIVE queryBundleStateInfos promise number : ' + i);
console.log('BUNDLE_ACTIVE queryBundleStateInfos promise result ' + JSON.stringify(res[key]));
i++;
}
}).catch(err => {
console.log('BUNDLE_ACTIVE queryBundleStateInfos promise failed, because: ' + err.code);
});
// Asynchronous callback mode
stats.queryBundleStateInfos(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleStateInfos callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryBundleStateInfos callback success.');
let i = 1;
for(let key in res){
console.log('BUNDLE_ACTIVE queryBundleStateInfos callback number : ' + i);
console.log('BUNDLE_ACTIVE queryBundleStateInfos callback result ' + JSON.stringify(res[key]));
i++;
}
}
});
```
4. Query events of this application based on the specified start time and end time. This requires no permission to be configured in the **config.json** file.
```js
import stats from '@ohos.bundleState'
// Promise mode
stats.queryCurrentBundleActiveStates(0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise result ' + JSON.stringify(res[i]));
}
}).catch(err => {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise failed, because: ' + err.code);
});
// Asynchronous callback mode
stats.queryCurrentBundleActiveStates(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback result ' + JSON.stringify(res[i]));
}
}
});
```
5. Query the application usage duration statistics in the specified time frame at the specified interval (daily, weekly, monthly, or annually). This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured in the **config.json** file.
```js
import stats from '@ohos.bundleState'
// Promise mode
stats.queryBundleStateInfoByInterval(0, 0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise result ' + JSON.stringify(res[i]));
}
}).catch(err => {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise failed, because: ' + err.code);
});
// Asynchronous callback mode
stats.queryBundleStateInfoByInterval(0, 0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback result ' + JSON.stringify(res[i]));
}
}
});
```
6. Query the priority group of the current application. This requires no permission to be configured in the **config.json** file.
```js
import stats from '@ohos.bundleState'
// Promise mode
stats.queryAppUsagePriorityGroup().then(res => {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch(err => {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise failed. because: ' + err.code);
});
// Callback mode
stats.queryAppUsagePriorityGroup((err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
```
7. Check whether the application specified by **bundleName** is in the idle state. This requires no permission to be configured in the **config.json** file. A third-party application can only check the idle status of itself.
```js
import stats from '@ohos.bundleState'
// Promise mode
stats.isIdleState("com.ohos.camera").then(res => {
console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res));
}).catch(err => {
console.log('BUNDLE_ACTIVE isIdleState promise failed, because: ' + err.code);
});
// Asynchronous callback mode
stats.isIdleState("com.ohos.camera", (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res));
}
});
```
8. Obtain the number of FA usage records specified by **maxNum**. If **maxNum** is not specified, the default value **1000** is used. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured in the **config.json** file.
```js
import stats from '@ohos.bundleState'
// Promise mode
stats.getRecentlyUsedModules(1000).then(res => {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise succeeded');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise result ' + JSON.stringify(res[i]));
}
}).catch(err=> {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code);
});
// Promise mode when maxNum is not specified
stats.getRecentlyUsedModules().then(res => {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise succeeded');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise result ' + JSON.stringify(res[i]));
}
}).catch( err=> {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code);
});
// Asynchronous callback mode
stats.getRecentlyUsedModules(1000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i]));
}
}
});
// Asynchronous callback mode when maxNum is not specified
stats.getRecentlyUsedModules((err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i]));
}
}
});
```
9. Query the number of notifications from all applications based on the specified start time and end time. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured in the **config.json** file.
```js
import stats from '@ohos.bundleState'
// Promise mode
stats.queryAppNotificationNumber(0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise success.');
console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise result ' + JSON.stringify(res));
}).catch(err => {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise failed, because: ' + err.code);
});
// Asynchronous callback mode
stats.queryAppNotificationNumber(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback success.');
console.log('BUNDLE_ACTIVE queryAppNotificationNumber callback result ' + JSON.stringify(res));
}
});
```
10. Query statistics about system events (hibernation, wakeup, unlocking, and screen locking) that occur between the specified start time and end time. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured in the **config.json** file.
```js
import stats from '@ohos.bundleState'
// Promise mode
stats.queryBundleActiveEventStates(0, 20000000000000).then(res => {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise success.');
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise result ' + JSON.stringify(res));
}).catch(err => {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise failed, because: ' + err.code);
});
// Asynchronous callback mode
stats.queryBundleActiveEventStates(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback success.');
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback result ' + JSON.stringify(res));
}
});
```
11. Query the priority group of the current application. This requires no permission to be configured in the **config.json** file. Query the priority group of a specified application. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured in the **config.json** file.
```js
import stats from '@ohos.bundleState'
// Promise mode when bundleName is not specified
stats.queryAppUsagePriorityGroup().then(res => {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch(err => {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise failed. because: ' + err.code);
});
// Asynchronous callback mode when bundleName is not specified
stats.queryAppUsagePriorityGroup((err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
let bundleName = "com.ohos.camera";
// Promise mode when bundleName is specified
stats.queryAppUsagePriorityGroup(bundleName).then(res => {
console.log('BUNDLE_ACTIVE QueryPackageGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch(err => {
console.log('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code);
});
// Asynchronous callback mode when bundleName is specified
stats.queryAppUsagePriorityGroup(bundleName, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
```
11. Set the group for the application specified by **bundleName**.
```javascript
import stats from '@ohos.bundleState'
// Promise mode
stats.setBundleGroup(this.bundleName, this.newGroup).then(() => {
console.log('BUNDLE_ACTIVE SetBundleGroup promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE SetBundleGroup promise failed. because: ' + err.code);
});
// Asynchronous callback mode
stats.setBundleGroup(this.bundleName, this.newGroup, (err) => {
if (err) {
console.log('BUNDLE_ACTIVE SetBundleGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE SetBundleGroup callback succeeded.');
}
});
```
12. Register a callback for application group changes. When an application group of the user changes, the change is returned to all applications that have registered the callback.
```javascript
import stats from '@ohos.bundleState'
// Promise mode
let onBundleGroupChanged = (err,res) => {
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.');
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result oldGroup is : ' + res.oldGroup);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result newGroup is : ' + res.newGroup);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result changeReason is : ' + res.newGroup);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result userId is : ' + res.userId);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result bundleName is : ' + res.bundleName);
};
stats.registerGroupCallBack(onBundleGroupChanged).then(() => {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise succeeded.');
}).catch(err => {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise failed. because: ' + err.code);
});
// Asynchronous callback mode
let onBundleGroupChanged = (err,res) => {
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.');
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result's oldGroup is : ' + res.oldGroup);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result's newGroup is : ' + res.newGroup);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result's changeReason is : ' + res.newGroup);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result's userId is : ' + res.userId);
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack result's bundleName is : ' + res.bundleName);
};
stats.registerGroupCallBack(onBundleGroupChanged, (err) => {
if (err) {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback success.');
}
});
```
13. Deregister the callback for application group changes.
```javascript
import stats from '@ohos.bundleState'
// Promise mode
stats.unRegisterGroupCallBack().then(() => {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise succeeded.');
}).catch(err => {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise failed. because: ' + err.code);
});
// Asynchronous callback mode
stats.unRegisterGroupCallBack((err) => {
if (err) {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback success.');
}
});
```
en/application-dev/device-usage-statistics/device-usage-statistics-use-guide.md 0 → 100644
浏览文件 @ 49c181a2
# Device Usage Statistics Development (API Version 9)
## When to Use
With device usage statistics APIs, you can have a better understanding of the application, notification, and system usage. For example, in application usage statistics, you can query the application usage, event log, and application group.
The application records (usage history statistics and event records) cached by components are updated to the database for persistent storage within 30 minutes after an event is reported.
## Available APIs
Import the **stats** package to implement registration:
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics';
```
**Table 1** Major APIs for device usage statistics
| API| Description|
| -------- | -------- |
| function queryBundleEvents(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleEvents&gt;&gt;): void | Queries events of all applications based on the specified start time and end time.|
| function queryBundleStatsInfos(begin: number, end: number, callback: AsyncCallback&lt;BundleStatsMap&gt;): void | Queries the application usage duration statistics based on the specified start time and end time.|
| function queryCurrentBundleEvents(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleEvents&gt;&gt;): void | Queries events of this application based on the specified start time and end time.|
| function queryBundleStatsInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleStatsInfo&gt;&gt;): void | Queries the application usage duration statistics in the specified time frame at the specified interval (daily, weekly, monthly, or annually).|
| function queryAppGroup(callback: AsyncCallback&lt;number&gt;): void | Queries the priority group of this application. This API uses an asynchronous callback to return the result.|
| function queryAppGroup(): Promise&lt;number&gt;; | Queries the priority group of this application. This API uses a promise to return the result.|
| function queryAppGroup(bundleName : string, callback: AsyncCallback&lt;number&gt;): void | Queries the priority group of the application specified by **bundleName**. This API uses an asynchronous callback to return the result.|
| function queryAppGroup(bundleName : string): Promise&lt;number&gt;; | Queries the priority group of the application specified by **bundleName**. If **bundleName** is not specified, the priority group of the current application is queried. This API uses a promise to return the result.|
| function isIdleState(bundleName: string, callback: AsyncCallback&lt;boolean&gt;): void | Checks whether the application specified by **bundleName** is in the idle state. |
| function queryModuleUsageRecords(callback: AsyncCallback&lt;HapModuleInfo&gt;): void | Obtains a maximum of 1000 FA usage records.|
| function queryModuleUsageRecords(maxNum: number, callback: AsyncCallback&lt;HapModuleInfo&gt;): void | Obtains the number of FA usage records specified by **maxNum**, which cannot exceed 1000.|
| function queryNotificationEventStats(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;DeviceEventStats&gt;&gt;): void | Queries the number of notifications from all applications based on the specified start time and end time.|
| function queryDeviceEventStats(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;DeviceEventStats&gt;&gt;): void | Queries statistics about system events (hibernation, wakeup, unlocking, and screen locking) that occur between the specified start time and end time.|
| function setAppGroup(bundleName : string, newGroup: GroupType, callback: AsyncCallback&gt;boolean&gt;): void | Sets the group for the application specified by **bundleName**. This API uses an asynchronous callback to return the result.|
| function setAppGroup(bundleName : string, newGroup : GroupType): Promise&gt;boolean&gt;; | Sets the group for the application specified by **bundleName**. This API uses a promise to return the result.|
| function registerAppGroupCallBack(groupCallback: Callback&gt;AppGroupCallbackInfo&gt;, callback: AsyncCallback&gt;boolean&gt;): void | Registers a callback for application group changes. When an application group of the user changes, the change is returned to all applications that have registered the callback. This API uses an asynchronous callback to return the result.|
| function registerAppGroupCallBack(groupCallback: Callback&gt;AppGroupCallbackInfo&gt;): Promise&gt;boolean&gt;; | Registers a callback for application group changes. When an application group of the user changes, the change is returned to all applications that have registered the callback. This API uses a promise to return the result.|
| function unregisterAppGroupCallBack(callback: AsyncCallback&gt;boolean&gt;): void | Deregisters the callback for application group changes. This API uses an asynchronous callback to return the result.|
| function unregisterAppGroupCallBack(): Promise&gt;boolean&gt;; | Deregisters the callback for application group changes. This API uses a promise to return the result.|
## How to Develop
1. Before obtaining the device usage statistics, check whether the **ohos.permission.BUNDLE_ACTIVE_INFO** permission is configured. For details about how to configure a permission, see [Declaring Permissions](../security/accesstoken-guidelines.md).
2. Query events of all applications based on the specified start time and end time. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
try{
usageStatistics.queryBundleEvents(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryBundleEvents promise success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleEvents promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleEvents promise result ' + JSON.stringify(res[i]));
}
}).catch( err => {
console.log('BUNDLE_ACTIVE queryBundleEvents promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
try{
usageStatistics.queryBundleEvents(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleEvents callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryBundleEvents callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleEvents callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleEvents callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
3. Query the application usage duration statistics based on the specified start time and end time. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
try{
usageStatistics.queryBundleStatsInfos(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise success.');
let i = 1;
for(let key in res){
console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise number : ' + i);
console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise result ' + JSON.stringify(res[key]));
i++;
}
}).catch( err => {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
try{
usageStatistics.queryBundleStatsInfos(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback success.');
let i = 1;
for(let key in res){
console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback number : ' + i);
console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback result ' + JSON.stringify(res[key]));
i++;
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
4. Query events of this application based on the specified start time and end time. This requires no permission to be configured.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
try{
usageStatistics.queryCurrentBundleEvents(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise result ' + JSON.stringify(res[i]));
}
}).catch( err => {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
try{
usageStatistics.queryCurrentBundleEvents(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
5. Query the application usage duration statistics in the specified time frame at the specified interval (daily, weekly, monthly, or annually). This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
try{
usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise result ' + JSON.stringify(res[i]));
}
}).catch( err => {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
try{
usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
6. Query the priority group of the current application. This requires no permission to be configured.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
try{
usageStatistics.queryAppGroup().then( res => {
console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch( err => {
console.log('BUNDLE_ACTIVE queryAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Callback mode
try{
usageStatistics.queryAppGroup((err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
7. Check whether the application specified by **bundleName** is in the idle state. This requires no permission to be configured. A third-party application can only check the idle status of itself.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
try{
usageStatistics.isIdleState("com.ohos.camera").then( res => {
console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res));
}).catch( err => {
console.log('BUNDLE_ACTIVE isIdleState promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE isIdleState throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
try{
usageStatistics.isIdleState("com.ohos.camera", (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE isIdleState callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res));
}
});
} catch(error) {
console.log('BUNDLE_ACTIVE isIdleState throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
8. Obtain the number of FA usage records specified by **maxNum**. If **maxNum** is not specified, the default value **1000** is used. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
try{
usageStatistics.queryModuleUsageRecords(1000).then( res => {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i]));
}
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Promise mode when maxNum is not specified
try{
usageStatistics.queryModuleUsageRecords().then( res => {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i]));
}
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
try{
usageStatistics.queryModuleUsageRecords(1000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode when maxNum is not specified
try{
usageStatistics.queryModuleUsageRecords((err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
9. Query the number of notifications from all applications based on the specified start time and end time. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
try{
usageStatistics.queryNotificationEventStats(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryNotificationEventStats promise success.');
console.log('BUNDLE_ACTIVE queryNotificationEventStats promise result ' + JSON.stringify(res));
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryNotificationEventStats promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
try{
usageStatistics.queryNotificationEventStats(0, 20000000000000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryNotificationEventStats callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryNotificationEventStats callback success.');
console.log('BUNDLE_ACTIVE queryNotificationEventStats callback result ' + JSON.stringify(res));
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
10. Query statistics about system events (hibernation, wakeup, unlocking, and screen locking) that occur between the specified start time and end time. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
try{
usageStatistics.queryDeviceEventStats(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryDeviceEventStates promise success.');
console.log('BUNDLE_ACTIVE queryDeviceEventStates promise result ' + JSON.stringify(res));
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryDeviceEventStats promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
try{
usageStatistics.queryDeviceEventStats(0, 20000000000000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryDeviceEventStats callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryDeviceEventStats callback success.');
console.log('BUNDLE_ACTIVE queryDeviceEventStats callback result ' + JSON.stringify(res));
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
11. Query the priority group of the application specified by **bundleName**. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```js
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode when bundleName is specified
let bundleName = "com.ohos.camera";
try{
usageStatistics.queryAppGroup(bundleName).then( res => {
console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch( err => {
console.log('BUNDLE_ACTIVE queryAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode when bundleName is specified
let bundleName = "com.ohos.camera";
try{
usageStatistics.queryAppGroup(bundleName, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
12. Set the priority group of for application specified by **bundleName**. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```javascript
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
let bundleName = "com.example.deviceUsageStatistics";
let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY;
try{
usageStatistics.setAppGroup(bundleName, newGroup).then( () => {
console.log('BUNDLE_ACTIVE setAppGroup promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE setAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
let bundleName = "com.example.deviceUsageStatistics";
let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY;
try{
usageStatistics.setAppGroup(bundleName, newGroup, (err) => {
if(err) {
console.log('BUNDLE_ACTIVE setAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE setAppGroup callback succeeded.');
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
13. Register a callback for application group changes. When an application group of the user changes, the change is returned to all applications that have registered the callback. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```javascript
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// Promise mode
let onBundleGroupChanged = (res) =>{
console.log('BUNDLE_ACTIVE registerAppGroupCallBack RegisterGroupCallBack callback success.');
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName);
};
try{
usageStatistics.registerAppGroupCallBack(onBundleGroupChanged).then( () => {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// Asynchronous callback mode
let onBundleGroupChanged = (err, res) =>{
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.');
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName);
};
try{
usageStatistics.registerAppGroupCallBack(onBundleGroupChanged, err => {
if(err) {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback success.');
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
14. Deregister the callback for application group changes. This requires the **ohos.permission.BUNDLE_ACTIVE_INFO** permission to be configured.
```javascript
import usageStatistics from '@ohos.resourceschedule.usageStatistics'
// promise
try{
usageStatistics.unregisterAppGroupCallBack().then( () => {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message);
}
// callback
try{
usageStatistics.unregisterAppGroupCallBack(err => {
if(err) {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack callback success.');
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
\ No newline at end of file
en/application-dev/reference/apis/Readme-EN.md
浏览文件 @ 49c181a2
...@@ -6,13 +6,14 @@ ...@@ -6,13 +6,14 @@
- [@ohos.ability.featureAbility](js-apis-featureAbility.md) - [@ohos.ability.featureAbility](js-apis-featureAbility.md)
- [@ohos.ability.particleAbility](js-apis-particleAbility.md) - [@ohos.ability.particleAbility](js-apis-particleAbility.md)
- ability/[dataAbilityHelper](js-apis-dataAbilityHelper.md) - ability/[dataAbilityHelper](js-apis-dataAbilityHelper.md)
- app/[context](js-apis-Context.md) - app/[context](js-apis-Context.md)
- Stage Model - Stage Model
- [@ohos.application.Ability](js-apis-application-ability.md) - [@ohos.application.Ability](js-apis-application-ability.md)
- [@ohos.application.AbilityConstant](js-apis-application-abilityConstant.md) - [@ohos.application.AbilityConstant](js-apis-application-abilityConstant.md)
- [@ohos.application.AbilityStage](js-apis-application-abilitystage.md) - [@ohos.application.AbilityStage](js-apis-application-abilitystage.md)
- [@ohos.application.abilityLifecycleCallback](js-apis-application-abilityLifecycleCallback.md) - [@ohos.application.abilityLifecycleCallback](js-apis-application-abilityLifecycleCallback.md)
- [@ohos.application.DataShareExtensionAbility](js-apis-application-DataShareExtensionAbility.md) - [@ohos.application.DataShareExtensionAbility](js-apis-application-DataShareExtensionAbility.md)
- [@ohos.application.EnvironmentCallback](js-apis-application-EnvironmentCallback.md)
- [@ohos.application.FormExtension](js-apis-formextension.md) - [@ohos.application.FormExtension](js-apis-formextension.md)
- [@ohos.application.ServiceExtensionAbility](js-apis-service-extension-ability.md) - [@ohos.application.ServiceExtensionAbility](js-apis-service-extension-ability.md)
- [@ohos.application.StartOptions](js-apis-application-StartOptions.md) - [@ohos.application.StartOptions](js-apis-application-StartOptions.md)
...@@ -25,19 +26,14 @@ ...@@ -25,19 +26,14 @@
- application/[ExtensionContext](js-apis-extension-context.md) - application/[ExtensionContext](js-apis-extension-context.md)
- application/[FormExtensionContext](js-apis-formextensioncontext.md) - application/[FormExtensionContext](js-apis-formextensioncontext.md)
- application/[PermissionRequestResult](js-apis-permissionrequestresult.md) - application/[PermissionRequestResult](js-apis-permissionrequestresult.md)
- application/[ServiceExtensionContext](js-apis-service-extension-context.md) - application/[ServiceExtensionContext](js-apis-service-extension-context.md)
- FA and Stage Models - FA and Stage Models
- [@ohos.ability.dataUriUtils](js-apis-DataUriUtils.md) - [@ohos.ability.dataUriUtils](js-apis-DataUriUtils.md)
- [@ohos.ability.errorCode](js-apis-ability-errorCode.md) - [@ohos.ability.errorCode](js-apis-ability-errorCode.md)
- [@ohos.ability.wantConstant](js-apis-ability-wantConstant.md) - [@ohos.ability.wantConstant](js-apis-ability-wantConstant.md)
- [@ohos.application.abilityDelegatorRegistry](js-apis-abilityDelegatorRegistry.md) - [@ohos.application.abilityDelegatorRegistry](js-apis-abilityDelegatorRegistry.md)
- [@ohos.application.abilityManager](js-apis-application-abilityManager.md) - [@ohos.application.abilityManager](js-apis-application-abilityManager.md)
- [@ohos.application.AccessibilityExtensionAbility](js-apis-accessibility-extension-context.md)
- [@ohos.application.AccessibilityExtensionAbility](js-apis-application-AccessibilityExtensionAbility.md)
- [@ohos.application.appManager](js-apis-appmanager.md) - [@ohos.application.appManager](js-apis-appmanager.md)
- [@ohos.application.Configuration](js-apis-configuration.md)
- [@ohos.application.ConfigurationConstant](js-apis-configurationconstant.md)
- [@ohos.application.EnvironmentCallback](js-apis-application-EnvironmentCallback.md)
- [@ohos.application.errorManager](js-apis-errorManager.md) - [@ohos.application.errorManager](js-apis-errorManager.md)
- [@ohos.application.formBindingData](js-apis-formbindingdata.md) - [@ohos.application.formBindingData](js-apis-formbindingdata.md)
- [@ohos.application.formError](js-apis-formerror.md) - [@ohos.application.formError](js-apis-formerror.md)
...@@ -47,7 +43,6 @@ ...@@ -47,7 +43,6 @@
- [@ohos.application.missionManager](js-apis-missionManager.md) - [@ohos.application.missionManager](js-apis-missionManager.md)
- [@ohos.application.quickFixManager](js-apis-application-quickFixManager.md) - [@ohos.application.quickFixManager](js-apis-application-quickFixManager.md)
- [@ohos.application.Want](js-apis-application-Want.md) - [@ohos.application.Want](js-apis-application-Want.md)
- [@ohos.continuation.continuationManager](js-apis-continuation-continuationExtraParams.md)
- [@ohos.continuation.continuationManager](js-apis-continuation-continuationManager.md) - [@ohos.continuation.continuationManager](js-apis-continuation-continuationManager.md)
- [@ohos.wantAgent](js-apis-wantAgent.md) - [@ohos.wantAgent](js-apis-wantAgent.md)
- application/[abilityDelegator](js-apis-application-abilityDelegator.md) - application/[abilityDelegator](js-apis-application-abilityDelegator.md)
...@@ -56,38 +51,16 @@ ...@@ -56,38 +51,16 @@
- application/[AbilityRunningInfo](js-apis-abilityrunninginfo.md) - application/[AbilityRunningInfo](js-apis-abilityrunninginfo.md)
- application/[ExtensionRunningInfo](js-apis-extensionrunninginfo.md) - application/[ExtensionRunningInfo](js-apis-extensionrunninginfo.md)
- application/[MissionSnapshot](js-apis-application-MissionSnapshot.md) - application/[MissionSnapshot](js-apis-application-MissionSnapshot.md)
- application/[ProcessRunningInfo](js-apis-processrunninginfo.md)
- application/[ProcessRunningInformation](js-apis-processrunninginformation.md) - application/[ProcessRunningInformation](js-apis-processrunninginformation.md)
- application/[shellCmdResult](js-apis-application-shellCmdResult.md) - application/[shellCmdResult](js-apis-application-shellCmdResult.md)
- continuation/[continuationExtraParams](js-apis-continuation-continuationExtraParams.md)
- continuation/[ContinuationResult](js-apis-continuation-continuationResult.md) - continuation/[ContinuationResult](js-apis-continuation-continuationResult.md)
- Common Event and Notification - Common Event and Notification
- [@ohos.commonEvent](js-apis-commonEvent.md)
- [@ohos.events.emitter](js-apis-emitter.md) - [@ohos.events.emitter](js-apis-emitter.md)
- [@ohos.notification](js-apis-notification.md) - [@ohos.notification](js-apis-notification.md)
- application/[EventHub](js-apis-eventhub.md) - application/[EventHub](js-apis-eventhub.md)
- Bundle Management - Bundle Management
- [@ohos.bundle](js-apis-Bundle.md)
- [@ohos.bundle.defaultAppManager](js-apis-bundle-defaultAppManager.md)
- [@ohos.bundle.innerBundleManager)](js-apis-Bundle-InnerBundleManager.md)
- [@ohos.distributedBundle)](js-apis-Bundle-distributedBundle.md)
- [@ohos.zlib](js-apis-zlib.md) - [@ohos.zlib](js-apis-zlib.md)
- bundle/[AbilityInfo](js-apis-bundle-AbilityInfo.md)
- bundle/[ApplicationInfo](js-apis-bundle-ApplicationInfo.md)
- bundle/[BundleInfo](js-apis-bundle-BundleInfo.md)
- bundle/[BundleInstaller](js-apis-bundle-BundleInstaller.md)
- bundle/[BundleStatusCallback](js-apis-Bundle-BundleStatusCallback.md)
- bundle/[CustomizeData](js-apis-bundle-CustomizeData.md)
- bundle/[DispatchInfo](js-apis-dispatchInfo.md)
- bundle/[ElementName](js-apis-bundle-ElementName.md)
- bundle/[ExtensionAbilityInfo](js-apis-bundle-ExtensionAbilityInfo.md)
- bundle/[HapModuleInfo](js-apis-bundle-HapModuleInfo.md)
- bundle/[LauncherAbilityInfo](js-apis-bundle-LauncherAbilityInfo.md)
- bundle/[Metadata](js-apis-bundle-Metadata.md)
- bundle/[ModuleInfo](js-apis-bundle-ModuleInfo.md)
- bundle/[PermissionDef](js-apis-bundle-PermissionDef.md)
- bundle/[RemoteAbilityInfo](js-apis-bundle-remoteAbilityInfo.md)
- bundle/[ShortcutInfo<sup>(deprecated)</sup>](js-apis-bundle-ShortcutInfo.md)
- bundle/[PackInfo](js-apis-bundle-PackInfo.md)
- UI Page - UI Page
- [@ohos.animator](js-apis-animator.md) - [@ohos.animator](js-apis-animator.md)
- [@ohos.mediaquery](js-apis-mediaquery.md) - [@ohos.mediaquery](js-apis-mediaquery.md)
...@@ -115,13 +88,11 @@ ...@@ -115,13 +88,11 @@
- Resource Scheduling - Resource Scheduling
- [@ohos.backgroundTaskManager](js-apis-backgroundTaskManager.md) - [@ohos.backgroundTaskManager](js-apis-backgroundTaskManager.md)
- [@ohos.distributedMissionManager](js-apis-distributedMissionManager.md) - [@ohos.distributedMissionManager](js-apis-distributedMissionManager.md)
- [@ohos.workScheduler ](js-apis-workScheduler.md) - [@ohos.reminderAgentManager](js-apis-reminderAgentManager.md)
- [@ohos.resourceschedule.backgroundTaskManager](js-apis-resourceschedule-backgroundTaskManager.md)
- [@ohos.resourceschedule.workScheduler](js-apis-resourceschedule-workScheduler.md)
- [@ohos.resourceschedule.usageStatistics](js-apis-resourceschedule-deviceUsageStatistics.md)
- [@ohos.WorkSchedulerExtensionAbility](js-apis-WorkSchedulerExtensionAbility.md) - [@ohos.WorkSchedulerExtensionAbility](js-apis-WorkSchedulerExtensionAbility.md)
- Custom Management
- [@ohos.configPolicy](js-apis-config-policy.md)
- [@ohos.EnterpriseAdminExtensionAbility](js-apis-EnterpriseAdminExtensionAbility.md)
- [@ohos.enterpriseDeviceManager](js-apis-enterprise-device-manager.md)
- enterpriseDeviceManager/[DeviceSettingsManager](js-apis-enterpriseDeviceManager-DeviceSettingsManager.md)
- Security - Security
- [@ohos.abilityAccessCtrl](js-apis-abilityAccessCtrl.md) - [@ohos.abilityAccessCtrl](js-apis-abilityAccessCtrl.md)
- [@ohos.privacyManager](js-apis-privacyManager.md) - [@ohos.privacyManager](js-apis-privacyManager.md)
...@@ -129,9 +100,7 @@ ...@@ -129,9 +100,7 @@
- [@ohos.userIAM.faceAuth](js-apis-useriam-faceauth.md) - [@ohos.userIAM.faceAuth](js-apis-useriam-faceauth.md)
- [@ohos.userIAM.userAuth ](js-apis-useriam-userauth.md) - [@ohos.userIAM.userAuth ](js-apis-useriam-userauth.md)
- [@system.cipher](js-apis-system-cipher.md) - [@system.cipher](js-apis-system-cipher.md)
- Data Management - Data Management
- [@ohos.data.dataAbility ](js-apis-data-ability.md) - [@ohos.data.dataAbility ](js-apis-data-ability.md)
- [@ohos.data.dataShare](js-apis-data-dataShare.md) - [@ohos.data.dataShare](js-apis-data-dataShare.md)
- [@ohos.data.dataSharePredicates](js-apis-data-dataSharePredicates.md) - [@ohos.data.dataSharePredicates](js-apis-data-dataSharePredicates.md)
...@@ -141,9 +110,7 @@ ...@@ -141,9 +110,7 @@
- [@ohos.data.rdb](js-apis-data-rdb.md) - [@ohos.data.rdb](js-apis-data-rdb.md)
- [@ohos.data.ValuesBucket](js-apis-data-ValuesBucket.md) - [@ohos.data.ValuesBucket](js-apis-data-ValuesBucket.md)
- data/rdb/[resultSet](js-apis-data-resultset.md) - data/rdb/[resultSet](js-apis-data-resultset.md)
- File Management - File Management
- [@ohos.document](js-apis-document.md) - [@ohos.document](js-apis-document.md)
- [@ohos.environment](js-apis-environment.md) - [@ohos.environment](js-apis-environment.md)
- [@ohos.data.fileAccess](js-apis-fileAccess.md) - [@ohos.data.fileAccess](js-apis-fileAccess.md)
...@@ -188,8 +155,8 @@ ...@@ -188,8 +155,8 @@
- Basic Features - Basic Features
- [@ohos.accessibility](js-apis-accessibility.md) - [@ohos.accessibility](js-apis-accessibility.md)
- [@ohos.accessibility.config](js-apis-accessibility-config.md) - [@ohos.accessibility.config](js-apis-accessibility-config.md)
- [@ohos.application.AccessibilityExtensionAbility](js-apis-application-AccessibilityExtensionAbility.md)
- [@ohos.faultLogger](js-apis-faultLogger.md) - [@ohos.faultLogger](js-apis-faultLogger.md)
- [@ohos.hiAppEvent](js-apis-hiappevent.md)
- [@ohos.hichecker](js-apis-hichecker.md) - [@ohos.hichecker](js-apis-hichecker.md)
- [@ohos.hidebug](js-apis-hidebug.md) - [@ohos.hidebug](js-apis-hidebug.md)
- [@ohos.hilog](js-apis-hilog.md) - [@ohos.hilog](js-apis-hilog.md)
...@@ -207,14 +174,12 @@ ...@@ -207,14 +174,12 @@
- [@ohos.wallpaper](js-apis-wallpaper.md) - [@ohos.wallpaper](js-apis-wallpaper.md)
- [console](js-apis-logs.md) - [console](js-apis-logs.md)
- [Timer](js-apis-timer.md) - [Timer](js-apis-timer.md)
- application/[AccessibilityExtensionContext](js-apis-accessibility-extension-context.md)
- Device Management - Device Management
- [@ohos.batteryInfo ](js-apis-battery-info.md) - [@ohos.batteryInfo ](js-apis-battery-info.md)
- [@ohos.brightness](js-apis-brightness.md) - [@ohos.brightness](js-apis-brightness.md)
- [@ohos.deviceInfo](js-apis-device-info.md) - [@ohos.deviceInfo](js-apis-device-info.md)
- [@ohos.distributedHardware.deviceManager](js-apis-device-manager.md) - [@ohos.distributedHardware.deviceManager](js-apis-device-manager.md)
- [@ohos.geolocation](js-apis-geolocation.md)
- [@ohos.multimodalInput.inputConsumer](js-apis-inputconsumer.md) - [@ohos.multimodalInput.inputConsumer](js-apis-inputconsumer.md)
- [@ohos.multimodalInput.inputDevice](js-apis-inputdevice.md) - [@ohos.multimodalInput.inputDevice](js-apis-inputdevice.md)
- [@ohos.multimodalInput.inputDeviceCooperate](js-apis-cooperate.md) - [@ohos.multimodalInput.inputDeviceCooperate](js-apis-cooperate.md)
...@@ -230,7 +195,6 @@ ...@@ -230,7 +195,6 @@
- [@ohos.runningLock](js-apis-runninglock.md) - [@ohos.runningLock](js-apis-runninglock.md)
- [@ohos.sensor](js-apis-sensor.md) - [@ohos.sensor](js-apis-sensor.md)
- [@ohos.settings](js-apis-settings.md) - [@ohos.settings](js-apis-settings.md)
- [@ohos.systemParameter](js-apis-system-parameter.md)
- [@ohos.thermal](js-apis-thermal.md) - [@ohos.thermal](js-apis-thermal.md)
- [@ohos.update](js-apis-update.md) - [@ohos.update](js-apis-update.md)
- [@ohos.usb](js-apis-usb.md) - [@ohos.usb](js-apis-usb.md)
...@@ -239,6 +203,11 @@ ...@@ -239,6 +203,11 @@
- [@ohos.account.appAccount](js-apis-appAccount.md) - [@ohos.account.appAccount](js-apis-appAccount.md)
- [@ohos.account.distributedAccount](js-apis-distributed-account.md) - [@ohos.account.distributedAccount](js-apis-distributed-account.md)
- [@ohos.account.osAccount](js-apis-osAccount.md) - [@ohos.account.osAccount](js-apis-osAccount.md)
- Custom Management
- [@ohos.configPolicy](js-apis-config-policy.md)
- [@ohos.EnterpriseAdminExtensionAbility](js-apis-EnterpriseAdminExtensionAbility.md)
- [@ohos.enterpriseDeviceManager](js-apis-enterprise-device-manager.md)
- enterpriseDeviceManager/[DeviceSettingsManager](js-apis-enterpriseDeviceManager-DeviceSettingsManager.md)
- Language Base Class Library - Language Base Class Library
- [@ohos.buffer](js-apis-buffer.md) - [@ohos.buffer](js-apis-buffer.md)
- [@ohos.convertxml](js-apis-convertxml.md) - [@ohos.convertxml](js-apis-convertxml.md)
...@@ -266,12 +235,21 @@ ...@@ -266,12 +235,21 @@
- [@ohos.application.testRunner](js-apis-testRunner.md) - [@ohos.application.testRunner](js-apis-testRunner.md)
- [@ohos.uitest](js-apis-uitest.md) - [@ohos.uitest](js-apis-uitest.md)
- APIs No Longer Maintained - APIs No Longer Maintained
- [@ohos.backgroundTaskManager](js-apis-backgroundTaskManager.md)
- [@ohos.bundle](js-apis-Bundle.md)
- [@ohos.bundle.innerBundleManager](js-apis-Bundle-InnerBundleManager.md)
- [@ohos.bundleState](js-apis-deviceUsageStatistics.md) - [@ohos.bundleState](js-apis-deviceUsageStatistics.md)
- [@ohos.bytrace](js-apis-bytrace.md) - [@ohos.bytrace](js-apis-bytrace.md)
- [@ohos.commonEvent](js-apis-commonEvent.md)
- [@ohos.data.storage](js-apis-data-storage.md) - [@ohos.data.storage](js-apis-data-storage.md)
- [@ohos.data.distributedData](js-apis-distributed-data.md) - [@ohos.data.distributedData](js-apis-distributed-data.md)
- [@ohos.distributedBundle](js-apis-Bundle-distributedBundle.md)
- [@ohos.document](js-apis-document.md)
- [@ohos.geolocation](js-apis-geolocation.md)
- [@ohos.hiAppEvent](js-apis-hiappevent.md)
- [@ohos.prompt](js-apis-prompt.md) - [@ohos.prompt](js-apis-prompt.md)
- [@ohos.reminderAgent](js-apis-reminderAgent.md) - [@ohos.reminderAgent](js-apis-reminderAgent.md)
- [@ohos.systemParameter](js-apis-system-parameter.md)
- [@system.app](js-apis-system-app.md) - [@system.app](js-apis-system-app.md)
- [@system.battery](js-apis-system-battery.md) - [@system.battery](js-apis-system-battery.md)
- [@system.bluetooth](js-apis-system-bluetooth.md) - [@system.bluetooth](js-apis-system-bluetooth.md)
...@@ -291,4 +269,16 @@ ...@@ -291,4 +269,16 @@
- [@system.sensor](js-apis-system-sensor.md) - [@system.sensor](js-apis-system-sensor.md)
- [@system.storage](js-apis-system-storage.md) - [@system.storage](js-apis-system-storage.md)
- [@system.vibrator](js-apis-system-vibrate.md) - [@system.vibrator](js-apis-system-vibrate.md)
- [console](js-apis-logs.md) - application/[ProcessRunningInfo](js-apis-processrunninginfo.md)
- bundle/[abilityInfo](js-apis-bundle-AbilityInfo.md)
- bundle/[applicationInfo](js-apis-bundle-ApplicationInfo.md)
- bundle/[bundleInfo](js-apis-bundle-BundleInfo.md)
- bundle/[bundleInstaller](js-apis-bundle-BundleInstaller.md)
- bundle/[bundleStatusCallback](js-apis-Bundle-BundleStatusCallback.md)
- bundle/[elementName](js-apis-bundle-ElementName.md)
- bundle/[hapModuleInfo](js-apis-bundle-HapModuleInfo.md)
- bundle/[launcherAbilityInfo](js-apis-bundle-LauncherAbilityInfo.md)
- bundle/[moduleInfo](js-apis-bundle-ModuleInfo.md)
- bundle/[PermissionDef](js-apis-bundle-PermissionDef.md)
- bundle/[remoteAbilityInfo](js-apis-bundle-remoteAbilityInfo.md)
- bundle/[shortcutInfo](js-apis-bundle-ShortcutInfo.md)
en/application-dev/reference/apis/js-apis-WorkSchedulerExtensionAbility.md
浏览文件 @ 49c181a2
...@@ -28,7 +28,7 @@ Triggered when the Work Scheduler task starts. ...@@ -28,7 +28,7 @@ Triggered when the Work Scheduler task starts.
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ---- | ---------------------------------------- | ---- | -------------- | | ---- | ---------------------------------------- | ---- | -------------- |
| work | [workScheduler.WorkInfo](js-apis-workScheduler.md#workinfo) | Yes | Target task. | | work | [workScheduler.WorkInfo](js-apis-resourceschedule-workScheduler.md#workinfo) | Yes | Target task.|
**Example** **Example**
...@@ -52,7 +52,7 @@ Triggered when the Work Scheduler task stops. ...@@ -52,7 +52,7 @@ Triggered when the Work Scheduler task stops.
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ---- | ---------------------------------------- | ---- | -------------- | | ---- | ---------------------------------------- | ---- | -------------- |
| work | [workScheduler.WorkInfo](js-apis-workScheduler.md#workinfo) | Yes | Target task. | | work | [workScheduler.WorkInfo](js-apis-resourceschedule-workScheduler.md#workinfo) | Yes | Target task.|
**Example** **Example**
......
en/application-dev/reference/apis/js-apis-backgroundTaskManager.md
浏览文件 @ 49c181a2
...@@ -8,11 +8,11 @@ If an application has a task that needs to be continued when the application is ...@@ -8,11 +8,11 @@ If an application has a task that needs to be continued when the application is
If an application has a service that can be intuitively perceived by users and needs to run in the background for a long period of time (for example, music playback in the background), the application can request a continuous task. If an application has a service that can be intuitively perceived by users and needs to run in the background for a long period of time (for example, music playback in the background), the application can request a continuous task.
If a privileged system application needs to use certain system resources (for example, resources required to receive common events) when suspended, it can request efficiency resources. If a privileged system application needs to use certain system resources (for example, it wants to receive common events when suspended), it can request efficiency resources.
> **NOTE** > **NOTE**
> > - This module is deprecated since API version 9. You are advised to use [@ohos.resourceschedule.backgroundTaskManager](js-apis-resourceschedule-backgroundTaskManager.md) instead.
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. > - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Modules to Import
...@@ -28,17 +28,19 @@ requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspen ...@@ -28,17 +28,19 @@ requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspen
Requests delayed suspension after the application switches to the background. Requests delayed suspension after the application switches to the background.
The default duration of delayed suspension is 180000 when the battery level is higher than or equal to the broadcast low battery level and 60000 when the battery level is lower than the broadcast low battery level. The default duration of delayed suspension is 3 minutes when the battery level is higher than or equal to the broadcast low battery level and 1 minute when the battery level is lower than the broadcast low battery level.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | -------------------- | ---- | ------------------------------ | | -------- | -------------------- | ---- | ------------------------------ |
| reason | string | Yes | Reason for delayed transition to the suspended state. | | reason | string | Yes | Reason for delayed transition to the suspended state. |
| callback | Callback&lt;void&gt; | Yes | Invoked when a delay is about to time out. Generally, this callback is used to notify the application 6 seconds before the delay times out.| | callback | Callback&lt;void&gt; | Yes | Invoked when a delay is about to time out. Generally, this callback is used to notify the application 6 seconds before the delay times out.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ------------------------------------- | --------- | | ------------------------------------- | --------- |
| [DelaySuspendInfo](#delaysuspendinfo) | Information about the suspension delay.| | [DelaySuspendInfo](#delaysuspendinfo) | Information about the suspension delay.|
...@@ -46,13 +48,15 @@ The default duration of delayed suspension is 180000 when the battery level is h ...@@ -46,13 +48,15 @@ The default duration of delayed suspension is 180000 when the battery level is h
**Example** **Example**
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let myReason = 'test requestSuspendDelay'; let myReason = 'test requestSuspendDelay';
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out."); console.info("Request suspension delay will time out.");
}) })
var id = delayInfo.requestId; let id = delayInfo.requestId;
var time = delayInfo.actualDelayTime; let time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id); console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time); console.info("The actualDelayTime is: " + time);
``` ```
...@@ -67,16 +71,19 @@ Obtains the remaining duration before the application is suspended. This API use ...@@ -67,16 +71,19 @@ Obtains the remaining duration before the application is suspended. This API use
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| --------- | --------------------------- | ---- | ---------------------------------------- | | --------- | --------------------------- | ---- | ---------------------------------------- |
| requestId | number | Yes | ID of the suspension delay request. | | requestId | number | Yes | ID of the suspension delay request. The value is obtained by calling [requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay).|
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the remaining duration before the application is suspended, in milliseconds.| | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the remaining duration before the application is suspended, in milliseconds.|
**Example** **Example**
```js ```js
let id = 1; import backgroundTaskManager from '@ohos.backgroundTaskManager';
backgroundTaskManager.getRemainingDelayTime(id, (err, res) => {
let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {});
backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId, (err, res) => {
if(err) { if(err) {
console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.code); console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.code);
} else { } else {
...@@ -95,19 +102,22 @@ Obtains the remaining duration before the application is suspended. This API use ...@@ -95,19 +102,22 @@ Obtains the remaining duration before the application is suspended. This API use
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| --------- | ------ | ---- | ---------- | | --------- | ------ | ---- | ---------- |
| requestId | number | Yes | ID of the suspension delay request.| | requestId | number | Yes | ID of the suspension delay request. The value is obtained by calling [requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay).|
**Return value** **Return value**
| Type | Description | | Type | Description |
| --------------------- | ---------------------------------------- | | --------------------- | ---------------------------------------- |
| Promise&lt;number&gt; | Promise used to return the remaining duration before the application is suspended, in milliseconds.| | Promise&lt;number&gt; | Promise used to return the remaining duration before the application is suspended, in milliseconds.|
**Example** **Example**
```js ```js
let id = 1; let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {});
backgroundTaskManager.getRemainingDelayTime(id).then( res => { backgroundTaskManager.getRemainingDelayTime(delayInfo.requestId).then( res => {
console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( err => { }).catch( err => {
console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code); console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code);
...@@ -124,14 +134,16 @@ Cancels the suspension delay. ...@@ -124,14 +134,16 @@ Cancels the suspension delay.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| --------- | ------ | ---- | ---------- | | --------- | ------ | ---- | ---------- |
| requestId | number | Yes | ID of the suspension delay request.| | requestId | number | Yes | ID of the suspension delay request. The value is obtained by calling [requestSuspendDelay](#backgroundtaskmanagerrequestsuspenddelay).|
**Example** **Example**
```js ```js
let id = 1; let delayInfo = backgroundTaskManager.requestSuspendDelay("test", () => {});
backgroundTaskManager.cancelSuspendDelay(id); backgroundTaskManager.cancelSuspendDelay(delayInfo.requestId);
``` ```
...@@ -146,6 +158,7 @@ Requests a continuous task from the system. This API uses an asynchronous callba ...@@ -146,6 +158,7 @@ Requests a continuous task from the system. This API uses an asynchronous callba
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| --------- | ---------------------------------- | ---- | ---------------------------------------- | | --------- | ---------------------------------- | ---- | ---------------------------------------- |
| context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).| | context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).|
...@@ -154,6 +167,9 @@ Requests a continuous task from the system. This API uses an asynchronous callba ...@@ -154,6 +167,9 @@ Requests a continuous task from the system. This API uses an asynchronous callba
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. | | callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
**Example** **Example**
FA model:
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
...@@ -181,11 +197,48 @@ let wantAgentInfo = { ...@@ -181,11 +197,48 @@ let wantAgentInfo = {
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj, callback) backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback)
}); });
``` ```
Stage model:
```ts
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent';
function callback(err, data) {
if (err) {
console.error("Operation startBackgroundRunning failed Cause: " + err);
} else {
console.info("Operation startBackgroundRunning succeeded");
}
}
export default class MainAbility extends Ability {
onCreate(want, launchParam) {
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(this.context,
backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback)
});
}
};
```
## backgroundTaskManager.startBackgroundRunning<sup>8+</sup> ## backgroundTaskManager.startBackgroundRunning<sup>8+</sup>
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt; startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;
...@@ -205,11 +258,15 @@ Requests a continuous task from the system. This API uses a promise to return th ...@@ -205,11 +258,15 @@ Requests a continuous task from the system. This API uses a promise to return th
| wantAgent | [WantAgent](js-apis-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. | | wantAgent | [WantAgent](js-apis-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
**Return value** **Return value**
| Type | Description | | Type | Description |
| -------------- | ---------------- | | -------------- | ---------------- |
| Promise\<void> | Promise used to return the result.| | Promise\<void> | Promise used to return the result.|
**Example** **Example**
FA model:
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
...@@ -229,13 +286,45 @@ let wantAgentInfo = { ...@@ -229,13 +286,45 @@ let wantAgentInfo = {
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded"); console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => { }).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err); console.error("Operation startBackgroundRunning failed Cause: " + err);
}); });
}); });
```
Stage model:
```ts
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent';
export default class MainAbility extends Ability {
onCreate(want, launchParam) {
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(this.context,
backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err);
});
});
}
};
``` ```
## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup> ## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup>
...@@ -247,12 +336,16 @@ Requests to cancel a continuous task. This API uses an asynchronous callback to ...@@ -247,12 +336,16 @@ Requests to cancel a continuous task. This API uses an asynchronous callback to
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | ------------------------- | ---- | ---------------------------------------- | | -------- | ------------------------- | ---- | ---------------------------------------- |
| context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).| | context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. | | callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
**Example** **Example**
FA model:
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
...@@ -269,6 +362,27 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callbac ...@@ -269,6 +362,27 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext(), callbac
``` ```
Stage model:
```ts
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.backgroundTaskManager';
function callback(err, data) {
if (err) {
console.error("Operation stopBackgroundRunning failed Cause: " + err);
} else {
console.info("Operation stopBackgroundRunning succeeded");
}
}
export default class MainAbility extends Ability {
onCreate(want, launchParam) {
backgroundTaskManager.stopBackgroundRunning(this.context, callback);
}
};
```
## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup> ## backgroundTaskManager.stopBackgroundRunning<sup>8+</sup>
stopBackgroundRunning(context: Context): Promise&lt;void&gt; stopBackgroundRunning(context: Context): Promise&lt;void&gt;
...@@ -278,16 +392,21 @@ Requests to cancel a continuous task. This API uses a promise to return the resu ...@@ -278,16 +392,21 @@ Requests to cancel a continuous task. This API uses a promise to return the resu
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**Parameters** **Parameters**
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ------- | ------- | ---- | ---------------------------------------- | | ------- | ------- | ---- | ---------------------------------------- |
| context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).| | context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).|
**Return value** **Return value**
| Type | Description | | Type | Description |
| -------------- | ---------------- | | -------------- | ---------------- |
| Promise\<void> | Promise used to return the result.| | Promise\<void> | Promise used to return the result.|
**Example** **Example**
FA model:
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
...@@ -300,62 +419,21 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() ...@@ -300,62 +419,21 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(()
``` ```
## backgroundTaskManager.applyEfficiencyResources<sup>9+</sup> Stage model:
applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): boolean
Requests efficiency resources from the system.
A process and its application can request the same type of resources at the same time, for example, CPU resources. When the application releases the resources, the same type of resources requested by the process are also released.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ------- | ---- | ---------------------------------------- |
| request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest9) | Yes | Necessary information carried in the request, including the resource type and timeout interval. For details, see [EfficiencyResourcesRequest](#efficiencyresourcesrequest9).|
**Return value**
| Type | Description |
| -------------- | ---------------- |
| boolean | Returns **true** if the request for the resources is successful; returns **false** otherwise.|
**Example** ```ts
import Ability from '@ohos.application.Ability'
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.backgroundTaskManager';
let request = { export default class MainAbility extends Ability {
resourceTypes: backgroundTaskManager.ResourceType.CPU, onCreate(want, launchParam) {
isApply: true, backgroundTaskManager.stopBackgroundRunning(this.context).then(() => {
timeOut: 0, console.info("Operation stopBackgroundRunning succeeded");
reason: "apply", }).catch((err) => {
isPersist: true, console.error("Operation stopBackgroundRunning failed Cause: " + err);
isProcess: false, });
}
}; };
let res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("result of applyEfficiencyResources is: " + res)
```
## backgroundTaskManager.resetAllEfficiencyResources<sup>9+</sup>
resetAllEfficiencyResources(): void
Releases all resources that have been requested.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**System API**: This is a system API.
**Example**
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
``` ```
## DelaySuspendInfo ## DelaySuspendInfo
...@@ -374,49 +452,14 @@ Provides the information about the suspension delay. ...@@ -374,49 +452,14 @@ Provides the information about the suspension delay.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask **System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
| Name | Value | Description | | Name | Description |
| ----------------------- | ---- | --------------------- | | ----------------------- | --------------------- |
| DATA_TRANSFER | 1 | Data transfer. | | DATA_TRANSFER | Data transfer. |
| AUDIO_PLAYBACK | 2 | Audio playback. | | AUDIO_PLAYBACK | Audio playback. |
| AUDIO_RECORDING | 3 | Audio recording. | | AUDIO_RECORDING | Audio recording. |
| LOCATION | 4 | Positioning and navigation. | | LOCATION | Positioning and navigation. |
| BLUETOOTH_INTERACTION | 5 | Bluetooth-related task. | | BLUETOOTH_INTERACTION | Bluetooth-related task. |
| MULTI_DEVICE_CONNECTION | 6 | Multi-device connection. | | MULTI_DEVICE_CONNECTION | Multi-device connection. |
| WIFI_INTERACTION | 7 | WLAN-related.<br>This is a system API.| | WIFI_INTERACTION | WLAN-related (system API).|
| VOIP | 8 | Audio and video calls.<br>This is a system API. | | VOIP | Audio and video calls (system API). |
| TASK_KEEPING | 9 | Computing task (effective only for specific devices). | | TASK_KEEPING | Computing task (effective only for specific devices). |
## EfficiencyResourcesRequest<sup>9+</sup>
Describes the parameters for requesting efficiency resources.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**System API**: This is a system API.
| Name | Type | Mandatory | Description |
| --------------- | ------ | ---- | ---------------------------------------- |
| resourceTypes | number | Yes | Type of the resource to request. |
| isApply | boolean | Yes | Whether the request is used to apply for resources. The value **true** means that the request is used to apply for resources, and **false** means that the request is used to release resources. |
| timeOut | number | Yes | Duration for which the resource will be used, in milliseconds. |
| isPersist | boolean | No | Whether the resource is permanently held. If the value is **true**, **timeOut** is invalid. |
| isProcess | boolean | No | Whether the request is initiated by a process. The value **true** means that the request is initiated by a process, and **false** means that the request is initiated by an application. |
| reason | string | Yes | Reason for requesting the resource. |
## ResourceType<sup>9+</sup>
Enumerates the efficiency resource types.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**System API**: This is a system API.
| Name | Value | Description |
| ----------------------- | ---- | --------------------- |
| CPU | 1 | CPU resources, which prevent the application from being suspended. |
| COMMON_EVENT | 2 | A type of software resources, which prevent common events from being proxied when the application is suspended. |
| TIMER | 4 | A type of software resources, which prevent timers from being proxied when the application is suspended. |
| WORK_SCHEDULER | 8 | WORK_SCHEDULER resources, which ensure that the application has more time to execute the task. |
| BLUETOOTH | 16 | A type of hardware resources, which prevent Bluetooth resources from being proxied when the application is suspended. |
| GPS | 32 | A type of hardware resources, which prevent GPS resources from being proxied when the application is suspended. |
| AUDIO | 64 | A type of hardware resources, which prevent audio resources from being proxied when the application is suspended.|
en/application-dev/reference/apis/js-apis-deviceUsageStatistics.md
浏览文件 @ 49c181a2
...@@ -5,11 +5,8 @@ This module provides APIs for collecting statistics on device usage. ...@@ -5,11 +5,8 @@ This module provides APIs for collecting statistics on device usage.
System applications can call these APIs to implement the following features: System applications can call these APIs to implement the following features:
- Query the usage duration in different time segments, events (foreground, background, start and end of continuous tasks), and the number of notifications, on a per application basis. - Query the usage duration in different time segments, events (foreground, background, start and end of continuous tasks), and the number of notifications, on a per application basis.
- Query statistics about system events (sleep, wakeup, unlock, and screen lock). - Query the bundle group information of the invoking application itself.
- Query the bundle group information of applications, including the invoking application itself.
- Query the idle status of applications, including the invoking application itself. - Query the idle status of applications, including the invoking application itself.
- Set the bundle group for other applications.
- Register and deregister the callback for application group changes.
Third-party applications can call these APIs to implement the following features: Third-party applications can call these APIs to implement the following features:
...@@ -19,12 +16,15 @@ Third-party applications can call these APIs to implement the following features ...@@ -19,12 +16,15 @@ Third-party applications can call these APIs to implement the following features
> **NOTE** > **NOTE**
> >
> This module is deprecated since API version 9. You are advised to use [@ohos.resourceschedule.usageStatistics](js-apis-resourceschedule-deviceUsageStatistics.md) instead.
>
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
## Modules to Import ## Modules to Import
``` ```js
import bundleState from '@ohos.bundleState' import bundleState from '@ohos.bundleState'
``` ```
...@@ -32,7 +32,7 @@ import bundleState from '@ohos.bundleState' ...@@ -32,7 +32,7 @@ import bundleState from '@ohos.bundleState'
isIdleState(bundleName: string, callback: AsyncCallback&lt;boolean&gt;): void isIdleState(bundleName: string, callback: AsyncCallback&lt;boolean&gt;): void
Checks whether the application specified by **bundleName** is in the idle state. This API uses an asynchronous callback to return the result. A third-party application can only check the idle status of itself. Checks whether the application specified by **bundleName** is in the idle state. This API uses an asynchronous callback to return the result. By default, a third-party application can only check the idle state of itself. To query the idle state of other applications, it must request the **ohos.permission.BUNDLE_ACTIVE_INFO** permission.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup **System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
...@@ -41,11 +41,11 @@ Checks whether the application specified by **bundleName** is in the idle state. ...@@ -41,11 +41,11 @@ Checks whether the application specified by **bundleName** is in the idle state.
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ---------- | ---------------------------- | ---- | ---------------------------------------- | | ---------- | ---------------------------- | ---- | ---------------------------------------- |
| bundleName | string | Yes | Bundle name of an application. | | bundleName | string | Yes | Bundle name of an application. |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the result. Returns the idle state of the application if the specified **bundleName** is valid; returns **null** otherwise.| | callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the result. If the specified **bundleName** is valid, the idle state of the application is returned; otherwise, **null** is returned.|
**Example** **Example**
``` ```js
bundleState.isIdleState("com.ohos.camera", (err, res) => { bundleState.isIdleState("com.ohos.camera", (err, res) => {
if (err) { if (err) {
console.log('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code); console.log('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code);
...@@ -59,7 +59,7 @@ Checks whether the application specified by **bundleName** is in the idle state. ...@@ -59,7 +59,7 @@ Checks whether the application specified by **bundleName** is in the idle state.
isIdleState(bundleName: string): Promise&lt;boolean&gt; isIdleState(bundleName: string): Promise&lt;boolean&gt;
Checks whether the application specified by **bundleName** is in the idle state. This API uses a promise to return the result. A third-party application can only check the idle status of itself. Checks whether the application specified by **bundleName** is in the idle state. This API uses a promise to return the result. By default, a third-party application can only check the idle state of itself. To query the idle state of other applications, it must request the **ohos.permission.BUNDLE_ACTIVE_INFO** permission.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup **System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
...@@ -73,7 +73,7 @@ Checks whether the application specified by **bundleName** is in the idle state. ...@@ -73,7 +73,7 @@ Checks whether the application specified by **bundleName** is in the idle state.
| Type | Description | | Type | Description |
| ---------------------- | ---------------------------------------- | | ---------------------- | ---------------------------------------- |
| Promise&lt;boolean&gt; | Promise used to return the result. Returns the idle state of the application if the specified **bundleName** is valid; returns **null** otherwise.| | Promise&lt;boolean&gt; | Promise used to return the result. If the specified **bundleName** is valid, the idle state of the application is returned; otherwise, **null** is returned.|
**Example** **Example**
...@@ -97,7 +97,7 @@ Queries the priority group of this application. This API uses a promise to retur ...@@ -97,7 +97,7 @@ Queries the priority group of this application. This API uses a promise to retur
| Type | Description | | Type | Description |
| --------------- | --------------------------- | | --------------- | --------------------------- |
| Promise&lt;number&gt; | Promise used to return the result.| | Promise&lt;number&gt; | Promise used to return the priority group.|
**Example** **Example**
...@@ -121,7 +121,7 @@ Queries the priority group of this application. This API uses an asynchronous ca ...@@ -121,7 +121,7 @@ Queries the priority group of this application. This API uses an asynchronous ca
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | --------------------- | ---- | -------------------------- | | -------- | --------------------- | ---- | -------------------------- |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the result.| | callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the priority group.|
**Example** **Example**
...@@ -151,9 +151,9 @@ Queries the application usage duration statistics based on the specified start t ...@@ -151,9 +151,9 @@ Queries the application usage duration statistics based on the specified start t
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------------------------------------- | | -------- | ---------------------------------------- | ---- | --------------------------------------- |
| begin | number | Yes | Start time. | | begin | number | Yes | Start time, in milliseconds. |
| end | number | Yes | End time. | | end | number | Yes | End time, in milliseconds. |
| callback | AsyncCallback&lt;[BundleActiveInfoResponse](#bundleactiveinforesponse)&gt; | Yes | Callback used to return the result.| | callback | AsyncCallback&lt;[BundleActiveInfoResponse](#bundleactiveinforesponse)&gt; | Yes | Callback used to return the application usage duration statistics.|
**Example** **Example**
...@@ -189,14 +189,14 @@ Queries the application usage duration statistics based on the specified start t ...@@ -189,14 +189,14 @@ Queries the application usage duration statistics based on the specified start t
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- | | ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.| | begin | number | Yes | Start time, in milliseconds.|
| end | number | Yes | End time.| | end | number | Yes | End time, in milliseconds.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ---------------------------------------- | -------------------------------------- | | ---------------------------------------- | -------------------------------------- |
| Promise&lt;[BundleActiveInfoResponse](#bundleactiveinforesponse)&gt; | Promise used to return the result.| | Promise&lt;[BundleActiveInfoResponse](#bundleactiveinforesponse)&gt; | Promise used to return the application usage duration statistics.|
**Example** **Example**
...@@ -231,14 +231,14 @@ Queries the application usage duration statistics in the specified time frame at ...@@ -231,14 +231,14 @@ Queries the application usage duration statistics in the specified time frame at
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | | ---------- | ---------------------------------------- | ---- | ---------------------------------------- |
| byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried. | | byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried. |
| begin | number | Yes | Start time. | | begin | number | Yes | Start time, in milliseconds. |
| end | number | Yes | End time. | | end | number | Yes | End time, in milliseconds. |
| callback | AsyncCallback&lt;Array&lt;[BundleStateInfo](#bundlestateinfo)&gt;&gt; | Yes | Callback used to return the result.| | callback | AsyncCallback&lt;Array&lt;[BundleStateInfo](#bundlestateinfo)&gt;&gt; | Yes | Callback used to return the application usage duration statistics.|
**Example** **Example**
```js ```js
bundleState.queryBundleStateInfoByInterval(0, 0, 20000000000000, (err, res) => { bundleState.queryBundleStateInfoByInterval(bundleState.IntervalType.BY_OPTIMIZED, 0, 20000000000000, (err, res) => {
if (err) { if (err) {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code); console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code);
} else { } else {
...@@ -268,19 +268,19 @@ Queries the application usage duration statistics in the specified time frame at ...@@ -268,19 +268,19 @@ Queries the application usage duration statistics in the specified time frame at
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ---------- | ----------------------------- | ---- | ----- | | ---------- | ----------------------------- | ---- | ----- |
| byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried.| | byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried.|
| begin | number | Yes | Start time.| | begin | number | Yes | Start time, in milliseconds.|
| end | number | Yes | End time.| | end | number | Yes | End time, in milliseconds.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ---------------------------------------- | ---------------------------------------- | | ---------------------------------------- | ---------------------------------------- |
| Promise&lt;Array&lt;[BundleStateInfo](#bundlestateinfo)&gt;&gt; | Promise used to return the result. | | Promise&lt;Array&lt;[BundleStateInfo](#bundlestateinfo)&gt;&gt; | Promise used to return the application usage duration statistics.|
**Example** **Example**
```js ```js
bundleState.queryBundleStateInfoByInterval(0, 0, 20000000000000).then( res => { bundleState.queryBundleStateInfoByInterval(bundleState.IntervalType.BY_OPTIMIZED, 0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise success.'); console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise success.');
for (let i = 0; i < res.length; i++) { for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise number : ' + (i + 1)); console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise number : ' + (i + 1));
...@@ -307,9 +307,9 @@ Queries events of all applications based on the specified start time and end tim ...@@ -307,9 +307,9 @@ Queries events of all applications based on the specified start time and end tim
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------------------------------------- | | -------- | ---------------------------------------- | ---- | --------------------------------------- |
| begin | number | Yes | Start time. | | begin | number | Yes | Start time, in milliseconds. |
| end | number | Yes | End time. | | end | number | Yes | End time, in milliseconds. |
| callback | AsyncCallback&lt;Array&lt;[BundleActiveState](#bundleactivestate)&gt;&gt; | Yes | Callback used to return the result. | | callback | AsyncCallback&lt;Array&lt;[BundleActiveState](#bundleactivestate)&gt;&gt; | Yes | Callback used to return the events obtained.|
**Example** **Example**
...@@ -343,14 +343,14 @@ Queries events of all applications based on the specified start time and end tim ...@@ -343,14 +343,14 @@ Queries events of all applications based on the specified start time and end tim
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- | | ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.| | begin | number | Yes | Start time, in milliseconds.|
| end | number | Yes | End time.| | end | number | Yes | End time, in milliseconds.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ---------------------------------------- | -------------------------------------- | | ---------------------------------------- | -------------------------------------- |
| Promise&lt;Array&lt;[BundleActiveState](#bundleactivestate)&gt;&gt; | Promise used to return the result. | | Promise&lt;Array&lt;[BundleActiveState](#bundleactivestate)&gt;&gt; | Promise used to return the events obtained.|
**Example** **Example**
...@@ -378,9 +378,9 @@ Queries events of this application based on the specified start time and end tim ...@@ -378,9 +378,9 @@ Queries events of this application based on the specified start time and end tim
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------------------------------------- | | -------- | ---------------------------------------- | ---- | --------------------------------------- |
| begin | number | Yes | Start time. | | begin | number | Yes | Start time, in milliseconds. |
| end | number | Yes | End time. | | end | number | Yes | End time, in milliseconds. |
| callback | AsyncCallback&lt;Array&lt;[BundleActiveState](#bundleactivestate)&gt;&gt; | Yes | Callback used to return the result. | | callback | AsyncCallback&lt;Array&lt;[BundleActiveState](#bundleactivestate)&gt;&gt; | Yes | Callback used to return the events obtained.|
**Example** **Example**
...@@ -410,14 +410,14 @@ Queries events of this application based on the specified start time and end tim ...@@ -410,14 +410,14 @@ Queries events of this application based on the specified start time and end tim
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- | | ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.| | begin | number | Yes | Start time, in milliseconds.|
| end | number | Yes | End time.| | end | number | Yes | End time, in milliseconds.|
**Return value** **Return value**
| Type | Description | | Type | Description |
| ---------------------------------------- | -------------------------------------- | | ---------------------------------------- | -------------------------------------- |
| Promise&lt;Array&lt;[BundleActiveState](#bundleactivestate)&gt;&gt; | Promise used to return the result. | | Promise&lt;Array&lt;[BundleActiveState](#bundleactivestate)&gt;&gt; | Promise used to return the events obtained.|
**Example** **Example**
...@@ -433,637 +433,9 @@ Queries events of this application based on the specified start time and end tim ...@@ -433,637 +433,9 @@ Queries events of this application based on the specified start time and end tim
}); });
``` ```
## bundleState.getRecentlyUsedModules<sup>9+</sup>
getRecentlyUsedModules(maxNum?: number): Promise&lt;Array&lt;BundleActiveModuleInfo&gt;&gt;
Obtains the number of FA usage records specified by **maxNum**. This API uses a promise to return the records sorted by time (most recent first).
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| ------ | ------ | ---- | ---------------------------------- |
| maxNum | number | No | Maximum number of returned records. The maximum and default value is **1000**. If this parameter is not specified, **1000** is used.|
**Return value**
| Type | Description |
| ---------------------------------------- | ---------------------------------- |
| Promise&lt;Array&lt;[BundleActiveModuleInfo](#bundleactivemoduleinfo9)&gt;&gt; | Promise used to return the result. |
**Example**
```js
bundleState.getRecentlyUsedModules(1000).then( res => {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise succeeded');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise result ' + JSON.stringify(res[i]));
}
}).catch( err=> {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code);
});
// Invocation when maxNum is not passed
bundleState.getRecentlyUsedModules().then( res => {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise succeeded');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise result ' + JSON.stringify(res[i]));
}
}).catch( err=> {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules promise failed, because: ' + err.code);
});
```
## bundleState.getRecentlyUsedModules<sup>9+</sup>
getRecentlyUsedModules(callback: AsyncCallback&lt;Array&lt;BundleActiveModuleInfo&gt;&gt;): void
Obtains FA usage records. This API uses an asynchronous callback to return a maximum of 1000 FA usage records sorted by time in descending order.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ----------------------------------- |
| callback | AsyncCallback&lt;Array&lt;[BundleActiveModuleInfo](#bundleactivemoduleinfo9)&gt;&gt; | Yes | Callback used to return the result. |
**Example**
```js
bundleState.getRecentlyUsedModules((err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i]));
}
}
});
```
## bundleState.getRecentlyUsedModules<sup>9+</sup>
getRecentlyUsedModules(maxNum: number, callback: AsyncCallback&lt;Array&lt;BundleActiveModuleInfo&gt;&gt;): void
Obtains the number of FA usage records specified by **maxNum**. This API uses an asynchronous callback to return the records sorted by time (most recent first).
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ----------------------------------- |
| maxNum | number | Yes | Maximum number of returned records. The maximum value is **1000**.|
| callback | AsyncCallback&lt;Array&lt;[BundleActiveModuleInfo](#bundleactivemoduleinfo9)&gt;&gt; | Yes | Callback used to return the result. |
**Example**
```js
bundleState.getRecentlyUsedModules(1000,(err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE getRecentlyUsedModules callback result ' + JSON.stringify(res[i]));
}
}
});
```
## bundleState.queryAppUsagePriorityGroup<sup>9+</sup>
queryAppUsagePriorityGroup(bundleName? : string): Promise&lt;number&gt;
Queries the priority group of the application specified by **bundleName**. If **bundleName** is not specified, the priority group of the current application is queried. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ------ | ---- | ---------------------------------------- |
| bundleName | string | No | Bundle name of the target application. If this parameter is not specified, the priority group of the current application is queried.|
**Return value**
| Type | Description |
| --------------- | --------------------------- |
| Promise&lt;number&gt; | Promise used to return the result.|
**Example**
```javascript
// Promise mode when bundleName is specified
let bundleName = "com.ohos.camera";
bundleState.queryAppUsagePriorityGroup(bundleName).then( res => {
console.log('BUNDLE_ACTIVE QueryPackageGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch( err => {
console.log('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code);
});
// Promise mode when bundleName is not specified
bundleState.queryAppUsagePriorityGroup().then( res => {
console.log('BUNDLE_ACTIVE QueryPackageGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch( err => {
console.log('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code);
});
```
## bundleState.queryAppUsagePriorityGroup<sup>9+</sup>
queryAppUsagePriorityGroup(callback: AsyncCallback&lt;number&gt;): void
Queries the priority group of this application. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | --------------------- | ---- | ---------------------------------------- |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the result. |
**Example**
```javascript
bundleState.queryAppUsagePriorityGroup((err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
```
## bundleState.queryAppUsagePriorityGroup<sup>9+</sup>
queryAppUsagePriorityGroup(bundleName : string, callback: AsyncCallback&lt;number&gt;): void
Queries the priority group of the application specified by **bundleName**. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | --------------------- | ---- | ---------------------------------------- |
| bundleName | string | Yes | Bundle name of the target application.|
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the result. |
**Example**
```javascript
let bundleName = "com.ohos.camera";
bundleState.queryAppUsagePriorityGroup(bundleName, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
```
## bundleState.setBundleGroup<sup>9+</sup>
setBundleGroup(bundleName: string, newGroup: GroupType): Promise&lt;void&gt;
Sets the group for the application specified by **bundleName**. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | --------- | ---- | ---- |
| bundleName | string | Yes | Bundle name of an application.|
| newGroup | [GroupType](#grouptype) | Yes | Application group.|
**Return value**
| Type | Description |
| ------------- | ------------------------- |
| Promise&lt;void&gt; | Promise used to return the result. |
**Example**
```javascript
let bundleName = "com.example.deviceUsageStatistics";
let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY;
bundleState.setBundleGroup(bundleName, newGroup).then( () => {
console.log('BUNDLE_ACTIVE SetBundleGroup promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE SetBundleGroup promise failed. because: ' + err.code);
});
```
## bundleState.setBundleGroup<sup>9+</sup>
setBundleGroup(bundleName: string, newGroup: GroupType, callback: AsyncCallback&lt;void&gt;): void
Sets the group for the application specified by **bundleName**. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ------------------- | ---- | ------------------------- |
| bundleName | string | Yes | Bundle name of an application. |
| newGroup | [GroupType](#grouptype) | Yes | Application group. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
**Example**
```javascript
let bundleName = "com.example.deviceUsageStatistics";
let newGroup = bundleState.GroupType.ACTIVE_GROUP_DAILY;
bundleState.setBundleGroup(bundleName, newGroup, (err) => {
if(err) {
console.log('BUNDLE_ACTIVE SetBundleGroup callback failed. because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE SetBundleGroup callback succeeded.');
}
});
```
## bundleState.registerGroupCallBack<sup>9+</sup>
registerGroupCallBack(groupCallback: Callback&lt;BundleActiveGroupCallbackInfo&gt;): Promise&lt;void&gt;
Registers a callback for application group changes. When an application group of the user changes, a **[BundleActiveGroupCallbackInfo](#bundleactivegroupcallbackinfo9)** instance is returned to all applications that have registered the callback. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
| callback | Callback&lt;[BundleActiveGroupCallbackInfo](#bundleactivegroupcallbackinfo9)&gt; | Yes | Callback used to return the application group changes.|
**Return value**
| Type | Description |
| ------------- | ----------------------- |
| Promise&lt;void&gt; | Promise used to return the result. |
**Example**
```javascript
let onBundleGroupChanged = (err,res) =>{
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.');
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result appUsageOldGroup is : ' + res.appUsageOldGroup);
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result appUsageNewGroup is : ' + res.appUsageNewGroup);
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result changeReason is : ' + res.changeReason);
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result userId is : ' + res.userId);
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result bundleName is : ' + res.bundleName);
};
bundleState.registerGroupCallBack(onBundleGroupChanged).then( () => {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack promise failed. because: ' + err.code);
});
```
## bundleState.registerGroupCallBack<sup>9+</sup>
registerGroupCallBack(groupCallback: Callback&lt;BundleActiveGroupCallbackInfo&gt;, callback: AsyncCallback&lt;void&gt;): void
Registers a callback for application group changes. When an application group of the user changes, a **[BundleActiveGroupCallbackInfo](#bundleactivegroupcallbackinfo9)** instance is returned to all applications that have registered the callback. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- |
| callback | Callback&lt;[BundleActiveGroupCallbackInfo](#bundleactivegroupcallbackinfo9)&gt; | Yes | Callback used to return the application group changes. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result.|
**Example**
```javascript
let onBundleGroupChanged = (err,res) =>{
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.');
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result appUsageOldGroup is : ' + res.appUsageOldGroup);
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result appUsageNewGroup is : ' + res.appUsageNewGroup);
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result changeReason is : ' + res.changeReason);
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result userId is : ' + res.userId);
console.log('BUNDLE_ACTIVE RegisterGroupCallBack result bundleName is : ' + res.bundleName);
};
bundleState.registerGroupCallBack(onBundleGroupChanged, (err)=>{
if(err) {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE RegisterGroupCallBack callback success.');
}
});
```
## bundleState.unRegisterGroupCallBack<sup>9+</sup>
unRegisterGroupCallBack(): Promise&lt;void&gt;
Deregisters the callback for application group changes. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**: none
**Return value**
| Type | Description |
| ------------- | ------------------------ |
| Promise&lt;void&gt; | Promise used to return the result. |
**Example**
```javascript
bundleState.unRegisterGroupCallBack().then( () => {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack promise failed. because: ' + err.code);
});
```
## bundleState.unRegisterGroupCallBack<sup>9+</sup>
unRegisterGroupCallBack(callback: AsyncCallback&lt;void&gt;): void;
Deregisters the callback for application group changes. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------------------- | ---- | -------------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result.|
**Example**
```javascript
bundleState.unRegisterGroupCallBack((err)=>{
if(err) {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE UnRegisterGroupCallBack callback success.');
}
});
```
## bundleState.queryBundleActiveEventStates<sup>9+</sup>
queryBundleActiveEventStates(begin: number, end: number): Promise&lt;Array&lt;BundleActiveEventState&gt;&gt;
Queries statistics about system events (hibernation, wakeup, unlocking, and screen locking) that occur between the specified start time and end time. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.|
| end | number | Yes | End time.|
**Return value**
| Type | Description |
| ---------------------------------------- | ---------------------------------------- |
| Promise&lt;Array&lt;[BundleActiveEventState](#bundleactiveeventstate9)&gt;&gt; | Promise used to return the result. |
**Example**
```js
bundleState.queryBundleActiveEventStates(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise success.');
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise result ' + JSON.stringify(res));
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates promise failed, because: ' + err.code);
});
```
## bundleState.queryBundleActiveEventStates<sup>9+</sup>
queryBundleActiveEventStates(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleActiveEventState&gt;&gt;): void
Queries statistics about system events (hibernation, wakeup, unlocking, and screen locking) that occur between the specified start time and end time. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
| begin | number | Yes | Start time. |
| end | number | Yes | End time. |
| callback | AsyncCallback&lt;Array&lt;[BundleActiveEventState](#bundleactiveeventstate9)&gt;&gt; | Yes | Callback used to return the result. |
**Example**
```js
bundleState.queryBundleActiveEventStates(0, 20000000000000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback success.');
console.log('BUNDLE_ACTIVE queryBundleActiveEventStates callback result ' + JSON.stringify(res));
}
});
```
## bundleState.queryAppNotificationNumber<sup>9+</sup>
queryAppNotificationNumber(begin: number, end: number): Promise&lt;Array&lt;BundleActiveEventState&gt;&gt;
Queries the number of notifications from all applications based on the specified start time and end time. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.|
| end | number | Yes | End time.|
**Return value**
| Type | Description |
| ---------------------------------------- | ---------------------------------------- |
| Promise&lt;Array&lt;[BundleActiveEventState](#bundleactiveeventstate9)&gt;&gt; | Promise used to return the result. |
**Example**
```js
bundleState.queryAppNotificationNumber(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise success.');
console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise result ' + JSON.stringify(res));
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryAppNotificationNumber promise failed, because: ' + err.code);
});
```
## bundleState.queryAppNotificationNumber<sup>9+</sup>
queryAppNotificationNumber(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleActiveEventState&gt;&gt;): void
Queries the number of notifications from all applications based on the specified start time and end time. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
| begin | number | Yes | Start time. |
| end | number | Yes | End time. |
| callback | AsyncCallback&lt;Array&lt;[BundleActiveEventState](#bundleactiveeventstate9)&gt;&gt; | Yes | Callback used to return the result. |
**Example**
```js
bundleState.queryAppNotificationNumber(0, 20000000000000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryAppNotificationNumberCallBack callback failed, because: ' + err.code);
} else {
console.log('BUNDLE_ACTIVE queryAppNotificationNumberCallBack callback success.');
console.log('BUNDLE_ACTIVE queryAppNotificationNumberCallBack callback result ' + JSON.stringify(res));
}
});
```
## BundleActiveModuleInfo<sup>9+</sup>
Provides the information about the FA usage.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
| Name | Type | Mandatory | Description |
| -------------------- | ---------------------------------------- | ---- | ----------------------------- |
| deviceId | string | No | ID of the device to which the FA belongs. |
| bundleName | string | Yes | Name of the application bundle to which the FA belongs. |
| moduleName | string | Yes | Name of the module to which the FA belongs. |
| abilityName | string | No | **MainAbility** name of the FA. |
| appLabelId | number | No | Application label ID of the FA. |
| labelId | number | No | Label ID of the module to which the FA belongs. |
| descriptionId | number | No | Description ID of the application to which the FA belongs. |
| abilityLableId | number | No | **MainAbility** label ID of the FA. |
| abilityDescriptionId | number | No | **MainAbility** description ID of the FA.|
| abilityIconId | number | No | **MainAbility** icon ID of the FA. |
| launchedCount | number | Yes | Number of FA startup times. |
| lastModuleUsedTime | number | Yes | Last time when the FA was used. |
| formRecords | Array&lt;[BundleActiveFormInfo](#bundleactiveforminfo9)&gt; | Yes | Array of widget usage records in the FA. |
## BundleActiveFormInfo<sup>9+</sup>
Provides the FA widget usage information.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
| Name | Type | Mandatory | Description |
| ---------------- | ------ | ---- | ----------- |
| formName | string | Yes | Widget name. |
| formDimension | number | Yes | Widget dimensions. |
| formId | number | Yes | Widget ID. |
| formLastUsedTime | number | Yes | Last time when the widget was clicked.|
| count | number | Yes | Number of clicks on the widget. |
## BundleActiveGroupCallbackInfo<sup>9+</sup>
Provides the application group changes returned through a callback.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
| Name | Type | Mandatory| Description |
| ---------------- | ------ | ---- | ---------------- |
| appUsageOldGroup | number | Yes | Application group before the change.|
| appUsageNewGroup | number | Yes | Application group after the change.|
| userId | number | Yes | User ID. |
| changeReason | number | Yes | Reason for the group change. |
| bundleName | string | Yes | Bundle name of an application. |
## BundleStateInfo ## BundleStateInfo
Provides the usage duration information of applications. Provides the usage duration information of an application.
### Attributes ### Attributes
...@@ -1074,18 +446,20 @@ Provides the usage duration information of applications. ...@@ -1074,18 +446,20 @@ Provides the usage duration information of applications.
| bundleName | string | Yes | Bundle name of an application. | | bundleName | string | Yes | Bundle name of an application. |
| abilityPrevAccessTime | number | Yes | Last time when the application was used. | | abilityPrevAccessTime | number | Yes | Last time when the application was used. |
| abilityInFgTotalTime | number | Yes | Total time that the application runs in the foreground. | | abilityInFgTotalTime | number | Yes | Total time that the application runs in the foreground. |
| id | number | No | User ID.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | id | number | No | User ID.|
| abilityPrevSeenTime | number | No | Last time when the application was visible in the foreground.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | abilityPrevSeenTime | number | No | Last time when the application was visible in the foreground.|
| abilitySeenTotalTime | number | No | Total time that the application is visible in the foreground.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | abilitySeenTotalTime | number | No | Total time that the application is visible in the foreground.|
| fgAbilityAccessTotalTime | number | No | Total time that the application accesses the foreground.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | fgAbilityAccessTotalTime | number | No | Total time that the application accesses the foreground.|
| fgAbilityPrevAccessTime | number | No | Last time when the application accessed the foreground.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | fgAbilityPrevAccessTime | number | No | Last time when the application accessed the foreground.|
| infosBeginTime | number | No | Time logged in the first application usage record in the **BundleActiveInfo** object.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | infosBeginTime | number | No | Time logged in the first application usage record in the **BundleActiveInfo** object.|
| infosEndTime | number | No | Time logged in the last application usage record in the **BundleActiveInfo** object.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | infosEndTime | number | No | Time logged in the last application usage record in the **BundleActiveInfo** object.|
## BundleActiveState ## BundleActiveState
Provides information about an application event. Provides information about an application event.
Provides the usage duration information of applications.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App **System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
| Name | Type | Mandatory | Description | | Name | Type | Mandatory | Description |
...@@ -1093,9 +467,9 @@ Provides information about an application event. ...@@ -1093,9 +467,9 @@ Provides information about an application event.
| bundleName | string | Yes | Bundle name of an application. | | bundleName | string | Yes | Bundle name of an application. |
| stateType | number | Yes | Application event type. | | stateType | number | Yes | Application event type. |
| stateOccurredTime | number | Yes | Timestamp when the application event occurs. | | stateOccurredTime | number | Yes | Timestamp when the application event occurs. |
| appUsagePriorityGroup | number | No | Usage priority group of the application.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | appUsagePriorityGroup | number | No | Usage priority group of the application.|
| indexOfLink | string | No | Shortcut ID.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | indexOfLink | string | No | Shortcut ID.|
| nameOfClass | string | No | Class name.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| | nameOfClass | string | No | Class name.|
## BundleActiveInfoResponse ## BundleActiveInfoResponse
...@@ -1107,20 +481,6 @@ Provides the usage duration information of applications. ...@@ -1107,20 +481,6 @@ Provides the usage duration information of applications.
| ------------------------------ | ---------------------------------------- | ---- | -------------- | | ------------------------------ | ---------------------------------------- | ---- | -------------- |
| [key: string]: BundleStateInfo | [key: string]: [BundleStateInfo](#bundlestateinfo) | Yes | Usage duration information by application.| | [key: string]: BundleStateInfo | [key: string]: [BundleStateInfo](#bundlestateinfo) | Yes | Usage duration information by application.|
## BundleActiveEventState<sup>9+</sup>
Provides statistics about notifications and system events.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API and cannot be called by third-party applications.
| Name | Type | Mandatory | Description |
| ------- | ------ | ---- | ----------------- |
| name | string | Yes | Bundle name of the notification sending application or system event name. |
| eventId | number | Yes | Type of the notification or system event. |
| count | number | Yes | Number of application notifications or system event triggering times.|
## IntervalType ## IntervalType
Enumerates the interval types for querying the application usage duration. Enumerates the interval types for querying the application usage duration.
...@@ -1134,20 +494,3 @@ Enumerates the interval types for querying the application usage duration. ...@@ -1134,20 +494,3 @@ Enumerates the interval types for querying the application usage duration.
| BY_WEEKLY | 2 | The system obtains the application usage duration statistics in the specified time frame on a weekly basis. | | BY_WEEKLY | 2 | The system obtains the application usage duration statistics in the specified time frame on a weekly basis. |
| BY_MONTHLY | 3 | The system obtains the application usage duration statistics in the specified time frame on a monthly basis. | | BY_MONTHLY | 3 | The system obtains the application usage duration statistics in the specified time frame on a monthly basis. |
| BY_ANNUALLY | 4 | The system obtains the application usage duration statistics in the specified time frame on an annual basis. | | BY_ANNUALLY | 4 | The system obtains the application usage duration statistics in the specified time frame on an annual basis. |
## GroupType<sup>9+</sup>
Enumerates the application group types.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API and cannot be called by third-party applications.
| Name | Default Value | Description |
| ------------------ | ---- | ----------------- |
| ACTIVE_GROUP_ALIVE | 10 | Group of active applications. |
| ACTIVE_GROUP_DAILY | 20 | Group of frequently used applications that are not in the active state. |
| ACTIVE_GROUP_FIXED | 30 | Group of applications that are used periodically but not every day.|
| ACTIVE_GROUP_RARE | 40 | Group of rarely used applications. |
| ACTIVE_GROUP_LIMIT | 50 | Group of restricted applications. |
| ACTIVE_GROUP_NEVER | 60 | Group of applications that have been installed but never run. |
en/application-dev/reference/apis/js-apis-particleAbility.md
浏览文件 @ 49c181a2
...@@ -203,7 +203,7 @@ Requests a continuous task from the system. This API uses an asynchronous callba ...@@ -203,7 +203,7 @@ Requests a continuous task from the system. This API uses an asynchronous callba
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| id | number | Yes| Notification ID of a continuous task.| | id | number | Yes| Notification ID of a continuous task.|
| request | NotificationRequest | Yes| Notification parameter, which is used to display information in the notification bar.| | request | [NotificationRequest](js-apis-notification.md#notificationrequest) | Yes| Notification parameter, which is used to display information in the notification bar.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.| | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result.|
**Example** **Example**
...@@ -215,7 +215,7 @@ import wantAgent from '@ohos.wantAgent'; ...@@ -215,7 +215,7 @@ import wantAgent from '@ohos.wantAgent';
function callback(err, data) { function callback(err, data) {
if (err) { if (err) {
console.error("Operation failed Cause: " + err); console.error("Operation failed cause: " + JSON.stringify(err));
} else { } else {
console.info("Operation succeeded"); console.info("Operation succeeded");
} }
...@@ -267,7 +267,7 @@ Requests a continuous task from the system. This API uses a promise to return th ...@@ -267,7 +267,7 @@ Requests a continuous task from the system. This API uses a promise to return th
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| id | number | Yes| Notification ID of a continuous task.| | id | number | Yes| Notification ID of a continuous task.|
| request | NotificationRequest | Yes| Notification parameter, which is used to display information in the notification bar.| | request | [NotificationRequest](js-apis-notification.md#notificationrequest) | Yes| Notification parameter, which is used to display information in the notification bar.|
**Return value** **Return value**
...@@ -311,7 +311,7 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { ...@@ -311,7 +311,7 @@ wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
particleAbility.startBackgroundRunning(id, request).then(() => { particleAbility.startBackgroundRunning(id, request).then(() => {
console.info("Operation succeeded"); console.info("Operation succeeded");
}).catch((err) => { }).catch((err) => {
console.error("Operation failed Cause: " + err); console.error("Operation failed cause: " + JSON.stringify(err));
}); });
}); });
...@@ -338,7 +338,7 @@ import particleAbility from '@ohos.ability.particleAbility'; ...@@ -338,7 +338,7 @@ import particleAbility from '@ohos.ability.particleAbility';
function callback(err, data) { function callback(err, data) {
if (err) { if (err) {
console.error("Operation failed Cause: " + err); console.error("Operation failed cause: " + JSON.stringify(err));
} else { } else {
console.info("Operation succeeded"); console.info("Operation succeeded");
} }
...@@ -370,7 +370,7 @@ import particleAbility from '@ohos.ability.particleAbility'; ...@@ -370,7 +370,7 @@ import particleAbility from '@ohos.ability.particleAbility';
particleAbility.cancelBackgroundRunning().then(() => { particleAbility.cancelBackgroundRunning().then(() => {
console.info("Operation succeeded"); console.info("Operation succeeded");
}).catch((err) => { }).catch((err) => {
console.error("Operation failed Cause: " + err); console.error("Operation failed cause: " + JSON.stringify(err));
}); });
``` ```
......
en/application-dev/reference/apis/js-apis-reminderAgent.md
浏览文件 @ 49c181a2
...@@ -6,12 +6,14 @@ You can set your application to use the reminder agent APIs to create scheduled ...@@ -6,12 +6,14 @@ You can set your application to use the reminder agent APIs to create scheduled
> **NOTE** > **NOTE**
> >
> This module is deprecated since API version 9. You are advised to use [@ohos.reminderAgentManager](js-apis-reminderAgentManager.md) instead.
>
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import ## Modules to Import
``` ```js
import reminderAgent from'@ohos.reminderAgent'; import reminderAgent from'@ohos.reminderAgent';
``` ```
...@@ -20,7 +22,7 @@ import reminderAgent from'@ohos.reminderAgent'; ...@@ -20,7 +22,7 @@ import reminderAgent from'@ohos.reminderAgent';
publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback&lt;number&gt;): void publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback&lt;number&gt;): void
Publishes a reminder through the reminder agent. This API uses an asynchronous callback to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8). Publishes a reminder through the reminder agent. This API uses an asynchronous callback to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8).
**Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER **Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER
...@@ -28,10 +30,10 @@ Publishes a reminder through the reminder agent. This API uses an asynchronous c ...@@ -28,10 +30,10 @@ Publishes a reminder through the reminder agent. This API uses an asynchronous c
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| reminderReq | [ReminderRequest](#reminderrequest) | Yes| Reminder to be published.| | reminderReq | [ReminderRequest](#reminderrequest) | Yes| Reminder to be published.|
| callback | AsyncCallback&lt;number&gt; | Yes| Asynchronous callback used to return the published reminder's ID.| | callback | AsyncCallback&lt;number&gt; | Yes| Asynchronous callback used to return the published reminder's ID.|
**Example** **Example**
```js ```js
...@@ -49,21 +51,21 @@ Publishes a reminder through the reminder agent. This API uses an asynchronous c ...@@ -49,21 +51,21 @@ Publishes a reminder through the reminder agent. This API uses an asynchronous c
publishReminder(reminderReq: ReminderRequest): Promise&lt;number&gt; publishReminder(reminderReq: ReminderRequest): Promise&lt;number&gt;
Publishes a reminder through the reminder agent. This API uses a promise to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8). Publishes a reminder through the reminder agent. This API uses a promise to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8).
**Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER **Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER
**System capability**: SystemCapability.Notification.ReminderAgent **System capability**: SystemCapability.Notification.ReminderAgent
**Parameters** **Parameters**
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| reminderReq | [ReminderRequest](#reminderrequest) | Yes| Reminder to be published.| | reminderReq | [ReminderRequest](#reminderrequest) | Yes| Reminder to be published.|
**Return value** **Return value**
| Type| Description| | Type| Description|
| -------- | -------- | | -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the published reminder's ID.| | Promise&lt;number&gt; | Promise used to return the published reminder's ID.|
**Example** **Example**
```js ```js
...@@ -89,7 +91,7 @@ Cancels the reminder with the specified ID. This API uses an asynchronous callba ...@@ -89,7 +91,7 @@ Cancels the reminder with the specified ID. This API uses an asynchronous callba
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| reminderId | number | Yes| ID of the reminder to cancel.| | reminderId | number | Yes| ID of the reminder to cancel. The value is obtained by calling [publishReminder](#reminderagentpublishreminder).|
| callback | AsyncCallback&lt;void&gt; | Yes| Asynchronous callback used to return the result.| | callback | AsyncCallback&lt;void&gt; | Yes| Asynchronous callback used to return the result.|
**Example** **Example**
...@@ -113,7 +115,7 @@ Cancels the reminder with the specified ID. This API uses a promise to return th ...@@ -113,7 +115,7 @@ Cancels the reminder with the specified ID. This API uses a promise to return th
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| reminderId | number | Yes| ID of the reminder to cancel.| | reminderId | number | Yes| ID of the reminder to cancel. The value is obtained by calling [publishReminder](#reminderagentpublishreminder).|
**Return value** **Return value**
...@@ -453,10 +455,10 @@ Defines the reminder to publish. ...@@ -453,10 +455,10 @@ Defines the reminder to publish.
| Name| Type| Mandatory| Description| | Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- | | -------- | -------- | -------- | -------- |
| reminderType | ReminderType | Yes| Type of the reminder.| | reminderType | [ReminderType](#remindertype) | Yes| Type of the reminder.|
| actionButton | [ActionButton?,&nbsp;ActionButton?] | No| Button displayed in the reminder notification. (The parameter is optional. Up to two buttons are supported.)| | actionButton | [ActionButton](#actionbutton) | No| Button displayed in the reminder notification. (The parameter is optional. Up to two buttons are supported.)|
| wantAgent | WantAgent | No| Information about the ability that is redirected to when the notification is clicked.| | wantAgent | [WantAgent](#wantagent) | No| Information about the ability that is redirected to when the notification is clicked.|
| maxScreenWantAgent | MaxScreenWantAgent | No| Information about the ability that is automatically started when the reminder arrives. If the device is in use, a notification will be displayed.| | maxScreenWantAgent | [MaxScreenWantAgent](#maxscreenwantagent) | No| Information about the ability that is automatically started when the reminder arrives. If the device is in use, a notification will be displayed.|
| ringDuration | number | No| Ringing duration.| | ringDuration | number | No| Ringing duration.|
| snoozeTimes | number | No| Number of reminder snooze times.| | snoozeTimes | number | No| Number of reminder snooze times.|
| timeInterval | number | No| Reminder snooze interval.| | timeInterval | number | No| Reminder snooze interval.|
......
en/application-dev/reference/apis/js-apis-reminderAgentManager.md 0 → 100644
浏览文件 @ 49c181a2
# reminderAgentManager
The **reminderAgentManager** module provides APIs for publishing scheduled reminders through the reminder agent.
You can set your application to use the reminder agent APIs to create scheduled reminders for countdown timers, calendar events, and alarm clocks. When the created reminders are published, the timing and pop-up notification functions of your application will be taken over by the reminder agent in the background when your application is frozen or exits.
> **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 reminderAgentManager from'@ohos.reminderAgentManager';
```
## reminderAgentManager.publishReminder
publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback&lt;number&gt;): void
Publishes a reminder through the reminder agent. This API uses an asynchronous callback to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8).
**Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| reminderReq | [ReminderRequest](#reminderrequest) | Yes| Reminder to be published.|
| callback | AsyncCallback&lt;number&gt; | Yes| Asynchronous callback used to return the published reminder's ID.|
**Error codes**
For details about the error codes, see [reminderAgentManager Error Codes](../errorcodes/errorcode-reminderAgentManager.md).
| ID | Error Message|
| --------- | ------- |
| 1700001 | Notification does not enable. |
| 1700002 | The number of reminders exceeds the limit. |
**Example**
```js
let timer = {
reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,
triggerTimeInSeconds: 10
}
try {
reminderAgentManager.publishReminder(timer, (err, reminderId) => {
if (err) {
console.log("callback err code:" + err.code + " message:" + err.message);
} else {
console.log("callback, reminderId = " + reminderId);
}
});
} catch (error) {
console.log("publishReminder code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.publishReminder
publishReminder(reminderReq: ReminderRequest): Promise&lt;number&gt;
Publishes a reminder through the reminder agent. This API uses a promise to return the result. It can be called only when notification is enabled for the application through [Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8).
**Required permissions**: ohos.permission.PUBLISH_AGENT_REMINDER
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| reminderReq | [ReminderRequest](#reminderrequest) | Yes| Reminder to be published.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the published reminder's ID.|
**Error codes**
For details about the error codes, see [reminderAgentManager Error Codes](../errorcodes/errorcode-reminderAgentManager.md).
| ID | Error Message|
| --------- | ------- |
| 1700001 | Notification does not enable. |
| 1700002 | The number of reminders exceeds the limit. |
**Example**
```js
let timer = {
reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,
triggerTimeInSeconds: 10
}
try {
reminderAgentManager.publishReminder(timer).then((reminderId) => {
console.log("promise, reminderId = " + reminderId);
}).catch(err => {
console.log("promise err code:" + err.code + " message:" + err.message);
});
} catch (error) {
console.log("publishReminder code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.cancelReminder
cancelReminder(reminderId: number, callback: AsyncCallback&lt;void&gt;): void
Cancels the reminder with the specified ID. This API uses an asynchronous callback to return the cancellation result.
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| reminderId | number | Yes| ID of the reminder to cancel.|
| callback | AsyncCallback&lt;void&gt; | Yes| Asynchronous callback used to return the result.|
**Error codes**
For details about the error codes, see [reminderAgentManager Error Codes](../errorcodes/errorcode-reminderAgentManager.md).
| ID | Error Message|
| --------- | ------- |
| 1700003 | The reminder does not exist. |
| 1700004 | The package name does not exist. |
**Example**
```js
try {
reminderAgentManager.cancelReminder(1, (err, data) => {
if (err) {
console.log("callback err code:" + err.code + " message:" + err.message);
} else {
console.log("cancelReminder callback");
}
});
} catch (error) {
console.log("cancelReminder code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.cancelReminder
cancelReminder(reminderId: number): Promise&lt;void&gt;
Cancels the reminder with the specified ID. This API uses a promise to return the cancellation result.
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| reminderId | number | Yes| ID of the reminder to cancel.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
**Error codes**
For details about the error codes, see [reminderAgentManager Error Codes](../errorcodes/errorcode-reminderAgentManager.md).
| ID | Error Message|
| --------- | ------- |
| 1700003 | The reminder does not exist. |
| 1700004 | The package name does not exist. |
**Example**
```js
try {
reminderAgentManager.cancelReminder(1).then(() => {
console.log("cancelReminder promise");
}).catch(err => {
console.log("promise err code:" + err.code + " message:" + err.message);
});
} catch (error) {
console.log("cancelReminder code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.getValidReminders
getValidReminders(callback: AsyncCallback&lt;Array&lt;ReminderRequest&gt;&gt;): void
Obtains all valid (not yet expired) reminders set by the current application. This API uses an asynchronous callback to return the reminders.
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;Array&lt;[ReminderRequest](#reminderrequest)&gt;&gt; | Yes| Asynchronous callback used to return an array of all valid reminders set by the current application.|
**Error codes**
For details about the error codes, see [reminderAgentManager Error Codes](../errorcodes/errorcode-reminderAgentManager.md).
| ID | Error Message|
| --------- | ------- |
| 1700004 | The package name does not exist. |
**Example**
```js
try {
reminderAgentManager.getValidReminders((err, reminders) => {
if (err) {
console.log("callback err code:" + err.code + " message:" + err.message);
} else {
console.log("callback, getValidReminders length = " + reminders.length);
for (let i = 0; i < reminders.length; i++) {
console.log("getValidReminders = " + reminders[i]);
console.log("getValidReminders, reminderType = " + reminders[i].reminderType);
for (let j = 0; j < reminders[i].actionButton.length; j++) {
console.log("getValidReminders, actionButton.title = " + reminders[i].actionButton[j].title);
console.log("getValidReminders, actionButton.type = " + reminders[i].actionButton[j].type);
}
console.log("getValidReminders, wantAgent.pkgName = " + reminders[i].wantAgent.pkgName);
console.log("getValidReminders, wantAgent.abilityName = " + reminders[i].wantAgent.abilityName);
console.log("getValidReminders, maxScreenWantAgent.pkgName = " + reminders[i].maxScreenWantAgent.pkgName);
console.log("getValidReminders, maxScreenWantAgent.abilityName = " + reminders[i].maxScreenWantAgent.abilityName);
console.log("getValidReminders, ringDuration = " + reminders[i].ringDuration);
console.log("getValidReminders, snoozeTimes = " + reminders[i].snoozeTimes);
console.log("getValidReminders, timeInterval = " + reminders[i].timeInterval);
console.log("getValidReminders, title = " + reminders[i].title);
console.log("getValidReminders, content = " + reminders[i].content);
console.log("getValidReminders, expiredContent = " + reminders[i].expiredContent);
console.log("getValidReminders, snoozeContent = " + reminders[i].snoozeContent);
console.log("getValidReminders, notificationId = " + reminders[i].notificationId);
console.log("getValidReminders, slotType = " + reminders[i].slotType);
}
}
})
} catch (error) {
console.log("getValidReminders code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.getValidReminders
getValidReminders(): Promise&lt;Array&lt;ReminderRequest&gt;&gt;
Obtains all valid (not yet expired) reminders set by the current application. This API uses a promise to return the reminders.
**System capability**: SystemCapability.Notification.ReminderAgent
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;Array&lt;[ReminderRequest](#reminderrequest)&gt;&gt; | Promise used to return an array of all valid reminders set by the current application.|
**Error codes**
For details about the error codes, see [reminderAgentManager Error Codes](../errorcodes/errorcode-reminderAgentManager.md).
| ID | Error Message|
| --------- | ------- |
| 1700004 | The package name does not exist. |
**Example**
```js
try {
reminderAgentManager.getValidReminders().then((reminders) => {
console.log("promise, getValidReminders length = " + reminders.length);
for (let i = 0; i < reminders.length; i++) {
console.log("getValidReminders = " + reminders[i]);
console.log("getValidReminders, reminderType = " + reminders[i].reminderType);
for (let j = 0; j < reminders[i].actionButton.length; j++) {
console.log("getValidReminders, actionButton.title = " + reminders[i].actionButton[j].title);
console.log("getValidReminders, actionButton.type = " + reminders[i].actionButton[j].type);
}
console.log("getValidReminders, wantAgent.pkgName = " + reminders[i].wantAgent.pkgName);
console.log("getValidReminders, wantAgent.abilityName = " + reminders[i].wantAgent.abilityName);
console.log("getValidReminders, maxScreenWantAgent.pkgName = " + reminders[i].maxScreenWantAgent.pkgName);
console.log("getValidReminders, maxScreenWantAgent.abilityName = " + reminders[i].maxScreenWantAgent.abilityName);
console.log("getValidReminders, ringDuration = " + reminders[i].ringDuration);
console.log("getValidReminders, snoozeTimes = " + reminders[i].snoozeTimes);
console.log("getValidReminders, timeInterval = " + reminders[i].timeInterval);
console.log("getValidReminders, title = " + reminders[i].title);
console.log("getValidReminders, content = " + reminders[i].content);
console.log("getValidReminders, expiredContent = " + reminders[i].expiredContent);
console.log("getValidReminders, snoozeContent = " + reminders[i].snoozeContent);
console.log("getValidReminders, notificationId = " + reminders[i].notificationId);
console.log("getValidReminders, slotType = " + reminders[i].slotType);
}
}).catch(err => {
console.log("promise err code:" + err.code + " message:" + err.message);
});
} catch (error) {
console.log("getValidReminders code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.cancelAllReminders
cancelAllReminders(callback: AsyncCallback&lt;void&gt;): void
Cancels all reminders set by the current application. This API uses an asynchronous callback to return the cancellation result.
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;void&gt; | Yes| Asynchronous callback used to return the result.|
**Error codes**
For details about the error codes, see [reminderAgentManager Error Codes](../errorcodes/errorcode-reminderAgentManager.md).
| ID | Error Message|
| --------- | ------- |
| 1700004 | The package name does not exist. |
**Example**
```js
try {
reminderAgentManager.cancelAllReminders((err, data) =>{
if (err) {
console.log("callback err code:" + err.code + " message:" + err.message);
} else {
console.log("cancelAllReminders callback")
}
})
} catch (error) {
console.log("cancelAllReminders code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.cancelAllReminders
cancelAllReminders(): Promise&lt;void&gt;
Cancels all reminders set by the current application. This API uses a promise to return the cancellation result.
**System capability**: SystemCapability.Notification.ReminderAgent
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
**Error codes**
For details about the error codes, see [reminderAgentManager Error Codes](../errorcodes/errorcode-reminderAgentManager.md).
| ID | Error Message|
| --------- | ------- |
| 1700004 | The package name does not exist. |
**Example**
```js
try {
reminderAgentManager.cancelAllReminders().then(() => {
console.log("cancelAllReminders promise")
}).catch(err => {
console.log("promise err code:" + err.code + " message:" + err.message);
});
} catch (error) {
console.log("cancelAllReminders code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.addNotificationSlot
addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback&lt;void&gt;): void
Adds a notification slot. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| slot | [NotificationSlot](js-apis-notification.md#notificationslot) | Yes| Notification slot, whose type can be set.|
| callback | AsyncCallback&lt;void&gt; | Yes| Asynchronous callback used to return the result.|
**Example**
```js
import notification from '@ohos.notification'
let mySlot = {
type: notification.SlotType.SOCIAL_COMMUNICATION
}
try {
reminderAgentManager.addNotificationSlot(mySlot, (err, data) => {
if (err) {
console.log("callback err code:" + err.code + " message:" + err.message);
} else {
console.log("addNotificationSlot callback");
}
});
} catch (error) {
console.log("addNotificationSlot code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.addNotificationSlot
addNotificationSlot(slot: NotificationSlot): Promise&lt;void&gt;
Adds a notification slot. This API uses a promise to return the result.
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| slot | [NotificationSlot](js-apis-notification.md#notificationslot) | Yes| Notification slot, whose type can be set.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
```js
import notification from '@ohos.notification'
let mySlot = {
type: notification.SlotType.SOCIAL_COMMUNICATION
}
try {
reminderAgentManager.addNotificationSlot(mySlot).then(() => {
console.log("addNotificationSlot promise");
}).catch(err => {
console.log("promise err code:" + err.code + " message:" + err.message);
});
} catch (error) {
console.log("addNotificationSlot code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.removeNotificationSlot
removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback&lt;void&gt;): void
Removes a notification slot of a specified type. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| slotType | [notification.SlotType](js-apis-notification.md#slottype) | Yes| Type of the notification slot to remove.|
| callback | AsyncCallback&lt;void&gt; | Yes| Asynchronous callback used to return the result.|
**Example**
```js
import notification from '@ohos.notification'
try {
reminderAgentManager.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION, (err, data) => {
if (err) {
console.log("callback err code:" + err.code + " message:" + err.message);
} else {
console.log("removeNotificationSlot callback");
}
});
} catch (error) {
console.log("removeNotificationSlot code:" + error.code + " message:" + error.message);
};
```
## reminderAgentManager.removeNotificationSlot
removeNotificationSlot(slotType: notification.SlotType): Promise&lt;void&gt;
Removes a notification slot of a specified type. This API uses a promise to return the result.
**System capability**: SystemCapability.Notification.ReminderAgent
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| slotType | [notification.SlotType](js-apis-notification.md#slottype) | Yes| Type of the notification slot to remove.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
**Example**
```js
import notification from '@ohos.notification'
try {
reminderAgentManager.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION).then(() => {
console.log("removeNotificationSlot promise");
}).catch(err => {
console.log("promise err code:" + err.code + " message:" + err.message);
});
} catch (error) {
console.log("removeNotificationSlot code:" + error.code + " message:" + error.message);
};
```
## ActionButtonType
Enumerates button types.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Default Value| Description|
| -------- | -------- | -------- |
| ACTION_BUTTON_TYPE_CLOSE | 0 | Button for closing the reminder.|
| ACTION_BUTTON_TYPE_SNOOZE | 1 | Button for snoozing the reminder.|
## ReminderType
Enumerates reminder types.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Default Value| Description|
| -------- | -------- | -------- |
| REMINDER_TYPE_TIMER | 0 | Countdown reminder.|
| REMINDER_TYPE_CALENDAR | 1 | Calendar reminder.|
| REMINDER_TYPE_ALARM | 2 | Alarm reminder.|
## ActionButton
Defines a button displayed in the reminder notification.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| title | string | Yes| Text on the button.|
| type | [ActionButtonType](#actionbuttontype) | Yes| Button type.|
## WantAgent
Sets the package and ability that are redirected to when the reminder notification is clicked.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| pkgName | string | Yes| Name of the package that is redirected to when the reminder notification is clicked.|
| abilityName | string | Yes| Name of the ability that is redirected to when the reminder notification is clicked.|
## MaxScreenWantAgent
Provides the information about the target package and ability to start automatically when the reminder is displayed in full-screen mode. This API is reserved.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| pkgName | string | Yes| Name of the package that is automatically started when the reminder arrives and the device is not in use.|
| abilityName | string | Yes| Name of the ability that is automatically started when the reminder arrives and the device is not in use.|
## ReminderRequest
Defines the reminder to publish.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| reminderType | [ReminderType](#remindertype) | Yes| Type of the reminder.|
| actionButton | [ActionButton](#actionbutton) | No| Button displayed in the reminder notification. (The parameter is optional. Up to two buttons are supported.)|
| wantAgent | [WantAgent](#wantagent) | No| Information about the ability that is redirected to when the notification is clicked.|
| maxScreenWantAgent | [MaxScreenWantAgent](#maxscreenwantagent) | No| Information about the ability that is automatically started when the reminder arrives. If the device is in use, a notification will be displayed.|
| ringDuration | number | No| Ringing duration, in seconds.|
| snoozeTimes | number | No| Number of reminder snooze times.|
| timeInterval | number | No| Reminder snooze interval, in seconds.|
| title | string | No| Reminder title.|
| content | string | No| Reminder content.|
| expiredContent | string | No| Content to be displayed after the reminder expires.|
| snoozeContent | string | No| Content to be displayed when the reminder is snoozing.|
| notificationId | number | No| Notification ID used by the reminder. If there are reminders with the same notification ID, the later one will overwrite the earlier one.|
| slotType | [notification.SlotType](js-apis-notification.md#slottype) | No| Type of the slot used by the reminder.|
## ReminderRequestCalendar
ReminderRequestCalendar extends ReminderRequest
Defines a reminder for a calendar event.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| dateTime | [LocalDateTime](#localdatetime) | Yes| Reminder time.|
| repeatMonths | Array&lt;number&gt; | No| Month in which the reminder repeats.|
| repeatDays | Array&lt;number&gt; | No| Date on which the reminder repeats.|
## ReminderRequestAlarm
ReminderRequestAlarm extends ReminderRequest
Defines a reminder for an alarm.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| hour | number | Yes| Hour portion of the reminder time.|
| minute | number | Yes| Minute portion of the reminder time.|
| daysOfWeek | Array&lt;number&gt; | No| Days of a week when the reminder repeats.|
## ReminderRequestTimer
ReminderRequestTimer extends ReminderRequest
Defines a reminder for a scheduled timer.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| triggerTimeInSeconds | number | Yes| Number of seconds in the countdown timer.|
## LocalDateTime
Sets the time information for a calendar reminder.
**System capability**: SystemCapability.Notification.ReminderAgent
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| year | number | Yes| Year.|
| month | number | Yes| Month.|
| day | number | Yes| Date.|
| hour | number | Yes| Hour.|
| minute | number | Yes| Minute.|
| second | number | No| Second.|
en/application-dev/reference/apis/js-apis-resourceschedule-backgroundTaskManager.md 0 → 100644
浏览文件 @ 49c181a2
# Background Task Management
The **BackgroundTaskManager** module provides APIs to manage background tasks.
If a service needs to be continued when the application or service module is running in the background (not visible to users), the application or service module can request a transient task to delay the suspension or a continuous task to prevent the suspension.
If an application has a task that needs to be continued when the application is switched to the background and can be completed within a short period of time, the application can request a transient task. For example, if a user chooses to clear junk files in the **Files** application and exits the application, the application can request a transient task to complete the cleanup.
If an application has a service that can be intuitively perceived by users and needs to run in the background for a long period of time (for example, music playback in the background), the application can request a continuous task.
If a privileged system application needs to use certain system resources (for example, it wants to receive common events when suspended), it can request efficiency resources.
> **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
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
```
## backgroundTaskManager.requestSuspendDelay
requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): DelaySuspendInfo
Requests delayed suspension after the application switches to the background.
The default duration of delayed suspension is 3 minutes when the battery level is higher than or equal to the broadcast low battery level and 1 minute when the battery level is lower than the broadcast low battery level.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | -------------------- | ---- | ------------------------------ |
| reason | string | Yes | Reason for delayed transition to the suspended state. |
| callback | Callback&lt;void&gt; | Yes | Invoked when a delay is about to time out. Generally, this callback is used to notify the application 6 seconds before the delay times out.|
**Return value**
| Type | Description |
| ------------------------------------- | --------- |
| [DelaySuspendInfo](#delaysuspendinfo) | Information about the suspension delay.|
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 9900001 | Caller information verification failed for a transient task. |
| 9900002 | Transient task verification failed. |
**Example**
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let myReason = 'test requestSuspendDelay';
try {
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
})
var id = delayInfo.requestId;
var time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);
} catch (error) {
console.error(`requestSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.getRemainingDelayTime:callback
getRemainingDelayTime(requestId: number, callback: AsyncCallback&lt;number&gt;): void
Obtains the remaining duration before the application is suspended. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**Parameters**
| Name | Type | Mandatory | Description |
| --------- | --------------------------- | ---- | ---------------------------------------- |
| requestId | number | Yes | ID of the suspension delay request. |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the remaining duration before the application is suspended, in milliseconds.|
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 9900001 | Caller information verification failed for a transient task. |
| 9900002 | Transient task verification failed. |
**Example**
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let id = 1;
try {
backgroundTaskManager.getRemainingDelayTime(id, (error, res) => {
if(error) {
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
} else {
console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}
})
} catch (error) {
console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.getRemainingDelayTime:promise
getRemainingDelayTime(requestId: number): Promise&lt;number&gt;
Obtains the remaining duration before the application is suspended. This API uses a promise to return the result.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**Parameters**
| Name | Type | Mandatory | Description |
| --------- | ------ | ---- | ---------- |
| requestId | number | Yes | ID of the suspension delay request.|
**Return value**
| Type | Description |
| --------------------- | ---------------------------------------- |
| Promise&lt;number&gt; | Promise used to return the remaining duration before the application is suspended, in milliseconds.|
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 9900001 | Caller information verification failed for a transient task. |
| 9900002 | Transient task verification failed. |
**Example**
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let id = 1;
try {
backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( error => {
console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
})
} catch (error) {
console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.cancelSuspendDelay
cancelSuspendDelay(requestId: number): void
Cancels the suspension delay.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
**Parameters**
| Name | Type | Mandatory | Description |
| --------- | ------ | ---- | ---------- |
| requestId | number | Yes | ID of the suspension delay request.|
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 9900001 | Caller information verification failed for a transient task. |
| 9900002 | Transient task verification failed. |
**Example**
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let id = 1;
try {
backgroundTaskManager.cancelSuspendDelay(id);
} catch (error) {
console.error(`cancelSuspendDelay failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.startBackgroundRunning:callback
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback&lt;void&gt;): void
Requests a continuous task from the system. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**Parameters**
| Name | Type | Mandatory | Description |
| --------- | ---------------------------------- | ---- | ---------------------------------------- |
| context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).|
| bgMode | [BackgroundMode](#backgroundmode) | Yes | Background mode requested. |
| wantAgent | [WantAgent](js-apis-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 9800005 | Continuous task verification failed. |
| 9800006 | Notification verification failed. |
| 9800007 | Task storage failed. |
**Example**
```js
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent';
function callback(error, data) {
if (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
} else {
console.info("Operation startBackgroundRunning succeeded");
}
}
export default class MainAbility extends Ability {
onCreate(want, launchParam) {
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
try {
backgroundTaskManager.startBackgroundRunning(this.context,
backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback)
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
});
}
};
```
## backgroundTaskManager.startBackgroundRunning:promise
startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise&lt;void&gt;
Requests a continuous task from the system. This API uses a promise to return the result.
**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**Parameters**
| Name | Type | Mandatory | Description |
| --------- | ---------------------------------- | ---- | ---------------------------------------- |
| context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).|
| bgMode | [BackgroundMode](#backgroundmode) | Yes | Background mode requested. |
| wantAgent | [WantAgent](js-apis-wantAgent.md) | Yes | Notification parameter, which is used to specify the target page that is redirected to when a continuous task notification is clicked. |
**Return value**
| Type | Description |
| -------------- | ---------------- |
| Promise\<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 9800005 | Continuous task verification failed. |
| 9800006 | Notification verification failed. |
| 9800007 | Task storage failed. |
**Example**
```js
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent';
export default class MainAbility extends Ability {
onCreate(want, launchParam) {
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
try {
backgroundTaskManager.startBackgroundRunning(this.context,
backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((error) => {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
});
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
});
}
};
```
## backgroundTaskManager.stopBackgroundRunning:callback
stopBackgroundRunning(context: Context, callback: AsyncCallback&lt;void&gt;): void
Requests to cancel a continuous task. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------------------------- | ---- | ---------------------------------------- |
| context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 9800005 | Continuous task verification failed. |
| 9800006 | Notification verification failed. |
| 9800007 | Task storage failed. |
**Example**
```js
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
function callback(error, data) {
if (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
} else {
console.info("Operation stopBackgroundRunning succeeded");
}
}
export default class MainAbility extends Ability {
onCreate(want, launchParam) {
try {
backgroundTaskManager.stopBackgroundRunning(this.context, callback);
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
}
};
```
## backgroundTaskManager.stopBackgroundRunning:promise
stopBackgroundRunning(context: Context): Promise&lt;void&gt;
Requests to cancel a continuous task. This API uses a promise to return the result.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ------- | ---- | ---------------------------------------- |
| context | Context | Yes | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).|
**Return value**
| Type | Description |
| -------------- | ---------------- |
| Promise\<void> | Promise used to return the result.|
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 9800005 | Continuous task verification failed. |
| 9800006 | Notification verification failed. |
| 9800007 | Task storage failed. |
**Example**
```js
import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
export default class MainAbility extends Ability {
onCreate(want, launchParam) {
try {
backgroundTaskManager.stopBackgroundRunning(this.context).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((error) => {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
});
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
}
};
```
## backgroundTaskManager.applyEfficiencyResources
applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest)): void
Requests efficiency resources from the system.
A process and its application can request the same type of resources at the same time, for example, CPU resources. When the application releases the resources, the same type of resources requested by the process are also released.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ------- | ------- | ---- | ---------------------------------------- |
| request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest) | Yes | Necessary information carried in the request, including the resource type and timeout interval. For details, see [EfficiencyResourcesRequest](#efficiencyresourcesrequest).|
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 18700001 | Caller information verification failed when applying for efficiency resources. |
**Example**
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
let request = {
resourceTypes: backgroundTaskManager.ResourceType.CPU,
isApply: true,
timeOut: 0,
reason: "apply",
isPersist: true,
isProcess: false,
};
try {
backgroundTaskManager.applyEfficiencyResources(request);
console.info("applyEfficiencyResources success. ");
} catch (error) {
console.error(`applyEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
```
## backgroundTaskManager.resetAllEfficiencyResources
resetAllEfficiencyResources(): void
Releases all resources that have been requested.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**System API**: This is a system API.
**Error codes**
For details about the error codes, see [backgroundTaskManager Error Codes](../errorcodes/errorcode-backgroundTaskMgr.md).
| ID | Error Message |
| ---- | --------------------- |
| 9800001 | Memory operation failed. |
| 9800002 | Parcel operation failed. |
| 9800003 | IPC failed. | |
| 9800004 | System service operation failed. |
| 18700001 | Caller information verification failed when applying for efficiency resources. |
**Example**
```js
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
try {
backgroundTaskManager.resetAllEfficiencyResources();
} catch (error) {
console.error(`resetAllEfficiencyResources failed. code is ${error.code} message is ${error.message}`);
}
```
## DelaySuspendInfo
Provides the information about the suspension delay.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask
| Name | Type | Mandatory | Description |
| --------------- | ------ | ---- | ---------------------------------------- |
| requestId | number | Yes | ID of the suspension delay request. |
| actualDelayTime | number | Yes | Actual suspension delay duration of the application, in milliseconds.<br>The default duration is 180000 when the battery level is higher than or equal to the broadcast low battery level and 60000 when the battery level is lower than the broadcast low battery level.|
## BackgroundMode
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask
| Name | Value | Description |
| ----------------------- | ---- | --------------------- |
| DATA_TRANSFER | 1 | Data transfer. |
| AUDIO_PLAYBACK | 2 | Audio playback. |
| AUDIO_RECORDING | 3 | Audio recording. |
| LOCATION | 4 | Positioning and navigation. |
| BLUETOOTH_INTERACTION | 5 | Bluetooth-related task. |
| MULTI_DEVICE_CONNECTION | 6 | Multi-device connection. |
| WIFI_INTERACTION | 7 | WLAN-related (system API).|
| VOIP | 8 | Audio and video calls (system API). |
| TASK_KEEPING | 9 | Computing task (effective only for specific devices). |
## EfficiencyResourcesRequest
Describes the parameters for requesting efficiency resources.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**System API**: This is a system API.
| Name | Type | Mandatory | Description |
| --------------- | ------ | ---- | ---------------------------------------- |
| resourceTypes | number | Yes | Type of the resource to request. |
| isApply | boolean | Yes | Whether the request is used to apply for resources. The value **true** means that the request is used to apply for resources, and **false** means that the request is used to release resources. |
| timeOut | number | Yes | Duration for which the resource will be used, in milliseconds. |
| isPersist | boolean | No | Whether the resource is permanently held. If the value is **true**, **timeOut** is invalid. |
| isProcess | boolean | No | Whether the request is initiated by a process. The value **true** means that the request is initiated by a process, and **false** means that the request is initiated by an application. |
| reason | string | Yes | Reason for requesting the resource. |
## ResourceType
Enumerates the efficiency resource types.
**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply
**System API**: This is a system API.
| Name | Description |
| ----------------------- | --------------------- |
| CPU | CPU resources, which prevent the application from being suspended. |
| COMMON_EVENT | A type of software resources, which prevent common events from being proxied when the application is suspended. |
| TIMER | A type of software resources, which prevent timers from being proxied when the application is suspended. |
| WORK_SCHEDULER | WORK_SCHEDULER resources, which ensure that the application has more time to execute the task. |
| BLUETOOTH | A type of hardware resources, which prevent Bluetooth resources from being proxied when the application is suspended. |
| GPS | A type of hardware resources, which prevent GPS resources from being proxied when the application is suspended. |
| AUDIO | A type of hardware resources, which prevent audio resources from being proxied when the application is suspended.|
en/application-dev/reference/apis/js-apis-resourceschedule-deviceUsageStatistics.md 0 → 100644
浏览文件 @ 49c181a2
# Device Usage Statistics
This module provides APIs for collecting statistics on device usage.
System applications can call these APIs to implement the following features:
- Query the usage duration in different time segments, events (foreground, background, start and end of continuous tasks), and the number of notifications, on a per application basis.
- Query statistics about system events (sleep, wakeup, unlock, and screen lock).
- Query the bundle group information of applications, including the invoking application itself.
- Query the idle status of applications, including the invoking application itself.
- Set the bundle group for other applications.
- Register and deregister the callback for application group changes.
Third-party applications can call these APIs to implement the following features:
- Query the idle status of the invoking application itself.
- Query the bundle group information of the invoking application itself.
- Query the events of the invoking application itself.
> **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 usageStatistics from '@ohos.resourceschedule.usageStatistics'
```
## usageStatistics.isIdleState
isIdleState(bundleName: string, callback: AsyncCallback&lt;boolean&gt;): void
Checks whether the application specified by **bundleName** is in the idle state. This API uses an asynchronous callback to return the result. A third-party application can only check the idle status of itself.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ---------------------------- | ---- | ---------------------------------------- |
| bundleName | string | Yes | Bundle name of the application. |
| callback | AsyncCallback&lt;boolean&gt; | Yes | Callback used to return the result. If the specified **bundleName** is valid, the idle state of the application is returned; otherwise, **null** is returned.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
**Example**
```js
try{
usageStatistics.isIdleState("com.ohos.camera", (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE isIdleState callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res));
}
});
} catch(error) {
console.log('BUNDLE_ACTIVE isIdleState throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.isIdleState
isIdleState(bundleName: string): Promise&lt;boolean&gt;
Checks whether the application specified by **bundleName** is in the idle state. This API uses a promise to return the result. A third-party application can only check the idle status of itself.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ------ | ---- | -------------- |
| bundleName | string | Yes | Bundle name of the application.|
**Return value**
| Type | Description |
| ---------------------- | ---------------------------------------- |
| Promise&lt;boolean&gt; | Promise used to return the result. If the specified **bundleName** is valid, the idle state of the application is returned; otherwise, **null** is returned.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
**Example**
```js
try{
usageStatistics.isIdleState("com.ohos.camera").then( res => {
console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res));
}).catch( err => {
console.log('BUNDLE_ACTIVE isIdleState promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE isIdleState throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryAppGroup
queryAppGroup(): Promise&lt;number&gt;
Queries the group of this application. This API uses a promise to return the result.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**Return value**
| Type | Description |
| --------------- | --------------------------- |
| Promise&lt;number&gt; | Promise used to return the group.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000005 | Application is not installed. |
| 10000006 | Get application info failed. |
| 10100002 | Get Application group info failed. |
**Example**
```javascript
try{
usageStatistics.queryAppGroup().then( res => {
console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch( err => {
console.log('BUNDLE_ACTIVE queryAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryAppGroup
queryAppGroup(callback: AsyncCallback&lt;number&gt;): void
Queries the group of this application. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | --------------------- | ---- | -------------------------- |
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the group.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000005 | Application is not installed. |
| 10000006 | Get application info failed. |
| 10100002 | Get Application group info failed. |
**Example**
```javascript
try{
usageStatistics.queryAppGroup((err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryBundleStatsInfos
queryBundleStatsInfos(begin: number, end: number, callback: AsyncCallback&lt;BundleStatsMap&gt;): void
Queries the application usage duration statistics based on the specified start time and end time. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------------------------------------- |
| begin | number | Yes | Start time. |
| end | number | Yes | End time. |
| callback | AsyncCallback&lt;[BundleStatsMap](#bundlestatsmap)&gt; | Yes | Callback used to return the application usage duration statistics.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryBundleStatsInfos(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback success.');
let i = 1;
for(let key in res){
console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback number : ' + i);
console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback result ' + JSON.stringify(res[key]));
i++;
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryBundleStatsInfos
queryBundleStatsInfos(begin: number, end: number): Promise&lt;BundleStatsMap&gt;
Queries the application usage duration statistics based on the specified start time and end time. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.|
| end | number | Yes | End time.|
**Return value**
| Type | Description |
| ---------------------------------------- | -------------------------------------- |
| Promise&lt;[BundleStatsMap](#bundlestatsmap)&gt; | Promise used to return the application usage duration statistics.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryBundleStatsInfos(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise success.');
let i = 1;
for(let key in res){
console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise number : ' + i);
console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise result ' + JSON.stringify(res[key]));
i++;
}
}).catch( err => {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfos throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryBundleStatsInfoByInterval
queryBundleStatsInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleStatsInfo&gt;&gt;): void
Queries the application usage duration statistics in the specified time frame at the specified interval (daily, weekly, monthly, or annually). This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ---------------------------------------- | ---- | ---------------------------------------- |
| byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried. |
| begin | number | Yes | Start time. |
| end | number | Yes | End time. |
| callback | AsyncCallback&lt;Array&lt;[BundleStatsInfo](#bundlestatsinfo)&gt;&gt; | Yes | Callback used to return the application usage duration statistics.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryBundleStatsInfoByInterval
queryBundleStatsInfoByInterval(byInterval: IntervalType, begin: number, end: number): Promise&lt;Array&lt;BundleStatsInfo&gt;&gt;
Queries the application usage duration statistics in the specified time frame at the specified interval (daily, weekly, monthly, or annually). This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ----------------------------- | ---- | ----- |
| byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried.|
| begin | number | Yes | Start time.|
| end | number | Yes | End time.|
**Return value**
| Type | Description |
| ---------------------------------------- | ---------------------------------------- |
| Promise&lt;Array&lt;[BundleStatsInfo](#bundlestatsinfo)&gt;&gt; | Promise used to return the application usage duration statistics.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise result ' + JSON.stringify(res[i]));
}
}).catch( err => {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryBundleEvents
queryBundleEvents(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleEvents&gt;&gt;): void
Queries events of all applications based on the specified start time and end time. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------------------------------------- |
| begin | number | Yes | Start time. |
| end | number | Yes | End time. |
| callback | AsyncCallback&lt;Array&lt;[BundleEvents](#bundleevents)&gt;&gt; | Yes | Callback used to return the events obtained.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryBundleEvents(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryBundleEvents callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryBundleEvents callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleEvents callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleEvents callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryBundleEvents
queryBundleEvents(begin: number, end: number): Promise&lt;Array&lt;BundleEvents&gt;&gt;
Queries events of all applications based on the specified start time and end time. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.|
| end | number | Yes | End time.|
**Return value**
| Type | Description |
| ---------------------------------------- | -------------------------------------- |
| Promise&lt;Array&lt;[BundleEvents](#bundleevents)&gt;&gt; | Promise used to return the events obtained.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryBundleEvents(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryBundleEvents promise success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryBundleEvents promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryBundleEvents promise result ' + JSON.stringify(res[i]));
}
}).catch( err => {
console.log('BUNDLE_ACTIVE queryBundleEvents promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryCurrentBundleEvents
queryCurrentBundleEvents(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;BundleEvents&gt;&gt;): void
Queries events of this application based on the specified start time and end time. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | --------------------------------------- |
| begin | number | Yes | Start time. |
| end | number | Yes | End time. |
| callback | AsyncCallback&lt;Array&lt;[BundleEvents](#bundleevents)&gt;&gt; | Yes | Callback used to return the events obtained.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryCurrentBundleEvents(0, 20000000000000, (err, res) => {
if (err) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryCurrentBundleEvents
queryCurrentBundleEvents(begin: number, end: number): Promise&lt;Array&lt;BundleEvents&gt;&gt;
Queries events of this application based on the specified start time and end time. This API uses a promise to return the result.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.|
| end | number | Yes | End time.|
**Return value**
| Type | Description |
| ---------------------------------------- | -------------------------------------- |
| Promise&lt;Array&lt;[BundleEvents](#bundleevents)&gt;&gt; | Promise used to return the events obtained.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryCurrentBundleEvents(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise success.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise result ' + JSON.stringify(res[i]));
}
}).catch( err => {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryModuleUsageRecords
queryModuleUsageRecords(): Promise&lt;Array&lt;HapModuleInfo&gt;&gt;
Queries FA usage records. This API uses a promise to return a maximum of 1000 FA usage records sorted by time (most recent first).
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Return value**
| Type | Description |
| ---------------------------------------- | ---------------------------------- |
| Promise&lt;Array&lt;[HapModuleInfo](#hapmoduleinfo)&gt;&gt; | Promise used to return a maximum of 1000 FA usage records.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
// Invocation when maxNum is not passed
try{
usageStatistics.queryModuleUsageRecords().then( res => {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i]));
}
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryModuleUsageRecords
queryModuleUsageRecords(callback: AsyncCallback&lt;Array&lt;HapModuleInfo&gt;&gt;): void
Queries FA usage records. This API uses an asynchronous callback to return a maximum of 1000 FA usage records sorted by time (most recent first).
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ----------------------------------- |
| callback | AsyncCallback&lt;Array&lt;[HapModuleInfo](#hapmoduleinfo)&gt;&gt; | Yes | Callback used to return a maximum of 1000 FA usage records.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryModuleUsageRecords((err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryModuleUsageRecords
queryModuleUsageRecords(maxNum: number): Promise&lt;Array&lt;HapModuleInfo&gt;&gt;
Queries the number of FA usage records specified by **maxNum**. This API uses a promise to return the records sorted by time (most recent first).
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ------ | ------ | ---- | ---------------------------------- |
| maxNum | number | Yes | Maximum number of returned records. The maximum and default value is **1000**.|
**Return value**
| Type | Description |
| ---------------------------------------- | ---------------------------------- |
| Promise&lt;Array&lt;[HapModuleInfo](#hapmoduleinfo)&gt;&gt; | Promise used to return a maximum of **maxNum** FA usage records.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryModuleUsageRecords(1000).then( res => {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i]));
}
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryModuleUsageRecords
queryModuleUsageRecords(maxNum: number, callback: AsyncCallback&lt;Array&lt;HapModuleInfo&gt;&gt;): void
Queries the number of FA usage records. This API uses an asynchronous callback to return the records sorted by time (most recent first).
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ----------------------------------- |
| maxNum | number | Yes | Maximum number of returned records. The maximum value is **1000**.|
| callback | AsyncCallback&lt;Array&lt;[HapModuleInfo](#hapmoduleinfo)&gt;&gt; | Yes | Callback used to return a maximum of **maxNum** FA usage records.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryModuleUsageRecords(1000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.');
for (let i = 0; i < res.length; i++) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1));
console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i]));
}
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryAppGroup
queryAppGroup(bundleName : string): Promise&lt;number&gt;
Queries the group of the application specified by **bundleName**. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ------ | ---- | ---------------------------------------- |
| bundleName | string | Yes | Bundle name of the application.|
**Return value**
| Type | Description |
| --------------- | --------------------------- |
| Promise&lt;number&gt; | Promise used to return the group.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000005 | Application is not installed. |
| 10000006 | Get application info failed. |
| 10100002 | Get Application group info failed. |
**Example**
```javascript
// Promise mode when bundleName is specified
let bundleName = "com.ohos.camera";
try{
usageStatistics.queryAppGroup(bundleName).then( res => {
console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res));
}).catch( err => {
console.log('BUNDLE_ACTIVE queryAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryAppGroup
queryAppGroup(bundleName : string, callback: AsyncCallback&lt;number&gt;): void
Queries the group of the application specified by **bundleName**. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | --------------------- | ---- | ---------------------------------------- |
| bundleName | string | Yes | Bundle name of the application.|
| callback | AsyncCallback&lt;number&gt; | Yes | Callback used to return the group.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000005 | Application is not installed. |
| 10000006 | Get application info failed. |
| 10100002 | Get Application group info failed. |
**Example**
```javascript
let bundleName = "com.ohos.camera";
try{
usageStatistics.queryAppGroup(bundleName, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res));
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.setAppGroup
setAppGroup(bundleName: string, newGroup: GroupType): Promise&lt;void&gt;
Sets a group for the application specified by **bundleName**. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | --------- | ---- | ---- |
| bundleName | string | Yes | Bundle name of the application.|
| newGroup | [GroupType](#grouptype) | Yes | Group to set.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10100001 | Application group operation repeated. |
**Return value**
| Type | Description |
| ------------- | ------------------------- |
| Promise&lt;void&gt; | Promise used to return the result. |
**Example**
```javascript
let bundleName = "com.example.deviceUsageStatistics";
let newGroup = usageStatistics.GroupType.DAILY_GROUP;
try{
usageStatistics.setAppGroup(bundleName, newGroup).then( () => {
console.log('BUNDLE_ACTIVE setAppGroup promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE setAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.setAppGroup
setAppGroup(bundleName: string, newGroup: GroupType, callback: AsyncCallback&lt;void&gt;): void
Sets a group for the application specified by **bundleName**. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ---------- | ------------------- | ---- | ------------------------- |
| bundleName | string | Yes | Bundle name of the application. |
| newGroup | [GroupType](#grouptype) | Yes | Group to set. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed. |
| 10100001 | Application group operation repeated. |
**Example**
```javascript
let bundleName = "com.example.deviceUsageStatistics";
let newGroup = usageStatistics.GroupType.DAILY_GROUP;
try{
usageStatistics.setAppGroup(bundleName, newGroup, (err) => {
if(err) {
console.log('BUNDLE_ACTIVE setAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE setAppGroup callback succeeded.');
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.registerAppGroupCallBack
registerAppGroupCallBack(groupCallback: Callback&lt;AppGroupCallbackInfo&gt;): Promise&lt;void&gt;
Registers a callback for application group changes. When an application group of the user changes, an [AppGroupCallbackInfo](#appgroupcallbackinfo) instance is returned to all applications that have registered the callback. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
| callback | Callback&lt;[AppGroupCallbackInfo](#appgroupcallbackinfo)&gt; | Yes | Callback used to return the application group changes.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10100001 | Application group operation repeated. |
**Return value**
| Type | Description |
| ------------- | ----------------------- |
| Promise&lt;void&gt; | Promise used to return the result. |
**Example**
```javascript
let onBundleGroupChanged = (res) =>{
console.log('BUNDLE_ACTIVE registerAppGroupCallBack RegisterGroupCallBack callback success.');
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName);
};
try{
usageStatistics.registerAppGroupCallBack(onBundleGroupChanged).then( () => {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.registerAppGroupCallBack
registerAppGroupCallBack(groupCallback: Callback&lt;AppGroupCallbackInfo&gt;, callback: AsyncCallback&lt;void&gt;): void
Registers a callback for application group changes. When an application group of the user changes, an [AppGroupCallbackInfo](#appgroupcallbackinfo) instance is returned to all applications that have registered the callback. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- |
| groupCallback | Callback&lt;[AppGroupCallbackInfo](#appgroupcallbackinfo)&gt; | Yes | Callback used to return the application group changes. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10100001 | Application group operation repeated. |
**Example**
```javascript
let onBundleGroupChanged = (err, res) =>{
console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.');
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId);
console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName);
};
try{
usageStatistics.registerAppGroupCallBack(onBundleGroupChanged, err => {
if(err) {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback success.');
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.unregisterAppGroupCallBack
unregisterAppGroupCallBack(): Promise&lt;void&gt;
Deregisters the callback for application group changes. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
**Parameters**: none
**Return value**
| Type | Description |
| ------------- | ------------------------ |
| Promise&lt;void&gt; | Promise used to return the result. |
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10100001 | Application group operation repeated. |
**Example**
```javascript
try{
usageStatistics.unregisterAppGroupCallBack().then( () => {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack promise succeeded.');
}).catch( err => {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.unregisterAppGroupCallBack
unregisterAppGroupCallBack(callback: AsyncCallback&lt;void&gt;): void;
Deregisters the callback for application group changes. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ------------------- | ---- | -------------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback used to return the result.|
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10100001 | Application group operation repeated. |
**Example**
```javascript
try{
usageStatistics.unregisterAppGroupCallBack(err => {
if(err) {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack callback success.');
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryDeviceEventStats
queryDeviceEventStats(begin: number, end: number): Promise&lt;Array&lt;DeviceEventStats&gt;&gt;
Queries statistics about system events (hibernation, wakeup, unlocking, and screen locking) that occur between the specified start time and end time. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.|
| end | number | Yes | End time.|
**Return value**
| Type | Description |
| ---------------------------------------- | ---------------------------------------- |
| Promise&lt;Array&lt;[DeviceEventStats](#deviceeventstats)&gt;&gt; | Promise used to return the result. |
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryDeviceEventStats(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryDeviceEventStates promise success.');
console.log('BUNDLE_ACTIVE queryDeviceEventStates promise result ' + JSON.stringify(res));
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryDeviceEventStats promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryDeviceEventStats
queryDeviceEventStats(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;DeviceEventStats&gt;&gt;): void
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
| begin | number | Yes | Start time. |
| end | number | Yes | End time. |
| callback | AsyncCallback&lt;Array&lt;[DeviceEventStats](#deviceeventstats)&gt;&gt; | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryDeviceEventStats(0, 20000000000000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryDeviceEventStats callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryDeviceEventStats callback success.');
console.log('BUNDLE_ACTIVE queryDeviceEventStats callback result ' + JSON.stringify(res));
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryNotificationEventStats
queryNotificationEventStats(begin: number, end: number): Promise&lt;Array&lt;DeviceEventStats&gt;&gt;
Queries the number of notifications from all applications based on the specified start time and end time. This API uses a promise to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ----- | ------ | ---- | ----- |
| begin | number | Yes | Start time.|
| end | number | Yes | End time.|
**Return value**
| Type | Description |
| ---------------------------------------- | ---------------------------------------- |
| Promise&lt;Array&lt;[DeviceEventStats](#deviceeventstats)&gt;&gt; | Promise used to return the result. |
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryNotificationEventStats(0, 20000000000000).then( res => {
console.log('BUNDLE_ACTIVE queryNotificationEventStats promise success.');
console.log('BUNDLE_ACTIVE queryNotificationEventStats promise result ' + JSON.stringify(res));
}).catch( err=> {
console.log('BUNDLE_ACTIVE queryNotificationEventStats promise failed. code is: ' + err.code + ',message is: ' + err.message);
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## usageStatistics.queryNotificationEventStats
queryNotificationEventStats(begin: number, end: number, callback: AsyncCallback&lt;Array&lt;DeviceEventStats&gt;&gt;): void
Queries the number of notifications from all applications based on the specified start time and end time. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
| begin | number | Yes | Start time. |
| end | number | Yes | End time. |
| callback | AsyncCallback&lt;Array&lt;[DeviceEventStats](#deviceeventstats)&gt;&gt; | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md).
| ID | Error Message |
| ---------- | ---------------------------- |
| 10000001 | Memory operation failed. |
| 10000002 | Parcel operation failed. |
| 10000003 | System service operation failed. |
| 10000004 | IPC Communication failed. |
| 10000006 | Get application info failed |
| 10000007 | Get system or actual time failed. |
**Example**
```js
try{
usageStatistics.queryNotificationEventStats(0, 20000000000000, (err, res) => {
if(err) {
console.log('BUNDLE_ACTIVE queryNotificationEventStats callback failed. code is: ' + err.code + ',message is: ' + err.message);
} else {
console.log('BUNDLE_ACTIVE queryNotificationEventStats callback success.');
console.log('BUNDLE_ACTIVE queryNotificationEventStats callback result ' + JSON.stringify(res));
}
});
} catch (error) {
console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message);
}
```
## HapModuleInfo
Provides the information about the FA usage.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
| Name | Type | Mandatory | Description |
| -------------------- | ---------------------------------------- | ---- | ----------------------------- |
| deviceId | string | No | ID of the device to which the FA belongs. |
| bundleName | string | Yes | Name of the application bundle to which the FA belongs. |
| moduleName | string | Yes | Name of the module to which the FA belongs. |
| abilityName | string | No | **MainAbility** name of the FA. |
| appLabelId | number | No | Application label ID of the FA. |
| labelId | number | No | Label ID of the module to which the FA belongs. |
| descriptionId | number | No | Description ID of the application to which the FA belongs. |
| abilityLableId | number | No | **MainAbility** label ID of the FA. |
| abilityDescriptionId | number | No | **MainAbility** description ID of the FA.|
| abilityIconId | number | No | **MainAbility** icon ID of the FA. |
| launchedCount | number | Yes | Number of FA startup times. |
| lastModuleUsedTime | number | Yes | Last time when the FA was used. |
| formRecords | Array&lt;[HapFormInfo](#hapforminfo)&gt; | Yes | Array of widget usage records in the FA. |
## HapFormInfo
Provides the FA widget usage information.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
| Name | Type | Mandatory | Description |
| ---------------- | ------ | ---- | ----------- |
| formName | string | Yes | Widget name. |
| formDimension | number | Yes | Widget dimensions. |
| formId | number | Yes | Widget ID. |
| formLastUsedTime | number | Yes | Last time when the widget was clicked.|
| count | number | Yes | Number of clicks on the widget. |
## AppGroupCallbackInfo
Provides the application group changes returned through a callback.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
| Name | Type | Mandatory| Description |
| ---------------- | ------ | ---- | ---------------- |
| appOldGroup | number | Yes | Application group before the change.|
| appNewGroup | number | Yes | Application group after the change.|
| userId | number | Yes | User ID. |
| changeReason | number | Yes | Reason for the group change. |
| bundleName | string | Yes | Bundle name of the application. |
## BundleStatsInfo
Provides the usage duration information of an application.
### Attributes
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
| Name | Type | Mandatory | Description |
| ------------------------ | ------ | ---- | ---------------------------------------- |
| bundleName | string | Yes | Bundle name of the application. |
| abilityPrevAccessTime | number | Yes | Last time when the application was used. |
| abilityInFgTotalTime | number | Yes | Total time that the application runs in the foreground. |
| id | number | No | User ID.|
| abilityPrevSeenTime | number | No | Last time when the application was visible in the foreground.|
| abilitySeenTotalTime | number | No | Total time that the application is visible in the foreground.|
| fgAbilityAccessTotalTime | number | No | Total time that the application accesses the foreground.|
| fgAbilityPrevAccessTime | number | No | Last time when the application accessed the foreground.|
| infosBeginTime | number | No | Time logged in the first application usage record in the **BundleActiveInfo** object.|
| infosEndTime | number | No | Time logged in the last application usage record in the **BundleActiveInfo** object.|
## BundleEvents
Provides information about an application event.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
| Name | Type | Mandatory | Description |
| --------------------- | ------ | ---- | ---------------------------------------- |
| bundleName | string | Yes | Bundle name of the application. |
| eventId | number | Yes | Application event type. |
| eventOccurredTime | number | Yes | Timestamp when the application event occurs. |
| appGroup | number | No | Usage priority group of the application.|
| indexOfLink | string | No | Shortcut ID.|
| nameOfClass | string | No | Class name.|
## BundleStatsMap
Provides the usage duration information of an application.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
| Name | Type | Mandatory | Description |
| ------------------------------ | ---------------------------------------- | ---- | -------------- |
| [key: string]: BundleStatsInfo | [key: string]: [BundleStatsInfo](#bundlestatsinfo) | Yes | Usage duration information by application.|
## DeviceEventStats
Provides statistics about notifications and system events.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
**System API**: This is a system API.
| Name | Type | Mandatory | Description |
| ------- | ------ | ---- | ----------------- |
| name | string | Yes | Bundle name of the notification sending application or system event name. |
| eventId | number | Yes | Type of the notification or system event. |
| count | number | Yes | Number of application notifications or system event triggering times.|
## IntervalType
Enumerates the interval types for querying the application usage duration.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App
| Name | Default Value | Description |
| ------------ | ---- | ---------------------------------------- |
| BY_OPTIMIZED | 0 | The system queries the application usage duration statistics in the specified time frame at the interval the system deems appropriate.|
| BY_DAILY | 1 | The system queries the application usage duration statistics in the specified time frame on a daily basis. |
| BY_WEEKLY | 2 | The system queries the application usage duration statistics in the specified time frame on a weekly basis. |
| BY_MONTHLY | 3 | The system queries the application usage duration statistics in the specified time frame on a monthly basis. |
| BY_ANNUALLY | 4 | The system queries the application usage duration statistics in the specified time frame on an annual basis. |
## GroupType
Enumerates the application group types.
**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup
**System API**: This is a system API.
| Name | Default Value | Description |
| ------------------ | ---- | ----------------- |
| ALIVE_GROUP | 10 | Group of active applications. |
| DAILY_GROUP | 20 | Group of frequently used applications that are not in the active state. |
| FIXED_GROUP | 30 | Group of applications that are used periodically but not every day.|
| RARE_GROUP | 40 | Group of rarely used applications. |
| LIMITED_GROUP | 50 | Group of restricted applications. |
| NEVER_GROUP | 60 | Group of applications that have been installed but never run. |
en/application-dev/reference/apis/js-apis-resourceschedule-workScheduler.md 0 → 100644
浏览文件 @ 49c181a2
# 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](../../task-management/background-task-overview.md#restrictions-on-using-work-scheduler-tasks).
## Modules to Import
```js
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**
| Name | Type | Mandatory | Description |
| ---- | --------------------- | ---- | -------------- |
| work | [WorkInfo](#workinfo) | Yes | Task to be added to the execution queue.|
**Error codes**
For details about the error codes, see [workScheduler Error Codes](../errorcodes/errorcode-workScheduler.md).
| ID | Error Message |
| ---- | --------------------- |
| 9700001 | Memory operation failed. |
| 9700002 | Parcel operation failed. |
| 9700003 | System service operation failed. |
| 9700004 | Checking workInfo failed. |
| 9700005 | StartWork failed. |
**Example**
```js
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**
| Name | Type | Mandatory | Description |
| ---------- | --------------------- | ---- | ---------- |
| work | [WorkInfo](#workinfo) | Yes | Task to stop. |
| needCancel | boolean | Yes | Whether to cancel the task.|
**Error codes**
For details about the error codes, see [workScheduler Error Codes](../errorcodes/errorcode-workScheduler.md).
| ID | Error Message |
| ---- | --------------------- |
| 9700001 | Memory operation failed. |
| 9700002 | Parcel operation failed. |
| 9700003 | System service operation failed. |
| 9700004 | Checking workInfo failed. |
**Example**
```js
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:callback
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](#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.|
**Error codes**
For details about the error codes, see [workScheduler Error Codes](../errorcodes/errorcode-workScheduler.md).
| ID | Error Message |
| ---- | --------------------- |
| 9700001 | Memory operation failed. |
| 9700002 | Parcel operation failed. |
| 9700003 | System service operation failed. |
| 9700004 | Checking workInfo failed. |
**Example**
```js
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:promise
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](#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.|
**Error codes**
For details about the error codes, see [workScheduler Error Codes](../errorcodes/errorcode-workScheduler.md).
| ID | Error Message |
| ---- | --------------------- |
| 9700001 | Memory operation failed. |
| 9700002 | Parcel operation failed. |
| 9700003 | System service operation failed. |
| 9700004 | Checking workInfo failed. |
**Example**
```js
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:callback
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 the result. All tasks associated with the current application.|
**Return value**
| Type | Description |
| ----------------------------- | --------------- |
| Array\<[WorkInfo](#workinfo)> | All tasks associated with the current application.|
**Error codes**
For details about the error codes, see [workScheduler Error Codes](../errorcodes/errorcode-workScheduler.md).
| ID | Error Message |
| ---- | --------------------- |
| 9700001 | Memory operation failed. |
| 9700002 | Parcel operation failed. |
| 9700003 | System service operation failed. |
**Example**
```js
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:promise
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](#workinfo)>> | Promise used to return the result. All tasks associated with the current application.|
**Error codes**
For details about the error codes, see [workScheduler Error Codes](../errorcodes/errorcode-workScheduler.md).
| ID | Error Message |
| ---- | --------------------- |
| 9700001 | Memory operation failed. |
| 9700002 | Parcel operation failed. |
| 9700003 | System service operation failed. |
**Example**
```js
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](../errorcodes/errorcode-workScheduler.md).
| ID | Error Message |
| ---- | --------------------- |
| 9700001 | Memory operation failed. |
| 9700002 | Parcel operation failed. |
| 9700003 | System service operation failed. |
**Example**
```js
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:callback
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.|
**Error codes**
For details about the error codes, see [workScheduler Error Codes](../errorcodes/errorcode-workScheduler.md).
| ID | Error Message |
| ---- | --------------------- |
| 9700001 | Memory operation failed. |
| 9700002 | Parcel operation failed. |
| 9700003 | System service operation failed. |
**Example**
```js
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:promise
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.|
**Error codes**
For details about the error codes, see [workScheduler Error Codes](../errorcodes/errorcode-workScheduler.md).
| ID | Error Message |
| ---- | --------------------- |
| 9700001 | Memory operation failed. |
| 9700002 | Parcel operation failed. |
| 9700003 | System service operation failed. |
**Example**
```js
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](../../task-management/background-task-overview.md#restrictions-on-using-work-scheduler-tasks).
**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](#networktype) | No | Network type. |
| isCharging | boolean | No | Whether the device is charging. |
| chargerType | [ChargingType](#chargingtype) | No | Charging type. |
| batteryLevel | number | No | Battery level. |
| batteryStatus | [BatteryStatus](#batterystatus) | No | Battery status. |
| storageRequest | [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 | Description |
| ---------------------- | ----------------------- |
| NETWORK_TYPE_ANY | Any network type. |
| NETWORK_TYPE_MOBILE | Mobile network. |
| NETWORK_TYPE_WIFI | Wi-Fi network. |
| NETWORK_TYPE_BLUETOOTH | Bluetooth network.|
| NETWORK_TYPE_WIFI_P2P | Wi-Fi P2P network. |
| NETWORK_TYPE_ETHERNET | Ethernet. |
## ChargingType
Enumerates the charging types that can trigger the task.
**System capability**: SystemCapability.ResourceSchedule.WorkScheduler
| Name | Description |
| ------------------------- | -------------------- |
| CHARGING_PLUGGED_ANY | Any charging type.|
| CHARGING_PLUGGED_AC | DC charging. |
| CHARGING_PLUGGED_USB | USB charging. |
| CHARGING_PLUGGED_WIRELESS | Wireless charging. |
## BatteryStatus
Enumerates the battery states that can trigger the task.
**System capability**: SystemCapability.ResourceSchedule.WorkScheduler
| Name | Description |
| -------------------------- | -------------------------- |
| BATTERY_STATUS_LOW | A low battery alert is displayed. |
| BATTERY_STATUS_OKAY | The battery level is restored from low to normal. |
| BATTERY_STATUS_LOW_OR_OKAY | 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 | Description |
| ------------------------- | ------------------------------ |
| STORAGE_LEVEL_LOW | The storage space is insufficient. |
| STORAGE_LEVEL_OKAY | The storage space is restored from insufficient to normal. |
| STORAGE_LEVEL_LOW_OR_OKAY | The storage space is restored from insufficient to normal, or the storage space is insufficient.|
en/application-dev/reference/errorcodes/errorcode-DeviceUsageStatistics.md 0 → 100644
浏览文件 @ 49c181a2
# DeviceUsageStatistics Error Codes
## 10000001 Memory Operation Failure
**Error Message**
Memory operation failed.
**Description**
Creating an instance fails.
**Possible Causes**
The system memory is insufficient.
**Solution**
Check whether memory leak occurs.
## 10000002 IPC Parcel Write Failure
**Error Message**
Parcel operation failed. Failed to write the parcel.
**Description**
Failed to write the data object during the IPC.
**Possible Causes**
Failed to write the object.
**Solution**
Check whether the object value is normal.
## 10000003 System Service Operation Failure
**Error Message**
System service operation failed.
**Description**
The client process fails to obtain the system service.
**Possible Causes**
The dependent service process is faulty.
**Solution**
Try again later or restart the device.
## 10000004 IPC Failure
**Error Message**
IPC communication failed.
**Description**
The IPC fails.
**Possible Causes**
The system service is abnormal or the IPC data is abnormal.
**Solution**
Try again later or restart the device.
## 10000005 Application Not Installed
**Error Message**
The application is not installed.
**Description**
The application is not installed.
**Possible Causes**
The application is not installed or has been uninstalled.
**Solution**
Check whether the application exists.
## 10000006 Failed to Obtain Application Information
**Error Message**
Get application info failed.
**Description**
The client process fails to obtain application information from the service.
**Possible Causes**
1. The value of **beginTime** or **endTime** is invalid.
2. The application is not installed or has been uninstalled.
3. The value of **intervalType** is invalid.
**Solution**
Check whether the input parameters are valid and whether the application exists.
## 10000007 Time Operation Failure
**Error Message**
Get system or actual time operation failed.
**Description**
The system service fails to obtain the system time.
**Possible Causes**
The system is abnormal.
**Solution**
Try again later or restart the device.
## 10100001 Duplicate Application Group Operation
**Error Message**
Application group operation failed. The application group are the the same or do not need te be updated.
**Description**
Operating the application group, for example, setting an application group or registering or deregistering a callback for application group changes, fails.
**Possible Causes**
The application group to set already exists, or the callback for application group changes to register or deregister has already been registered or deregistered.
**Solution**
Do not repeatedly set application groups, or register or deregister a callback for application group changes.
## 10100002 Failed to Obtain Application Group Information
**Error Message**
Get application group info failed. The application group infomation cannot be found.
**Description**
The client process fails to obtain the application group information.
**Possible Causes**
1. An incorrect bundle name is passed.
2. The application is not installed or has been uninstalled.
**Solution**
Check whether the bundle name is valid and whether the application exists.
en/application-dev/reference/errorcodes/errorcode-backgroundTaskMgr.md 0 → 100644
浏览文件 @ 49c181a2
# backgroundTaskManager Error Codes
## 9800001 Memory Operation Failure
**Error Message**
Memory operation failed.
**Possible Causes**
1. A memory leak occurs.
2. The system memory is insufficient.
**Solution**
1. Release the memory.
2. Check whether memory leak occurs.
## 9800002 Parcel Operation Failure
**Error Message**
Parcel operation failed.
**Possible Causes**
An exception occurs when invoking the **MessageParcel** object to read or write an object.
**Solution**
Try again later or restart the device.
## 9800003 IPC Failure
**Error Message**
IPC failed.
**Possible Causes**
IPC fails.
**Solution**
Try again later or restart the device.
## 9800004 System Service Failure
**Error Message**
System service operation failed.
**Possible Causes**
1. The system service is not started.
2. The system service is abnormal.
**Solution**
Try again later or restart the device.
## 9800005 Continuous Task Verification Failure
**Error Message**
Continuous task verification failed.
**Possible Causes**
1. The application repeatedly requests a continuous task.
2. The application repeatedly cancels a continuous task.
3. The value of **bgMode** is invalid because no continuous task type is configured for **backgroundModes** in the application's configuration file.
4. A non-PC device requests the continuous task **KEEPING_TASK**, which is available only for PCs.
5. A third-party application requests the continuous task **WIFI_INTERACTION** or **VOIP**, which is available only for system applications.
**Solution**
1. Check the application code.
2. Check whether the application has the system permissions.
3. Check the type of the device where the application is located.
4. Check the value of **backgroundModes**.
## 9800006 Notification Verification Failure
**Error Message**
Notification verification failed.
**Possible Causes**
1. The continuous task resources cached in the resource subsystem fail to be loaded.
2. The notification subsystem functions abnormally.
**Solution**
1. Check for the continuous task resources **ohos.backgroundtaskmgr.resources**.
2. Try again later or restart the device.
## 9800007 Continuous Task Storage Failure
**Error Message**
Task storage failed.
**Possible Causes**
1. Failed to create a file to store the task information.
2. Failed to obtain the file path.
3. Failed to open the file that stores the task information.
**Solution**
1. Check the **/data/service/el1/public/background_task_mgr/running_task** file.
2. Try again later or restart the device.
## 9900001 Caller Information Verification Failure for a Transient Task
**Error Message**
Caller information verification failed for a transient task.
**Possible Causes**
1. Failed to obtain the UID or PID of the caller.
2. Failed to obtain the bundle name of the caller.
3. The request ID passed in the API used to cancel the transient task is invalid.
**Solution**
1. Check whether the application UID exists.
2. Check whether the application has requested a transient task.
3. Try again later or restart the device.
## 9900002 Continuous Task Verification Failure
**Error Message**
Transient task verification failed.
**Possible Causes**
1. The callback passed in **requestSuspendDelay()** already exists.
2. The callback passed in **cancelSuspendDelay()** does not exist.
3. The application attempts to request a transient task 5 seconds after it switches to the background.
4. The application has already requested three transient tasks.
5. The application's daily quota for transient tasks is used up.
**Solution**
1. Check the application code.
2. The application should cancel transient tasks immediately after they are complete.
## 18700001 Caller Information Verification Failure for an Energy Resource Request
**Error Message**
Caller information verification failed when applying for efficiency resources.
**Possible Causes**
1. Failed to obtain the UID or PID of the caller.
2. The value of **resourceTypes **for requesting energy resources exceeds the upper limit.
**Solution**
Check the input parameters.
en/application-dev/reference/errorcodes/errorcode-reminderAgentManager.md 0 → 100644
浏览文件 @ 49c181a2
# reminderAgentManager Error Codes
## 1700001 Notification Disabled
**Error Message**
Notification does not enable.
**Description**
The application is not allowed to send notifications when **publishReminder()** is called.
**Possible Causes**
1. The application has not requested notification to be enabled.
2. The reminder function is disabled.
**Solution**
1. Call [Notification.requestEnableNotification](../apis/js-apis-notification.md#notificationrequestenablenotification8) to request notification to be enabled for the application.
2. Check whether the notification function is disabled.
## 1700002 Too Many Reminders
**Error Message**
The number of reminders exceeds the limit.
**Description**
The number of reminders exceeds the limit when **publishReminder()** is called.
**Possible Causes**
1. There are already 2000 reminders for the entire system.
2. There are already 30 reminders for the application.
**Solution**
Delete unnecessary reminders.
## 1700003 Nonexistent Reminder
**Error Message**
The reminder does not exist.
**Description**
The reminder passed in **cancelReminder()** does not exist.
**Possible Causes**
1. The reminder has expired.
2. The reminder has been deleted.
**Solution**
1. Check whether the reminder is valid.
2. Check whether the reminder has been deleted.
## 1700004 Nonexistent Bundle Name
**Error Message**
The package name does not exist.
**Description**
The bundle name passed is not found.
**Possible Causes**
1. The bundle name is incorrect.
2. The application is not installed.
**Solution**
Check whether the bundle name exists.
en/application-dev/reference/errorcodes/errorcode-workScheduler.md 0 → 100644
浏览文件 @ 49c181a2
# workScheduler Error Codes
## 9700001 Memory Operation Failure
**Error Message**
Memory operation failed.
**Possible Causes**
1. A memory leak occurs.
2. The system memory is insufficient.
**Solution**
1. Release the memory.
2. Check whether memory leak occurs.
## 9700002 Parcel Operation Failure
**Error Message**
Parcel operation failed.
**Possible Causes**
An exception occurs when invoking the **MessageParcel** object to read or write an object.
**Solution**
Try again later or restart the device.
## 9700003 System Service Failure
**Error Message**
System service operation failed.
**Possible Causes**
1. The system service is not started.
2. The system service is abnormal.
**Solution**
Try again later or restart the device.
## 9700004 workInfo Verification Failure
**Error Message**
Checking workInfo failed.
**Possible Causes**
1. The value of **bundleName** in **workInfo** does not match the UID of the application.
2. The Work Scheduler task to cancel or query does not exist.
**Solution**
Check the **workInfo** parameters.
## 9700005 startWork Failure
**Error Message**
StartWork failed.
**Possible Causes**
1. The Work Scheduler task already exists.
2. The application has already requested 10 Work Scheduler tasks.
3. The repeat interval of a Work Scheduler task must be at least 20 minutes.
**Solution**
Check the input parameters and application code.
en/application-dev/task-management/Readme-EN.md
浏览文件 @ 49c181a2
# Task Management # Task Management
- Background Task Management
- Background Task
- [Background Task Management Overview](background-task-overview.md) - [Background Task Management Overview](background-task-overview.md)
- [Background Task Management Development](background-task-dev-guide.md) - [Transient Task Development](transient-task-dev-guide.md)
- Work Scheduler - [Continuous Task Development](continuous-task-dev-guide.md)
- [Work Scheduler Overview](work-scheduler-overview.md)
- [Work Scheduler Development](work-scheduler-dev-guide.md) - [Work Scheduler Development](work-scheduler-dev-guide.md)
- [Efficiency Resource Request Development](efficiency-resources-apply-dev-guide.md)
- Agent-Powered Scheduled Reminder
- [Agent-Powered Scheduled Reminder Overview](background-agent-scheduled-reminder-overview.md)
- [Agent-Powered Scheduled Reminder Development](background-agent-scheduled-reminder-guide.md)
en/application-dev/task-management/background-agent-scheduled-reminder-guide.md 0 → 100644
浏览文件 @ 49c181a2
# Agent-Powered Scheduled Reminder Development
## When to Use
You can set your application to call the **ReminderRequest** class to create scheduled reminders for countdown timers, calendar events, and alarm clocks. When the created reminders are published, the timing and pop-up notification functions of your application will be taken over by the reminder agent in the background, even when your application is frozen or exits.
## Available APIs
**reminderAgentManager** encapsulates the APIs for publishing and canceling reminders.
For details about the APIs, see [reminderAgentManager](../reference/apis/js-apis-reminderAgentManager.md).
**Table 1** Major APIs in reminderAgentManager
| Name| Description|
| -------- | -------- |
| publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback&lt;number&gt;): void<br>publishReminder(reminderReq: ReminderRequest): Promise&lt;number&gt; | Publishes a scheduled reminder.<br>The maximum number of valid notifications (excluding expired ones that will not pop up again) is 30 for one application and 2000 for the entire system. |
| cancelReminder(reminderId: number, callback: AsyncCallback&lt;void&gt;): void<br>cancelReminder(reminderId: number): Promise&lt;void&gt; | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.)|
| getValidReminders(callback: AsyncCallback&lt;Array&lt;ReminderRequest&gt;&gt;): void<br>getValidReminders(): Promise&lt;Array&lt;ReminderRequest&gt;&gt; | Obtains all valid reminders set by the current application.|
| cancelAllReminders(callback: AsyncCallback&lt;void&gt;): void<br>cancelAllReminders(): Promise&lt;void&gt; | Cancels all reminders set by the current application.|
| addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback&lt;void&gt;): void<br>addNotificationSlot(slot: NotificationSlot): Promise&lt;void&gt; | Registers a **NotificationSlot** instance to be used by the reminder.|
| removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback&lt;void&gt;): void<br>removeNotificationSlot(slotType: notification.SlotType): Promise&lt;void&gt; | Removes a **NotificationSlot** instance of a specified type.|
## How to Develop
> **NOTE**
>
> 1. To publish a reminder through the reminder agent, your application must apply for the **ohos.permission.PUBLISH_AGENT_REMINDER** permission.
>2. Your application must have notification enabled. For details, see [Notification.requestEnableNotification](../reference/apis/js-apis-notification.md#notificationrequestenablenotification8).
> 3. The reminder agent can be used only after being authorized by the user.
1. Define a reminder agent.
2. Publish the reminder agent.
```ts
import reminderAgentManager from '@ohos.reminderAgentManager';
import notification from '@ohos.notification';
// Sample code for defining a reminder agent for a countdown timer:
let timer : reminderAgentManager.ReminderRequestTimer = {
reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,
triggerTimeInSeconds: 10,
actionButton: [
{
title: "close",
type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
}
],
wantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
maxScreenWantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
title: "this is title",
content: "this is content",
expiredContent: "this reminder has expired",
notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION
}
// Sample code for defining a reminder agent for a calendar event:
let calendar : reminderAgentManager.ReminderRequestCalendar = {
reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR,
dateTime: {
year: 2050,
month: 7,
day: 30,
hour: 11,
minute: 14,
second: 30
},
repeatMonths: [1],
repeatDays: [1],
actionButton: [
{
title: "close",
type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
},
{
title: "snooze",
type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
},
],
wantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
maxScreenWantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
ringDuration: 5,
snoozeTimes: 2,
timeInterval: 5,
title: "this is title",
content: "this is content",
expiredContent: "this reminder has expired",
snoozeContent: "remind later",
notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION
}
// Sample code for defining a reminder agent for an alarm:
let alarm : reminderAgentManager.ReminderRequestAlarm = {
reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM,
hour: 11,
minute: 14,
daysOfWeek: [0],
actionButton: [
{
title: "close",
type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
},
{
title: "snooze",
type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
},
],
wantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
maxScreenWantAgent: {
pkgName: "com.example.device",
abilityName: "com.example.device.MainAbility"
},
ringDuration: 5,
snoozeTimes: 2,
timeInterval: 5,
title: "this is title",
content: "this is content",
expiredContent: "this reminder has expired",
snoozeContent: "remind later",
notificationId: 100,
slotType: notification.SlotType.SOCIAL_COMMUNICATION
}
@Entry
@Component
struct Index {
@State message: string = 'test'
publishReminder() {
try {
reminderAgentManager.publishReminder(timer).then(res => {
console.log("publishReminder promise reminderId:" + res);
}).catch(err => {
console.log("publishReminder err code:" + err.code + " message:" + err.message);
})
} catch (error) {
console.log("publishReminder code:" + error.code + " message:" + error.message);
};
}
build() {
Row() {
Column() {
Text("Index")
.fontSize(50)
.fontWeight(FontWeight.Bold)
Button() { Text('Countdown reminder agent').fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule)
.margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40)
.onClick(() => {
// Sample code for publishing the reminder agent.
this.publishReminder();
})
}
.width('100%')
}
.height('100%')
}
}
```
en/application-dev/task-management/background-agent-scheduled-reminder-overview.md 0 → 100644
浏览文件 @ 49c181a2
# Agent-Powered Scheduled Reminder Overview
According to the OpenHarmony background activity specifications, a third-party application will be suspended if it does not execute background tasks after switching to the background. In practice, an application may need to process certain work at specified moments, no matter what state it is in. For example, a shopping application needs to remind users of flash sale activities at some time points. Generally, a timer is used to achieve the preceding scenario. When the timer expires, the system starts the application to execute the task. However, some applications abuse the timer mechanism so they can be frequently waken up when running in the background. To avoid malicious background activities and meet service requirements of applications, OpenHarmony introduces the agent-powered scheduled reminder.
With the agent-powered scheduled reminder, the timing and pop-up notification functions of an application will be taken over by the reminder agent in the background, even when the application is suspended or exits. This prevents an application from being frequently woken up and helps reduce power consumption.
## Notification Instance Types
- **Countdown timers**: Applications can use this type to implement short-time timing notification services.
- **Calendar events**: Applications can use this type to implement long-time notification services.
- **Alarm clocks**: Applications can use this type to implement alarm-related services.
en/application-dev/task-management/background-task-overview.md
浏览文件 @ 49c181a2
# Background Task Management Overview # Background Task Management Overview
Frequent activities of background applications cause user devices to consume power quickly and respond slowly. To meet performance and power consumption requirements, the system allows applications to execute only activities within the specifications in the background. Activities beyond the specifications are suspended by default, and resources allocated to them will be reclaimed when the available resources are insufficient. Frequent activities of background applications cause user devices to consume power quickly and respond slowly. To meet performance and power consumption requirements, the system allows applications in the background to execute only activities within the specifications. Activities beyond the specifications are suspended by default, and resources allocated to them will be reclaimed when the available resources are insufficient.
If an application or a service module running in the background has a service to continue, it can request a [transient task](#transient-tasks) to delay the suspension or a [continuous task](#continuous-tasks) to prevent the suspension. If an application needs to execute a non-real-time task when running in the background, it can request a [Work Scheduler Task](#work-scheduler-tasks). A privileged application can also request [efficiency resources](#efficiency-resources) for more flexibility.
## Background Task Types ## Background Task Types
Background tasks described in this document refer to the services that need to be continued when the respective applications or service modules are running in the background (not visible to the users). For more targeted management of background applications and service modules, OpenHarmony classifies applications and service modules into the following types: For more targeted management of background applications, OpenHarmony classifies background tasks into the following types and provides an extended resource request mode:
- **No background task**: An application or service module does not need further processing when switched to the background. **No background task**: An application or service module does not need further processing when switched to the background.
- **Transient task**: If an application or service module has an urgent, short task that must continue in the background until it is completed, such as data compression, the application or service module can request a transient task to delay the suspension. **Transient task**: If an application or service module has an urgent, short task that must continue in the background until it is completed, such as data compression, the application or service module can request a transient task for delayed suspension.
- **Continuous task**: If an application or service module has a user-initiated, perceivable task that needs to run in an extended period of time in the background, it can request a continuous task so that it will not be suspended. Examples of continuous tasks include music playback, navigation, device connection, and VoIP. **Continuous task**: If an application or service module has a user-initiated, perceivable task that needs to run in an extended period of time in the background, it can request a continuous task so that it will not be suspended. Examples of continuous tasks include music playback, navigation, device connection, and VoIP.
- **Efficiency resources**: If an application needs to ensure that it will not be suspended within a period of time or can normally use certain system resources when it is suspended, it can request efficiency resources, including CPU, WORK_SCHEDULER, software, and hardware resources. Different types of efficiency resources come with different privileges. For example, the CPU resources enable an application or process to keep running without being suspended, and WORK_SCHEDULER resources allow for more task execution time before the application or process is suspended. **Work Scheduler task**: 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.
**Efficiency resources**: If an application needs to ensure that it will not be suspended within a period of time or can normally use certain system resources when it is suspended, it can request efficiency resources, including CPU, WORK_SCHEDULER, software, and hardware resources. Different types of efficiency resources come with different privileges. For example, the CPU resources enable an application or process to keep running without being suspended, and the WORK_SCHEDULER resources allow for more task execution time before the application or process is suspended.
## Selecting a Background Task
![Background Task Selection](public_sys-resources/bgtask_choice.png)
## Transient Tasks ## Transient Tasks
...@@ -64,10 +70,45 @@ OpenHarmony provides 9 background modes for services that require continuous tas ...@@ -64,10 +70,45 @@ OpenHarmony provides 9 background modes for services that require continuous tas
- If a requested continuous task is not actually executed, the system will suspend the task once it detects the issue. - If a requested continuous task is not actually executed, the system will suspend the task once it detects the issue.
- Each ability can request only one continuous task at a time. - Each ability can request only one continuous task at a time.
## Work Scheduler Tasks
The Work Scheduler provides a mechanism for an application to execute a non-real-time task, for example, data learning, when the system is idle. The system places the Work Scheduler tasks requested by applications in a queue and determines the optimal scheduling time of each task based on the storage space, power consumption, temperature, and more. Persistence is supported. This means that a requested Work Scheduler task can be triggered when the application exits or the device restarts.
### Restrictions on Using Work Scheduler Tasks
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. The default timeout duration is 2 minutes. System applications can request [efficiency resources](efficiency-resources-apply-dev-guide.md) to obtain a longer duration (20 minutes in the charging state and 10 minutes in the non-charging state).
- **Execution frequency**: The system controls the execution frequency of Work Scheduler tasks based on the activity level of their respective applications. If an application has applied for the WORK_SCHEDULER resources through the efficiency resource API, the execution frequency is not limited within the validity period of the resources.
| Application Group | Work Scheduler Task Execution Frequency |
| --------------------|------------------------- |
| Active| At a minimum interval of 2 hours|
| Used every day| At a minimum interval of 4 hours|
| Frequently used| At a minimum interval of 24 hours|
| Infrequently used| At a minimum interval of 48 hours|
| Restricted| Prohibited|
| Unused| Prohibited|
| [Exemption group for efficiency resources](../reference/apis/js-apis-backgroundTaskManager.md#resourcetype9) | Unlimited|
- **WorkInfo setting**
- **workId**, **bundleName**, and **abilityName** are mandatory. **bundleName** must be set to the name of the current application. Otherwise, the verification will fail.
- At least one condition must be set.
- The repeat interval must be at least 20 minutes and must work with the Always repeat pattern or repeat times.
- The carried parameters can be of the number, string, or boolean type.
## Efficiency Resources ## Efficiency Resources
Efficiency resources are classified into CPU, WORK_SCHEDULER, software, and hardware resources. Efficiency resources are classified into CPU, WORK_SCHEDULER, software, and hardware resources.
An application or process is assigned the privileges associated with the obtained efficiency resources. For example, with the CPU resources, the application or process will not be suspended. With the WORK_SCHEDULER resources, the application or process has more time to execute a task and is not restricted by the execution frequency. With the software and hardware resources, related resources are not proxied when the application or process is suspended.
An application or process is assigned the privileges associated with the obtained efficiency resources.
* With the CPU resources, the application or process will not be suspended.
* With the WORK_SCHEDULER resources, the application or process has more time to execute a task and is not restricted by the execution frequency.
* With the COMMON_EVENT resources, the application can still receive common events when it is suspended in the background.
* With the TIMER resources, the application can use the timer to execute precise scheduled tasks.
* With the hardware resources, the application can still be woken up by related services to execute tasks when it is suspended in the background.
**Table 2** Efficiency resource types **Table 2** Efficiency resource types
...@@ -83,5 +124,11 @@ An application or process is assigned the privileges associated with the obtaine ...@@ -83,5 +124,11 @@ An application or process is assigned the privileges associated with the obtaine
### Restrictions on Using Efficiency Resources ### Restrictions on Using Efficiency Resources
- Applications or processes are responsible for requesting and releasing efficiency resources. A process can release the resources requested by itself, whereas an application can release the resources requested by both itself and its processes. For example, an application requests CPU resources, and its process requests CPU and WORK_SCHEDULER resources. If the application initiates CPU resource release, the CPU resources requested by the process are also released. However, the WORK_SCHEDULER resources are not released. If the process initiates CPU resource release, the CPU resources requested by the application are retained until being released by the application. - Applications or processes are responsible for requesting and releasing efficiency resources. A process can release the resources requested by itself, whereas an application can release the resources requested by both itself and its processes. For example, an application requests CPU resources, and its process requests CPU and WORK_SCHEDULER resources. If the application initiates CPU resource release, the CPU resources requested by the process are also released. However, the WORK_SCHEDULER resources are not released. If the process initiates CPU resource release, the CPU resources requested by the application are retained until being released by the application.
- If persistent resources and non-persistent resources of the same type are requested, the persistent resources overwrite the non-persistent resources and they will not be released upon a timeout. For example, if an application first requests 10-second CPU resources and then requests persistent CPU resources at the 5th second, the CPU resources become persistent and will not be released at the tenth second. If the application releases the CPU resources at the 8th second, both types of CPU resources are released. - If persistent resources and non-persistent resources of the same type are requested, the persistent resources overwrite the non-persistent resources and they will not be released upon a timeout. For example, if an application first requests 10-second CPU resources and then requests persistent CPU resources at the 5th second, the CPU resources become persistent and will not be released at the tenth second. If the application releases the CPU resources at the 8th second, both types of CPU resources are released.
- The WORK_SCHEDULER resources can be requested and released by applications, but not by processes. - The WORK_SCHEDULER resources can be requested and released by applications, but not by processes.
- To use efficiency resources, an application must first submit a request to the application center to obtain corresponding privileges.
<!--no_check-->
en/application-dev/task-management/background-task-dev-guide.md → en/application-dev/task-management/continuous-task-dev-guide.md
浏览文件 @ 49c181a2
# Background Task Management Development # Continuous Task Development
## When to Use ## When to Use
If a service needs to be continued when the application or service module is running in the background (not visible to users), the application or service module can request a transient task to delay the suspension or a continuous task to prevent the suspension. The application can also request efficiency resources in the following scenarios for more flexibility: If an application has a perceivable task that needs to run in an extended period of time in the background, it can request a continuous task so that it will not be suspended. Examples of continuous tasks include music playback, navigation, device connection, and VoIP.
There is no time limit for a continuous task running in the background. To prevent abuse, the system limits the number of continuous tasks that can be requested. It also attaches a notification to the task so that the task is perceivable. In addition, the system verifies whether the application is actually executing the continuous task.
- The application should not be suspended within a period of time until it finishes the task. ## Available APIs
- The application requires system resources even when it is suspended. For example, an alarm clock requires timer resources even when being suspended. **Table 1** Main APIs for continuous tasks
- The application needs to execute the task at an unlimited frequency and within a longer time.
## Transient Tasks
### Available APIs
**Table 1** Main APIs for transient tasks
| API | Description |
| ---------------------------------------- | ---------------------------------------- |
| requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): [DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo)| Requests delayed suspension after the application switches to the background.<br>The default duration value of delayed suspension is 180000 when the battery level is normal and 60000 when the battery level is low.|
| getRemainingDelayTime(requestId: number): Promise&lt;number&gt; | Obtains the remaining duration before the application is suspended.<br>This API uses a promise to return the result. |
| cancelSuspendDelay(requestId: number): void | Cancels the suspension delay. |
### How to Develop
1. Request a suspension delay.
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let myReason = 'test requestSuspendDelay';
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
});
var id = delayInfo.requestId;
console.info("requestId is: " + id);
```
2. Obtain the remaining duration before the application is suspended.
```js
backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( err => {
console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code);
});
```
3. Cancel the suspension delay.
```js
backgroundTaskManager.cancelSuspendDelay(id);
```
### Development Examples
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let myReason = 'test requestSuspendDelay';
// Request a suspension delay.
let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
});
// Print the suspension delay information.
var id = delayInfo.requestId;
var time = delayInfo.actualDelayTime;
console.info("The requestId is: " + id);
console.info("The actualDelayTime is: " + time);
// Obtain the remaining duration before the application is suspended.
backgroundTaskManager.getRemainingDelayTime(id).then( res => {
console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
}).catch( err => {
console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code);
});
// Cancel the suspension delay.
backgroundTaskManager.cancelSuspendDelay(id);
```
## Continuous Tasks
### Required Permissions
ohos.permission.KEEP_BACKGROUND_RUNNING
### Available APIs
**Table 2** Main APIs for continuous tasks
| API | Description | | API | Description |
| ---------------------------------------- | ---------------------------- | | ---------------------------------------- | ---------------------------- |
...@@ -105,168 +17,57 @@ ohos.permission.KEEP_BACKGROUND_RUNNING ...@@ -105,168 +17,57 @@ ohos.permission.KEEP_BACKGROUND_RUNNING
For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantAgent.md). For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantAgent.md).
**Table 3** Background modes **Table 2** Background modes
| Name | ID | Description | Configuration Item |
| ----------------------- | ---- | -------------- | --------------------- |
| DATA_TRANSFER | 1 | Data transfer. | dataTransfer |
| AUDIO_PLAYBACK | 2 | Audio playback. | audioPlayback |
| AUDIO_RECORDING | 3 | Audio recording. | audioRecording |
| LOCATION | 4 | Positioning and navigation. | location |
| BLUETOOTH_INTERACTION | 5 | Bluetooth-related task. | bluetoothInteraction |
| MULTI_DEVICE_CONNECTION | 6 | Multi-device connection. | multiDeviceConnection |
| WIFI_INTERACTION | 7 | WLAN-related task (reserved). | wifiInteraction |
| VOIP | 8 | Voice and video call (reserved). | voip |
| TASK_KEEPING | 9 | Computing task (for specific devices only).| taskKeeping |
### How to Develop
Development on the FA model: | Name | Description | Item |
| ----------------------- | -------------- | --------------------- |
| DATA_TRANSFER | Data transfer. | dataTransfer |
| AUDIO_PLAYBACK | Audio playback. | audioPlayback |
| AUDIO_RECORDING | Audio recording. | audioRecording |
| LOCATION | Positioning and navigation. | location |
| BLUETOOTH_INTERACTION | Bluetooth-related task. | bluetoothInteraction |
| MULTI_DEVICE_CONNECTION | Multi-device connection. | multiDeviceConnection |
| WIFI_INTERACTION | WLAN-related task (reserved). | wifiInteraction |
| VOIP | Voice and video call (reserved). | voip |
| TASK_KEEPING | Computing task (for specific devices only).| taskKeeping |
1. Create an API version 8 project. Then right-click the project directory and choose **New > Ability > Service Ability** to create a Service ability. Configure the continuous task permission and background mode type in the **config.json** file, with the ability type set to **service**.
```
"module": {
"package": "com.example.myapplication",
"abilities": [
{
"backgroundModes": [
"dataTransfer",
"location"
], // Background mode
"type": "service" // The ability type is service.
}
],
"reqPermissions": [
{
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // Continuous task permission
}
]
}
```
2. Request a continuous task. ## How to Develop
```js ### Development on the FA Model
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent';
let wantAgentInfo = { For details about how to use the Service ability in the FA model, see [Service Ability Development](../ability/fa-serviceability.md).
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
// Obtain the WantAgent object by using the getWantAgent API of the wantAgent module.
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err);
});
});
```
3. Cancel the continuous task.
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility';
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
``` If an application does not need to interact with a continuous task in the background, you can use **startAbility()** to start the Service ability. In the **onStart** callback of the Service ability, call **startBackgroundRunning()** to declare that the Service ability needs to run in the background for a long time. After the task execution is complete, call **stopBackgroundRunning()** to release resources.
Development on the stage model: If an application needs to interact with a continuous task in the background (for example, an application related to music playback), you can use **connectAbility()** to start and connect to the Service ability. After obtaining the proxy of the Service ability, the application can communicate with the Service ability and control the request and cancellation of continuous tasks.
1. Create an API version 9 project. Then right-click the project directory and choose **New > Ability** to create an ability. Configure the continuous task permission and background mode type in the **module.json5** file. 1. Create an API version 8 project. Then right-click the project directory and choose **New > Ability > Service Ability** to create a Service ability. Configure the continuous task permission (**ohos.permission.KEEP_BACKGROUND_RUNNING**) and background mode type in the **config.json** file, with the ability type set to **service**.
``` ```
"module": { "module": {
"abilities": [ "package": "com.example.myapplication",
"abilities": [
{ {
"backgroundModes": [ "backgroundModes": [
"dataTransfer", "dataTransfer",
"location" "location"
], // Background mode ], // Background mode
"type": "service" // The ability type is service.
} }
], ],
"requestPermissions": [ "reqPermissions": [
{ {
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // Continuous task permission "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // Continuous task permission
} }
] ]
} }
``` ```
2. Request a continuous task.
```ts
import backgroundTaskManager from '@ohos.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent';
let wantAgentInfo = {
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility"
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
// Obtain the WantAgent object by using the getWantAgent API of the wantAgent module.
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(this.context,
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err);
});
});
```
3. Cancel the continuous task.
```ts
import backgroundTaskManager from '@ohos.backgroundTaskManager';
backgroundTaskManager.stopBackgroundRunning(this.context).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
```
### Development Examples
Development on the FA model:
For details about how to use the Service ability in the FA model, see [Service Ability Development](../ability/fa-serviceability.md).
If an application does not need to interact with a continuous task in the background, you can use **startAbility()** to start the Service ability. In the **onStart** callback of the Service ability, call **startBackgroundRunning()** to declare that the Service ability needs to run in the background for a long time. After the task execution is complete, call **stopBackgroundRunning()** to release resources. 2. Call the APIs for requesting and canceling a continuous task in the Service ability.
If an application needs to interact with a continuous task in the background (for example, an application related to music playback), you can use **connectAbility()** to start and connect to the Service ability. After obtaining the proxy of the Service ability, the application can communicate with the Service ability and control the request and cancellation of continuous tasks.
```js ```js
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import featureAbility from '@ohos.ability.featureAbility'; import featureAbility from '@ohos.ability.featureAbility';
import wantAgent from '@ohos.wantAgent'; import wantAgent from '@ohos.wantAgent';
import rpc from "@ohos.rpc"; import rpc from "@ohos.rpc";
...@@ -290,21 +91,29 @@ function startContinuousTask() { ...@@ -290,21 +91,29 @@ function startContinuousTask() {
// Obtain the WantAgent object by using the getWantAgent API of the wantAgent module. // Obtain the WantAgent object by using the getWantAgent API of the wantAgent module.
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), try {
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
console.info("Operation startBackgroundRunning succeeded"); backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
}).catch((err) => { console.info("Operation startBackgroundRunning succeeded");
console.error("Operation startBackgroundRunning failed Cause: " + err); }).catch((err) => {
}); console.error("Operation startBackgroundRunning failed Cause: " + err);
});
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
}); });
} }
function stopContinuousTask() { function stopContinuousTask() {
backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { try {
console.info("Operation stopBackgroundRunning succeeded"); backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
}).catch((err) => { console.info("Operation stopBackgroundRunning succeeded");
console.error("Operation stopBackgroundRunning failed Cause: " + err); }).catch((err) => {
}); console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
} }
async function processAsyncJobs() { async function processAsyncJobs() {
...@@ -368,16 +177,128 @@ export default { ...@@ -368,16 +177,128 @@ export default {
}; };
``` ```
Development on the stage model: ### Development on the Stage Model
For details about the stage model, see [Stage Model Overview](../ability/stage-brief.md). For details about the stage model, see [Stage Model Overview](../ability/stage-brief.md).
If an application needs to run a continuous task in the background, you can use **Call** to create and run an ability in the background. For details, see [Call Development](../ability/stage-call.md).
1. Create an API version 9 project. Then right-click the project directory and choose **New > Ability** to create an ability. Configure the continuous task permission (ohos.permission.KEEP_BACKGROUND_RUNNING) and background mode type in the **module.json5** file.
```
"module": {
"abilities": [
{
"backgroundModes": [
"dataTransfer",
"location"
], // Background mode
}
],
"requestPermissions": [
{
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING" // Continuous task permission
}
]
}
```
2. If an application needs to execute a continuous task for its own, include the execution logic in the Page ability. This is because an application cannot use **startAbilityByCall** to create and run its own ability in the background due to the restriction of ability startup controls. For details about how to use an ability in the stage model, see [Ability Development](../ability/stage-ability.md).
```ts
import wantAgent from '@ohos.wantAgent';
import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
@Entry
@Component
struct Index {
@State message: string = 'test'
// Use getContext to obtain the context of the Page ability.
private context: any = getContext(this)
startContinuousTask() {
let wantAgentInfo = {
// List of operations to be executed after the notification is clicked.
wants: [
{
bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility",
}
],
// Type of the operation to perform after the notification is clicked.
operationType: wantAgent.OperationType.START_ABILITY,
// Custom request code.
requestCode: 0,
// Execution attribute of the operation to perform after the notification is clicked.
wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
// Obtain the WantAgent object by using the getWantAgent API of the wantAgent module.
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
try {
backgroundTaskManager.startBackgroundRunning(this.context,
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
console.info("Operation startBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation startBackgroundRunning failed Cause: " + err);
});
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
});
}
stopContinuousTask() {
try {
backgroundTaskManager.stopBackgroundRunning(this.context).then(() => {
console.info("Operation stopBackgroundRunning succeeded");
}).catch((err) => {
console.error("Operation stopBackgroundRunning failed Cause: " + err);
});
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
}
build() {
Row() {
Column() {
Text("Index")
.fontSize(50)
.fontWeight(FontWeight.Bold)
Button() { Text('Request continuous task').fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule)
.margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40)
.onClick(() => {
// Request a continuous task by clicking a button.
this.startContinuousTask();
// Execute the continuous task logic, for example, music playback.
})
Button() {Text('Cancel continuous task') .fontSize(25).fontWeight(FontWeight.Bold) }.type(ButtonType.Capsule)
.margin({ top: 10 }).backgroundColor('#0D9FFB').width(250).height(40)
.onClick(() => {
// Stop the continuous task.
// Cancel the continuous task by clicking a button.
this.stopContinuousTask();
})
}
.width('100%')
}
.height('100%')
}
}
```
3. If a continuous task needs to be executed in the background for another application or on another device, you can create and run an ability in the background in Call mode. For details, see [Call Development](../ability/stage-call.md).
```ts ```ts
import Ability from '@ohos.application.Ability' import Ability from '@ohos.application.Ability'
import backgroundTaskManager from '@ohos.backgroundTaskManager'; import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';
import wantAgent from '@ohos.wantAgent'; import wantAgent from '@ohos.wantAgent';
const MSG_SEND_METHOD: string = 'CallSendMsg'
let mContext = null; let mContext = null;
function startContinuousTask() { function startContinuousTask() {
...@@ -386,7 +307,7 @@ function startContinuousTask() { ...@@ -386,7 +307,7 @@ function startContinuousTask() {
wants: [ wants: [
{ {
bundleName: "com.example.myapplication", bundleName: "com.example.myapplication",
abilityName: "com.example.myapplication.MainAbility" abilityName: "com.example.myapplication.MainAbility",
} }
], ],
// Type of the operation to perform after the notification is clicked. // Type of the operation to perform after the notification is clicked.
...@@ -399,21 +320,29 @@ function startContinuousTask() { ...@@ -399,21 +320,29 @@ function startContinuousTask() {
// Obtain the WantAgent object by using the getWantAgent API of the wantAgent module. // Obtain the WantAgent object by using the getWantAgent API of the wantAgent module.
wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => {
backgroundTaskManager.startBackgroundRunning(mContext, try {
backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(),
console.info("Operation startBackgroundRunning succeeded"); backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => {
}).catch((err) => { console.info("Operation startBackgroundRunning succeeded");
console.error("Operation startBackgroundRunning failed Cause: " + err); }).catch((error) => {
}); console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
});
} catch (error) {
console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
}); });
} }
function stopContinuousTask() { function stopContinuousTask() {
backgroundTaskManager.stopBackgroundRunning(mContext).then(() => { try {
console.info("Operation stopBackgroundRunning succeeded"); backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => {
}).catch((err) => { console.info("Operation stopBackgroundRunning succeeded");
console.error("Operation stopBackgroundRunning failed Cause: " + err); }).catch((err) => {
}); console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
});
} catch (error) {
console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`);
}
} }
class MySequenceable { class MySequenceable {
...@@ -440,15 +369,16 @@ class MySequenceable { ...@@ -440,15 +369,16 @@ class MySequenceable {
function sendMsgCallback(data) { function sendMsgCallback(data) {
console.info('BgTaskAbility funcCallBack is called ' + data) console.info('BgTaskAbility funcCallBack is called ' + data)
let receivedData = new Mysequenceable(0, "") let receivedData = new MySequenceable(0, "")
data.readSequenceable(receivedData) data.readSequenceable(receivedData)
console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`) console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`)
// You can execute different methods based on the str value in the sequenceable data sent by the caller.
if (receivedData.str === 'start_bgtask') { if (receivedData.str === 'start_bgtask') {
startContinuousTask() startContinuousTask()
} else if (receivedData.str === 'stop_bgtask') { } else if (receivedData.str === 'stop_bgtask') {
stopContinuousTask(); stopContinuousTask();
} }
return new Mysequenceable(10, "Callee test"); return new MySequenceable(10, "Callee test");
} }
export default class BgTaskAbility extends Ability { export default class BgTaskAbility extends Ability {
...@@ -471,7 +401,7 @@ export default class BgTaskAbility extends Ability { ...@@ -471,7 +401,7 @@ export default class BgTaskAbility extends Ability {
onWindowStageCreate(windowStage) { onWindowStageCreate(windowStage) {
console.info("[Demo] BgTaskAbility onWindowStageCreate") console.info("[Demo] BgTaskAbility onWindowStageCreate")
windowStage.loadContent("pages/second").then((data)=> { windowStage.loadContent("pages/index").then((data)=> {
console.info(`load content succeed with data ${JSON.stringify(data)}`) console.info(`load content succeed with data ${JSON.stringify(data)}`)
}).catch((error)=>{ }).catch((error)=>{
console.error(`load content failed with error ${JSON.stringify(error)}`) console.error(`load content failed with error ${JSON.stringify(error)}`)
...@@ -491,90 +421,3 @@ export default class BgTaskAbility extends Ability { ...@@ -491,90 +421,3 @@ export default class BgTaskAbility extends Ability {
} }
}; };
``` ```
## Efficiency Resources
### Available APIs
**Table 4** Main APIs for efficiency resources
| API | Description |
| ---------------------------------------- | ---------------------------------------- |
| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): boolean | Requests efficiency resources.|
| resetAllEfficiencyResources():void | Releases efficiency resources. |
### How to Develop
1. Request efficiency resources.
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let request = {
resourceTypes: backgroundTaskManager.ResourceType.CPU,
isApply: true,
timeOut: 0,
reason: "apply",
isPersist: true,
isProcess: true,
};
let res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res);
```
2. Release some efficiency resources.
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let request = {
resourceTypes: backgroundTaskManager.ResourceType.CPU,
isApply: false,
timeOut: 0,
reason: "reset",
};
let res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res);
```
3. Release all efficiency resources.
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
```
### Development Examples
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
// Apply for efficiency resources.
let request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT |
backgroundTaskManager.ResourceType.TIMER,
isApply: true,
timeOut: 0,
reason: "apply",
isPersist: true,
isProcess: true,
};
let res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res);
// Release some efficiency resources.
request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT,
isApply: false,
timeOut: 0,
reason: "reset",
};
res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res);
// Release all efficiency resources.
backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources();
```
en/application-dev/task-management/efficiency-resources-apply-dev-guide.md 0 → 100644
浏览文件 @ 49c181a2
## Efficiency Resource Request Development
### When to Use
To further balance power consumption overhead of the system, privileged system applications can be suspended in the background as other applications. To ensure normal provisioning of important functions, efficiency resource APIs are provided for these applications so that they can execute special tasks and use specific system resources in the background. For example, if they want to receive common events when suspended, they can use the APIs to request the common event resources.
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.
### Available APIs
**Table 1** Main APIs for efficiency resources
| API | Description |
| ---------------------------------------- | ---------------------------------------- |
| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): boolean | Requests efficiency resources.|
| resetAllEfficiencyResources():void | Releases efficiency resources. |
### How to Develop
1. When a privileged application in the background needs to use special resources, request the target resources from the system.
2. When the task is complete, release the resources in time. You can choose whether to release some or all resources.
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
// Request efficiency resources.
let request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT |
backgroundTaskManager.ResourceType.TIMER,
isApply: true,
timeOut: 0,
reason: "apply",
isPersist: true,
isProcess: true,
};
let res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res);
// Release some efficiency resources.
request = {
resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT,
isApply: false,
timeOut: 0,
reason: "reset",
};
res = backgroundTaskManager.applyEfficiencyResources(request);
console.info("the result of request is: " + res);
// Release all efficiency resources.
backgroundTaskManager.resetAllEfficiencyResources();
```
<!--no_check-->
\ No newline at end of file
en/application-dev/task-management/transient-task-dev-guide.md 0 → 100644
浏览文件 @ 49c181a2
# Transient Task Development
## When to Use
By default, an application can run for 6 to 12 seconds after it switches to the background but before being suspended. If an application requires more time to execute an important task, it can call the **requestSuspendDelay** API to delay the suspension.
It is recommended that an application calls the **requestSuspendDelay** API before executing any time-consuming task, rather than when it is already running in the background.
The calling of the **requestSuspendDelay** API when the application is running in the foreground does not affect the transient task quota of the application.
Each application has a daily time quota for transient tasks. Therefore, after the time-consuming task finishes execution, the application should cancel the transient task in a timely manner.
Typical time-consuming tasks include saving status data to the local database, opening and processing a large file, and synchronizing data to the cloud server.
## Available APIs
**Table 1** Main APIs for transient tasks
| API | Description |
| ---------------------------------------- | ---------------------------------------- |
| requestSuspendDelay(reason: string, callback: Callback&lt;void&gt;): [DelaySuspendInfo](../reference/apis/js-apis-backgroundTaskManager.md#delaysuspendinfo) | Requests delayed suspension after the application switches to the background.<br>The default duration value of delayed suspension is 3 minutes when the battery level is normal and 1 minute when the battery level is low.|
| getRemainingDelayTime(requestId: number): Promise&lt;number&gt; | Obtains the remaining duration before the application is suspended.<br>This API uses a promise to return the result. |
| cancelSuspendDelay(requestId: number): void | Cancels the suspension delay. |
## How to Develop
1. When an application needs to execute a time-consuming task, call the API to request a transient task. After the time-consuming task finishes execution, call the API to cancel the transient task.
```js
import backgroundTaskManager from '@ohos.backgroundTaskManager';
let delayInfo;
let id;
// Request a suspension delay.
function requestSuspendDelay() {
let myReason = 'test requestSuspendDelay';
delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => {
console.info("Request suspension delay will time out.");
// The callback in invoked to notify the application that the suspension delay request is about to time out. The application needs to perform some cleanup and annotation operations.
});
id = delayInfo.requestId;
console.info("requestId is: " + id);
}
// Obtain the remaining duration before the application is suspended.
function getRemainingDelayTime() {
let delayTime = 0;
backgroundTaskManager.getRemainingDelayTime(id).then((res) => {
console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res));
delayTime = res;
}).catch((err) => {
console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.code);
});
return delayTime;
}
// Cancel the suspension delay.
function cancelSuspendDelay() {
backgroundTaskManager.cancelSuspendDelay(id);
}
function performingLongRunningTask() {
// Before executing the time-consuming task, call the API to request a transient task to delay the suspension.
requestSuspendDelay();
// Obtain the available time quota through the getRemainingDelayTime() API.
let delayTime = getRemainingDelayTime();
if (delayTime < 0) {// If the time is less than a certain value, cancel the time-consuming operation.
// Handle the scenario where the time quota is insufficient.
cancelSuspendDelay();
return;
}
// Execute the time-consuming task.
// After the time-consuming task is executed, call the API to cancel the transient task.
cancelSuspendDelay();
}
```
en/application-dev/task-management/work-scheduler-dev-guide.md
浏览文件 @ 49c181a2
...@@ -2,53 +2,39 @@ ...@@ -2,53 +2,39 @@
## When to Use ## 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. For details about the constraints on the Work Scheduler usage, see [Work Scheduler Overview](./work-scheduler-overview.md). 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. For details about the restrictions, see [Restrictions on Using Work Scheduler](./background-task-overview.md#restrictions-on-using-work-scheduler).
## Available APIs ## 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 **Table 1** Major workScheduler APIs
API | Description API | Description
------------------------------------------------------------ | ------------------------------------------------------------ ---------------------------------------------------------|-----------------------------------------
startWork(work: WorkInfo): boolean | Starts a Work Scheduler task. startWork(work: WorkInfo): void; | Starts a Work Scheduler task.
stopWork(work: WorkInfo, needCancel?: boolean): boolean | Stops a Work Scheduler task. stopWork(work: WorkInfo, needCancel?: boolean): void; | Stops a Work Scheduler task.
getWorkStatus(workId: number, callback: AsyncCallback\<WorkInfo>): void | Obtains the status of a Work Scheduler task. This API uses an asynchronous callback to return the result. getWorkStatus(workId: number, callback: AsyncCallback\<WorkInfo>): void;| Obtains the status of a Work Scheduler task. This API uses an asynchronous callback to return the result.
getWorkStatus(workId: number): Promise\<WorkInfo> | Obtains the status of a Work Scheduler task. This API uses a promise to return the result. getWorkStatus(workId: number): Promise\<WorkInfo>; | Obtains the status of a Work Scheduler task. This API uses a promise to return the result.
obtainAllWorks(callback: AsyncCallback\<void>): Array\<WorkInfo> | Obtains Work Scheduler tasks. This API uses an asynchronous callback to return the result. obtainAllWorks(callback: AsyncCallback\<void>): Array\<WorkInfo>;| Obtains Work Scheduler tasks. This API uses an asynchronous callback to return the result.
obtainAllWorks(): Promise<Array\<WorkInfo>> | Obtains Work Scheduler tasks. This API uses a promise to return the result. obtainAllWorks(): Promise<Array\<WorkInfo>>;| Obtains Work Scheduler tasks. This API uses a promise to return the result.
stopAndClearWorks(): boolean; | Stops and clears Work Scheduler tasks. stopAndClearWorks(): void;| Stops and clears Work Scheduler tasks.
isLastWorkTimeOut(workId: number, callback: AsyncCallback\<void>): boolean | Checks whether the last execution of the specified task has timed out. This API uses an asynchronous callback to return the result. It is applicable to repeated tasks. isLastWorkTimeOut(workId: number, callback: AsyncCallback\<void>): boolean;| Checks whether the last execution of the specified task has timed out. This API uses an asynchronous callback to return the result. It is applicable to repeated tasks.
isLastWorkTimeOut(workId: number): Promise\<boolean> | Checks whether the last execution of the specified task has timed out. This API uses a promise to return the result. It is applicable to repeated tasks. isLastWorkTimeOut(workId: number): Promise\<boolean>;| Checks whether the last execution of the specified task has timed out. This API uses a promise to return the result. It is applicable to repeated tasks.
**Table 2** WorkInfo parameters **Table 2** WorkInfo parameters
> **NOTE** For details about the constraints on configuring **WorkInfo**, see [Restrictions on Using Work Scheduler](./background-task-overview.md#restrictions-on-using-work-scheduler).
>
> For details about the constraints on configuring **WorkInfo**, see [Work Scheduler Overview](./work-scheduler-overview.md).
Name| Type|Description Name| Type|Description
---------------------------------------------------------|-----------------------------------------|--------------------------------------------------------- ---------------------------------------------------------|-----------------------------------------|---------------------------------------------------------
workId| number | Work ID. Mandatory. workId| number | Work ID. Mandatory.
bundleName| string | Name of the Work Scheduler task bundle. Mandatory. bundleName| string | Name of the Work Scheduler task bundle. Mandatory.
abilityName| string | Name of the component to be notified by a Work Scheduler callback. Mandatory. abilityName| string | Name of the component to be notified by a Work Scheduler callback. Mandatory.
networkType | [NetworkType](../reference/apis/js-apis-workScheduler.md#networktype) | Network type. networkType | [NetworkType](../reference/apis/js-apis-resourceschedule-workScheduler.md#networktype) | Network type.
isCharging| boolean | Whether the device is charging. isCharging| boolean | Whether the device is charging.
chargerType| [ChargingType](../reference/apis/js-apis-workScheduler.md#chargingtype) | Charging type. chargerType| [ChargingType](../reference/apis/js-apis-resourceschedule-workScheduler.md#chargingtype) | Charging type.
batteryLevel| number | Battery level. batteryLevel| number | Battery level.
batteryStatus| [BatteryStatus](../reference/apis/js-apis-workScheduler.md#batterystatus) | Battery status. batteryStatus| [BatteryStatus](../reference/apis/js-apis-resourceschedule-workScheduler.md#batterystatus) | Battery status.
storageRequest| [StorageRequest](../reference/apis/js-apis-workScheduler.md#storagerequest) |Storage status. storageRequest| [StorageRequest](../reference/apis/js-apis-resourceschedule-workScheduler.md#storagerequest) |Storage status.
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.
...@@ -63,135 +49,149 @@ onWorkStop(work: WorkInfo): void | Triggered when the Work Scheduler task stops. ...@@ -63,135 +49,149 @@ onWorkStop(work: WorkInfo): void | Triggered when the Work Scheduler task stops.
### How to Develop ### How to Develop
**Implementing WorkSchedulerExtensionAbility** 1. Import the modules.
import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility'; Import the **workScheduler** package to implement registration:
```js
export default class MyWorkSchedulerExtensionAbility extends WorkSchedulerExtensionAbility { import workScheduler from '@ohos.resourceschedule.workScheduler';
onWorkStart(workInfo) { ```
console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(workInfo));
} Import the **WorkSchedulerExtensionAbility** package to implement callback:
onWorkStop(workInfo) { ```js
console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo)); import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility';
} ```
}
2. Develop an Extension ability to execute a Work Scheduler task. For details about the Extension ability, see [ExtensionAbility Mechanism](../ability/stage-brief.md#extensionability-mechanism).
**Registering a Work Scheduler Task** ```ts
import WorkSchedulerExtensionAbility from '@ohos.WorkSchedulerExtensionAbility';
import workScheduler from '@ohos.workScheduler'; export default class MyExtension extends WorkSchedulerExtensionAbility {
onWorkStart(workInfo) {
let workInfo = { console.log('MyWorkSchedulerExtensionAbility onWorkStart' + JSON.stringify(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); onWorkStop(workInfo) {
console.info("workschedulerLog res:" + res); console.log('MyWorkSchedulerExtensionAbility onWorkStop' + JSON.stringify(workInfo));
}
}
```
**Canceling the Work Scheduler Task**
3. Register a Work Scheduler task.
import workScheduler from '@ohos.workScheduler'; ```ts
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
} }
} }
var res = workScheduler.stopWork(workInfo, false); try{
console.info("workschedulerLog res:" + res); workScheduler.startWork(workInfo);
console.info('workschedulerLog startWork success');
} catch (error) {
**Obtaining a Specified Work Scheduler Task** console.error(`workschedulerLog startwork failed. code is ${error.code} message is ${error.message}`);
}
```
1. Callback syntax
workScheduler.getWorkStatus(50, (err, res) => { 4. Cancel the Work Scheduler task.
if (err) {
console.info('workschedulerLog getWorkStatus failed, because:' + err.code); ```ts
} else { import workScheduler from '@ohos.resourceschedule.workScheduler';
for (let item in res) {
console.info('workschedulerLog getWorkStatuscallback success,' + item + ' is:' + res[item]); 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}`);
}
```
2. Promise syntax 5. Obtain a specified Work Scheduler task.
workScheduler.getWorkStatus(50).then((res) => { ```ts
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) { for (let item in res) {
console.info('workschedulerLog getWorkStatus success,' + item + ' is:' + res[item]); console.info(`workschedulerLog getWorkStatus success, ${item} is: ${res[item]}`);
} }
}).catch((err) => { }
console.info('workschedulerLog getWorkStatus failed, because:' + err.code); });
}) } catch (error) {
console.error(`workschedulerLog getWorkStatus failed. code is ${error.code} message is ${error.message}`);
}
**Obtaining All Work Scheduler Tasks** ```
1. Callback syntax
workScheduler.obtainAllWorks((err, res) =>{ 6. Obtain all Work Scheduler tasks.
if (err) {
console.info('workschedulerLog obtainAllWorks failed, because:' + err.code);
} else {
console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res));
}
});
2. Promise syntax ```ts
try{
workScheduler.obtainAllWorks().then((res) => { workScheduler.obtainAllWorks((error, res) =>{
console.info('workschedulerLog obtainAllWorks success, data is:' + JSON.stringify(res)); if (error) {
}).catch((err) => { console.error(`workschedulerLog obtainAllWorks failed. code is ${error.code} message is ${error.message}`);
console.info('workschedulerLog obtainAllWorks failed, because:' + err.code); } 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}`);
}
```
**Stopping and Clearing Work Scheduler Tasks** 7. Stop and clear Work Scheduler tasks.
let res = workScheduler.stopAndClearWorks(); ```ts
console.info("workschedulerLog res:" + res); try{
workScheduler.stopAndClearWorks();
console.info(`workschedulerLog stopAndClearWorks success`);
} catch (error) {
console.error(`workschedulerLog stopAndClearWorks failed. code is ${error.code} message is ${error.message}`);
}
```
**Checking Whether the Last Execution Has Timed Out** 8. Check whether the last execution has timed out.
1. Callback syntax ```ts
try{
workScheduler.isLastWorkTimeOut(500, (error, res) =>{
if (error) {
onsole.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(500, (err, res) =>{
if (err) {
console.info('workschedulerLog isLastWorkTimeOut failed, because:' + err.code);
} 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.code);
});
})
en/application-dev/task-management/work-scheduler-overview.md 已删除 100644 → 0
浏览文件 @ b0fa0e39
# 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.
- **Execution frequency**: The system controls the execution frequency of Work Scheduler tasks based on the activity level of their respective applications.
Application Group | Work Scheduler Task Execution Frequency
--------------------|-------------------------
Active| At a minimum interval of 2 hours
Used every day| At a minimum interval of 4 hours
Frequently used| At a minimum interval of 24 hours
Infrequently used| At a minimum interval of 48 hours
Restricted| Prohibited
Unused| Prohibited
- **WorkInfo setting**
- **workId**, **bundleName**, and **abilityName** are mandatory. **bundleName** must be set to the name of the current application. Otherwise, the verification will fail.
- At least one condition must be set.
- The repeat interval must be at least 20 minutes and must work with the Always repeat pattern or repeat times.
- The carried parameters can be of the number, string, or bool type.
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或