1# @ohos.app.ability.wantAgent (WantAgent) (System API)
2
3The **app.ability.WantAgent** module provides APIs for creating and comparing **WantAgent** objects, and obtaining the user ID, Want, and bundle name of a **WantAgent** object. You are advised to use this module, since it will replace the [@ohos.wantAgent](js-apis-wantAgent.md) module in the near future.
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> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.app.ability.wantAgent (WantAgent)](js-apis-app-ability-wantAgent.md).
10
11## Modules to Import
12
13```ts
14import { WantAgent } from '@kit.AbilityKit';
15```
16
17## WantAgent.getWant
18
19getWant(agent: WantAgent, callback: AsyncCallback\<Want\>): void
20
21Obtains the Want in a **WantAgent** object. This API uses an asynchronous callback to return the result.
22
23**System capability**: SystemCapability.Ability.AbilityRuntime.Core
24
25**System API**: This is a system API and cannot be called by third-party applications.
26
27**Parameters**
28
29| Name    | Type                 | Mandatory| Description                           |
30| -------- | --------------------- | ---- | ------------------------------- |
31| agent    | WantAgent             | Yes  | Target **WantAgent** object.                  |
32| callback | AsyncCallback\<[Want](js-apis-app-ability-want.md)\> | Yes  | Callback used to return the Want.|
33
34**Error codes**
35
36For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
37
38| ID   | Error Message           |
39|-----------|--------------------|
40| 401        | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
41| 16000007   | Service busy. There are concurrent tasks. Try again later. |
42| 16000015   | Service timeout.|
43| 16000151   | Invalid wantagent object.|
44
45**Example**
46
47```ts
48import { wantAgent, WantAgent as _WantAgent, Want } from '@kit.AbilityKit';
49import { BusinessError } from '@kit.BasicServicesKit';
50
51// WantAgent object
52let wantAgentData: _WantAgent;
53// WantAgentInfo object
54let wantAgentInfo: wantAgent.WantAgentInfo = {
55  wants: [
56    {
57      deviceId: 'deviceId',
58      bundleName: 'com.example.myapplication',
59      abilityName: 'EntryAbility',
60      action: 'action1',
61      entities: ['entity1'],
62      type: 'MIMETYPE',
63      uri: 'key={true,true,false}',
64      parameters:
65      {
66        mykey0: 2222,
67        mykey1: [1, 2, 3],
68        mykey2: '[1, 2, 3]',
69        mykey3: 'ssssssssssssssssssssssssss',
70        mykey4: [false, true, false],
71        mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
72        mykey6: true,
73      }
74    } as Want
75  ],
76  operationType: wantAgent.OperationType.START_ABILITIES,
77  requestCode: 0,
78  wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
79};
80
81// getWantAgent callback
82function getWantAgentCallback(err: BusinessError, data: _WantAgent) {
83  if (err) {
84    console.info(`getWantAgent failed, code: ${JSON.stringify(err.code)}, message: ${JSON.stringify(err.message)}`);
85  } else {
86    wantAgentData = data;
87  }
88  // getWant callback
89  let getWantCallback = (err: BusinessError, data: Want) => {
90    if(err) {
91      console.error(`getWant failed! ${err.code} ${err.message}`);
92    } else {
93      console.info(`getWant ok! ${JSON.stringify(data)}`);
94    }
95  }
96  try {
97    wantAgent.getWant(wantAgentData, getWantCallback);
98  } catch(err) {
99    console.error(`getWant failed! ${err.code} ${err.message}`);
100  }
101}
102
103try {
104  wantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback);
105} catch(err) {
106  console.error(`getWantAgent failed! ${err.code} ${err.message}`);
107}
108```
109
110
111
112## WantAgent.getWant
113
114getWant(agent: WantAgent): Promise\<Want\>
115
116Obtains the Want in a **WantAgent** object. This API uses a promise to return the result.
117
118**System capability**: SystemCapability.Ability.AbilityRuntime.Core
119
120**System API**: This is a system API and cannot be called by third-party applications.
121
122**Parameters**
123
124| Name | Type     | Mandatory| Description         |
125| ----- | --------- | ---- | ------------- |
126| agent | WantAgent | Yes  | Target **WantAgent** object.|
127
128**Return value**
129
130| Type                                                       | Description                                                        |
131| ----------------------------------------------------------- | ------------------------------------------------------------ |
132| Promise\<[Want](js-apis-app-ability-want.md)\> | Promise used to return the Want.|
133
134**Error codes**
135
136For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
137
138| ID   | Error Message           |
139|-----------|--------------------|
140| 401        | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
141| 16000007   | Service busy. There are concurrent tasks. Try again later. |
142| 16000015   | Service timeout.|
143| 16000151   | Invalid wantagent object.|
144
145For details about the error codes, see [Ability Error Codes](errorcode-ability.md).
146
147**Example**
148
149```ts
150import { wantAgent, WantAgent as _WantAgent, Want } from '@kit.AbilityKit';
151import { BusinessError } from '@kit.BasicServicesKit';
152
153// WantAgent object
154let wantAgentData: _WantAgent;
155// WantAgentInfo object
156let wantAgentInfo: wantAgent.WantAgentInfo = {
157  wants: [
158    {
159      deviceId: 'deviceId',
160      bundleName: 'com.example.myapplication',
161      abilityName: 'EntryAbility',
162      action: 'action1',
163      entities: ['entity1'],
164      type: 'MIMETYPE',
165      uri: 'key={true,true,false}',
166      parameters:
167      {
168        mykey0: 2222,
169        mykey1: [1, 2, 3],
170        mykey2: '[1, 2, 3]',
171        mykey3: 'ssssssssssssssssssssssssss',
172        mykey4: [false, true, false],
173        mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
174        mykey6: true,
175      }
176    } as Want
177  ],
178  operationType: wantAgent.OperationType.START_ABILITIES,
179  requestCode: 0,
180  wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
181};
182
183// getWantAgent callback
184function getWantAgentCallback(err: BusinessError, data: _WantAgent) {
185  if (err) {
186    console.info(`getWantAgent failed, code: ${JSON.stringify(err.code)}, message: ${JSON.stringify(err.message)}`);
187  } else {
188    wantAgentData = data;
189  }
190  try {
191    wantAgent.getUid(wantAgentData).then((data)=>{
192      console.info(`getUid ok! ${JSON.stringify(data)}`);
193    }).catch((err: BusinessError)=>{
194      console.error(`getUid failed! ${err.code} ${err.message}`);
195    });
196  } catch(err){
197    console.error(`getUid failed! ${err.code} ${err.message}`);
198  }
199}
200
201try {
202  wantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback);
203} catch(err) {
204  console.error(`getWantAgent failed! ${err.code} ${err.message}}`);
205}
206```
207## OperationType
208
209Enumerates the operation types of the **WantAgent** objects.
210
211**System capability**: SystemCapability.Ability.AbilityRuntime.Core
212
213| Name                     | Value| Description                                           |
214|-------------------------|---|-----------------------------------------------|
215| START_SERVICE_EXTENSION<sup>12+</sup> | 6 | Starts a ServiceExtensionAbility.<br>**System API**: This is a system API.|
216