• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.app.ability.wantAgent (WantAgent)
2
3The **WantAgent** module provides APIs for triggering, canceling, and comparing **WantAgent** objects. You can use the APIs to create a **WantAgent** object, and obtain the user ID, bundle name, and want information of the object.
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## Modules to Import
10
11```js
12import WantAgent from '@ohos.app.ability.wantAgent';
13```
14
15## WantAgent.getWantAgent
16
17getWantAgent(info: WantAgentInfo, callback: AsyncCallback\<WantAgent\>): void
18
19Obtains a **WantAgent** object. This API uses an asynchronous callback to return the result. If the creation fails, a null **WantAgent** object is returned.
20
21**System capability**: SystemCapability.Ability.AbilityRuntime.Core
22
23**Parameters**
24
25| Name    | Type                      | Mandatory| Description                   |
26| -------- | -------------------------- | ---- | ----------------------- |
27| info     | WantAgentInfo              | Yes  | Information about the **WantAgent** object to obtain.          |
28| callback | AsyncCallback\<WantAgent\> | Yes  | Callback used to return the **WantAgent** object.|
29
30**Error codes**
31
32| ID   | Error Message           |
33|-----------|--------------------|
34| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
35| 16000151   | Invalid wantagent object.|
36
37For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
38
39**Example**
40
41```js
42import WantAgent from '@ohos.app.ability.wantAgent';
43
44// getWantAgent callback
45function getWantAgentCallback(err, data) {
46	console.info('==========================>getWantAgentCallback=======================>');
47}
48// WantAgentInfo object
49let wantAgentInfo = {
50    wants: [
51        {
52            deviceId: 'deviceId',
53            bundleName: 'com.neu.setResultOnAbilityResultTest1',
54            abilityName: 'com.example.test.MainAbility',
55            action: 'action1',
56            entities: ['entity1'],
57            type: 'MIMETYPE',
58            uri: 'key={true,true,false}',
59            parameters:
60            {
61                mykey0: 2222,
62                mykey1: [1, 2, 3],
63                mykey2: '[1, 2, 3]',
64                mykey3: 'ssssssssssssssssssssssssss',
65                mykey4: [false, true, false],
66                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
67                mykey6: true,
68            }
69        }
70    ],
71    operationType: WantAgent.OperationType.START_ABILITIES,
72    requestCode: 0,
73    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
74};
75
76try {
77    WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback);
78} catch (paramError) {
79    console.log('error: ' + paramError.code + ', ' + paramError.message);
80}
81```
82
83
84
85## WantAgent.getWantAgent
86
87getWantAgent(info: WantAgentInfo): Promise\<WantAgent\>
88
89Obtains a **WantAgent** object. This API uses a promise to return the result. If the creation fails, a null **WantAgent** object is returned.
90
91**System capability**: SystemCapability.Ability.AbilityRuntime.Core
92
93**Parameters**
94
95| Name| Type         | Mandatory| Description         |
96| ---- | ------------- | ---- | ------------- |
97| info | [WantAgentInfo](js-apis-inner-wantAgent-wantAgentInfo.md) | Yes  | Information about the **WantAgent** object to obtain.|
98
99**Return value**
100
101| Type                                                       | Description                                                        |
102| ----------------------------------------------------------- | ------------------------------------------------------------ |
103| Promise\<WantAgent\> | Promise used to return the **WantAgent** object.|
104
105**Error codes**
106
107| ID   | Error Message           |
108|-----------|--------------------|
109| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
110| 16000151   | Invalid wantagent object.|
111
112For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
113
114**Example**
115
116```ts
117let wantAgent;
118// WantAgentInfo object
119let wantAgentInfo = {
120    wants: [
121        {
122            deviceId: 'deviceId',
123            bundleName: 'com.neu.setResultOnAbilityResultTest1',
124            abilityName: 'com.example.test.MainAbility',
125            action: 'action1',
126            entities: ['entity1'],
127            type: 'MIMETYPE',
128            uri: 'key={true,true,false}',
129            parameters:
130            {
131                mykey0: 2222,
132                mykey1: [1, 2, 3],
133                mykey2: '[1, 2, 3]',
134                mykey3: 'ssssssssssssssssssssssssss',
135                mykey4: [false, true, false],
136                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
137                mykey6: true,
138            }
139        }
140    ],
141    operationType: WantAgent.OperationType.START_ABILITIES,
142    requestCode: 0,
143    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
144};
145
146try {
147    WantAgent.getWantAgent(wantAgentInfo).then((data) => {
148	    console.info('==========================>getWantAgentCallback=======================>');
149    });
150} catch (paramError) {
151    console.log('error: ' + paramError.code + ', ' + paramError.message);
152}
153```
154
155
156
157## WantAgent.getBundleName
158
159getBundleName(agent: WantAgent, callback: AsyncCallback\<string\>): void
160
161Obtains the bundle name of a **WantAgent** object. This API uses an asynchronous callback to return the result.
162
163**System capability**: SystemCapability.Ability.AbilityRuntime.Core
164
165**Parameters**
166
167| Name    | Type                   | Mandatory| Description                             |
168| -------- | ----------------------- | ---- | --------------------------------- |
169| agent    | WantAgent               | Yes  | Target **WantAgent** object.                    |
170| callback | AsyncCallback\<string\> | Yes  | Callback used to return the bundle name.|
171
172**Error codes**
173
174| ID   | Error Message           |
175|-----------|--------------------|
176| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
177| 16000151   | Invalid wantagent object.|
178
179For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
180
181**Example**
182
183```js
184import WantAgent from '@ohos.app.ability.wantAgent';
185
186
187// WantAgent object
188let wantAgent;
189
190// getWantAgent callback
191function getWantAgentCallback(err, data) {
192	console.info('==========================>getWantAgentCallback=======================>');
193    if (err.code == 0) {
194    	wantAgent = data;
195    } else {
196        console.info('----getWantAgent failed!----');
197    }
198}
199// WantAgentInfo object
200let wantAgentInfo = {
201    wants: [
202        {
203            deviceId: 'deviceId',
204            bundleName: 'com.neu.setResultOnAbilityResultTest1',
205            abilityName: 'com.example.test.MainAbility',
206            action: 'action1',
207            entities: ['entity1'],
208            type: 'MIMETYPE',
209            uri: 'key={true,true,false}',
210            parameters:
211            {
212                mykey0: 2222,
213                mykey1: [1, 2, 3],
214                mykey2: '[1, 2, 3]',
215                mykey3: 'ssssssssssssssssssssssssss',
216                mykey4: [false, true, false],
217                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
218                mykey6: true,
219            }
220        }
221    ],
222    operationType: WantAgent.OperationType.START_ABILITIES,
223    requestCode: 0,
224    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
225};
226
227try {
228    WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback);
229
230    // getBundleName callback
231    function getBundleNameCallback(err, data) {
232	    console.info('==========================>getBundleNameCallback=======================>');
233    }
234    WantAgent.getBundleName(wantAgent, getBundleNameCallback);
235} catch (paramError) {
236    console.log('error: ' + paramError.code + ', ' + paramError.message);
237}
238```
239
240
241
242## WantAgent.getBundleName
243
244getBundleName(agent: WantAgent): Promise\<string\>
245
246Obtains the bundle name of a **WantAgent** object. This API uses a promise to return the result.
247
248**System capability**: SystemCapability.Ability.AbilityRuntime.Core
249
250**Parameters**
251
252| Name | Type     | Mandatory| Description         |
253| ----- | --------- | ---- | ------------- |
254| agent | WantAgent | Yes  | Target **WantAgent** object.|
255
256**Return value**
257
258| Type                                                       | Description                                                        |
259| ----------------------------------------------------------- | ------------------------------------------------------------ |
260| Promise\<string\> | Promise used to return the bundle name.|
261
262**Error codes**
263
264| ID   | Error Message           |
265|-----------|--------------------|
266| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
267| 16000151   | Invalid wantagent object.|
268
269For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
270
271**Example**
272
273```js
274import WantAgent from '@ohos.app.ability.wantAgent';
275
276
277// WantAgent object
278let wantAgent;
279
280// WantAgentInfo object
281let wantAgentInfo = {
282    wants: [
283        {
284            deviceId: 'deviceId',
285            bundleName: 'com.neu.setResultOnAbilityResultTest1',
286            abilityName: 'com.example.test.MainAbility',
287            action: 'action1',
288            entities: ['entity1'],
289            type: 'MIMETYPE',
290            uri: 'key={true,true,false}',
291            parameters:
292            {
293                mykey0: 2222,
294                mykey1: [1, 2, 3],
295                mykey2: '[1, 2, 3]',
296                mykey3: 'ssssssssssssssssssssssssss',
297                mykey4: [false, true, false],
298                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
299                mykey6: true,
300            }
301        }
302    ],
303    operationType: WantAgent.OperationType.START_ABILITIES,
304    requestCode: 0,
305    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
306};
307
308try {
309    WantAgent.getWantAgent(wantAgentInfo).then((data) => {
310	    console.info('==========================>getWantAgentCallback=======================>');
311        wantAgent = data;
312    });
313
314    WantAgent.getBundleName(wantAgent).then((data) => {
315	    console.info('==========================>getBundleNameCallback=======================>');
316    });
317} catch (paramError) {
318    console.log('error: ' + paramError.code + ', ' + paramError.message);
319}
320```
321
322
323
324## WantAgent.getUid
325
326getUid(agent: WantAgent, callback: AsyncCallback\<number\>): void
327
328Obtains the user ID of a **WantAgent** object. This API uses an asynchronous callback to return the result.
329
330**System capability**: SystemCapability.Ability.AbilityRuntime.Core
331
332**Parameters**
333
334| Name    | Type                   | Mandatory| Description                               |
335| -------- | ----------------------- | ---- | ----------------------------------- |
336| agent    | WantAgent               | Yes  | Target **WantAgent** object.                      |
337| callback | AsyncCallback\<number\> | Yes  | Callback used to return the user ID.|
338
339**Error codes**
340
341| ID   | Error Message           |
342|-----------|--------------------|
343| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
344| 16000151   | Invalid wantagent object.|
345
346For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
347
348**Example**
349
350```js
351import WantAgent from '@ohos.app.ability.wantAgent';
352
353
354// WantAgent object
355let wantAgent;
356
357// getWantAgent callback
358function getWantAgentCallback(err, data) {
359	console.info('==========================>getWantAgentCallback=======================>');
360    if (err.code == 0) {
361    	wantAgent = data;
362    } else {
363        console.info('----getWantAgent failed!----');
364    }
365}
366// WantAgentInfo object
367let wantAgentInfo = {
368    wants: [
369        {
370            deviceId: 'deviceId',
371            bundleName: 'com.neu.setResultOnAbilityResultTest1',
372            abilityName: 'com.example.test.MainAbility',
373            action: 'action1',
374            entities: ['entity1'],
375            type: 'MIMETYPE',
376            uri: 'key={true,true,false}',
377            parameters:
378            {
379                mykey0: 2222,
380                mykey1: [1, 2, 3],
381                mykey2: '[1, 2, 3]',
382                mykey3: 'ssssssssssssssssssssssssss',
383                mykey4: [false, true, false],
384                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
385                mykey6: true,
386            }
387        }
388    ],
389    operationType: WantAgent.OperationType.START_ABILITIES,
390    requestCode: 0,
391    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
392};
393
394try {
395    WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback);
396
397    // getUid callback
398    function getUidCallback(err, data) {
399	    console.info('==========================>getUidCallback=======================>');
400    }
401    WantAgent.getUid(wantAgent, getUidCallback);
402} catch (paramError) {
403    console.log('error: ' + paramError.code + ', ' + paramError.message);
404}
405```
406
407
408
409## WantAgent.getUid
410
411getUid(agent: WantAgent): Promise\<number\>
412
413Obtains the user ID of a **WantAgent** object. This API uses a promise to return the result.
414
415**System capability**: SystemCapability.Ability.AbilityRuntime.Core
416
417**Parameters**
418
419| Name | Type     | Mandatory| Description         |
420| ----- | --------- | ---- | ------------- |
421| agent | WantAgent | Yes  | Target **WantAgent** object.|
422
423**Return value**
424
425| Type                                                       | Description                                                        |
426| ----------------------------------------------------------- | ------------------------------------------------------------ |
427| Promise\<number\> | Promise used to return the user ID.|
428
429**Error codes**
430
431| ID   | Error Message           |
432|-----------|--------------------|
433| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
434| 16000151   | Invalid wantagent object.|
435
436For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
437
438**Example**
439
440```js
441import WantAgent from '@ohos.app.ability.wantAgent';
442
443
444// WantAgent object
445let wantAgent;
446
447// WantAgentInfo object
448let wantAgentInfo = {
449    wants: [
450        {
451            deviceId: 'deviceId',
452            bundleName: 'com.neu.setResultOnAbilityResultTest1',
453            abilityName: 'com.example.test.MainAbility',
454            action: 'action1',
455            entities: ['entity1'],
456            type: 'MIMETYPE',
457            uri: 'key={true,true,false}',
458            parameters:
459            {
460                mykey0: 2222,
461                mykey1: [1, 2, 3],
462                mykey2: '[1, 2, 3]',
463                mykey3: 'ssssssssssssssssssssssssss',
464                mykey4: [false, true, false],
465                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
466                mykey6: true,
467            }
468        }
469    ],
470    operationType: WantAgent.OperationType.START_ABILITIES,
471    requestCode: 0,
472    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
473};
474
475try {
476    WantAgent.getWantAgent(wantAgentInfo).then((data) => {
477	    console.info('==========================>getWantAgentCallback=======================>');
478        wantAgent = data;
479    });
480
481    WantAgent.getUid(wantAgent).then((data) => {
482	    console.info('==========================>getUidCallback=======================>');
483    });
484} catch (paramError) {
485    console.log('error: ' + paramError.code + ', ' + paramError.message);
486}
487```
488
489
490
491## WantAgent.getWant
492
493getWant(agent: WantAgent, callback: AsyncCallback\<Want\>): void
494
495Obtains the want in a **WantAgent** object. This API uses an asynchronous callback to return the result.
496
497**System capability**: SystemCapability.Ability.AbilityRuntime.Core
498
499**System API**: This is a system API and cannot be called by third-party applications.
500
501**Parameters**
502
503| Name    | Type                 | Mandatory| Description                           |
504| -------- | --------------------- | ---- | ------------------------------- |
505| agent    | WantAgent             | Yes  | Target **WantAgent** object.                  |
506| callback | AsyncCallback\<[Want](js-apis-app-ability-want.md)\> | Yes  | Callback used to return the want.|
507
508**Error codes**
509
510| ID   | Error Message           |
511|-----------|--------------------|
512| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
513| 16000015   | Service timeout.|
514| 16000151   | Invalid wantagent object.|
515
516For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
517
518**Example**
519
520```js
521import WantAgent from '@ohos.app.ability.wantAgent';
522
523
524// WantAgent object
525let wantAgent;
526
527// getWantAgent callback
528function getWantAgentCallback(err, data) {
529	console.info('==========================>getWantAgentCallback=======================>');
530    if (err.code == 0) {
531    	wantAgent = data;
532    } else {
533        console.info('----getWantAgent failed!----');
534    }
535}
536// WantAgentInfo object
537let wantAgentInfo = {
538    wants: [
539        {
540            deviceId: 'deviceId',
541            bundleName: 'com.neu.setResultOnAbilityResultTest1',
542            abilityName: 'com.example.test.MainAbility',
543            action: 'action1',
544            entities: ['entity1'],
545            type: 'MIMETYPE',
546            uri: 'key={true,true,false}',
547            parameters:
548            {
549                mykey0: 2222,
550                mykey1: [1, 2, 3],
551                mykey2: '[1, 2, 3]',
552                mykey3: 'ssssssssssssssssssssssssss',
553                mykey4: [false, true, false],
554                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
555                mykey6: true,
556            }
557        }
558    ],
559    operationType: WantAgent.OperationType.START_ABILITIES,
560    requestCode: 0,
561    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
562};
563
564try {
565    WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback);
566
567    // getWant callback
568    function getWantCallback(err, data) {
569	    console.info('==========================>getWantCallback=======================>');
570    }
571    WantAgent.getWant(wantAgent, getWantCallback);
572} catch (paramError) {
573    console.log('error: ' + paramError.code + ', ' + paramError.message);
574}
575```
576
577
578
579## WantAgent.getWant
580
581getWant(agent: WantAgent): Promise\<Want\>
582
583Obtains the want in a **WantAgent** object. This API uses a promise to return the result.
584
585**System capability**: SystemCapability.Ability.AbilityRuntime.Core
586
587**System API**: This is a system API and cannot be called by third-party applications.
588
589**Parameters**
590
591| Name | Type     | Mandatory| Description         |
592| ----- | --------- | ---- | ------------- |
593| agent | WantAgent | Yes  | Target **WantAgent** object.|
594
595**Return value**
596
597| Type                                                       | Description                                                        |
598| ----------------------------------------------------------- | ------------------------------------------------------------ |
599| Promise\<Want\> | Promise used to return the want.|
600
601**Error codes**
602
603| ID   | Error Message           |
604|-----------|--------------------|
605| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
606| 16000015   | Service timeout.|
607| 16000151   | Invalid wantagent object.|
608
609For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
610
611**Example**
612
613```js
614import WantAgent from '@ohos.app.ability.wantAgent';
615
616
617// WantAgent object
618let wantAgent;
619
620// WantAgentInfo object
621let wantAgentInfo = {
622    wants: [
623        {
624            deviceId: 'deviceId',
625            bundleName: 'com.neu.setResultOnAbilityResultTest1',
626            abilityName: 'com.example.test.MainAbility',
627            action: 'action1',
628            entities: ['entity1'],
629            type: 'MIMETYPE',
630            uri: 'key={true,true,false}',
631            parameters:
632            {
633                mykey0: 2222,
634                mykey1: [1, 2, 3],
635                mykey2: '[1, 2, 3]',
636                mykey3: 'ssssssssssssssssssssssssss',
637                mykey4: [false, true, false],
638                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
639                mykey6: true,
640            }
641        }
642    ],
643    operationType: WantAgent.OperationType.START_ABILITIES,
644    requestCode: 0,
645    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
646};
647
648try {
649    WantAgent.getWantAgent(wantAgentInfo).then((data) => {
650	    console.info('==========================>getWantAgentCallback=======================>');
651        wantAgent = data;
652    });
653
654    WantAgent.getWant(wantAgent).then((data) => {
655	    console.info('==========================>getWantCallback=======================>');
656    });
657} catch (paramError) {
658    console.log('error: ' + paramError.code + ', ' + paramError.message);
659}
660```
661
662
663
664## WantAgent.cancel
665
666cancel(agent: WantAgent, callback: AsyncCallback\<void\>): void
667
668Cancels a **WantAgent** object. This API uses an asynchronous callback to return the result.
669
670**System capability**: SystemCapability.Ability.AbilityRuntime.Core
671
672**Parameters**
673
674| Name    | Type                 | Mandatory| Description                       |
675| -------- | --------------------- | ---- | --------------------------- |
676| agent    | WantAgent             | Yes  | Target **WantAgent** object.              |
677| callback | AsyncCallback\<void\> | Yes  | Callback used to return the result.|
678
679**Error codes**
680
681| ID   | Error Message           |
682|-----------|--------------------|
683| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
684| 16000151   | Invalid wantagent object.|
685
686For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
687
688**Example**
689
690```js
691import WantAgent from '@ohos.app.ability.wantAgent';
692
693
694// WantAgent object
695let wantAgent;
696
697// getWantAgent callback
698function getWantAgentCallback(err, data) {
699	console.info('==========================>getWantAgentCallback=======================>');
700    if (err.code == 0) {
701    	wantAgent = data;
702    } else {
703        console.info('----getWantAgent failed!----');
704    }
705}
706// WantAgentInfo object
707let wantAgentInfo = {
708    wants: [
709        {
710            deviceId: 'deviceId',
711            bundleName: 'com.neu.setResultOnAbilityResultTest1',
712            abilityName: 'com.example.test.MainAbility',
713            action: 'action1',
714            entities: ['entity1'],
715            type: 'MIMETYPE',
716            uri: 'key={true,true,false}',
717            parameters:
718            {
719                mykey0: 2222,
720                mykey1: [1, 2, 3],
721                mykey2: '[1, 2, 3]',
722                mykey3: 'ssssssssssssssssssssssssss',
723                mykey4: [false, true, false],
724                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
725                mykey6: true,
726            }
727        }
728    ],
729    operationType: WantAgent.OperationType.START_ABILITIES,
730    requestCode: 0,
731    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
732};
733
734try {
735    WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback);
736
737    // cancel callback
738    function cancelCallback(err, data) {
739	    console.info('==========================>cancelCallback=======================>');
740    }
741    WantAgent.cancel(wantAgent, cancelCallback);
742} catch (paramError) {
743    console.log('error: ' + paramError.code + ', ' + paramError.message);
744}
745```
746
747
748
749## WantAgent.cancel
750
751cancel(agent: WantAgent): Promise\<void\>
752
753Cancels a **WantAgent** object. This API uses a promise to return the result.
754
755**System capability**: SystemCapability.Ability.AbilityRuntime.Core
756
757**Parameters**
758
759| Name | Type     | Mandatory| Description         |
760| ----- | --------- | ---- | ------------- |
761| agent | WantAgent | Yes  | Target **WantAgent** object.|
762
763**Return value**
764
765| Type           | Description                           |
766| --------------- | ------------------------------- |
767| Promise\<void\> | Promise used to return the result.|
768
769**Error codes**
770
771| ID   | Error Message           |
772|-----------|--------------------|
773| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
774| 16000151   | Invalid wantagent object.|
775
776For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
777
778**Example**
779
780```js
781import WantAgent from '@ohos.app.ability.wantAgent';
782
783
784// WantAgent object
785let wantAgent;
786
787// WantAgentInfo object
788let wantAgentInfo = {
789    wants: [
790        {
791            deviceId: 'deviceId',
792            bundleName: 'com.neu.setResultOnAbilityResultTest1',
793            abilityName: 'com.example.test.MainAbility',
794            action: 'action1',
795            entities: ['entity1'],
796            type: 'MIMETYPE',
797            uri: 'key={true,true,false}',
798            parameters:
799            {
800                mykey0: 2222,
801                mykey1: [1, 2, 3],
802                mykey2: '[1, 2, 3]',
803                mykey3: 'ssssssssssssssssssssssssss',
804                mykey4: [false, true, false],
805                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
806                mykey6: true,
807            }
808        }
809    ],
810    operationType: WantAgent.OperationType.START_ABILITIES,
811    requestCode: 0,
812    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
813};
814
815try {
816    WantAgent.getWantAgent(wantAgentInfo).then((data) => {
817	    console.info('==========================>getWantAgentCallback=======================>');
818        wantAgent = data;
819    });
820
821    WantAgent.cancel(wantAgent).then((data) => {
822	    console.info('==========================>cancelCallback=======================>');
823    });
824} catch (paramError) {
825    console.log('error: ' + paramError.code + ', ' + paramError.message);
826}
827```
828
829
830
831## WantAgent.trigger
832
833trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: AsyncCallback\<CompleteData\>): void
834
835Triggers a **WantAgent** object. This API uses an asynchronous callback to return the result.
836
837**System capability**: SystemCapability.Ability.AbilityRuntime.Core
838
839**Parameters**
840
841| Name       | Type                         | Mandatory| Description                           |
842| ----------- | ----------------------------- | ---- | ------------------------------- |
843| agent       | WantAgent                     | Yes  | Target **WantAgent** object.                  |
844| triggerInfo | TriggerInfo                   | Yes  | **TriggerInfo** object.                |
845| callback    | AsyncCallback\<[CompleteData](#completedata)\> | No  | Callback used to return the result.|
846
847**Example**
848
849```js
850import WantAgent from '@ohos.app.ability.wantAgent';
851
852
853// WantAgent object
854let wantAgent;
855
856// getWantAgent callback
857function getWantAgentCallback(err, data) {
858	console.info('==========================>getWantAgentCallback=======================>');
859    if (err.code == 0) {
860    	wantAgent = data;
861    } else {
862        console.info('----getWantAgent failed!----');
863    }
864}
865// WantAgentInfo object
866let wantAgentInfo = {
867    wants: [
868        {
869            deviceId: 'deviceId',
870            bundleName: 'com.neu.setResultOnAbilityResultTest1',
871            abilityName: 'com.example.test.MainAbility',
872            action: 'action1',
873            entities: ['entity1'],
874            type: 'MIMETYPE',
875            uri: 'key={true,true,false}',
876            parameters:
877            {
878                mykey0: 2222,
879                mykey1: [1, 2, 3],
880                mykey2: '[1, 2, 3]',
881                mykey3: 'ssssssssssssssssssssssssss',
882                mykey4: [false, true, false],
883                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
884                mykey6: true,
885            }
886        }
887    ],
888    operationType: WantAgent.OperationType.START_ABILITIES,
889    requestCode: 0,
890    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
891};
892
893try {
894    WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback);
895
896    // trigger callback
897    function triggerCallback(data) {
898	    console.info('==========================>triggerCallback=======================>');
899    }
900
901
902    let triggerInfo = {
903        code:0
904    };
905    WantAgent.trigger(wantAgent, triggerInfo, triggerCallback);
906} catch (paramError) {
907    console.log('error: ' + paramError.code + ', ' + paramError.message);
908}
909```
910
911
912
913## WantAgent.equal
914
915equal(agent: WantAgent, otherAgent: WantAgent, callback: AsyncCallback\<boolean\>): void
916
917Checks whether two **WantAgent** objects are equal. This API uses an asynchronous callback to return the result.
918
919**System capability**: SystemCapability.Ability.AbilityRuntime.Core
920
921**Parameters**
922
923| Name      | Type                    | Mandatory| Description                                   |
924| ---------- | ------------------------ | ---- | --------------------------------------- |
925| agent      | WantAgent                | Yes  | The first **WantAgent** object.                          |
926| otherAgent | WantAgent                | Yes  | The second **WantAgent** object.                          |
927| callback   | AsyncCallback\<boolean\> | Yes  | Callback used to return the result.|
928
929**Example**
930
931```js
932import WantAgent from '@ohos.app.ability.wantAgent';
933
934
935// WantAgent object
936let wantAgent1;
937let wantAgent2;
938
939// getWantAgent callback
940function getWantAgentCallback(err, data) {
941	console.info('==========================>getWantAgentCallback=======================>');
942    if (err.code == 0) {
943    	wantAgent1 = data;
944        wantAgent2 = data;
945    } else {
946        console.info('----getWantAgent failed!----');
947    }
948}
949// WantAgentInfo object
950let wantAgentInfo = {
951    wants: [
952        {
953            deviceId: 'deviceId',
954            bundleName: 'com.neu.setResultOnAbilityResultTest1',
955            abilityName: 'com.example.test.MainAbility',
956            action: 'action1',
957            entities: ['entity1'],
958            type: 'MIMETYPE',
959            uri: 'key={true,true,false}',
960            parameters:
961            {
962                mykey0: 2222,
963                mykey1: [1, 2, 3],
964                mykey2: '[1, 2, 3]',
965                mykey3: 'ssssssssssssssssssssssssss',
966                mykey4: [false, true, false],
967                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
968                mykey6: true,
969            }
970        }
971    ],
972    operationType: WantAgent.OperationType.START_ABILITIES,
973    requestCode: 0,
974    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
975};
976
977try {
978    WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback);
979
980    // equal callback
981    function equalCallback(err, data) {
982	    console.info('==========================>equalCallback=======================>');
983    }
984    WantAgent.equal(wantAgent1, wantAgent2, equalCallback);
985} catch (paramError) {
986    console.log('error: ' + paramError.code + ', ' + paramError.message);
987}
988```
989
990
991
992## WantAgent.equal
993
994equal(agent: WantAgent, otherAgent: WantAgent): Promise\<boolean\>
995
996Checks whether two **WantAgent** objects are equal. This API uses a promise to return the result.
997
998**System capability**: SystemCapability.Ability.AbilityRuntime.Core
999
1000**Parameters**
1001
1002| Name      | Type     | Mandatory| Description         |
1003| ---------- | --------- | ---- | ------------- |
1004| agent      | WantAgent | Yes  | The first **WantAgent** object.|
1005| otherAgent | WantAgent | Yes  | The second **WantAgent** object.|
1006
1007**Return value**
1008
1009| Type                                                       | Description                                                        |
1010| ----------------------------------------------------------- | ------------------------------------------------------------ |
1011| Promise\<boolean\> | Promise used to return the result.|
1012
1013**Example**
1014
1015```js
1016import WantAgent from '@ohos.app.ability.wantAgent';
1017
1018
1019// WantAgent object
1020let wantAgent1;
1021let wantAgent2;
1022
1023// WantAgentInfo object
1024let wantAgentInfo = {
1025    wants: [
1026        {
1027            deviceId: 'deviceId',
1028            bundleName: 'com.neu.setResultOnAbilityResultTest1',
1029            abilityName: 'com.example.test.MainAbility',
1030            action: 'action1',
1031            entities: ['entity1'],
1032            type: 'MIMETYPE',
1033            uri: 'key={true,true,false}',
1034            parameters:
1035            {
1036                mykey0: 2222,
1037                mykey1: [1, 2, 3],
1038                mykey2: '[1, 2, 3]',
1039                mykey3: 'ssssssssssssssssssssssssss',
1040                mykey4: [false, true, false],
1041                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
1042                mykey6: true,
1043            }
1044        }
1045    ],
1046    operationType: WantAgent.OperationType.START_ABILITIES,
1047    requestCode: 0,
1048    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
1049};
1050
1051try {
1052    WantAgent.getWantAgent(wantAgentInfo).then((data) => {
1053	    console.info('==========================>getWantAgentCallback=======================>');
1054        wantAgent1 = data;
1055        wantAgent2 = data;
1056    });
1057
1058    WantAgent.equal(wantAgent1, wantAgent2).then((data) => {
1059	    console.info('==========================>equalCallback=======================>');
1060    });
1061} catch (paramError) {
1062    console.log('error: ' + paramError.code + ', ' + paramError.message);
1063}
1064```
1065
1066## WantAgent.getOperationType
1067
1068getOperationType(agent: WantAgent, callback: AsyncCallback\<number>): void;
1069
1070Obtains the operation type of a **WantAgent** object. This API uses an asynchronous callback to return the result.
1071
1072**System capability**: SystemCapability.Ability.AbilityRuntime.Core
1073
1074**Parameters**
1075
1076| Name      | Type                    | Mandatory| Description                                   |
1077| ---------- | ------------------------ | ---- | --------------------------------------- |
1078| agent      | WantAgent                | Yes  | Target **WantAgent** object.                          |
1079| callback   | AsyncCallback\<number> | Yes  | Callback used to return the operation type.|
1080
1081**Error codes**
1082
1083| ID   | Error Message           |
1084|-----------|--------------------|
1085| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
1086| 16000015   | Service timeout.|
1087| 16000151   | Invalid wantagent object.|
1088
1089For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
1090
1091**Example**
1092
1093```js
1094import WantAgent from '@ohos.app.ability.wantAgent';
1095
1096// WantAgent object
1097let wantAgent;
1098
1099// WantAgentInfo object
1100let wantAgentInfo = {
1101    wants: [
1102        {
1103            deviceId: 'deviceId',
1104            bundleName: 'com.neu.setResultOnAbilityResultTest1',
1105            abilityName: 'com.example.test.MainAbility',
1106            action: 'action1',
1107            entities: ['entity1'],
1108            type: 'MIMETYPE',
1109            uri: 'key={true,true,false}',
1110            parameters:
1111            {
1112                mykey0: 2222,
1113                mykey1: [1, 2, 3],
1114                mykey2: '[1, 2, 3]',
1115                mykey3: 'ssssssssssssssssssssssssss',
1116                mykey4: [false, true, false],
1117                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
1118                mykey6: true,
1119            }
1120        }
1121    ],
1122    operationType: WantAgent.OperationType.START_ABILITIES,
1123    requestCode: 0,
1124    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
1125};
1126
1127// getWantAgent callback
1128function getWantAgentCallback(err, data) {
1129    if (err === undefined) {
1130        wantAgent = data;
1131    } else {
1132        console.error('getWantAgent failed ${JSON.stringify(wantAgent)}');
1133    }
1134    // getOperationTypeCallback callback
1135    function getOperationTypeCallback(err, data) {
1136        if(err) {
1137            console.error('getOperationType failed! ${err.code} ${err.message}');
1138        } else {
1139            console.info('getOperationType ok! ${JSON.stringify(data)}');
1140        }
1141    }
1142    try {
1143        WantAgent.getOperationType(wantAgent, getOperationTypeCallback);
1144    } catch(err) {
1145        console.error('getOperationTypeCallback failed! ${err.code} ${err.message}');
1146    }
1147}
1148try {
1149    WantAgent.getWantAgent(wantAgentInfo).then((data) => {
1150	    console.info('==========================>getWantAgentCallback=======================>');
1151        wantAgent = data;
1152    });
1153
1154    WantAgent.getOperationType(wantAgent, (OperationType) => {
1155        console.log('----------- getOperationType ----------, OperationType: ' + OperationType);
1156    })
1157} catch (paramError) {
1158    console.log('error: ' + paramError.code + ', ' + paramError.message);
1159}
1160```
1161
1162## WantAgent.getOperationType
1163
1164getOperationType(agent: WantAgent): Promise\<number>;
1165
1166Obtains the operation type of a **WantAgent** object. This API uses a promise to return the result.
1167
1168**System capability**: SystemCapability.Ability.AbilityRuntime.Core
1169
1170**Parameters**
1171
1172| Name      | Type     | Mandatory| Description         |
1173| ---------- | --------- | ---- | ------------- |
1174| agent      | WantAgent | Yes  | Target **WantAgent** object.|
1175
1176**Return value**
1177
1178| Type                                                       | Description                                                        |
1179| ----------------------------------------------------------- | ------------------------------------------------------------ |
1180| Promise\<number> | Promise used to return the operation type.|
1181
1182**Error codes**
1183
1184| ID   | Error Message           |
1185|-----------|--------------------|
1186| 16000007   | Service busyness. There are concurrent tasks, waiting for retry.|
1187| 16000015   | Service timeout.|
1188| 16000151   | Invalid wantagent object.|
1189
1190For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
1191
1192**Example**
1193
1194```js
1195import WantAgent from '@ohos.app.ability.wantAgent';
1196
1197// WantAgent object
1198let wantAgent;
1199
1200// WantAgentInfo object
1201let wantAgentInfo = {
1202    wants: [
1203        {
1204            deviceId: 'deviceId',
1205            bundleName: 'com.neu.setResultOnAbilityResultTest1',
1206            abilityName: 'com.example.test.MainAbility',
1207            action: 'action1',
1208            entities: ['entity1'],
1209            type: 'MIMETYPE',
1210            uri: 'key={true,true,false}',
1211            parameters:
1212            {
1213                mykey0: 2222,
1214                mykey1: [1, 2, 3],
1215                mykey2: '[1, 2, 3]',
1216                mykey3: 'ssssssssssssssssssssssssss',
1217                mykey4: [false, true, false],
1218                mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
1219                mykey6: true,
1220            }
1221        }
1222    ],
1223    operationType: WantAgent.OperationType.START_ABILITIES,
1224    requestCode: 0,
1225    wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
1226};
1227
1228try {
1229    WantAgent.getWantAgent(wantAgentInfo).then((data) => {
1230	    console.info('==========================>getWantAgentCallback=======================>');
1231        wantAgent = data;
1232    });
1233
1234    WantAgent.getOperationType(wantAgent).then((OperationType) => {
1235        console.log('getOperationType success, OperationType: ' + OperationType);
1236    }).catch((err) => {
1237        console.log('getOperationType fail, err: ' + err);
1238    })
1239} catch (paramError) {
1240    console.log('error: ' + paramError.code + ', ' + paramError.message);
1241}
1242```
1243
1244## WantAgentFlags
1245
1246**System capability**: SystemCapability.Ability.AbilityRuntime.Core
1247
1248| Name               | Value            | Description                                                        |
1249| ------------------- | -------------- | ------------------------------------------------------------ |
1250| ONE_TIME_FLAG       | 0 | The **WantAgent** object can be used only once.                                     |
1251| NO_BUILD_FLAG       | 1 | The **WantAgent** object does not exist and hence it is not created. In this case, **null** is returned.     |
1252| CANCEL_PRESENT_FLAG | 2 | The existing **WantAgent** object should be canceled before a new object is generated.|
1253| UPDATE_PRESENT_FLAG | 3 | Extra information of the existing **WantAgent** object is replaced with that of the new object.|
1254| CONSTANT_FLAG       | 4 | The **WantAgent** object is immutable.                                       |
1255| REPLACE_ELEMENT     | 5 | The **element** attribute of the current **Want** can be replaced by the **element** attribute of the **Want** in **WantAgent.trigger()**.|
1256| REPLACE_ACTION      | 6 | The **action** attribute of the current **Want** can be replaced by the **action** attribute of the **Want** in **WantAgent.trigger()**.|
1257| REPLACE_URI         | 7 | The **uri** attribute of the current **Want** can be replaced by the **uri** attribute of the **Want** in **WantAgent.trigger()**.|
1258| REPLACE_ENTITIES    | 8 | The **entities** attribute of the current **Want** can be replaced by the **entities** attribute of the **Want** in **WantAgent.trigger()**.|
1259| REPLACE_BUNDLE      | 9 | The **bundleName** attribute of the current **Want** can be replaced by the **bundleName** attribute of **Want** in **WantAgent.trigger()**.|
1260
1261
1262
1263## OperationType
1264
1265**System capability**: SystemCapability.Ability.AbilityRuntime.Core
1266
1267| Name             | Value           | Description                     |
1268| ----------------- | ------------- | ------------------------- |
1269| UNKNOWN_TYPE      | 0 | Unknown operation type.           |
1270| START_ABILITY     | 1 | Starts an ability with a UI.|
1271| START_ABILITIES   | 2 | Starts multiple abilities with a UI.|
1272| START_SERVICE     | 3 | Starts an ability without a UI.|
1273| SEND_COMMON_EVENT | 4 | Sends a common event.       |
1274
1275
1276
1277## CompleteData
1278
1279**System capability**: SystemCapability.Ability.AbilityRuntime.Core
1280
1281| Name          | Type                          | Mandatory| Description                   |
1282| -------------- | ------------------------------ | ---- | ---------------------- |
1283| info           | WantAgent                       | Yes  | A triggered **WantAgent** object.      |
1284| want           | Want                            | Yes  | An existing triggered **want**.    |
1285| finalCode      | number                          | Yes  | Request code that triggers the **WantAgent** object.|
1286| finalData      | string                          | Yes  | Final data collected by the common event. |
1287| extraInfo      | {[key: string]: any}            | No  | Extra information.              |
1288