Mission Management Scenarios (for System Applications Only)

Before getting started with the development of mission management, be familiar with the following concepts related to mission management:

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.
MissionRecord: minimum unit for mission management. One MissionRecord has only one AbilityRecord. In other words, a UIAbility component instance corresponds to a mission.
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.
MissionListManager: system mission management module that maintains all the MissionLists and is consistent with the list in the recent task list.

Figure 1 Mission management

Missions are managed by system applications (such as home screen), rather than third-party applications. Users interact with missions through the recent task list. After creating a mission, users can perform the following operations in the recent task list:

Delete a mission.
Lock or unlock a mission. (Locked missions are not cleared when users attempt to clear all missions in the recent task list.)
Clear all missions in the recent task list.
Switch a mission to the foreground.

A UIAbility instance corresponds to an independent mission. Therefore, when an application calls startAbility() to start a UIAbility, a mission is created.

To call missionManager to manage missions, the home screen application must request the ohos.permission.MANAGE_MISSIONS permission. For details, see Requesting Permissions for system_basic Applications.

You can use missionManager to manage missions, for example, listening for mission changes, obtaining mission information or snapshots, and clearing, locking, or unlocking missions.

import { missionManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { image } from '@kit.ImageKit';
import { promptAction } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = 'TaskManager';
const DOMAIN_NUMBER: number = 0xFF00;

private listenerId: number = 0;
private missionId: number = 0;
private listener: missionManager.MissionListener = {
  // Listen for mission creation.
  onMissionCreated: (mission: number) => {
    hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionCreated-------');
  },
  // Listen for mission destruction.
  onMissionDestroyed: (mission: number) => {
    hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionDestroyed-------');
  },
  // Listen for mission snapshot changes.
  onMissionSnapshotChanged: (mission: number) => {
    hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionSnapshotChanged-------');
  },
  // Listen for switching the mission to the foreground.
  onMissionMovedToFront: (mission: number) => {
    hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionMovedToFront-------');
  },
  // Listen for mission icon changes.
  onMissionIconUpdated: (mission: number, icon: image.PixelMap) => {
    hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionIconUpdated-------');
  },
  // Listen for mission name changes.
  onMissionLabelUpdated: (mission: number) => {
    hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionLabelUpdated-------');
  },
  // Listen for mission closure events.
  onMissionClosed: (mission: number) => {
    hilog.info(DOMAIN_NUMBER, TAG, '--------onMissionClosed-------');
  }
};

// 1. Register a mission change listener.
this.listenerId = missionManager.on('mission', this.listener);
this.getUIContext().getPromptAction().showToast({
  message: 'register_success_toast'
});
hilog.info(DOMAIN_NUMBER, TAG, `missionManager.on success, listenerId = ${this.listenerId}`);

// 2. Obtain the latest 20 missions in the system.
missionManager.getMissionInfos('', 20,
  (error: BusinessError, missions: Array<missionManager.MissionInfo>) => {
    if (error.code) {
      hilog.error(DOMAIN_NUMBER, TAG,
        `getMissionInfos is called, error code: ${error.code}, err msg: ${error.message}.`);
      return;
    }
    hilog.info(DOMAIN_NUMBER, TAG, `size = ${missions.length}.`);
    hilog.info(DOMAIN_NUMBER, TAG, `missions = ${JSON.stringify(missions)}.`);

    //Check whether the recent task list contains etsclock.
    for (let i = 0; i < missions.length; i++) {
      if (missions[i].want.bundleName === 'ohos.samples.etsclock') {
        this.getUIContext().getPromptAction().showToast({
          message: 'obtain_success_toast'
        });
        hilog.info(DOMAIN_NUMBER, TAG,
          `getMissionInfos.find etsclock, missionId  = ${missions[i].missionId}`);
        this.missionId = missions[i].missionId;
        return;
      }
    }
    this.getUIContext().getPromptAction().showToast({
      message: 'obtain_failed_toast'
    });
  });

// 3. Obtain the detailed information about a mission.
missionManager.getMissionInfo('', this.missionId).then((data: missionManager.MissionInfo) => {
  this.getUIContext().getPromptAction().showToast({
    message: JSON.stringify(data.want.bundleName)
  });
  hilog.info(DOMAIN_NUMBER, TAG, `getMissionInfo successfully. Data: ${JSON.stringify(data)}`);
}).catch((error: BusinessError) => {
  hilog.error(DOMAIN_NUMBER, TAG, `getMissionInfo failed. Cause: ${error.message}`);
});

// 4. Obtain the mission snapshot.
missionManager.getMissionSnapShot('', this.missionId,
  (error: BusinessError, snapshot: missionManager.MissionSnapshot) => {
    if (error === null) {
      hilog.info(DOMAIN_NUMBER, TAG, `bundleName = ${snapshot.ability.bundleName}.`);
      this.getUIContext().getPromptAction().showToast({
        message: 'obtain_snapshot_success_toast'
      });
    } else {
      hilog.error(DOMAIN_NUMBER, TAG,
          `getMissionSnapShot is called, error code: ${error.code}, error msg: ${error.message}.`);
    }
  });

// 5. Obtain the low-resolution mission snapshot.
missionManager.getLowResolutionMissionSnapShot('', this.missionId,
  (error: BusinessError, snapshot: missionManager.MissionSnapshot) => {
    if (error === null) {
      hilog.info(DOMAIN_NUMBER, TAG, `bundleName = ${snapshot.ability.bundleName}.`);
      this.getUIContext().getPromptAction().showToast({
        message: 'obtain_low_snapshot_success_toast'
      });
    } else {
      hilog.error(DOMAIN_NUMBER, TAG,
          `getLowResolutionMissionSnapShot is called, error code: ${error.code}, error msg: ${error.message}.`);
    }
  });

// 6-1. Lock the mission.
missionManager.lockMission(this.missionId).then(() => {
  this.getUIContext().getPromptAction().showToast({
    message: 'lock_success_toast'
  });
  hilog.info(DOMAIN_NUMBER, TAG, 'lockMission is called ');
});

// 6-2. Unlock the mission.
missionManager.unlockMission(this.missionId).then(() => {
  this.getUIContext().getPromptAction().showToast({
    message: 'unlock_success_toast'
  });
  hilog.info(DOMAIN_NUMBER, TAG, 'unlockMission is called ');
});

// 7. Switch the mission to the foreground.
missionManager.moveMissionToFront(this.missionId).then(() => {
  hilog.info(DOMAIN_NUMBER, TAG, 'moveMissionToFront is called ');
});

// 8. Clear a single mission.
missionManager.clearMission(this.missionId).then(() => {
  this.getUIContext().getPromptAction().showToast({
    message: 'delete_success_toast'
  });
  hilog.info(DOMAIN_NUMBER, TAG, 'clearMission is called ');
});

// 9. Clear all missions.
missionManager.clearAllMissions().catch((err: BusinessError) => {
  hilog.error(DOMAIN_NUMBER, TAG, `${err.code}`);
});

// 10. Deregister the mission change listener.
missionManager.off('mission', this.listenerId, (error: BusinessError) => {
  if (error === null) {
    this.getUIContext().getPromptAction().showToast({
      message: 'unregister_success_toast'
    });
  }
  hilog.info(DOMAIN_NUMBER, TAG, 'unregisterMissionListener');
});