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