1# missionManager 2 3 4> **NOTE** 5> 6> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 7 8 9Provides mission management. You can use the APIs to lock, unlock, and clear missions, and switch a mission to the foreground. 10 11 12## Modules to Import 13 14 15``` 16import missionManager from '@ohos.application.missionManager' 17``` 18 19 20## missionManager.registerMissionListener 21 22registerMissionListener(listener: MissionListener): number; 23 24Registers a listener to observe the mission status. 25 26**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 27 28**Parameters** 29 30| Name| Type| Mandatory| Description| 31| -------- | -------- | -------- | -------- | 32| listener | MissionListener | Yes| Listener to register.| 33 34**Return value** 35 36| Type| Description| 37| -------- | -------- | 38| number | Returns the unique index of the mission status listener, which is created by the system and allocated when the listener is registered.| 39 40**Example** 41 42 ```js 43 var listener = { 44 onMissionCreated: this.onMissionCreatedCallback, 45 onMissionDestroyed: this.onMissionDestroyedCallback, 46 onMissionSnapshotChanged: this.onMissionSnapshotChangedCallback, 47 onMissionMovedToFront: this.onMissionMovedToFrontCallback 48 }; 49 console.log("registerMissionListener") 50 var listenerid = missionManager.registerMissionListener(listener); 51 52 ``` 53 54 55## missionManager.unregisterMissionListener 56 57unregisterMissionListener(listenerId: number, callback: AsyncCallback<void>): void; 58 59Deregisters a mission status listener. This API uses an asynchronous callback to return the result. 60 61**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 62 63**Parameters** 64 65| Name| Type| Mandatory| Description| 66| -------- | -------- | -------- | -------- | 67| listenerId | number | Yes| Unique index of the mission status listener to unregister. It is returned by **registerMissionListener**.| 68| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 69 70**Example** 71 72 ```js 73 var listener = { 74 onMissionCreated: this.onMissionCreatedCallback, 75 onMissionDestroyed: this.onMissionDestroyedCallback, 76 onMissionSnapshotChanged: this.onMissionSnapshotChangedCallback, 77 onMissionMovedToFront: this.onMissionMovedToFrontCallback 78 }; 79 console.log("registerMissionListener") 80 var listenerid = missionManager.registerMissionListener(listener); 81 82 missionManager.unregisterMissionListener(listenerid, (error) => { 83 console.log("unregisterMissionListener"); 84 }) 85 ``` 86 87 88## missionManager.unregisterMissionListener 89 90unregisterMissionListener(listenerId: number): Promise<void>; 91 92Deregisters a mission status listener. This API uses a promise to return the result. 93 94**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 95 96**Parameters** 97 98| Name| Type| Mandatory| Description| 99| -------- | -------- | -------- | -------- | 100| listenerId | number | Yes| Unique index of the mission status listener to unregister. It is returned by **registerMissionListener**.| 101 102**Return value** 103 104| Type| Description| 105| -------- | -------- | 106| Promise<void> | Promise used to return the result.| 107 108**Example** 109 110 ```js 111 var listener = { 112 onMissionCreated: this.onMissionCreatedCallback, 113 onMissionDestroyed: this.onMissionDestroyedCallback, 114 onMissionSnapshotChanged: this.onMissionSnapshotChangedCallback, 115 onMissionMovedToFront: this.onMissionMovedToFrontCallback 116 }; 117 console.log("registerMissionListener") 118 var listenerid = missionManager.registerMissionListener(listener); 119 120 missionManager.unregisterMissionListener(listenerid).catch(function (err){ 121 console.log(err); 122 }); 123 ``` 124 125 126## missionManager.getMissionInfo 127 128getMissionInfo(deviceId: string, missionId: number, callback: AsyncCallback<MissionInfo>): void; 129 130Obtains the information about a given mission. This API uses an asynchronous callback to return the result. 131 132**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 133 134**Parameters** 135 136| Name| Type| Mandatory| Description| 137| -------- | -------- | -------- | -------- | 138| deviceId | string | Yes| Device ID. It is a null string by default for the local device.| 139| missionId | number | Yes| Mission ID.| 140| callback | AsyncCallback<[MissionInfo](#missioninfo)> | Yes| Callback used to return the mission information obtained.| 141 142**Example** 143 144 ```js 145 import missionManager from '@ohos.application.missionManager' 146 147 missionManager.getMissionInfo("", allMissions[0].missionId, (error, mission) => { 148 console.log("getMissionInfo is called, error.code = " + error.code) 149 console.log("mission.missionId = " + mission.missionId); 150 console.log("mission.runningState = " + mission.runningState); 151 console.log("mission.lockedState = " + mission.lockedState); 152 console.log("mission.timestamp = " + mission.timestamp); 153 console.log("mission.label = " + mission.label); 154 console.log("mission.iconPath = " + mission.iconPath); 155 }); 156 ``` 157 158 159## missionManager.getMissionInfo 160 161getMissionInfo(deviceId: string, missionId: number): Promise<MissionInfo>; 162 163Obtains the information about a given mission. This API uses a promise to return the result. 164 165**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 166 167**Parameters** 168 169| Name| Type| Mandatory| Description| 170| -------- | -------- | -------- | -------- | 171| deviceId | string | Yes| Device ID. It is a null string by default for the local device.| 172| missionId | number | Yes| Mission ID.| 173 174**Return value** 175 176| Type| Description| 177| -------- | -------- | 178| Promise<[MissionInfo](#missioninfo)> | Promise used to return the mission information obtained.| 179 180**Example** 181 182 ```js 183 import missionManager from '@ohos.application.missionManager' 184 185 var mission = missionManager.getMissionInfo("", id).catch(function (err){ 186 console.log(err); 187 }); 188 ``` 189 190 191## missionManager.getMissionInfos 192 193getMissionInfos(deviceId: string, numMax: number, callback: AsyncCallback<Array<MissionInfo>>): void; 194 195Obtains information about all missions. This API uses an asynchronous callback to return the result. 196 197**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 198 199**Parameters** 200 201| Name| Type| Mandatory| Description| 202| -------- | -------- | -------- | -------- | 203| deviceId | string | Yes| Device ID. It is a null string by default for the local device.| 204| numMax | number | Yes| Maximum number of missions whose information can be obtained.| 205| callback | AsyncCallback<Array<[MissionInfo](#missioninfo)>> | Yes| Callback used to return the array of mission information obtained.| 206 207**Example** 208 209 ```js 210 import missionManager from '@ohos.application.missionManager' 211 212 missionManager.getMissionInfos("", 10, (error, missions) => { 213 console.log("getMissionInfos is called, error.code = " + error.code); 214 console.log("size = " + missions.length); 215 console.log("missions = " + JSON.stringify(missions)); 216 }) 217 ``` 218 219 220## missionManager.getMissionInfos 221 222getMissionInfos(deviceId: string, numMax: number): Promise<Array<MissionInfo>>; 223 224Obtains information about all missions. This API uses a promise to return the result. 225 226**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 227 228**Parameters** 229 230| Name| Type| Mandatory| Description| 231| -------- | -------- | -------- | -------- | 232| deviceId | string | Yes| Device ID. It is a null string by default for the local device.| 233| numMax | number | Yes| Maximum number of missions whose information can be obtained.| 234 235**Return value** 236 237| Type| Description| 238| -------- | -------- | 239| Promise<Array<[MissionInfo](#missioninfo)>> | Promise used to return the array of mission information obtained.| 240 241**Example** 242 243 ```js 244 import missionManager from '@ohos.application.missionManager' 245 246 var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){ 247 console.log(err); 248 }); 249 ``` 250 251 252## missionManager.getMissionSnapShot 253 254getMissionSnapShot(deviceId: string, missionId: number, callback: AsyncCallback<MissionSnapshot>): void; 255 256Obtains the snapshot of a given mission. This API uses an asynchronous callback to return the result. 257 258**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 259 260**Parameters** 261 262| Name| Type| Mandatory| Description| 263| -------- | -------- | -------- | -------- | 264| deviceId | string | Yes| Device ID. It is a null string by default for the local device.| 265| missionId | number | Yes| Mission ID.| 266| callback | AsyncCallback<[MissionSnapshot](js-apis-application-MissionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.| 267 268**Example** 269 270 ```js 271 import missionManager from '@ohos.application.missionManager' 272 273 missionManager.getMissionInfos("", 10, (error, missions) => { 274 console.log("getMissionInfos is called, error.code = " + error.code); 275 console.log("size = " + missions.length); 276 console.log("missions = " + JSON.stringify(missions)); 277 var id = missions[0].missionId; 278 279 missionManager.getMissionSnapShot("", id, (error, snapshot) => { 280 console.log("getMissionSnapShot is called, error.code = " + error.code); 281 console.log("bundleName = " + snapshot.ability.bundleName); 282 }) 283 }) 284 ``` 285 286 287## missionManager.getMissionSnapShot 288 289getMissionSnapShot(deviceId: string, missionId: number): Promise<MissionSnapshot>; 290 291Obtains the snapshot of a given mission. This API uses a promise to return the result. 292 293**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 294 295**Parameters** 296 297| Name| Type| Mandatory| Description| 298| -------- | -------- | -------- | -------- | 299| deviceId | string | Yes| Device ID. It is a null string by default for the local device.| 300| missionId | number | Yes| Mission ID.| 301 302**Return value** 303 304| Type| Description| 305| -------- | -------- | 306| Promise<[MissionSnapshot](js-apis-application-MissionSnapshot.md)> | Promise used to return the snapshot information obtained.| 307 308**Example** 309 310 ```js 311 import missionManager from '@ohos.application.missionManager' 312 313 var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){ 314 console.log(err); 315 }); 316 console.log("size = " + allMissions.length); 317 console.log("missions = " + JSON.stringify(allMissions)); 318 var id = allMissions[0].missionId; 319 var snapshot = missionManager.getMissionSnapShot("", id).catch(function (err){ 320 console.log(err); 321 }); 322 ``` 323 324 325## missionManager.lockMission 326 327lockMission(missionId: number, callback: AsyncCallback<void>): void; 328 329Locks a given mission. This API uses an asynchronous callback to return the result. 330 331**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 332 333**Parameters** 334 335| Name| Type| Mandatory| Description| 336| -------- | -------- | -------- | -------- | 337| missionId | number | Yes| Mission ID.| 338| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 339 340**Example** 341 342 ```js 343 import missionManager from '@ohos.application.missionManager' 344 345 missionManager.getMissionInfos("", 10, (error, missions) => { 346 console.log("getMissionInfos is called, error.code = " + error.code); 347 console.log("size = " + missions.length); 348 console.log("missions = " + JSON.stringify(missions)); 349 var id = missions[0].missionId; 350 351 missionManager.lockMission(id).then(() => { 352 console.log("lockMission is called "); 353 }); 354 }); 355 ``` 356 357 358## missionManager.lockMission 359 360lockMission(missionId: number): Promise<void>; 361 362Locks a given mission. This API uses a promise to return the result. 363 364**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 365 366**Parameters** 367 368| Name| Type| Mandatory| Description| 369| -------- | -------- | -------- | -------- | 370| missionId | number | Yes| Mission ID.| 371 372**Return value** 373 374| Type| Description| 375| -------- | -------- | 376| Promise<void> | Promise used to return the result.| 377 378**Example** 379 380 ```js 381 import missionManager from '@ohos.application.missionManager' 382 383 var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){ 384 console.log(err); 385 }); 386 console.log("size = " + allMissions.length); 387 console.log("missions = " + JSON.stringify(allMissions)); 388 var id = allMissions[0].missionId; 389 390 missionManager.lockMission(id).catch(function (err){ 391 console.log(err); 392 }); 393 ``` 394 395 396## missionManager.unlockMission 397 398unlockMission(missionId: number, callback: AsyncCallback<void>): void; 399 400Unlocks a given mission. This API uses an asynchronous callback to return the result. 401 402**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 403 404**Parameters** 405 406| Name| Type| Mandatory| Description| 407| -------- | -------- | -------- | -------- | 408| missionId | number | Yes| Mission ID.| 409| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 410 411**Example** 412 413 ```js 414 import missionManager from '@ohos.application.missionManager' 415 416 missionManager.getMissionInfos("", 10, (error, missions) => { 417 console.log("getMissionInfos is called, error.code = " + error.code); 418 console.log("size = " + missions.length); 419 console.log("missions = " + JSON.stringify(missions)); 420 var id = missions[0].missionId; 421 422 missionManager.unlockMission(id).then(() => { 423 console.log("unlockMission is called "); 424 }); 425 }); 426 ``` 427 428 429## missionManager.unlockMission 430 431unlockMission(missionId: number): Promise<void>; 432 433Unlocks a given mission. This API uses a promise to return the result. 434 435**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 436 437**Parameters** 438 439| Name| Type| Mandatory| Description| 440| -------- | -------- | -------- | -------- | 441| missionId | number | Yes| Mission ID.| 442 443**Return value** 444 445| Type| Description| 446| -------- | -------- | 447| Promise<void> | Promise used to return the result.| 448 449**Example** 450 451 ```js 452 import missionManager from '@ohos.application.missionManager' 453 454 var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){ 455 console.log(err); 456 }); 457 console.log("size = " + allMissions.length); 458 console.log("missions = " + JSON.stringify(allMissions)); 459 var id = allMissions[0].missionId; 460 461 missionManager.lockMission(id).catch(function (err){ 462 console.log(err); 463 }); 464 missionManager.unlockMission(id).catch(function (err){ 465 console.log(err); 466 }); 467 ``` 468 469 470## missionManager.clearMission 471 472clearMission(missionId: number, callback: AsyncCallback<void>): void; 473 474Clears a given mission, regardless of whether it is locked. This API uses an asynchronous callback to return the result. 475 476**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 477 478**Parameters** 479 480| Name| Type| Mandatory| Description| 481| -------- | -------- | -------- | -------- | 482| missionId | number | Yes| Mission ID.| 483| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 484 485**Example** 486 487 ```js 488 import missionManager from '@ohos.application.missionManager' 489 490 missionManager.getMissionInfos("", 10, (error, missions) => { 491 console.log("getMissionInfos is called, error.code = " + error.code); 492 console.log("size = " + missions.length); 493 console.log("missions = " + JSON.stringify(missions)); 494 var id = missions[0].missionId; 495 496 missionManager.clearMission(id).then(() => { 497 console.log("clearMission is called "); 498 }); 499 }); 500 ``` 501 502 503## missionManager.clearMission 504 505clearMission(missionId: number): Promise<void>; 506 507Clears a given mission, regardless of whether it is locked. This API uses a promise to return the result. 508 509**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 510 511**Parameters** 512 513| Name| Type| Mandatory| Description| 514| -------- | -------- | -------- | -------- | 515| missionId | number | Yes| Mission ID.| 516 517**Return value** 518 519| Type| Description| 520| -------- | -------- | 521| Promise<void> | Promise used to return the result.| 522 523**Example** 524 525 ```js 526 import missionManager from '@ohos.application.missionManager' 527 528 var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){ 529 console.log(err); 530 }); 531 console.log("size = " + allMissions.length); 532 console.log("missions = " + JSON.stringify(allMissions)); 533 var id = allMissions[0].missionId; 534 535 missionManager.clearMission(id).catch(function (err){ 536 console.log(err); 537 }); 538 ``` 539 540 541## missionManager.clearAllMissions 542 543clearAllMissions(callback: AsyncCallback<void>): void; 544 545Clears all unlocked missions. This API uses an asynchronous callback to return the result. 546 547**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 548 549**Example** 550 551 ```js 552 import missionManager from '@ohos.application.missionManager' 553 554 missionManager.clearAllMissions().then(() => { 555 console.log("clearAllMissions is called "); 556 }); 557 ``` 558 559 560## missionManager.clearAllMissions 561 562clearAllMissions(): Promise<void>; 563 564Clears all unlocked missions. This API uses a promise to return the result. 565 566**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 567 568**Return value** 569 570| Type| Description| 571| -------- | -------- | 572| Promise<void> | Promise used to return the result.| 573 574**Example** 575 576 ```js 577 import missionManager from '@ohos.application.missionManager' 578 missionManager.clearAllMissions().catch(function (err){ 579 console.log(err); 580 }); 581 ``` 582 583 584## missionManager.moveMissionToFront 585 586moveMissionToFront(missionId: number, callback: AsyncCallback<void>): void; 587 588Switches a given mission to the foreground. This API uses an asynchronous callback to return the result. 589 590**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 591 592**Parameters** 593 594| Name| Type| Mandatory| Description| 595| -------- | -------- | -------- | -------- | 596| missionId | number | Yes| Mission ID.| 597| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 598 599**Example** 600 601 ```js 602 import missionManager from '@ohos.application.missionManager' 603 604 missionManager.getMissionInfos("", 10, (error, missions) => { 605 console.log("getMissionInfos is called, error.code = " + error.code); 606 console.log("size = " + missions.length); 607 console.log("missions = " + JSON.stringify(missions)); 608 var id = missions[0].missionId; 609 610 missionManager.moveMissionToFront(id).then(() => { 611 console.log("moveMissionToFront is called "); 612 }); 613 }); 614 ``` 615 616 617## missionManager.moveMissionToFront 618 619moveMissionToFront(missionId: number, options: StartOptions, callback: AsyncCallback<void>): void; 620 621Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses an asynchronous callback to return the result. 622 623**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 624 625**Parameters** 626 627| Name| Type| Mandatory| Description| 628| -------- | -------- | -------- | -------- | 629| missionId | number | Yes| Mission ID.| 630| options | StartOptions | Yes| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.| 631| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 632 633**Example** 634 635 ```js 636 import missionManager from '@ohos.application.missionManager' 637 638 missionManager.getMissionInfos("", 10, (error, missions) => { 639 console.log("getMissionInfos is called, error.code = " + error.code); 640 console.log("size = " + missions.length); 641 console.log("missions = " + JSON.stringify(missions)); 642 var id = missions[0].missionId; 643 644 missionManager.moveMissionToFront(id,{windowMode : 101}).then(() => { 645 console.log("moveMissionToFront is called "); 646 }); 647 }); 648 ``` 649 650 651## missionManager.moveMissionToFront 652 653moveMissionToFront(missionId: number, options?: StartOptions): Promise<void>; 654 655Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses a promise to return the result. 656 657**System capability**: SystemCapability.Ability.AbilityRuntime.Mission 658 659**Parameters** 660 661| Name| Type| Mandatory| Description| 662| -------- | -------- | -------- | -------- | 663| missionId | number | Yes| Mission ID.| 664| options | StartOptions | No| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.| 665 666**Return value** 667 668| Type| Description| 669| -------- | -------- | 670| Promise<void> | Promise used to return the result.| 671 672**Example** 673 674 ```js 675 import missionManager from '@ohos.application.missionManager' 676 677 var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){ 678 console.log(err); 679 }); 680 console.log("size = " + allMissions.length); 681 console.log("missions = " + JSON.stringify(allMissions)); 682 var id = allMissions[0].missionId; 683 684 missionManager.moveMissionToFront(id).catch(function (err){ 685 console.log(err); 686 }); 687 ``` 688