js-apis-missionManager.md

# missionManager


> **NOTE**
>
> 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.


Provides mission management. You can use the APIs to lock, unlock, and clear missions, and switch a mission to the foreground.


## Modules to Import


```
import missionManager from '@ohos.application.missionManager'
```


## missionManager.registerMissionListener

registerMissionListener(listener: MissionListener): number;

Registers a listener to observe the mission status.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| listener | MissionListener | Yes| Listener to register.|

**Return value**

| Type| Description|
| -------- | -------- |
| number | Returns the unique index of the mission status listener, which is created by the system and allocated when the listener is registered.|

**Example**

  ```js
  var listener =  {
  	onMissionCreated: this.onMissionCreatedCallback,
  	onMissionDestroyed: this.onMissionDestroyedCallback,
  	onMissionSnapshotChanged: this.onMissionSnapshotChangedCallback,
  	onMissionMovedToFront: this.onMissionMovedToFrontCallback
  };
  console.log("registerMissionListener")
  var listenerid = missionManager.registerMissionListener(listener);

  ```


## missionManager.unregisterMissionListener

unregisterMissionListener(listenerId: number, callback: AsyncCallback<void>): void;

Deregisters a mission status listener. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| listenerId | number | Yes| Unique index of the mission status listener to unregister. It is returned by **registerMissionListener**.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|

**Example**

  ```js
  var listener =  {
    onMissionCreated: this.onMissionCreatedCallback,
    onMissionDestroyed: this.onMissionDestroyedCallback,
    onMissionSnapshotChanged: this.onMissionSnapshotChangedCallback,
    onMissionMovedToFront: this.onMissionMovedToFrontCallback
  };
  console.log("registerMissionListener")
  var listenerid = missionManager.registerMissionListener(listener);

  missionManager.unregisterMissionListener(listenerid, (error) => {
    console.log("unregisterMissionListener");
  })
  ```


## missionManager.unregisterMissionListener

unregisterMissionListener(listenerId: number): Promise<void>;

Deregisters a mission status listener. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| listenerId | number | Yes| Unique index of the mission status listener to unregister. It is returned by **registerMissionListener**.|

**Return value**

| Type| Description|
| -------- | -------- |
| Promise<void> | Promise used to return the result.|

**Example**

  ```js
  var listener =  {
      onMissionCreated: this.onMissionCreatedCallback,
      onMissionDestroyed: this.onMissionDestroyedCallback,
      onMissionSnapshotChanged: this.onMissionSnapshotChangedCallback,
      onMissionMovedToFront: this.onMissionMovedToFrontCallback
    };
    console.log("registerMissionListener")
    var listenerid = missionManager.registerMissionListener(listener);

    missionManager.unregisterMissionListener(listenerid).catch(function (err){
      console.log(err);
    });
  ```


## missionManager.getMissionInfo

getMissionInfo(deviceId: string, missionId: number, callback: AsyncCallback<MissionInfo>): void;

Obtains the information about a given mission. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| deviceId | string | Yes| Device ID. It is a null string by default for the local device.|
| missionId | number | Yes| Mission ID.|
| callback | AsyncCallback<[MissionInfo](#missioninfo)> | Yes| Callback used to return the mission information obtained.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  missionManager.getMissionInfo("", allMissions[0].missionId, (error, mission) => {
  	console.log("getMissionInfo is called, error.code = " + error.code)
  	console.log("mission.missionId = " + mission.missionId);
  	console.log("mission.runningState = " + mission.runningState);
  	console.log("mission.lockedState = " + mission.lockedState);
  	console.log("mission.timestamp = " + mission.timestamp);
  	console.log("mission.label = " + mission.label);
  	console.log("mission.iconPath = " + mission.iconPath);
  });
  ```


## missionManager.getMissionInfo

getMissionInfo(deviceId: string, missionId: number): Promise<MissionInfo>;

Obtains the information about a given mission. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| deviceId | string | Yes| Device ID. It is a null string by default for the local device.|
| missionId | number | Yes| Mission ID.|

**Return value**

| Type| Description|
| -------- | -------- |
| Promise<[MissionInfo](#missioninfo)> | Promise used to return the mission information obtained.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  var mission = missionManager.getMissionInfo("", id).catch(function (err){
      console.log(err);
  });
  ```


## missionManager.getMissionInfos

getMissionInfos(deviceId: string, numMax: number, callback: AsyncCallback<Array<MissionInfo>>): void;

Obtains information about all missions. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| deviceId | string | Yes| Device ID. It is a null string by default for the local device.|
| numMax | number | Yes| Maximum number of missions whose information can be obtained.|
| callback | AsyncCallback<Array<[MissionInfo](#missioninfo)>> | Yes| Callback used to return the array of mission information obtained.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  missionManager.getMissionInfos("", 10, (error, missions) => {
      console.log("getMissionInfos is called, error.code = " + error.code);
      console.log("size = " + missions.length);
      console.log("missions = " + JSON.stringify(missions));
  })
  ```


## missionManager.getMissionInfos

getMissionInfos(deviceId: string, numMax: number): Promise<Array<MissionInfo>>;

Obtains information about all missions. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| deviceId | string | Yes| Device ID. It is a null string by default for the local device.|
| numMax | number | Yes| Maximum number of missions whose information can be obtained.|

**Return value**

| Type| Description|
| -------- | -------- |
| Promise<Array<[MissionInfo](#missioninfo)>> | Promise used to return the array of mission information obtained.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){
      console.log(err);
  });
  ```


## missionManager.getMissionSnapShot

getMissionSnapShot(deviceId: string, missionId: number, callback: AsyncCallback<MissionSnapshot>): void;

Obtains the snapshot of a given mission. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| deviceId | string | Yes| Device ID. It is a null string by default for the local device.|
| missionId | number | Yes| Mission ID.|
| callback | AsyncCallback<[MissionSnapshot](js-apis-application-MissionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  missionManager.getMissionInfos("", 10, (error, missions) => {
    console.log("getMissionInfos is called, error.code = " + error.code);
    console.log("size = " + missions.length);
    console.log("missions = " + JSON.stringify(missions));
    var id = missions[0].missionId;

    missionManager.getMissionSnapShot("", id, (error, snapshot) => {
  	console.log("getMissionSnapShot is called, error.code = " + error.code);
  	console.log("bundleName = " + snapshot.ability.bundleName);
  })
  })
  ```


## missionManager.getMissionSnapShot

getMissionSnapShot(deviceId: string, missionId: number): Promise<MissionSnapshot>;

Obtains the snapshot of a given mission. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| deviceId | string | Yes| Device ID. It is a null string by default for the local device.|
| missionId | number | Yes| Mission ID.|

**Return value**

| Type| Description|
| -------- | -------- |
| Promise<[MissionSnapshot](js-apis-application-MissionSnapshot.md)> | Promise used to return the snapshot information obtained.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){
    console.log(err);
  });
  console.log("size = " + allMissions.length);
  console.log("missions = " + JSON.stringify(allMissions));
  var id = allMissions[0].missionId;
  var snapshot = missionManager.getMissionSnapShot("", id).catch(function (err){
    console.log(err);
  });
  ```


## missionManager.lockMission

lockMission(missionId: number, callback: AsyncCallback<void>): void;

Locks a given mission. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| missionId | number | Yes| Mission ID.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  missionManager.getMissionInfos("", 10, (error, missions) => {
    console.log("getMissionInfos is called, error.code = " + error.code);
    console.log("size = " + missions.length);
    console.log("missions = " + JSON.stringify(missions));
    var id = missions[0].missionId;

    missionManager.lockMission(id).then(() => {
  	console.log("lockMission is called ");
  });
  });
  ```


## missionManager.lockMission

lockMission(missionId: number): Promise<void>;

Locks a given mission. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| missionId | number | Yes| Mission ID.|

**Return value**

| Type| Description|
| -------- | -------- |
| Promise<void> | Promise used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){
    console.log(err);
  });
  console.log("size = " + allMissions.length);
  console.log("missions = " + JSON.stringify(allMissions));
  var id = allMissions[0].missionId;

  missionManager.lockMission(id).catch(function (err){
      console.log(err);
  });
  ```


## missionManager.unlockMission

unlockMission(missionId: number, callback: AsyncCallback<void>): void;

Unlocks a given mission. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| missionId | number | Yes| Mission ID.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  missionManager.getMissionInfos("", 10, (error, missions) => {
    console.log("getMissionInfos is called, error.code = " + error.code);
    console.log("size = " + missions.length);
    console.log("missions = " + JSON.stringify(missions));
    var id = missions[0].missionId;

    missionManager.unlockMission(id).then(() => {
  	console.log("unlockMission is called ");
  });
  });
  ```


## missionManager.unlockMission

unlockMission(missionId: number): Promise<void>;

Unlocks a given mission. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| missionId | number | Yes| Mission ID.|

**Return value**

| Type| Description|
| -------- | -------- |
| Promise<void> | Promise used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){
    console.log(err);
  });
  console.log("size = " + allMissions.length);
  console.log("missions = " + JSON.stringify(allMissions));
  var id = allMissions[0].missionId;

  missionManager.lockMission(id).catch(function (err){
      console.log(err);
  });
  missionManager.unlockMission(id).catch(function (err){
      console.log(err);
  });
  ```


## missionManager.clearMission

clearMission(missionId: number, callback: AsyncCallback<void>): void;

Clears a given mission, regardless of whether it is locked. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| missionId | number | Yes| Mission ID.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  missionManager.getMissionInfos("", 10, (error, missions) => {
    console.log("getMissionInfos is called, error.code = " + error.code);
    console.log("size = " + missions.length);
    console.log("missions = " + JSON.stringify(missions));
    var id = missions[0].missionId;

    missionManager.clearMission(id).then(() => {
  	console.log("clearMission is called ");
  });
  });
  ```


## missionManager.clearMission

clearMission(missionId: number): Promise<void>;

Clears a given mission, regardless of whether it is locked. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| missionId | number | Yes| Mission ID.|

**Return value**

| Type| Description|
| -------- | -------- |
| Promise<void> | Promise used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){
    console.log(err);
  });
  console.log("size = " + allMissions.length);
  console.log("missions = " + JSON.stringify(allMissions));
  var id = allMissions[0].missionId;

  missionManager.clearMission(id).catch(function (err){
    console.log(err);
  });
  ```


## missionManager.clearAllMissions

clearAllMissions(callback: AsyncCallback<void>): void;

Clears all unlocked missions. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  missionManager.clearAllMissions().then(() => {
    console.log("clearAllMissions is called ");
  });
  ```


## missionManager.clearAllMissions

clearAllMissions(): Promise<void>;

Clears all unlocked missions. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Return value**

| Type| Description|
| -------- | -------- |
| Promise<void> | Promise used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'
  missionManager.clearAllMissions().catch(function (err){
    console.log(err);
  });
  ```


## missionManager.moveMissionToFront

moveMissionToFront(missionId: number, callback: AsyncCallback<void>): void;

Switches a given mission to the foreground. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| missionId | number | Yes| Mission ID.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  missionManager.getMissionInfos("", 10, (error, missions) => {
    console.log("getMissionInfos is called, error.code = " + error.code);
    console.log("size = " + missions.length);
    console.log("missions = " + JSON.stringify(missions));
    var id = missions[0].missionId;

    missionManager.moveMissionToFront(id).then(() => {
  	console.log("moveMissionToFront is called ");
  });
  });
  ```


## missionManager.moveMissionToFront

moveMissionToFront(missionId: number, options: StartOptions, callback: AsyncCallback<void>): void;

Switches a given mission to the foreground, with the startup parameters for the switch specified, such as the window mode and device ID. This API uses an asynchronous callback to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| missionId | number | Yes| Mission ID.|
| options | StartOptions | Yes| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  missionManager.getMissionInfos("", 10, (error, missions) => {
    console.log("getMissionInfos is called, error.code = " + error.code);
    console.log("size = " + missions.length);
    console.log("missions = " + JSON.stringify(missions));
    var id = missions[0].missionId;

    missionManager.moveMissionToFront(id,{windowMode : 101}).then(() => {
  	console.log("moveMissionToFront is called ");
    });
  });
  ```


## missionManager.moveMissionToFront

moveMissionToFront(missionId: number, options?: StartOptions): Promise<void>;

Switches a given mission to the foreground, with the startup parameters for the switch specified, such as the window mode and device ID. This API uses a promise to return the result.

**System capability**: SystemCapability.Ability.AbilityRuntime.Mission

**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| missionId | number | Yes| Mission ID.|
| options | StartOptions | No| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.|

**Return value**

| Type| Description|
| -------- | -------- |
| Promise<void> | Promise used to return the result.|

**Example**

  ```js
  import missionManager from '@ohos.application.missionManager'

  var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){
    console.log(err);
  });
  console.log("size = " + allMissions.length);
  console.log("missions = " + JSON.stringify(allMissions));
  var id = allMissions[0].missionId;

  missionManager.moveMissionToFront(id).catch(function (err){
    console.log(err);
  });
  ```