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