1# Mission Management Scenarios
2
3
4Before getting started with the development of mission management, be familiar with the following concepts related to mission management:
5
6
7- AbilityRecord: minimum unit for the system service to manage a UIAbility instance. It corresponds to a UIAbility component instance of an application. A maximum of 512 UIAbility instances can be managed on the system service side.
8
9- MissionRecord: minimum unit for mission management. One MissionRecord has only one AbilityRecord. In other words, a UIAbility component instance corresponds to a mission.
10
11- MissionList: a list of missions started from the home screen. It records the startup relationship between missions. In a MissionList, a mission is started by the mission above it, and the mission at the bottom is started by the home screen.
12
13- MissionListManager: system mission management module that maintains all the MissionLists and is consistent with the list in **Recents**.
14
15  **Figure 1** Mission management
16
17  ![mission-list-manager](figures/mission-list-manager.png)
18
19
20Missions are managed by system applications (such as home screen), rather than third-party applications. Users interact with missions through **Recents**. After creating a mission, users can perform the following operations on **Recents**:
21
22
23- Delete a mission.
24
25- Lock or unlock a mission. (Locked missions are not cleared when users attempt to clear all missions in **Recents**.)
26
27- Clear all missions in **Recents**.
28
29- Switch a mission to the foreground.
30
31
32A UIAbility instance corresponds to an independent mission. Therefore, when an application calls [startAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to start a UIAbility, a mission is created.
33
341. To call [missionManager](../reference/apis-ability-kit/js-apis-application-missionManager-sys.md) to manage missions, the home screen application must request the **ohos.permission.MANAGE_MISSIONS** permission. For details, see [Requesting Permissions for system_basic Applications](../security/AccessToken/determine-application-mode.md#requesting-permissions-for-system_basic-applications).
35
362. You can use **missionManager** to manage missions, for example, listening for mission changes, obtaining mission information or snapshots, and clearing, locking, or unlocking missions.
37
38    ```ts
39    import { missionManager } from '@kit.AbilityKit';
40    import { BusinessError } from '@kit.BasicServicesKit';
41    import { image } from '@kit.ImageKit';
42    import { promptAction } from '@kit.ArkUI';
43    import { hilog } from '@kit.PerformanceAnalysisKit';
44
45    const TAG: string = 'TaskManager';
46    const DOMAIN_NUMBER: number = 0xFF00;
47    ```
48    ```ts
49    private listenerId: number = 0;
50    private missionId: number = 0;
51    private listener: missionManager.MissionListener = {
52      // Listen for mission creation.
53      onMissionCreated: (mission: number) => {
54        hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionCreated-------');
55      },
56      // Listen for mission destruction.
57      onMissionDestroyed: (mission: number) => {
58        hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionDestroyed-------');
59      },
60      // Listen for mission snapshot changes.
61      onMissionSnapshotChanged: (mission: number) => {
62        hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionMovedToFront-------');
63      },
64      // Listen for switching the mission to the foreground.
65      onMissionMovedToFront: (mission: number) => {
66        hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionClosed-------');
67      },
68      // Listen for mission icon changes.
69      onMissionIconUpdated: (mission: number, icon: image.PixelMap) => {
70        hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionIconUpdated-------');
71      },
72      // Listen for mission name changes.
73      onMissionLabelUpdated: (mission: number) => {
74        hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionLabelUpdated-------');
75      },
76      // Listen for mission closure events.
77      onMissionClosed: (mission: number) => {
78        hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionClosed-------');
79      }
80    };
81    ```
82    ```ts
83    // 1. Register a mission change listener.
84    this.listenerId = missionManager.on('mission', this.listener);
85    promptAction.showToast({
86      message: 'register_success_toast'
87    });
88    hilog.info(DOMAIN_NUMBER, TAG, `missionManager.on success, listenerId = ${this.listenerId}`);
89    ```
90    ```ts
91    // 2. Obtain the latest 20 missions in the system.
92    missionManager.getMissionInfos('', 20, (error: BusinessError, missions: Array<missionManager.MissionInfo>) => {
93      hilog.info(DOMAIN_NUMBER, TAG, 'getMissionInfos is called, error = ' + JSON.stringify(error));
94      hilog.info(DOMAIN_NUMBER, TAG, 'size = ' + missions.length);
95      hilog.info(DOMAIN_NUMBER, TAG, 'missions = ' + JSON.stringify(missions));
96
97      //Check whether Recents in the system contains etsclock.
98      for (let i = 0;i < missions.length; i++) {
99        if (missions[i].want.bundleName === 'ohos.samples.etsclock') {
100          promptAction.showToast({
101            message: 'obtain_success_toast'
102          });
103          hilog.info(DOMAIN_NUMBER, TAG, `getMissionInfos.find etsclock, missionId  = ${missions[i].missionId}`);
104          this.missionId = missions[i].missionId;
105          return;
106        }
107      }
108      promptAction.showToast({
109        message: 'obtain_failed_toast'
110      });
111    });
112    ```
113    ```ts
114    // 3. Obtain the detailed information about a mission.
115    missionManager.getMissionInfo('', this.missionId).then((data: missionManager.MissionInfo) => {
116      promptAction.showToast({
117        message: JSON.stringify(data.want.bundleName)
118      });
119      hilog.info(DOMAIN_NUMBER, TAG, `getMissionInfo successfully. Data: ${JSON.stringify(data)}`);
120    }).catch((error: BusinessError) => {
121      hilog.info(DOMAIN_NUMBER, TAG, `getMissionInfo failed. Cause: ${error.message}`);
122    });
123    ```
124    ```ts
125    // 4. Obtain the mission snapshot.
126    missionManager.getMissionSnapShot('', this.missionId, (error: BusinessError, snapshot: missionManager.MissionSnapshot) => {
127      if (error === null) {
128        promptAction.showToast({
129          message: 'obtain_snapshot_success_toast'
130        });
131      }
132      hilog.info(DOMAIN_NUMBER, TAG, 'getMissionSnapShot is called, error = ' + JSON.stringify(error));
133      hilog.info(DOMAIN_NUMBER, TAG, 'bundleName = ' + snapshot.ability.bundleName);
134    })
135    ```
136    ```ts
137    // 5. Obtain the low-resolution mission snapshot.
138    missionManager.getLowResolutionMissionSnapShot('', this.missionId, (error: BusinessError, snapshot: missionManager.MissionSnapshot) => {
139      if (error === null) {
140        promptAction.showToast({
141          message: 'obtain_low_snapshot_success_toast'
142        });
143      }
144      hilog.info(DOMAIN_NUMBER, TAG, 'getLowResolutionMissionSnapShot is called, error = ' + JSON.stringify(error));
145      hilog.info(DOMAIN_NUMBER, TAG, 'bundleName = ' + snapshot.ability.bundleName);
146    })
147    ```
148    ```ts
149    // 6-1. Lock the mission.
150    missionManager.lockMission(this.missionId).then(() => {
151      promptAction.showToast({
152        message: 'lock_success_toast'
153      });
154      hilog.info(DOMAIN_NUMBER, TAG, 'lockMission is called ');
155    });
156    ```
157    ```ts
158    // 6-2. Unlock the mission.
159    missionManager.unlockMission(this.missionId).then(() => {
160      promptAction.showToast({
161        message: 'unlock_success_toast'
162      });
163      hilog.info(DOMAIN_NUMBER, TAG, 'unlockMission is called ');
164    });
165    ```
166    ```ts
167    // 7. Switch the mission to the foreground.
168    missionManager.moveMissionToFront(this.missionId).then(() => {
169      hilog.info(DOMAIN_NUMBER, TAG, 'moveMissionToFront is called ');
170    });
171    ```
172    ```ts
173    // 8. Clear a single mission.
174    missionManager.clearMission(this.missionId).then(() => {
175      promptAction.showToast({
176        message: 'delete_success_toast'
177      });
178      hilog.info(DOMAIN_NUMBER, TAG, 'clearMission is called ');
179    });
180    ```
181    ```ts
182    // 9. Clear all missions.
183    missionManager.clearAllMissions().catch((err: BusinessError) => {
184      hilog.info(DOMAIN_NUMBER, TAG, `${err.code}`);
185    });
186    ```
187    ```ts
188    // 10. Deregister the mission change listener.
189    missionManager.off('mission', this.listenerId, (error: BusinessError) => {
190      if (error === null) {
191        promptAction.showToast({
192          message: 'unregister_success_toast'
193        });
194      }
195      hilog.info(DOMAIN_NUMBER, TAG, 'unregisterMissionListener');
196    })
197    ```
198
199
200