1# @ohos.resourceschedule.backgroundTaskManager (Background Task Management) 2 3The **backgroundTaskManager** module provides APIs to request background tasks. You can use the APIs to request transient tasks, continuous tasks, or efficiency resources to prevent the application process from being terminated or suspended when your application is switched to the background. 4 5> **NOTE** 6> 7> 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. 8 9 10## Modules to Import 11 12```ts 13import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 14``` 15 16## backgroundTaskManager.requestSuspendDelay 17 18requestSuspendDelay(reason: string, callback: Callback<void>): DelaySuspendInfo 19 20Requests a transient task. 21 22> **NOTE** 23> 24> For details about the constraints on requesting and using a transient task, see [Transient Task (ArkTS)](../../task-management/transient-task.md#constraints). 25 26**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 27 28**Parameters** 29 30| Name | Type | Mandatory | Description | 31| -------- | -------------------- | ---- | ------------------------------ | 32| reason | string | Yes | Reason for requesting the transient task. | 33| callback | Callback<void> | Yes | Callback used to notify the application that the transient task is about to time out. Generally, the callback is invoked 6 seconds before the timeout.| 34 35**Return value** 36 37| Type | Description | 38| ------------------------------------- | --------- | 39| [DelaySuspendInfo](#delaysuspendinfo) | Information about the transient task.| 40 41**Error codes** 42 43For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 44 45| ID | Error Message| 46| --------- | ------- | 47| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 48| 9800001 | Memory operation failed. | 49| 9800002 | Parcel operation failed. | 50| 9800003 | Internal transaction failed. | 51| 9800004 | System service operation failed. | 52| 9900001 | Caller information verification failed for a transient task. | 53| 9900002 | Transient task verification failed. | 54 55**Example** 56 57```ts 58import { BusinessError } from '@kit.BasicServicesKit'; 59 60let myReason = 'test requestSuspendDelay'; 61try { 62 let delayInfo = backgroundTaskManager.requestSuspendDelay(myReason, () => { 63 // Callback function, which is triggered when the transient task is about to time out. The application can carry out data clear and annotation, and cancel the task in the callback. 64 // The callback is independent of the service of the application. After the request for the transient task is successful, the application normally executes its own service logic. 65 console.info("Request suspension delay will time out."); 66 }) 67 let id = delayInfo.requestId; 68 let time = delayInfo.actualDelayTime; 69 console.info("The requestId is: " + id); 70 console.info("The actualDelayTime is: " + time); 71} catch (error) { 72 console.error(`requestSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 73} 74``` 75 76 77## backgroundTaskManager.getRemainingDelayTime 78 79getRemainingDelayTime(requestId: number, callback: AsyncCallback<number>): void 80 81Obtains the remaining time of a transient task. This API uses an asynchronous callback to return the result. 82 83**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 84 85**Parameters** 86 87| Name | Type | Mandatory | Description | 88| --------- | --------------------------- | ---- | ---------------------------------------- | 89| requestId | number | Yes | Request ID of the transient task. | 90| callback | AsyncCallback<number> | Yes | Callback used to return the remaining time, in milliseconds.| 91 92**Error codes** 93 94For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 95 96| ID | Error Message| 97| --------- | ------- | 98| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 99| 9800001 | Memory operation failed. | 100| 9800002 | Parcel operation failed. | 101| 9800003 | Internal transaction failed. | 102| 9800004 | System service operation failed. | 103| 9900001 | Caller information verification failed for a transient task. | 104| 9900002 | Transient task verification failed. | 105 106 107**Example** 108 109```ts 110import { BusinessError } from '@kit.BasicServicesKit'; 111 112let id = 1; 113backgroundTaskManager.getRemainingDelayTime(id, (error: BusinessError, res: number) => { 114 if(error) { 115 console.error(`callback => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`); 116 } else { 117 console.log('callback => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 118 } 119}) 120``` 121 122 123## backgroundTaskManager.getRemainingDelayTime 124 125getRemainingDelayTime(requestId: number): Promise<number> 126 127Obtains the remaining time of a transient task. This API uses a promise to return the result. 128 129**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 130 131**Parameters** 132 133| Name | Type | Mandatory | Description | 134| --------- | ------ | ---- | ---------- | 135| requestId | number | Yes | Request ID of the transient task.| 136 137**Return value** 138 139| Type | Description | 140| --------------------- | ---------------------------------------- | 141| Promise<number> | Promise used to return the remaining time, in milliseconds.| 142 143**Error codes** 144 145For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 146 147| ID | Error Message| 148| --------- | ------- | 149| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 150| 9800001 | Memory operation failed. | 151| 9800002 | Parcel operation failed. | 152| 9800003 | Internal transaction failed. | 153| 9800004 | System service operation failed. | 154| 9900001 | Caller information verification failed for a transient task. | 155| 9900002 | Transient task verification failed. | 156 157**Example** 158 159```ts 160import { BusinessError } from '@kit.BasicServicesKit'; 161 162let id = 1; 163backgroundTaskManager.getRemainingDelayTime(id).then((res: number) => { 164 console.log('promise => Operation getRemainingDelayTime succeeded. Data: ' + JSON.stringify(res)); 165}).catch((error: BusinessError) => { 166 console.error(`promise => Operation getRemainingDelayTime failed. code is ${error.code} message is ${error.message}`); 167}) 168``` 169 170 171## backgroundTaskManager.cancelSuspendDelay 172 173cancelSuspendDelay(requestId: number): void 174 175Cancels a transient task. 176 177**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 178 179**Parameters** 180 181| Name | Type | Mandatory | Description | 182| --------- | ------ | ---- | ---------- | 183| requestId | number | Yes | Request ID of the transient task.| 184 185**Error codes** 186 187For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 188 189| ID | Error Message| 190| --------- | ------- | 191| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 192| 9800001 | Memory operation failed. | 193| 9800002 | Parcel operation failed. | 194| 9800003 | Internal transaction failed. | 195| 9800004 | System service operation failed. | 196| 9900001 | Caller information verification failed for a transient task. | 197| 9900002 | Transient task verification failed. | 198 199**Example** 200 201 ```js 202 import { BusinessError } from '@kit.BasicServicesKit'; 203 204 let id = 1; 205 try { 206 backgroundTaskManager.cancelSuspendDelay(id); 207 } catch (error) { 208 console.error(`cancelSuspendDelay failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 209 } 210 ``` 211 212## backgroundTaskManager.startBackgroundRunning 213 214startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent, callback: AsyncCallback<void>): void 215 216Requests a continuous task of a specific type. This API uses an asynchronous callback to return the result. 217 218**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING 219 220**Atomic service API**: This API can be used in atomic services since API version 12. 221 222**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 223 224**Parameters** 225 226| Name | Type | Mandatory | Description | 227| --------- | ---------------------------------- | ---- | ---------------------------------------- | 228| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](../apis-ability-kit/js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-context.md).| 229| bgMode | [BackgroundMode](#backgroundmode) | Yes | Type of the continuous task. | 230| wantAgent | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) | Yes | Notification parameters, which are used to specify the target page that is redirected to when a continuous task notification is clicked. | 231| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the continuous task is requested, **err** is **undefined**. Otherwise, **err** is an error object. | 232 233**Error codes** 234 235For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 236 237| ID | Error Message | 238| ---- | --------------------- | 239| 201 | Permission denied. | 240| 202 | Not System App. | 241| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 242| 9800001 | Memory operation failed. | 243| 9800002 | Parcel operation failed. | 244| 9800003 | Internal transaction failed. | 245| 9800004 | System service operation failed. | 246| 9800005 | Continuous task verification failed. | 247| 9800006 | Notification verification failed for a continuous task. | 248| 9800007 | Continuous task storage failed. | 249 250**Example** 251 252```js 253import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 254import { BusinessError } from '@kit.BasicServicesKit'; 255import { wantAgent, WantAgent } from '@kit.AbilityKit'; 256import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 257 258function callback(error: BusinessError, data: void) { 259 if (error) { 260 console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 261 } else { 262 console.info("Operation startBackgroundRunning succeeded"); 263 } 264} 265 266export default class EntryAbility extends UIAbility { 267 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 268 let wantAgentInfo: wantAgent.WantAgentInfo = { 269 // List of operations to be executed after the notification is clicked. 270 wants: [ 271 { 272 bundleName: "com.example.myapplication", 273 abilityName: "EntryAbility" 274 } 275 ], 276 // Type of the operation to perform after the notification is clicked. 277 actionType: wantAgent.OperationType.START_ABILITY, 278 // Custom request code. 279 requestCode: 0, 280 // Execution attribute of the operation to perform after the notification is clicked. 281 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 282 }; 283 284 try { 285 // Obtain the WantAgent object by using the getWantAgent API of the wantAgent module. 286 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => { 287 try { 288 backgroundTaskManager.startBackgroundRunning(this.context, 289 backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj, callback) 290 } catch (error) { 291 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 292 } 293 }); 294 } catch (error) { 295 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 296 } 297 } 298}; 299``` 300 301## backgroundTaskManager.startBackgroundRunning 302 303startBackgroundRunning(context: Context, bgMode: BackgroundMode, wantAgent: WantAgent): Promise<void> 304 305Requests a continuous task of a specific type. This API uses a promise to return the result. 306 307**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING 308 309**Atomic service API**: This API can be used in atomic services since API version 12. 310 311**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 312 313**Parameters** 314 315| Name | Type | Mandatory | Description | 316| --------- | ---------------------------------- | ---- | ---------------------------------------- | 317| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](../apis-ability-kit/js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-context.md).| 318| bgMode | [BackgroundMode](#backgroundmode) | Yes | Type of the continuous task. | 319| wantAgent | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) | Yes | Notification parameters, which are used to specify the target page that is redirected to when a continuous task notification is clicked. | 320 321**Return value** 322 323| Type | Description | 324| -------------- | ---------------- | 325| Promise\<void> | Promise that returns no value.| 326 327**Error codes** 328 329For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 330 331| ID | Error Message | 332| ---- | --------------------- | 333| 201 | Permission denied. | 334| 202 | Not System App. | 335| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 336| 9800001 | Memory operation failed. | 337| 9800002 | Parcel operation failed. | 338| 9800003 | Internal transaction failed. | 339| 9800004 | System service operation failed. | 340| 9800005 | Continuous task verification failed. | 341| 9800006 | Notification verification failed for a continuous task. | 342| 9800007 | Continuous task storage failed. | 343 344**Example** 345 346```js 347import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 348import { BusinessError } from '@kit.BasicServicesKit'; 349import { wantAgent, WantAgent } from '@kit.AbilityKit'; 350import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 351 352export default class EntryAbility extends UIAbility { 353 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 354 let wantAgentInfo: wantAgent.WantAgentInfo = { 355 // List of operations to be executed after the notification is clicked. 356 wants: [ 357 { 358 bundleName: "com.example.myapplication", 359 abilityName: "EntryAbility" 360 } 361 ], 362 // Type of the operation to perform after the notification is clicked. 363 actionType: wantAgent.OperationType.START_ABILITY, 364 // Custom request code. 365 requestCode: 0, 366 // Execution attribute of the operation to perform after the notification is clicked. 367 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 368 }; 369 370 try { 371 // Obtain the WantAgent object by using the getWantAgent API of the wantAgent module. 372 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => { 373 try { 374 backgroundTaskManager.startBackgroundRunning(this.context, 375 backgroundTaskManager.BackgroundMode.LOCATION, wantAgentObj).then(() => { 376 console.info("Operation startBackgroundRunning succeeded"); 377 }).catch((error: BusinessError) => { 378 console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 379 }); 380 } catch (error) { 381 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 382 } 383 }); 384 } catch (error) { 385 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 386 } 387 } 388}; 389``` 390 391## backgroundTaskManager.stopBackgroundRunning 392 393stopBackgroundRunning(context: Context, callback: AsyncCallback<void>): void 394 395Cancels a continuous task. This API uses an asynchronous callback to return the result. 396 397**Atomic service API**: This API can be used in atomic services since API version 12. 398 399**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 400 401**Parameters** 402 403| Name | Type | Mandatory | Description | 404| -------- | ------------------------- | ---- | ---------------------------------------- | 405| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](../apis-ability-kit/js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-context.md).| 406| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the continuous task is canceled, **err** is **undefined**. Otherwise, **err** is an error object.| 407 408**Error codes** 409 410For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 411 412| ID | Error Message | 413| ---- | --------------------- | 414| 201 | Permission denied. | 415| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 416| 9800001 | Memory operation failed. | 417| 9800002 | Parcel operation failed. | 418| 9800003 | Internal transaction failed. | 419| 9800004 | System service operation failed. | 420| 9800005 | Continuous task verification failed. | 421| 9800006 | Notification verification failed for a continuous task. | 422| 9800007 | Continuous task storage failed. | 423 424**Example** 425 426```js 427import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 428import { BusinessError } from '@kit.BasicServicesKit'; 429import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 430 431function callback(error: BusinessError, data: void) { 432 if (error) { 433 console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 434 } else { 435 console.info("Operation stopBackgroundRunning succeeded"); 436 } 437} 438 439export default class EntryAbility extends UIAbility { 440 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 441 try { 442 backgroundTaskManager.stopBackgroundRunning(this.context, callback); 443 } catch (error) { 444 console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 445 } 446 } 447}; 448``` 449 450## backgroundTaskManager.stopBackgroundRunning 451 452stopBackgroundRunning(context: Context): Promise<void> 453 454Cancels a continuous task. This API uses a promise to return the result. 455 456**Atomic service API**: This API can be used in atomic services since API version 12. 457 458**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 459 460**Parameters** 461 462| Name | Type | Mandatory | Description | 463| ------- | ------- | ---- | ---------------------------------------- | 464| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](../apis-ability-kit/js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-context.md).| 465 466**Return value** 467 468| Type | Description | 469| -------------- | ---------------- | 470| Promise\<void> | Promise that returns no value.| 471 472**Error codes** 473 474For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 475 476| ID | Error Message | 477| ---- | --------------------- | 478| 201 | Permission denied. | 479| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. | 480| 9800001 | Memory operation failed. | 481| 9800002 | Parcel operation failed. | 482| 9800003 | Internal transaction failed. | 483| 9800004 | System service operation failed. | 484| 9800005 | Continuous task verification failed. | 485| 9800006 | Notification verification failed for a continuous task. | 486| 9800007 | Continuous task storage failed. | 487 488**Example** 489 490```js 491import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 492import { BusinessError } from '@kit.BasicServicesKit'; 493import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 494 495export default class EntryAbility extends UIAbility { 496 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 497 try { 498 backgroundTaskManager.stopBackgroundRunning(this.context).then(() => { 499 console.info("Operation stopBackgroundRunning succeeded"); 500 }).catch((error: BusinessError) => { 501 console.error(`Operation stopBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 502 }); 503 } catch (error) { 504 console.error(`Operation stopBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 505 } 506 } 507}; 508``` 509 510## backgroundTaskManager.startBackgroundRunning<sup>12+</sup> 511 512startBackgroundRunning(context: Context, bgModes: string[], wantAgent: WantAgent): Promise<ContinuousTaskNotification> 513 514Requests continuous tasks of multiple types. This API uses a promise to return the result. 515 516**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING 517 518**Atomic service API**: This API can be used in atomic services since API version 12. 519 520**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 521 522**Parameters** 523 524| Name | Type | Mandatory | Description | 525| --------- | ---------------------------------- | ---- | ---------------------------------------- | 526| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context.| 527| bgModes | string[] | Yes | Types of continuous tasks. For details about the available options, see [Item](../../task-management/continuous-task.md#use-cases).<br> **Note**: One or more types can be passed.| 528| wantAgent | [WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md) | Yes | Notification parameters, which are used to specify the target page that is redirected to when a continuous task notification is clicked. | 529 530**Return value** 531 532| Type | Description | 533| -------------- | ---------------- | 534| Promise\<ContinuousTaskNotification> | Promise that returns a [continuous-task notification](#continuoustasknotification12).| 535 536**Error codes** 537 538For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 539 540| ID | Error Message | 541| ---- | --------------------- | 542| 201 | Permission denied. | 543| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 544| 9800001 | Memory operation failed. | 545| 9800002 | Parcel operation failed. | 546| 9800003 | Internal transaction failed. | 547| 9800004 | System service operation failed. | 548| 9800005 | Continuous task verification failed. | 549| 9800006 | Notification verification failed for a continuous task. | 550| 9800007 | Continuous task storage failed. | 551 552**Example** 553 554```js 555import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 556import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 557import { window } from '@kit.ArkUI'; 558import { BusinessError } from '@kit.BasicServicesKit'; 559import { wantAgent, WantAgent } from '@kit.AbilityKit'; 560import { notificationManager } from '@kit.NotificationKit'; 561 562export default class EntryAbility extends UIAbility { 563 id: number = 0; // Save the notification ID. 564 565 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 566 let wantAgentInfo: wantAgent.WantAgentInfo = { 567 // List of operations to be executed after the notification is clicked. 568 wants: [ 569 { 570 bundleName: "com.example.myapplication", 571 abilityName: "EntryAbility" 572 } 573 ], 574 // Type of the operation to perform after the notification is clicked. 575 actionType: wantAgent.OperationType.START_ABILITY, 576 // Custom request code. 577 requestCode: 0, 578 // Execution attribute of the operation to perform after the notification is clicked. 579 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 580 }; 581 582 try { 583 // Obtain the WantAgent object by using the getWantAgent API of the wantAgent module. 584 wantAgent.getWantAgent(wantAgentInfo).then((wantAgentObj: WantAgent) => { 585 try { 586 let list: Array<string> = ["dataTransfer"]; 587 backgroundTaskManager.startBackgroundRunning(this.context, list, wantAgentObj).then((res: backgroundTaskManager.ContinuousTaskNotification) => { 588 console.info("Operation startBackgroundRunning succeeded"); 589 // For a continuous task of the upload and download type, the application can use the notification ID returned in res to update the notification, for example, sending a template notification with a progress bar. 590 this.id = res.notificationId; 591 }).catch((error: BusinessError) => { 592 console.error(`Operation startBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 593 }); 594 } catch (error) { 595 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 596 } 597 }); 598 } catch (error) { 599 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 600 } 601 } 602 603 // The application updates its progress. 604 updateProcess(process: Number) { 605 // The application defines the download notification template. 606 let downLoadTemplate: notificationManager.NotificationTemplate = { 607 name: 'downloadTemplate', // Currently, only downloadTemplate is supported. Retain the value. 608 data: { 609 title: 'File download: music.mp4', // Mandatory. 610 fileName: 'senTemplate', // Mandatory. 611 progressValue: process, // The application updates the progress, which is user-defined. 612 } 613 }; 614 let request: notificationManager.NotificationRequest = { 615 content: { 616 // System live view type, which remains unchanged. 617 notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_SYSTEM_LIVE_VIEW, 618 systemLiveView: { 619 typeCode: 8, // Set this parameter to 8 for the upload and download type. Currently, only the upload and download type is supported. Retain the value. 620 title: "test", // Customized by the application. 621 text: "test", // Customized by the application. 622 } 623 }, 624 id: this.id, // The value must be the ID returned for a continuous-task request. Otherwise, the application fails to update the notification. 625 notificationSlotType: notificationManager.SlotType.LIVE_VIEW, // Live view type. Retain the value. 626 template: downLoadTemplate // Name of the template to be set for the application. 627 }; 628 629 try { 630 notificationManager.publish(request).then(() => { 631 console.info("publish success, id= " + this.id); 632 }).catch((err: BusinessError) => { 633 console.error(`publish fail: ${JSON.stringify(err)}`); 634 }); 635 } catch (err) { 636 console.error(`publish fail: ${JSON.stringify(err)}`); 637 } 638 } 639}; 640``` 641## backgroundTaskManager.updateBackgroundRunning<sup>12+</sup> 642 643updateBackgroundRunning(context: Context, bgModes: string[]): Promise<ContinuousTaskNotification> 644 645Updates continuous tasks of multiple types. This API uses a promise to return the result. 646 647**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING 648 649**Atomic service API**: This API can be used in atomic services since API version 12. 650 651**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 652 653**Parameters** 654 655| Name | Type | Mandatory | Description | 656| --------- | ---------------------------------- | ---- | ---------------------------------------- | 657| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | Yes | Application context.| 658| bgModes | string[] | Yes | Types of continuous tasks after the update. For details about the available options, see [Item](../../task-management/continuous-task.md#use-cases).<br> **Note**: One or more types can be passed.| 659 660**Return value** 661 662| Type | Description | 663| -------------- | ---------------- | 664| Promise\<ContinuousTaskNotification> | Promise that returns a [continuous-task notification](#continuoustasknotification12).| 665 666**Error codes** 667 668For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [backgroundTaskManager Error Codes](errorcode-backgroundTaskMgr.md). 669 670| ID | Error Message | 671| ---- | --------------------- | 672| 201 | Permission denied. | 673| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 674| 9800001 | Memory operation failed. | 675| 9800002 | Parcel operation failed. | 676| 9800003 | Internal transaction failed. | 677| 9800004 | System service operation failed. | 678| 9800005 | Continuous task verification failed. | 679| 9800006 | Notification verification failed for a continuous task. | 680| 9800007 | Continuous task storage failed. | 681 682**Example** 683 684```js 685import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 686import { BusinessError } from '@kit.BasicServicesKit'; 687import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 688 689export default class EntryAbility extends UIAbility { 690 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 691 try { 692 try { 693 // You must call startBackgroundRunning before updateBackgroundRunning. Here it is assumed that you have called startBackgroundRunning. 694 let list: Array<string> = ["audioPlayback"]; 695 backgroundTaskManager.updateBackgroundRunning(this.context, list).then(() => { 696 console.info("Operation updateBackgroundRunning succeeded"); 697 }).catch((error: BusinessError) => { 698 console.error(`Operation updateBackgroundRunning failed. code is ${error.code} message is ${error.message}`); 699 }); 700 } catch (error) { 701 console.error(`Operation startBackgroundRunning failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 702 } 703 } catch (error) { 704 console.error(`Operation getWantAgent failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 705 } 706 } 707}; 708``` 709 710## backgroundTaskManager.on('continuousTaskCancel')<sup>15+</sup> 711 712on(type: 'continuousTaskCancel', callback: Callback<ContinuousTaskCancelInfo>): void 713 714Subscribes to continuous task cancellation events. This API uses an asynchronous callback to return the result. 715 716**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING 717 718**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 719 720**Parameters** 721 722| Name | Type | Mandatory | Description | 723| --------- | ---------------------------------- | ---- | ---------------------------------------- | 724| type | string | Yes | Cancels a continuous task. The value is fixed at **'continuousTaskCancel'**.| 725| callback | Callback\<[ContinuousTaskCancelReason](#continuoustaskcancelreason15)> | Yes | Callback used to return the reason why a continuous task is canceled.| 726 727**Error codes** 728 729For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 730 731| ID | Error Message | 732| ---- | --------------------- | 733| 201 | Permission denied. | 734| 401 | Parameter error. Possible causes: 1. Callback parameter error; 2. Register a exist callback type; 3. Parameter verification failed. | 735 736**Example** 737 738```js 739import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 740import { BusinessError } from '@kit.BasicServicesKit'; 741import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 742 743function callback(info: backgroundTaskManager.ContinuousTaskCancelInfo) { 744 console.info('continuousTaskCancel callback id ' + info.id); 745 console.info('continuousTaskCancel callback reason ' + info.reason); 746} 747 748export default class EntryAbility extends UIAbility { 749 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 750 try { 751 backgroundTaskManager.on("continuousTaskCancel", callback); 752 } catch (error) { 753 console.error(`Operation onContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 754 } 755 } 756}; 757``` 758## backgroundTaskManager.off('continuousTaskCancel')<sup>15+</sup> 759 760off(type: 'continuousTaskCancel', callback?: Callback<ContinuousTaskCancelInfo>): void 761 762Unsubscribes from continuous task cancellation events. This API uses an asynchronous callback to return the result. 763 764**Required permissions**: ohos.permission.KEEP_BACKGROUND_RUNNING 765 766**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 767 768**Parameters** 769 770| Name | Type | Mandatory | Description | 771| --------- | ---------------------------------- | ---- | ---------------------------------------- | 772| type | string | Yes | Cancels a continuous task. The value is fixed at **'continuousTaskCancel'**.| 773| callback | Callback\<[ContinuousTaskCancelReason](#continuoustaskcancelreason15)> | No | Callback for which listening is cancelled. If this parameter is left unspecified, all registered callbacks are cancelled.| 774 775**Error codes** 776 777For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 778 779| ID | Error Message | 780| ---- | --------------------- | 781| 201 | Permission denied. | 782| 401 | Parameter error. Possible causes: 1. Callback parameter error; 2. Unregister type has not register; 3. Parameter verification failed. | 783 784**Example** 785 786```js 787import { backgroundTaskManager } from '@kit.BackgroundTasksKit'; 788import { BusinessError } from '@kit.BasicServicesKit'; 789import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 790 791function callback(info: backgroundTaskManager.ContinuousTaskCancelInfo) { 792 console.info('continuousTaskCancel callback id ' + info.id); 793 console.info('continuousTaskCancel callback reason ' + info.reason); 794} 795 796export default class EntryAbility extends UIAbility { 797 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 798 try { 799 backgroundTaskManager.off("continuousTaskCancel", callback); 800 } catch (error) { 801 console.error(`Operation onContinuousTaskCancel failed. code is ${(error as BusinessError).code} message is ${(error as BusinessError).message}`); 802 } 803 } 804}; 805``` 806 807## DelaySuspendInfo 808 809Defines the information about the transient task. 810 811**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.TransientTask 812 813| Name | Type | Mandatory | Description | 814| --------------- | ------ | ---- | ---------------------------------------- | 815| requestId | number | Yes | Request ID of the transient task. | 816| actualDelayTime | number | Yes | Actual duration of the transient task that the application requests, in milliseconds.<br> **Note**: The maximum duration is 3 minutes in normal cases. In the case of a [low battery](../apis-basic-services-kit/js-apis-battery-info.md), the maximum duration is decreased to 1 minute.| 817 818## BackgroundMode 819 820Type of the continuous task. 821 822**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 823 824| Name | Value | Description | 825| ----------------------- | ---- | --------------------- | 826| DATA_TRANSFER | 1 | Data transfer. | 827| AUDIO_PLAYBACK | 2 | Audio and video playback.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 828| AUDIO_RECORDING | 3 | Audio recording. | 829| LOCATION | 4 | Positioning and navigation. | 830| BLUETOOTH_INTERACTION | 5 | Bluetooth-related services. | 831| MULTI_DEVICE_CONNECTION | 6 | Multi-device connection.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 832| VOIP<sup>13+</sup> | 8 | Audio and video calls. | 833| TASK_KEEPING | 9 | Computing task (for 2-in-1 devices only). | 834 835## ContinuousTaskNotification<sup>12+</sup> 836 837Describes the information about a continuous-task notification. 838 839**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 840 841| Name | Type | Read-Only | Optional | Description | 842| --------------- | ------ | ---- | ---- | ---------------------------------------- | 843| slotType | [notificationManager.SlotType](../apis-notification-kit/js-apis-notificationManager.md#slottype) | No | No | Slot type of a continuous-task notification.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 844| contentType | [notificationManager.ContentType](../apis-notification-kit/js-apis-notificationManager.md#contenttype) | No | No | Content type of a continuous-task notification.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 845| notificationId | number | No | No | ID of the continuous-task notification.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 846| continuousTaskId<sup>15+</sup> | number | No | Yes | ID of a continuous task| 847 848## ContinuousTaskCancelInfo<sup>15+</sup> 849 850Describes the information about the cancellation of a continuous task. 851 852**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 853 854| Name | Type | Mandatory | Description | 855| --------------- | ------ | ---- | ---------------------------------------- | 856| reason | [ContinuousTaskCancelReason](#continuoustaskcancelreason15) | Yes | Reason for canceling the continuous task.| 857| id | number | Yes | ID of the continuous task canceled.| 858 859## ContinuousTaskCancelReason<sup>15+</sup> 860 861Describes the reason for canceling a continuous task. 862 863**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 864 865| Name | Value | Description | 866| ----------------------- | ---- | --------------------- | 867| USER_CANCEL | 1 | The task is canceled by the user. | 868| SYSTEM_CANCEL | 2 | The task is canceled by the system. | 869| USER_CANCEL_REMOVE_NOTIFICATION | 3 | User removal notification. This value is reserved. | 870| SYSTEM_CANCEL_DATA_TRANSFER_LOW_SPEED | 4 | A continuous task of the DATA_TRANSFER type is requested, but the data transmission rate is low. This value is reserved. | 871| SYSTEM_CANCEL_AUDIO_PLAYBACK_NOT_USE_AVSESSION | 5 | A continuous task of the AUDIO_PLAYBACK type is requested, but the [AVSession](../../media/avsession/avsession-overview.md) is not accessed. This value is reserved. | 872| SYSTEM_CANCEL_AUDIO_PLAYBACK_NOT_RUNNING | 6 | A continuous task of the AUDIO_PLAYBACK type is requested, but the audio and video are not played. This value is reserved. | 873| SYSTEM_CANCEL_AUDIO_RECORDING_NOT_RUNNING | 7 | A continuous task of the AUDIO_RECORDING type is requested, but audio recording is not in progress. This value is reserved. | 874| SYSTEM_CANCEL_NOT_USE_LOCATION | 8 | A continuous task of the LOCATION type is requested, but location and navigation are not used. This value is reserved. | 875| SYSTEM_CANCEL_NOT_USE_BLUETOOTH | 9 | A continuous task of the BLUETOOTH_INTERACTION type is requested, but Bluetooth-related services are not used. This value is reserved. | 876| SYSTEM_CANCEL_NOT_USE_MULTI_DEVICE | 10 | A continuous task of the MULTI_DEVICE_CONNECTION type is requested, but multi-device connection is not used. This value is reserved. | 877| SYSTEM_CANCEL_USE_ILLEGALLY | 11 | A continuous task of an invalid type is used. For example, a continuous task of the AUDIO_PLAYBACK type is requested, but the audio and video playback and location and navigation services are used. This value is reserved. | 878 879## BackgroundSubMode<sup>16+</sup> 880 881Subtype of a continuous task. 882 883**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 884 885| Name | Value | Description | 886| ----------------------- | ---- | --------------------- | 887| CAR_KEY | 1 | Car key.<br>Note: The car key subtype takes effect only when a continuous task of the BLUETOOTH_INTERACTION type is requested. | 888 889## BackgroundModeType<sup>16+</sup> 890 891Type of a continuous task. 892 893**System capability**: SystemCapability.ResourceSchedule.BackgroundTaskManager.ContinuousTask 894 895| Name | Value | Description | 896| ----------------------- | ---- | --------------------- | 897| SUB_MODE | 'subMode' | Subtype. | 898