From e1978c3dd434d1f0d17731b90e6ec1577e5d83c8 Mon Sep 17 00:00:00 2001 From: wusongqing Date: Thu, 12 May 2022 16:50:48 +0800 Subject: [PATCH] updated docs Signed-off-by: wusongqing --- .../background-task-dev-guide.md | 84 ++++++++++++++----- .../apis/js-apis-backgroundTaskManager.md | 37 ++++---- 2 files changed, 84 insertions(+), 37 deletions(-) diff --git a/en/application-dev/background-task-management/background-task-dev-guide.md b/en/application-dev/background-task-management/background-task-dev-guide.md index c96dfca665..4847e4745b 100644 --- a/en/application-dev/background-task-management/background-task-dev-guide.md +++ b/en/application-dev/background-task-management/background-task-dev-guide.md @@ -42,7 +42,8 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager'; console.info("Request suspension delay will time out."); }); - var id = delayInfo.requestId;console.info("requestId is: " + id); + var id = delayInfo.requestId; + console.info("requestId is: " + id); ``` @@ -50,9 +51,9 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager'; ```js backgroundTaskManager.getRemainingDelayTime(id).then( res => { - console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); + console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); }).catch( err => { - console.log('promise => Operation failed. Cause: ' + err.data); + console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.data); }); ``` @@ -83,9 +84,9 @@ console.info("The actualDelayTime is: " + time); // Obtain the remaining duration before the application is suspended. backgroundTaskManager.getRemainingDelayTime(id).then( res => { - console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); + console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); }).catch( err => { - console.log('promise => Operation failed. Cause: ' + err.data); + console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.data); }); // Cancel the suspension delay. @@ -110,7 +111,7 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA **Table 4** Background modes -| Name| ID Value| Description| Item| +| Name| ID| Description| Item| | -------- | -------- | -------- | -------- | | DATA_TRANSFER | 1 | Data transfer.| dataTransfer | | AUDIO_PLAYBACK | 2 | Audio playback.| audioPlayback | @@ -125,9 +126,9 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA ## How to Develop -1. Configure the continuous task permission and background mode type in the **config.json** file, with the ability type set to **service**. +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**. - ```json + ``` "module": { "package": "com.example.myapplication", @@ -172,16 +173,16 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA ], operationType: wantAgent.OperationType.START_ABILITY, requestCode: 0, - wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] }; - // Obtain the WantAgent object by using the getWantAgent method of the wantAgent module. + // 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 succeeded"); + console.info("Operation startBackgroundRunning succeeded"); }).catch((err) => { - console.error("Operation failed Cause: " + err); + console.error("Operation startBackgroundRunning failed Cause: " + err); }); }); ``` @@ -193,59 +194,98 @@ For details about **wantAgent**, see [WantAgent](../reference/apis/js-apis-wantA import featureAbility from '@ohos.ability.featureAbility'; backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { - console.info("Operation succeeded"); + console.info("Operation stopBackgroundRunning succeeded"); }).catch((err) => { - console.error("Operation failed Cause: " + err); + console.error("Operation stopBackgroundRunning failed Cause: " + err); }); ``` ## Development Examples +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. + After a service is started, call the API for requesting a continuous task in the **onStart** callback of the Service ability to declare that the service needs to run in the background for a long time. In the **onStop** callback, call the API for canceling the continuous task. -In the **service.js** file: +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 import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; import wantAgent from '@ohos.wantAgent'; +import rpc from "@ohos.rpc"; function startBackgroundRunning() { 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, - wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] + // 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 method of the wantAgent module. + // 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 succeeded"); + console.info("Operation startBackgroundRunning succeeded"); }).catch((err) => { - console.error("Operation failed Cause: " + err); + console.error("Operation startBackgroundRunning failed Cause: " + err); }); }); } function stopBackgroundRunning() { backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { - console.info("Operation succeeded"); + console.info("Operation stopBackgroundRunning succeeded"); }).catch((err) => { - console.error("Operation failed Cause: " + err); + console.error("Operation stopBackgroundRunning failed Cause: " + err); }); } +let mMyStub; + +class MyStub extends rpc.RemoteObject { + constructor(des) { + if (typeof des === 'string') { + super(des); + } else { + return null; + } + } + onRemoteRequest(code, data, reply, option) { + console.log('ServiceAbility onRemoteRequest called'); + // The meaning of code is user-defined. + if (code === 1) { + // Received the request code for requesting a continuous task. + startContinuousTask(); + // Execute the continuous task. + } else if (code === 2) { + // Received the request code for canceling the continuous task. + stopContinuousTask(); + } else { + console.log('ServiceAbility unknown request code'); + } + return true; + } +} + export default { onStart(want) { console.info('ServiceAbility onStart'); + mMyStub = new MyStub("ServiceAbility-test"); startBackgroundRunning(); + // Execute a specific continuous task in the background. + stopBackgroundRunning(); }, onStop() { console.info('ServiceAbility onStop'); @@ -253,7 +293,7 @@ export default { }, onConnect(want) { console.info('ServiceAbility onConnect'); - return {}; + return mMyStub; }, onReconnect(want) { console.info('ServiceAbility onReconnect'); diff --git a/en/application-dev/reference/apis/js-apis-backgroundTaskManager.md b/en/application-dev/reference/apis/js-apis-backgroundTaskManager.md index da5d93ba2a..1c15667d64 100644 --- a/en/application-dev/reference/apis/js-apis-backgroundTaskManager.md +++ b/en/application-dev/reference/apis/js-apis-backgroundTaskManager.md @@ -1,6 +1,7 @@ # Background Task Management > ![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. @@ -25,7 +26,7 @@ The default duration of delayed suspension is 180000 when the battery level is h | Name | Type | Mandatory | Description | | -------- | -------------------- | ---- | ------------------------------ | | reason | string | Yes | Reason for delayed transition to the suspended state. | -| callback | Callback<void> | 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<void> | 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 | @@ -33,11 +34,17 @@ The default duration of delayed suspension is 180000 when the battery level is h | [DelaySuspendInfo](#delaysuspendinfo) | Information about the suspension delay.| **Example** + ```js let myReason = 'test requestSuspendDelay'; 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); ``` @@ -61,9 +68,9 @@ Obtains the remaining duration before the application is suspended. This API use let id = 1; backgroundTaskManager.getRemainingDelayTime(id, (err, res) => { if(err.data === 0) { - console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); + console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); } else { - console.log('promise => Operation failed. Cause: ' + err.data); + console.log('callback => Operation getRemainingDelayTime failed. Cause: ' + err.data); } }) ``` @@ -91,9 +98,9 @@ Obtains the remaining duration before the application is suspended. This API use ```js let id = 1; backgroundTaskManager.getRemainingDelayTime(id).then( res => { - console.log('promise => Operation succeeded. Data: ' + JSON.stringify(res)); + console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); }).catch( err => { - console.log('promise => Operation failed. Cause: ' + err.data); + console.log('promise => Operation getRemainingDelayTime failed. Cause: ' + err.data); }) ``` @@ -143,9 +150,9 @@ import wantAgent from '@ohos.wantAgent'; function callback(err, data) { if (err) { - console.error("Operation failed Cause: " + err); + console.error("Operation startBackgroundRunning failed Cause: " + err); } else { - console.info("Operation succeeded"); + console.info("Operation startBackgroundRunning succeeded"); } } @@ -158,7 +165,7 @@ let wantAgentInfo = { ], operationType: wantAgent.OperationType.START_ABILITY, requestCode: 0, - wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] }; wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { @@ -206,15 +213,15 @@ let wantAgentInfo = { ], operationType: wantAgent.OperationType.START_ABILITY, requestCode: 0, - wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESET_FLAG] + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] }; wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj) => { backgroundTaskManager.startBackgroundRunning(featureAbility.getContext(), backgroundTaskManager.BackgroundMode.DATA_TRANSFER, wantAgentObj).then(() => { - console.info("Operation succeeded"); + console.info("Operation startBackgroundRunning succeeded"); }).catch((err) => { - console.error("Operation failed Cause: " + err); + console.error("Operation startBackgroundRunning failed Cause: " + err); }); }); @@ -241,9 +248,9 @@ import featureAbility from '@ohos.ability.featureAbility'; function callback(err, data) { if (err) { - console.error("Operation failed Cause: " + err); + console.error("Operation stopBackgroundRunning failed Cause: " + err); } else { - console.info("Operation succeeded"); + console.info("Operation stopBackgroundRunning succeeded"); } } @@ -275,9 +282,9 @@ import backgroundTaskManager from '@ohos.backgroundTaskManager'; import featureAbility from '@ohos.ability.featureAbility'; backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() => { - console.info("Operation succeeded"); + console.info("Operation stopBackgroundRunning succeeded"); }).catch((err) => { - console.error("Operation failed Cause: " + err); + console.error("Operation stopBackgroundRunning failed Cause: " + err); }); ``` -- GitLab