• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.distributedMissionManager (Distributed Mission Management)
2
3The **distributedMissionManager** module implements system mission management across devices. You can use the APIs provided by this module to register or deregister a mission status listener, start or stop synchronizing a remote mission list, and continue a mission on a remote device.
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> The APIs provided by this module are system APIs.
10
11## Modules to Import
12
13```js
14import distributedMissionManager from '@ohos.distributedMissionManager'
15```
16
17
18## distributedMissionManager.registerMissionListener
19
20registerMissionListener(parameter: MissionDeviceInfo, options: MissionCallback, callback: AsyncCallback<void>): void;
21
22Registers a mission status listener. This API uses an asynchronous callback to return the result.
23
24**Required permissions**: ohos.permission.MANAGE_MISSIONS
25
26**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
27
28**Parameters**
29
30| Name      | Type                                     | Mandatory  | Description       |
31| --------- | --------------------------------------- | ---- | --------- |
32| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes   | Information about the device to listen for.|
33| options   | [MissionCallback](#missioncallback)     | Yes   | Callback to register. |
34| callback  | AsyncCallback<void>               | Yes   | Callback used to return the result.|
35
36**Example**
37
38  ```ts
39  function NotifyMissionsChanged(deviceId) {
40      console.log('NotifyMissionsChanged deviceId ' + JSON.stringify(deviceId));
41  }
42  function NotifySnapshot(deviceId, missionId) {
43      console.log('NotifySnapshot deviceId ' + JSON.stringify(deviceId));
44      console.log('NotifySnapshot missionId ' + JSON.stringify(missionId));
45  }
46  function NotifyNetDisconnect(deviceId, state) {
47      console.log('NotifyNetDisconnect deviceId ' + JSON.stringify(deviceId));
48      console.log('NotifyNetDisconnect state ' + JSON.stringify(state));
49  }
50  var parameter =  {
51      deviceId: ""
52  };
53  var options = {
54      notifyMissionsChanged: NotifyMissionsChanged,
55      notifySnapshot: NotifySnapshot,
56      notifyNetDisconnect: NotifyNetDisconnect
57  }
58  try {
59      distributedMissionManager.registerMissionListener(parameter, options, (error) => {
60          if (error.code != 0) {
61              console.error('registerMissionListener failed, cause: ' + JSON.stringify(error))
62          }
63          console.info('registerMissionListener finished')
64      })
65  } catch (error) {
66      console.error('registerMissionListener failed, cause: ' + JSON.stringify(error))
67  }
68  ```
69## distributedMissionManager.registerMissionListener
70
71registerMissionListener(parameter: MissionDeviceInfo, options: MissionCallback): Promise<void>
72
73Registers a mission status listener. This API uses a promise to return the result.
74
75**Required permissions**: ohos.permission.MANAGE_MISSIONS
76
77**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
78
79**Parameters**
80
81| Name      | Type                                      | Mandatory  | Description      |
82| --------- | ---------------------------------------- | ---- | -------- |
83| parameter | [MissionDeviceInfo](#missiondeviceinfo)  | Yes   | Information about the device to listen for.   |
84| options   | <a href="#missioncallback">MissionCallback</a> | Yes   | Callback to register.|
85
86**Return value**
87
88| Type                 | Description              |
89| ------------------- | ---------------- |
90| Promise&lt;void&gt; | Promise used to return the result.|
91
92**Example**
93
94  ```ts
95  function NotifyMissionsChanged(deviceId) {
96      console.log('NotifyMissionsChanged deviceId ' + JSON.stringify(deviceId));
97  }
98  function NotifySnapshot(deviceId, missionId) {
99      console.log('NotifySnapshot deviceId ' + JSON.stringify(deviceId));
100      console.log('NotifySnapshot missionId ' + JSON.stringify(missionId));
101  }
102  function NotifyNetDisconnect(deviceId, state) {
103      console.log('NotifyNetDisconnect deviceId ' + JSON.stringify(deviceId));
104      console.log('NotifyNetDisconnect state ' + JSON.stringify(state));
105  }
106  var parameter =  {
107      deviceId: ""
108  };
109  var options = {
110      notifyMissionsChanged: NotifyMissionsChanged,
111      notifySnapshot: NotifySnapshot,
112      notifyNetDisconnect: NotifyNetDisconnect
113  }
114  try {
115      distributedMissionManager.registerMissionListener(parameter, options)
116      .then(data => {
117          console.info('registerMissionListener finished, ' + JSON.stringify(data));
118      }).catch(error => {
119          console.error('registerMissionListener failed, cause: ' + JSON.stringify(error));
120      })
121  } catch (error) {
122      console.error('registerMissionListener failed, cause: ' + JSON.stringify(error))
123  }
124  ```
125
126
127## distributedMissionManager.unRegisterMissionListener
128
129unRegisterMissionListener(parameter: MissionDeviceInfo, callback: AsyncCallback&lt;void&gt;): void;
130
131Deregisters a mission status listener. This API uses an asynchronous callback to return the result.
132
133**Required permissions**: ohos.permission.MANAGE_MISSIONS
134
135**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
136
137**Parameters**
138
139| Name      | Type                                     | Mandatory  | Description       |
140| --------- | --------------------------------------- | ---- | --------- |
141| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes   | Information about the device to listen for.    |
142| callback  | AsyncCallback&lt;void&gt;               | Yes   | Callback used to return the result.|
143
144**Example**
145
146  ```ts
147  var parameter =  {
148      deviceId: ""
149  };
150  try {
151      distributedMissionManager.unRegisterMissionListener(parameter, (error) => {
152          if (error.code != 0) {
153              console.error('unRegisterMissionListener failed, cause: ' + JSON.stringify(error))
154          }
155          console.info('unRegisterMissionListener finished')
156      })
157  } catch (error) {
158      console.error('unRegisterMissionListener failed, cause: ' + JSON.stringify(error))
159  }
160  ```
161
162
163## distributedMissionManager.unRegisterMissionListener
164
165unRegisterMissionListener(parameter: MissionDeviceInfo): Promise&lt;void&gt;
166
167Deregisters a mission status listener. This API uses a promise to return the result.
168
169**Required permissions**: ohos.permission.MANAGE_MISSIONS
170
171**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
172
173**Parameters**
174
175| Name      | Type                                     | Mandatory  | Description   |
176| --------- | --------------------------------------- | ---- | ----- |
177| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes   | Information about the device to listen for.|
178
179**Return value**
180
181| Type                 | Description              |
182| ------------------- | ---------------- |
183| Promise&lt;void&gt; | Promise used to return the result.|
184
185**Example**
186
187  ```ts
188  var parameter =  {
189      deviceId: ""
190  };
191  try {
192      distributedMissionManager.unRegisterMissionListener(parameter)
193      .then(data => {
194          console.info('unRegisterMissionListener finished, ' + JSON.stringify(data));
195      }).catch(error => {
196          console.error('unRegisterMissionListener failed, cause: ' + JSON.stringify(error));
197      })
198  } catch (error) {
199      console.error('unRegisterMissionListener failed, cause: ' + JSON.stringify(error))
200  }
201  ```
202
203## distributedMissionManager.startSyncRemoteMissions
204
205startSyncRemoteMissions(parameter: MissionParameter, callback: AsyncCallback&lt;void&gt;): void;
206
207Starts to synchronize the remote mission list. This API uses an asynchronous callback to return the result.
208
209**Required permissions**: ohos.permission.MANAGE_MISSIONS
210
211**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
212
213**Parameters**
214
215| Name      | Type                                   | Mandatory  | Description       |
216| --------- | ------------------------------------- | ---- | --------- |
217| parameter | [MissionParameter](#missionparameter) | Yes   | Parameters required for synchronization.    |
218| callback  | AsyncCallback&lt;void&gt;             | Yes   | Callback used to return the result.|
219
220**Example**
221
222  ```ts
223  var parameter =  {
224      deviceId: "",
225      fixConflict: false,
226      tag: 0
227  };
228  try {
229      distributedMissionManager.startSyncRemoteMissions(parameter, (error) => {
230          if (error.code != 0) {
231              console.error('startSyncRemoteMissions failed, cause: ' + JSON.stringify(error))
232          }
233          console.info('startSyncRemoteMissions finished')
234      })
235  } catch (error) {
236      console.error('startSyncRemoteMissions failed, cause: ' + JSON.stringify(error))
237  }
238  ```
239
240## distributedMissionManager.startSyncRemoteMissions
241
242startSyncRemoteMissions(parameter: MissionParameter): Promise&lt;void&gt;
243
244Starts to synchronize the remote mission list. This API uses a promise to return the result.
245
246**Required permissions**: ohos.permission.MANAGE_MISSIONS
247
248**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
249
250**Parameters**
251
252| Name      | Type                                   | Mandatory  | Description   |
253| --------- | ------------------------------------- | ---- | ----- |
254| parameter | [MissionParameter](#missionparameter) | Yes   | Parameters required for synchronization.|
255
256**Return value**
257
258| Type                 | Description              |
259| ------------------- | ---------------- |
260| Promise&lt;void&gt; | Promise used to return the result.|
261
262**Example**
263
264  ```ts
265  var parameter =  {
266      deviceId: "",
267      fixConflict: false,
268      tag: 0
269  };
270  try {
271      distributedMissionManager.startSyncRemoteMissions(parameter)
272      .then(data => {
273          console.info('startSyncRemoteMissions finished, ' + JSON.stringify(data));
274      }).catch(error => {
275          console.error('startSyncRemoteMissions failed, cause: ' + JSON.stringify(error));
276      })
277  } catch (error) {
278      console.error('startSyncRemoteMissions failed, cause: ' + JSON.stringify(error))
279  }
280  ```
281
282## distributedMissionManager.stopSyncRemoteMissions
283
284stopSyncRemoteMissions(parameter: MissionDeviceInfo, callback: AsyncCallback&lt;void&gt;): void;
285
286Stops synchronizing the remote mission list. This API uses an asynchronous callback to return the result.
287
288**Required permissions**: ohos.permission.MANAGE_MISSIONS
289
290**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
291
292**Parameters**
293
294| Name      | Type                                     | Mandatory  | Description       |
295| --------- | --------------------------------------- | ---- | --------- |
296| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes   | Parameters required for synchronization.    |
297| callback  | AsyncCallback&lt;void&gt;               | Yes   | Callback used to return the result.|
298
299**Example**
300
301  ```ts
302  var parameter =  {
303      deviceId: ""
304  };
305  try {
306      distributedMissionManager.stopSyncRemoteMissions(parameter, (error) => {
307          if (error.code != 0) {
308              console.error('stopSyncRemoteMissions failed, cause: ' + JSON.stringify(error))
309          }
310          console.info('stopSyncRemoteMissions finished')
311      })
312  } catch (error) {
313      console.error('stopSyncRemoteMissions failed, cause: ' + JSON.stringify(error))
314  }
315  ```
316
317## distributedMissionManager.stopSyncRemoteMissions
318
319stopSyncRemoteMissions(parameter: MissionDeviceInfo): Promise&lt;void&gt;
320
321Stops synchronizing the remote mission list. This API uses a promise to return the result.
322
323**Required permissions**: ohos.permission.MANAGE_MISSIONS
324
325**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
326
327**Parameters**
328
329| Name      | Type                                     | Mandatory  | Description   |
330| --------- | --------------------------------------- | ---- | ----- |
331| parameter | [MissionDeviceInfo](#missiondeviceinfo) | Yes   | Parameters required for synchronization.|
332
333**Return value**
334
335| Type                 | Description              |
336| ------------------- | ---------------- |
337| Promise&lt;void&gt; | Promise used to return the result.|
338
339**Example**
340
341  ```ts
342  var parameter =  {
343      deviceId: ""
344  };
345  try {
346      distributedMissionManager.stopSyncRemoteMissions(parameter)
347      .then(data => {
348          console.info('stopSyncRemoteMissions finished, ' + JSON.stringify(data));
349      }).catch(error => {
350          console.error('stopSyncRemoteMissions failed, cause: ' + JSON.stringify(error));
351      })
352  } catch (error) {
353      console.error('stopSyncRemoteMissions failed, cause: ' + JSON.stringify(error))
354  }
355  ```
356
357## distributedMissionManager.continueMission
358
359continueMission(parameter: ContinueDeviceInfo, options: ContinueCallback, callback: AsyncCallback&lt;void&gt;): void;
360
361Continues a mission on a remote device. This API uses an asynchronous callback to return the result.
362
363**Required permissions**: ohos.permission.MANAGE_MISSIONS and ohos.permission.DISTRIBUTED_DATASYNC
364
365**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
366
367**Parameters**
368
369| Name      | Type                                     | Mandatory  | Description   |
370| --------- | --------------------------------------- | ---- | ----- |
371| parameter | [ContinueDeviceInfo](#js-apis-inner-application-continueDeviceInfo.md) | Yes   | Parameters required for mission continuation.|
372| options | [ContinueCallback](#js-apis-inner-application-continueCallback.md) | Yes   | Callback invoked when the mission continuation is complete.|
373| callback | AsyncCallback&lt;void&gt; | Yes   | Callback used to return the result.|
374
375**Error codes**
376
377For details about the error codes, see [Distributed Scheduler Error Codes](../errorcodes/errorcode-DistributedSchedule.md).
378
379| ID| Error Message|
380| ------- | -------------------------------------------- |
381| 16300501 | The system ability work abnormally. |
382| 16300502 | Failed to get the missionInfo of the specified missionId. |
383| 16300503 | The application is not installed on the remote end and installation-free is not supported. |
384| 16300504 | The application is not installed on the remote end but installation-free is supported, try again with freeInstall flag. |
385| 16300505 | The operation device must be the device where the application to be continued is located or the target device to be continued. |
386| 16300506 | The local continuation task is already in progress. |
387
388**Example**
389
390  ```ts
391  var parameter =  {
392      srcDeviceId: "",
393      dstDeviceId: "",
394      missionId: 1,
395      wantParam: {"key": "value"}
396  };
397  function onContinueDone(resultCode) {
398      console.log('onContinueDone resultCode: ' + JSON.stringify(resultCode));
399  };
400  var options = {
401      onContinueDone: onContinueDone
402  };
403  try {
404      distributedMissionManager.continueMission(parameter, options, (error) => {
405          if (error.code != 0) {
406              console.error('continueMission failed, cause: ' + JSON.stringify(error))
407          }
408          console.info('continueMission finished')
409      })
410  } catch (error) {
411      console.error('continueMission failed, cause: ' + JSON.stringify(error))
412  }
413  ```
414
415## distributedMissionManager.continueMission
416
417continueMission(parameter: ContinueDeviceInfo, options: ContinueCallback): Promise&lt;void&gt;
418
419Continues a mission on a remote device. This API uses a promise to return the result.
420
421**Required permissions**: ohos.permission.MANAGE_MISSIONS and ohos.permission.DISTRIBUTED_DATASYNC
422
423**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
424
425**Parameters**
426
427| Name      | Type                                     | Mandatory  | Description   |
428| --------- | --------------------------------------- | ---- | ----- |
429| parameter | [ContinueDeviceInfo](#js-apis-inner-application-continueDeviceInfo.md) | Yes   | Parameters required for mission continuation.|
430| options | [ContinueCallback](#js-apis-inner-application-continueCallback.md) | Yes   | Callback invoked when the mission continuation is complete.|
431
432**Return value**
433
434| Type                 | Description              |
435| ------------------- | ---------------- |
436| Promise&lt;void&gt; | Promise used to return the result.|
437
438**Error codes**
439
440For details about the error codes, see [Distributed Scheduler Error Codes](../errorcodes/errorcode-DistributedSchedule.md).
441
442| ID| Error Message|
443| ------- | -------------------------------------------- |
444| 16300501 | The system ability work abnormally. |
445| 16300502 | Failed to get the missionInfo of the specified missionId. |
446| 16300503 | The application is not installed on the remote end and installation-free is not supported. |
447| 16300504 | The application is not installed on the remote end but installation-free is supported, try again with freeInstall flag. |
448| 16300505 | The operation device must be the device where the application to be continued is located or the target device to be continued. |
449| 16300506 | The local continuation task is already in progress. |
450
451**Example**
452
453  ```ts
454  var parameter =  {
455      srcDeviceId: "",
456      dstDeviceId: "",
457      missionId: 1,
458      wantParam: {"key": "value"}
459  };
460  function onContinueDone(resultCode) {
461      console.log('onContinueDone resultCode: ' + JSON.stringify(resultCode));
462  };
463  var options = {
464      onContinueDone: onContinueDone
465  };
466  try {
467      distributedMissionManager.continueMission(parameter, options)
468      .then(data => {
469          console.info('continueMission finished, ' + JSON.stringify(data));
470      }).catch(error => {
471          console.error('continueMission failed, cause: ' + JSON.stringify(error));
472      })
473  } catch (error) {
474      console.error('continueMission failed, cause: ' + JSON.stringify(error))
475  }
476  ```
477
478## MissionCallback
479
480Defines the callbacks that can be registered as a mission status listener.
481
482**Required permissions**: ohos.permission.MANAGE_MISSIONS
483
484**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
485
486| Name                   | Type      | Readable  | Writable  | Description                |
487| --------------------- | -------- | ---- | ---- | ------------------ |
488| notifyMissionsChanged | function | Yes   | No   | Callback used to notify the mission change event and return the device ID.    |
489| notifySnapshot        | function | Yes   | No   | Callback used to notify the snapshot change event and return the device ID and mission ID.|
490| notifyNetDisconnect   | function | Yes   | No   | Callback used to notify the disconnection event and return the device ID and network status.|
491
492## MissionParameter
493
494Defines the parameters required for mission synchronization.
495
496**Required permissions**: ohos.permission.MANAGE_MISSIONS
497
498**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
499
500| Name         | Type   | Readable  | Writable  | Description         |
501| ----------- | ------- | ---- | ---- | ----------- |
502| deviceId    | string  | Yes   | Yes   | Device ID.    |
503| fixConflict | boolean | Yes   | Yes   | Whether a version conflict occurs.|
504| tag         | number  | Yes   | Yes   | Tag of the mission.   |
505
506## MissionDeviceInfo
507
508Defines the parameters required for registering a listener.
509
510**Required permissions**: ohos.permission.MANAGE_MISSIONS
511
512**System capability**: SystemCapability.Ability.AbilityRuntime.Mission
513
514| Name      | Type  | Readable  | Writable  | Description     |
515| -------- | ------ | ---- | ---- | ------- |
516| deviceId | string | Yes   | Yes   | Device ID.|
517