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. 26 27**Parameters** 28 29| Name | Type | Mandatory| Description | 30| -------- | --------------------- | ---- | ------------------------------- | 31| agent | [WantAgent](js-apis-app-ability-wantAgent.md#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 actionType: 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.error(`getWantAgent failed, code: ${err.code}, message: ${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, code: ${err.code}, message: ${err.message}.`); 92 } else { 93 console.info(`getWant success, data: ${JSON.stringify(data)}.`); 94 } 95 } 96 try { 97 wantAgent.getWant(wantAgentData, getWantCallback); 98 } catch(err) { 99 let code = (err as BusinessError).code; 100 let msg = (err as BusinessError).message; 101 console.error(`getWant failed, code: ${code}, message: ${msg}.`); 102 } 103} 104 105try { 106 wantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback); 107} catch(err) { 108 let code = (err as BusinessError).code; 109 let msg = (err as BusinessError).message; 110 console.error(`getWantAgent failed, code: ${code}, message: ${msg}.`); 111} 112``` 113 114 115 116## WantAgent.getWant 117 118getWant(agent: WantAgent): Promise\<Want\> 119 120Obtains the Want in a WantAgent object. This API uses a promise to return the result. 121 122**System capability**: SystemCapability.Ability.AbilityRuntime.Core 123 124**System API**: This is a system API. 125 126**Parameters** 127 128| Name | Type | Mandatory| Description | 129| ----- | --------- | ---- | ------------- | 130| agent | [WantAgent](js-apis-app-ability-wantAgent.md#wantagent) | Yes | Target WantAgent object.| 131 132**Return value** 133 134| Type | Description | 135| ----------------------------------------------------------- | ------------------------------------------------------------ | 136| Promise\<[Want](js-apis-app-ability-want.md)\> | Promise used to return the Want.| 137 138**Error codes** 139 140For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 141 142| ID | Error Message | 143|-----------|--------------------| 144| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 145| 16000007 | Service busy. There are concurrent tasks. Try again later. | 146| 16000015 | Service timeout.| 147| 16000151 | Invalid wantAgent object.| 148 149For details about the error codes, see [Ability Error Codes](errorcode-ability.md). 150 151**Example** 152 153```ts 154import { wantAgent, WantAgent as _WantAgent, Want } from '@kit.AbilityKit'; 155import { BusinessError } from '@kit.BasicServicesKit'; 156 157// WantAgent object. 158let wantAgentData: _WantAgent; 159// WantAgentInfo object. 160let wantAgentInfo: wantAgent.WantAgentInfo = { 161 wants: [ 162 { 163 deviceId: 'deviceId', 164 bundleName: 'com.example.myapplication', 165 abilityName: 'EntryAbility', 166 action: 'action1', 167 entities: ['entity1'], 168 type: 'MIMETYPE', 169 uri: 'key={true,true,false}', 170 parameters: 171 { 172 mykey0: 2222, 173 mykey1: [1, 2, 3], 174 mykey2: '[1, 2, 3]', 175 mykey3: 'ssssssssssssssssssssssssss', 176 mykey4: [false, true, false], 177 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 178 mykey6: true, 179 } 180 } as Want 181 ], 182 actionType: wantAgent.OperationType.START_ABILITIES, 183 requestCode: 0, 184 wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 185}; 186 187// getWantAgent callback 188function getWantAgentCallback(err: BusinessError, data: _WantAgent) { 189 if (err) { 190 console.error(`getWantAgent failed, code: ${err.code}, message: ${err.message}`); 191 } else { 192 wantAgentData = data; 193 } 194 try { 195 wantAgent.getWant(wantAgentData).then((data)=>{ 196 console.info(`getWant success, data: ${JSON.stringify(data)}`); 197 }).catch((err: BusinessError)=>{ 198 console.error(`getWant failed, code: ${err.code}, message: ${err.message}.`); 199 }); 200 } catch(err){ 201 let code = (err as BusinessError).code; 202 let msg = (err as BusinessError).message; 203 console.error(`getWant failed, code: ${code}, message: ${msg}.`); 204 } 205} 206 207try { 208 wantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback); 209} catch(err) { 210 let code = (err as BusinessError).code; 211 let msg = (err as BusinessError).message; 212 console.error(`getWantAgent failed, code: ${code}, message: ${msg}.`); 213} 214``` 215 216## WantAgent.setWantAgentMultithreading<sup>18+</sup> 217 218setWantAgentMultithreading(isMultithreadingSupported: boolean) : void 219 220Enables or disables the WantAgent multithreading feature. 221 222**System capability**: SystemCapability.Ability.AbilityRuntime.Core 223 224**System API**: This is a system API. 225 226**Parameters** 227 228| Name | Type | Mandatory| Description | 229| ---------- | --------------------- | ---- | ------------------------------- | 230| isMultithreadingSupported | boolean | Yes |Whether to enable the multithreading feature. **true** to enable, **false** otherwise. | 231 232**Error codes** 233 234For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 235 236| ID | Error Message | 237|-----------|--------------------| 238| 202 | Not system app. Interface caller is not a system app. | 239| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 240 241**Example** 242 243```ts 244import { wantAgent, WantAgent as _WantAgent, Want } from '@kit.AbilityKit'; 245import { BusinessError } from '@kit.BasicServicesKit'; 246 247// Define a wantAgent object. 248let wantAgentData: _WantAgent; 249// Define a WantAgentInfo object. 250let wantAgentInfo: wantAgent.WantAgentInfo = { 251 wants: [ 252 { 253 deviceId: 'deviceId', 254 bundleName: 'com.example.myapplication', 255 abilityName: 'EntryAbility', 256 action: 'action1', 257 entities: ['entity1'], 258 type: 'MIMETYPE', 259 uri: 'key={true,true,false}', 260 parameters: 261 { 262 mykey0: 2222, 263 mykey1: [1, 2, 3], 264 mykey2: '[1, 2, 3]', 265 mykey3: 'ssssssssssssssssssssssssss', 266 mykey4: [false, true, false], 267 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 268 mykey6: true, 269 } 270 } as Want 271 ], 272 actionType: wantAgent.OperationType.START_ABILITIES, 273 requestCode: 0, 274 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 275}; 276 277// Define a getWantAgent callback. 278function getWantAgentCallback(err: BusinessError, data: _WantAgent) { 279 if (err) { 280 console.error(`Failed to call getWantAgentCallback. Code is ${err.code}. Message is ${err.message}.`); 281 } else { 282 wantAgentData = data; 283 } 284 285 try { 286 wantAgent.setWantAgentMultithreading(true); 287 } catch (err) { 288 console.error(`Failed to set wantAgentMultithreading. Code is ${err.code}. Message is ${err.message}.`); 289 } 290} 291 292try { 293 wantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback); 294} catch (err) { 295 console.error(`Failed to get wantAgent. Code is ${err.code}. Message is ${err.message}.`); 296} 297``` 298 299## wantAgent.triggerAsync<sup>20+</sup> 300 301triggerAsync(agent: WantAgent, triggerInfo: TriggerInfo, context: Context): Promise\<CompleteData\> 302 303Proactively triggers a WantAgent object, which involves executing the operations and parameters that are encapsulated within the WantAgent object. This API uses a promise to return the result. 304 305**Required permissions**: ohos.permission.TRIGGER_LOCAL_WANTAGENT (required only when the parameter **agent** is a local WantAgent instance.) 306 307**System capability**: SystemCapability.Ability.AbilityRuntime.Core 308 309**System API**: This is a system API. 310 311**Parameters** 312 313| Name | Type | Mandatory| Description | 314| ----------- | ----------------------------- | ---- | ------------------------------- | 315| agent | [WantAgent](js-apis-app-ability-wantAgent.md#wantagent) | Yes | Target WantAgent object. | 316| triggerInfo | [TriggerInfo](js-apis-inner-wantAgent-triggerInfo.md) | Yes | TriggerInfo object. | 317| context | [Context](js-apis-inner-application-context.md) | Yes | Context of the UIAbility or ExtensionAbility that is requesting to trigger the WantAgent object.| 318 319**Return value** 320 321| Type | Description | 322| ----------------------------------------------------------- | ------------------------------------------------------------ | 323| Promise\<[CompleteData](js-apis-app-ability-wantAgent.md#completedata)\> | Promise used to return the data obtained from the WantAgent object.| 324 325**Error codes** 326 327For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 328 329| ID | Error Message | 330|-----------|--------------------| 331| 201 | Permission verification failed. The application does not have the permission required to call the API. | 332| 202 | The application is not system-app, can not use system-api. | 333| 16000020 | The context is not ability context. | 334| 16000151 | Invalid wantAgent object.| 335| 16000153 | The WantAgent has been canceled.| 336 337**Example** 338 339```ts 340import { wantAgent, Want, UIAbility, AbilityConstant } from '@kit.AbilityKit'; 341import type { WantAgent } from '@kit.AbilityKit'; 342import { BusinessError } from '@kit.BasicServicesKit'; 343 344// WantAgent object. 345let wantAgentData: WantAgent; 346// triggerInfo 347let triggerInfo: wantAgent.TriggerInfo = { 348 code: 0 // Custom result code. 349}; 350// WantAgentInfo object. 351let wantAgentInfo: wantAgent.WantAgentInfo = { 352 // Custom parameters. 353 wants: [ 354 { 355 deviceId: 'deviceId', 356 bundleName: 'com.example.myapplication', 357 abilityName: 'EntryAbility', 358 action: 'action1', 359 entities: ['entity1'], 360 type: 'MIMETYPE', 361 uri: 'key={true,true,false}', 362 parameters: 363 { 364 mykey0: 2222, 365 mykey1: [1, 2, 3], 366 mykey2: '[1, 2, 3]', 367 mykey3: 'ssssssssssssssssssssssssss', 368 mykey4: [false, true, false], 369 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 370 mykey6: true, 371 } 372 } as Want 373 ], 374 // Specified operation. 375 actionType: wantAgent.OperationType.START_ABILITY, 376 requestCode: 0, 377 // WantAgent object type. 378 wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] 379}; 380 381class MyAbility extends UIAbility { 382 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 383 try { 384 // Create a WantAgent object. 385 wantAgent.getWantAgent(wantAgentInfo, (err: BusinessError, data: WantAgent) => { 386 if (err) { 387 console.info(`getWantAgent failed, code: ${err.code}, message: ${err.message}`); 388 } else { 389 wantAgentData = data; 390 } 391 392 try { 393 // Proactively trigger a WantAgent object. 394 wantAgent.triggerAsync(wantAgentData, triggerInfo, this.context).then((data) => { 395 console.info(`trigger success, data: ${JSON.stringify(data)}`); 396 }).catch((err: BusinessError) => { 397 console.error(`triggerAsync failed! ${err.code} ${err.message}`); 398 }); 399 } catch (err) { 400 console.error(`triggerAsync failed! ${err.code} ${err.message}`); 401 } 402 }); 403 } catch (err) { 404 let code = (err as BusinessError).code; 405 let msg = (err as BusinessError).message; 406 console.error(`getWantAgent failed, code: ${code}, message: ${msg}.`); 407 } 408 } 409} 410``` 411 412## wantAgent.createLocalWantAgent<sup>20+</sup> 413 414createLocalWantAgent(info: LocalWantAgentInfo): WantAgent 415 416Creates a local WantAgent object. 417 418> **NOTE** 419> 420> - The local WantAgent object created by calling this API is stored only on the WantAgent client and is not managed by the WantAgent server. Before using the local WantAgent object, verify the object to ensure security. 421> 422> - After the local WantAgent object is created, you can call [wantAgent.triggerAsync](#wantagenttriggerasync20) to trigger it. 423 424**System capability**: SystemCapability.Ability.AbilityRuntime.Core 425 426**System API**: This is a system API. 427 428**Model restriction**: This API can be used only in the stage model. 429 430**Parameters** 431 432| Name | Type | Mandatory| Description | 433| ----------- | ----------------------------- | ---- | ------------------------------- | 434| info | [LocalWantAgentInfo](js-apis-inner-wantAgent-wantAgentInfo.md) | Yes | LocalWantAgent information.| 435 436**Return value** 437 438| Type | Description | 439| ----------------------------------------------------------- | ------------------------------------------------------------ | 440| [WantAgent](js-apis-app-ability-wantAgent.md#wantagent) | WantAgent object created. | 441 442**Error codes** 443 444For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 445 446| ID | Error Message | 447|-----------|--------------------| 448| 202 | Not System App. Interface caller is not a system app. | 449 450**Example** 451 452```ts 453import { wantAgent, Want } from '@kit.AbilityKit'; 454import type { WantAgent } from '@kit.AbilityKit'; 455 456// Declare a wantAgent object. 457let wantAgentData: WantAgent; 458// Create a LocalWantAgentInfo object. 459let localWantAgentInfo: wantAgent.LocalWantAgentInfo = { 460 wants: [ 461 { 462 deviceId: 'deviceId', 463 bundleName: 'com.example.myapplication', 464 abilityName: 'EntryAbility', 465 action: 'action1', 466 entities: ['entity1'], 467 type: 'MIMETYPE', 468 uri: 'key={true,true,false}', 469 parameters: 470 { 471 mykey0: 2222, 472 mykey1: [1, 2, 3], 473 mykey2: '[1, 2, 3]', 474 mykey3: 'ssssssssssssssssssssssssss', 475 mykey4: [false, true, false], 476 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 477 mykey6: true, 478 } 479 } as Want 480 ], 481 operationType: wantAgent.OperationType.START_ABILITY, 482 requestCode: 0 483}; 484// Create a local WantAgent object. 485try { 486 wantAgentData = wantAgent.createLocalWantAgent(localWantAgentInfo); 487} catch (err) { 488 console.error('createLocalWantAgent failed'); 489} 490``` 491 492## wantAgent.isLocalWantAgent<sup>20+</sup> 493 494isLocalWantAgent(agent: WantAgent): boolean 495 496Checks whether a WantAgent object is a local object. 497 498**System capability**: SystemCapability.Ability.AbilityRuntime.Core 499 500**System API**: This is a system API. 501 502**Model restriction**: This API can be used only in the stage model. 503 504**Parameters** 505 506| Name | Type | Mandatory| Description | 507| ----------- | ----------------------------- | ---- | ------------------------------- | 508| agent | [WantAgent](js-apis-app-ability-wantAgent.md#wantagent) | Yes | WantAgent object. | 509 510**Return value** 511 512| Type | Description | 513| ----------------------------------------------------------- | ------------------------------------------------------------ | 514| boolean | Check result for whether the WantAgent object is stored on the local client. **true** if stored on the local client, **false** if stored on the server.| 515 516**Error codes** 517 518For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 519 520| ID | Error Message | 521|-----------|--------------------| 522| 202 | Not System App. Interface caller is not a system app. | 523 524**Example** 525 526```ts 527import { wantAgent } from '@kit.AbilityKit'; 528import type { WantAgent } from '@kit.AbilityKit'; 529 530// Declare a wantAgent object. 531let wantAgentData: WantAgent; 532// Create a LocalWantAgentInfo object. 533let localWantAgentInfo: wantAgent.LocalWantAgentInfo = { 534 wants: [ 535 { 536 deviceId: 'deviceId', 537 bundleName: 'com.example.myapplication', 538 abilityName: 'EntryAbility', 539 action: 'action1', 540 entities: ['entity1'], 541 type: 'MIMETYPE', 542 uri: 'key={true,true,false}', 543 parameters: 544 { 545 mykey0: 2222, 546 mykey1: [1, 2, 3], 547 mykey2: '[1, 2, 3]', 548 mykey3: 'ssssssssssssssssssssssssss', 549 mykey4: [false, true, false], 550 mykey5: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'], 551 mykey6: true, 552 } 553 } as Want 554 ], 555 operationType: wantAgent.OperationType.START_ABILITY, 556 requestCode: 0 557}; 558 559// Create a WantAgent object and check whether it is local. 560try { 561 wantAgentData = wantAgent.createLocalWantAgent(localWantAgentInfo); 562 let isLocal: boolean = wantAgent.isLocalWantAgent(wantAgentData); 563} catch (err) { 564 console.error('call isLocalWantAgent failed'); 565} 566``` 567 568## OperationType 569 570Enumerates the operation types of the WantAgent objects. 571 572**System capability**: SystemCapability.Ability.AbilityRuntime.Core 573 574| Name | Value| Description | 575|-------------------------|---|-----------------------------------------------| 576| START_SERVICE_EXTENSION<sup>12+</sup> | 6 | Starts a ServiceExtensionAbility.<br>**System API**: This is a system API.| 577