diff --git a/en/application-dev/device-usage-statistics/Readme-EN.md b/en/application-dev/device-usage-statistics/Readme-EN.md new file mode 100644 index 0000000000000000000000000000000000000000..75cfad35e1f36bfe07f0cb408c936f87e0ee520a --- /dev/null +++ b/en/application-dev/device-usage-statistics/Readme-EN.md @@ -0,0 +1,4 @@ +# Device Usage Statistics + +- [Device Usage Statistics Overview](device-usage-statistics-overview.md) +- [Device Usage Statistics Development](device-usage-statistics-dev-guide.md) diff --git a/en/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md b/en/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..ed6d64d2f532114c44220f493fcdce9180d0aa1f --- /dev/null +++ b/en/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md @@ -0,0 +1,207 @@ +## 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<Array<BundleActiveState>>): void | Queries events of all applications based on the specified start time and end time.| +| function queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback<BundleActiveInfoResponse>): void | Queries the application usage duration statistics based on the specified start time and end time.| +| function queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): 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<Array<BundleStateInfo>>): 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<number>): void | Queries the priority group of the current invoker application.| +| function isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void | Checks whether the application specified by **bundleName** is in the idle state. | + +## 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' + + // Use a promise to return the result. + 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); + }); + + // Use an asynchronous callback to return the result. + stats.queryBundleActiveStates(0, 20000000000000, (err, res) => { + if(err.code == 0) { + 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])); + } + } else { + console.log('BUNDLE_ACTIVE queryBundleActiveStates callback failed, because: ' + err.code); + } + }); + ``` + +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' + + // Use a promise to return the result. + 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); + }); + + // Use an asynchronous callback to return the result. + stats.queryBundleStateInfos(0, 20000000000000, (err, res) => { + if(err.code == 0) { + 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++; + } + } else { + console.log('BUNDLE_ACTIVE queryBundleStateInfos callback failed, because: ' + err.code); + } + }); + ``` + +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' + + // Use a promise to return the result. + 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); + }); + + // Use an asynchronous callback to return the result. + stats.queryCurrentBundleActiveStates(0, 20000000000000, (err, res) => { + if(err.code == 0) { + 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])); + } + } else { + console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback failed, because: ' + err.code); + } + }); + ``` + +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' + + // Use a promise to return the result. + 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); + }); + + // Use an asynchronous callback to return the result. + stats.queryBundleStateInfoByInterval(0, 0, 20000000000000, (err, res) => { + if(err.code == 0) { + 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])); + } + } else { + console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code); + } + }); + ``` + +6. Query the priority group of the current invoker application. This requires no permission to be configured in the **config.json** file. + + ```js + import stats from '@ohos.bundleState' + + // Use a promise to return the result. + 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); + }); + + // Use an asynchronous callback to return the result. + stats.queryAppUsagePriorityGroup((err, res) => { + if(err.code === 0) { + console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res)); + } else { + console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code); + } + }); + ``` + +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. + + ```js + import stats from '@ohos.bundleState' + + // Use a promise to return the result. + 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); + }); + + // Use an asynchronous callback to return the result. + stats.isIdleState("com.ohos.camera", (err, res) => { + if(err.code === 0) { + console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); + } else { + console.log('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code); + } + }); + ``` diff --git a/en/application-dev/device-usage-statistics/device-usage-statistics-overview.md b/en/application-dev/device-usage-statistics/device-usage-statistics-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..b34bd46548c94779dfa35ba21f1d7a5ea9ad01c3 --- /dev/null +++ b/en/application-dev/device-usage-statistics/device-usage-statistics-overview.md @@ -0,0 +1,24 @@ +# Device Usage Statistics Overview + +With device usage statistics APIs, you can have a better understanding of the application, notification, and system usage. 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. + +## Introduction + +Currently you can have access to statistics on the application usage, and notification and system usage statistics feature will be available for use in later versions. + +- **The application usage statistics is updated**: +>1. Every 30 minutes +>2. Upon system time change +>3. Upon start of a new day + +- **The application usage statistics can include the following**: +>1. Events of all applications based on the specified start time and end time +>2. Application usage duration statistics based on the specified start time and end time +>3. Events of the current application based on the specified start time and end time +>4. Application usage duration statistics in the specified time frame at the specified interval (daily, weekly, monthly, or annually) +>5. Priority group of the current invoker application +>6. Whether a specific application is in the idle state + +### Required Permissions +- The **queryBundleActiveStates**, **queryBundleStateInfos**, and **queryBundleStateInfoByInterval** APIs used for device usage statistics are system APIs. Before calling these APIs, you need to apply for the **ohos.permission.BUNDLE_ACTIVE_INFO** permission. +- This permission is not required for calling **queryCurrentBundleActiveStates**, **queryAppUsagePriorityGroup**, and **isIdleState**, which are third-party APIs. diff --git a/en/application-dev/reference/apis/js-apis-deviceUsageStatistics.md b/en/application-dev/reference/apis/js-apis-deviceUsageStatistics.md new file mode 100644 index 0000000000000000000000000000000000000000..4478eceb76e79a4ff0873eee07a6cd0fc2a6cf17 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-deviceUsageStatistics.md @@ -0,0 +1,443 @@ +# Device Usage Statistics + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> 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 + +``` +import bundleState from '@ohos.bundleState' +``` + +## bundleState.isIdleState +isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void
+Checks whether the application specified by **bundleName** is in the idle state. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns whether the application specified by **bundleName** is in the idle state if the value of **bundleName** is valid; returns **null** otherwise.| + +**Example** + + ``` + bundleState.isIdleState("com.ohos.camera", (err, res) => { + if(err.code === 0) { + console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); + } else { + console.log('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code); + } + }); + ``` + +## bundleState.isIdleState +isIdleState(bundleName: string): Promise<boolean>
+Checks whether the application specified by **bundleName** is in the idle state. This API uses a promise to return the result. + +**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<boolean> | Promise used to return the result. Returns whether the application specified by **bundleName** is in the idle state if the value of **bundleName** is valid; returns **null** otherwise.| + +**Example** + + ``` + bundleState.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); + }); + ``` + +## bundleState.queryAppUsagePriorityGroup +queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void
+Queries the priority group of the current invoker application. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<number> | Yes| Callback used to return the result.| + +**Example** + + ``` + bundleState.queryAppUsagePriorityGroup((err, res) => { + if(err.code === 0) { + console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res)); + } else { + console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code); + } + }); + ``` + +## bundleState.queryAppUsagePriorityGroup +queryAppUsagePriorityGroup(): Promise<number>
+Queries the priority group of the current invoker application. This API uses a promise to return the result. + +**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<number> | Promise used to return the result.| + +**Example** + + ``` + bundleState.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); + }); + ``` + +## bundleState.queryBundleStateInfos +queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback<BundleActiveInfoResponse>): 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 + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| begin | number | Yes| Start time.| +| end | number | Yes| End time.| +| callback | AsyncCallback<[BundleActiveInfoResponse](#bundleactiveinforesponse)> | Yes| Callback used to return the result.| + +**Example** + + ``` + bundleState.queryBundleStateInfos(0, 20000000000000, (err, res) => { + if(err.code == 0) { + 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++; + } + } else { + console.log('BUNDLE_ACTIVE queryBundleStateInfos callback failed, because: ' + err.code); + } + }); + ``` + +## bundleState.queryBundleStateInfos +queryBundleStateInfos(begin: number, end: number): Promise<BundleActiveInfoResponse>
+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 + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| begin | number | Yes| Start time.| +| end | number | Yes| End time.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[BundleActiveInfoResponse](#bundleactiveinforesponse)> | Promise used to return the result.| + +**Example** + + ``` + bundleState.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); + }); + ``` + +## bundleState.queryBundleStateInfoByInterval +queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback<Array<BundleStateInfo>>): 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 + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| byInterval | [IntervalType](#intervaltype) | Yes| Interval type.| +| begin | number | Yes| Start time.| +| end | number | Yes| End time.| +| callback | AsyncCallback<Array<[BundleStateInfo](#bundlestateinfo)>> | Yes| Callback used to return the result.| + +**Example** + + ``` + bundleState.queryBundleStateInfoByInterval(0, 0, 20000000000000, (err, res) => { + if(err.code == 0) { + 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])); + } + } else { + console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code); + } + }); + ``` + +## bundleState.queryBundleStateInfoByInterval +queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number): Promise<Array<BundleStateInfo>>
+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 + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| byInterval | [IntervalType](#intervaltype) | Yes| Interval type.| +| begin | number | Yes| Start time.| +| end | number | Yes| End time.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<Array<[BundleStateInfo](#bundlestateinfo)>> | Promise used to return the result.| + +**Example** + + ``` + bundleState.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); + }); + ``` + +## bundleState.queryBundleActiveStates +queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): 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 + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| begin | number | Yes| Start time.| +| end | number | Yes| End time.| +| callback | AsyncCallback<Array<[BundleActiveState](#bundleactivestate)>> | Yes| Callback used to return the result.| + +**Example** + + ``` + bundleState.queryBundleActiveStates(0, 20000000000000, (err, res) => { + if(err.code == 0) { + 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])); + } + } else { + console.log('BUNDLE_ACTIVE queryBundleActiveStates callback failed, because: ' + err.code); + } + }); + ``` + +## bundleState.queryBundleActiveStates +queryBundleActiveStates(begin: number, end: number): Promise<Array<BundleActiveState>>
+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 + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| begin | number | Yes| Start time.| +| end | number | Yes| End time.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<Array<[BundleActiveState](#bundleactivestate)>> | Promise used to return the result.| + +**Example** + + ``` + bundleState.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); + }); + ``` + +## bundleState.queryCurrentBundleActiveStates +queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): 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<Array<[BundleActiveState](#bundleactivestate)>> | Yes| Callback used to return the result.| + +**Example** + + ``` + bundleState.queryCurrentBundleActiveStates(0, 20000000000000, (err, res) => { + if(err.code == 0) { + 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])); + } + } else { + console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback failed, because: ' + err.code); + } + }); + ``` + +## bundleState.queryCurrentBundleActiveStates +queryCurrentBundleActiveStates(begin: number, end: number): Promise<Array<BundleActiveState>>
+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<Array<[BundleActiveState](#bundleactivestate)>> | Promise used to return the result.| + +**Example** + + ``` + bundleState.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); + }); + ``` + +## BundleStateInfo +Provides the usage duration information of an application. + +### Attributes +**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Application bundle name.| +| 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.
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.
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 when the application is visible in the foreground.
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.
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.
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.
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 last application usage record in the **BundleActiveInfo** object.
This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| + +### merge +merge(toMerge: BundleStateInfo): void + +Merges the application usage information that has the same bundle name.
+This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR. + +**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| toMerge | [BundleStateInfo](#bundlestateinfo) | Yes| Application usage information to merge.| + +## BundleActiveState +Provides information about an application event. + +**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Application bundle name.| +| stateType | number | Yes| Application event type.| +| stateOccurredTime | number | Yes| Timestamp when the application event occurs.| +| appUsagePriorityGroup | number | No| Usage priority group of the application.
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.
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.
This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| + +## BundleActiveInfoResponse +Provides the usage duration information of applications. + +**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| [key: string]: BundleStateInfo | [BundleStateInfo](#bundlestateinfo) | Yes| Usage duration information by application.| + +## 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 obtains the application usage duration statistics in the specified time frame at the interval the system deems appropriate.| +| BY_DAILY | 1 | The system obtains the application usage duration statistics in the specified time frame on a daily 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_ANNUALLY | 4 | The system obtains the application usage duration statistics in the specified time frame on an annual basis.|