1# ServiceExtensionContext (System API) 2 3The ServiceExtensionContext module, inherited from **ExtensionContext**, provides context for the ServiceExtensionAbility. 4 5You can use the APIs of this module to start, terminate, connect, and disconnect an ability. 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> - The APIs of this module can be used only in the stage model. 11> - The APIs of this module must be used in the main thread, but not in sub-threads such as Worker and TaskPool. 12> - The APIs provided by this module are system APIs. 13 14## Modules to Import 15 16```ts 17import { common } from '@kit.AbilityKit'; 18``` 19 20## Usage 21 22Before using the **ServiceExtensionContext** module, you must define a child class that inherits from **ServiceExtensionAbility**. 23 24**Example** 25 26```ts 27import { ServiceExtensionAbility } from '@kit.AbilityKit'; 28import { rpc } from '@kit.IPCKit'; 29 30let commRemote: rpc.IRemoteObject | null; // Release the instance when the connection is disconnected. 31 32class EntryAbility extends ServiceExtensionAbility { 33 onCreate() { 34 let context = this.context; // Obtain a ServiceExtensionContext instance. 35 } 36} 37``` 38 39## ServiceExtensionContext.startAbility 40 41startAbility(want: Want, callback: AsyncCallback<void>): void; 42 43Starts an ability. This API uses an asynchronous callback to return the result. 44 45**System capability**: SystemCapability.Ability.AbilityRuntime.Core 46 47**System API**: This is a system API and cannot be called by third-party applications. 48 49**Parameters** 50 51| Name| Type| Mandatory| Description| 52| -------- | -------- | -------- | -------- | 53| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| 54| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 55 56**Error codes** 57 58For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 59 60| ID| Error Message| 61| ------- | -------- | 62| 201 | The application does not have permission to call the interface. | 63| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 64| 16000001 | The specified ability does not exist. | 65| 16000002 | Incorrect ability type. | 66| 16000004 | Can not start invisible component. | 67| 16000005 | The specified process does not have the permission. | 68| 16000006 | Cross-user operations are not allowed. | 69| 16000008 | The crowdtesting application expires. | 70| 16000009 | An ability cannot be started or stopped in Wukong mode. | 71| 16000010 | The call with the continuation flag is forbidden. | 72| 16000011 | The context does not exist. | 73| 16000012 | The application is controlled. | 74| 16000013 | The application is controlled by EDM. | 75| 16000019 | Can not match any component. | 76| 16000050 | Internal error. | 77| 16000053 | The ability is not on the top of the UI. | 78| 16000055 | Installation-free timed out. | 79| 16200001 | The caller has been released. | 80| 16000073 | The app clone index is invalid. | 81 82**Example** 83 84```ts 85import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 86import { BusinessError } from '@kit.BasicServicesKit'; 87 88class EntryAbility extends ServiceExtensionAbility { 89 onCreate() { 90 let want: Want = { 91 bundleName: 'com.example.myapp', 92 abilityName: 'MyAbility' 93 }; 94 95 try { 96 this.context.startAbility(want, (error: BusinessError) => { 97 if (error.code) { 98 // Process service logic errors. 99 console.error(`startAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 100 return; 101 } 102 // Carry out normal service processing. 103 console.log('startAbility succeed'); 104 }); 105 } catch (paramError) { 106 // Process input parameter errors. 107 console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`); 108 } 109 } 110} 111``` 112 113## ServiceExtensionContext.startAbility 114 115startAbility(want: Want, options?: StartOptions): Promise\<void>; 116 117Starts an ability. This API uses a promise to return the result. 118 119**System capability**: SystemCapability.Ability.AbilityRuntime.Core 120 121**System API**: This is a system API and cannot be called by third-party applications. 122 123**Parameters** 124 125| Name| Type| Mandatory| Description| 126| -------- | -------- | -------- | -------- | 127| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| 128| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 129 130**Return value** 131 132| Type| Description| 133| -------- | -------- | 134| Promise<void> | Promise used to return the result.| 135 136**Error codes** 137 138For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 139 140| ID| Error Message| 141| ------- | -------- | 142| 201 | The application does not have permission to call the interface. | 143| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 144| 16000001 | The specified ability does not exist. | 145| 16000002 | Incorrect ability type. | 146| 16000004 | Can not start invisible component. | 147| 16000005 | The specified process does not have the permission. | 148| 16000006 | Cross-user operations are not allowed. | 149| 16000008 | The crowdtesting application expires. | 150| 16000009 | An ability cannot be started or stopped in Wukong mode. | 151| 16000010 | The call with the continuation flag is forbidden. | 152| 16000011 | The context does not exist. | 153| 16000012 | The application is controlled. | 154| 16000013 | The application is controlled by EDM. | 155| 16000019 | Can not match any component. | 156| 16000050 | Internal error. | 157| 16000053 | The ability is not on the top of the UI. | 158| 16000055 | Installation-free timed out. | 159| 16200001 | The caller has been released. | 160| 16000073 | The app clone index is invalid. | 161 162**Example** 163 164```ts 165import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 166import { BusinessError } from '@kit.BasicServicesKit'; 167 168class EntryAbility extends ServiceExtensionAbility { 169 onCreate() { 170 let want: Want = { 171 bundleName: 'com.example.myapp', 172 abilityName: 'MyAbility' 173 }; 174 let options: StartOptions = { 175 windowMode: 0, 176 }; 177 178 try { 179 this.context.startAbility(want, options) 180 .then((data: void) => { 181 // Carry out normal service processing. 182 console.log('startAbility succeed'); 183 }) 184 .catch((error: BusinessError) => { 185 // Process service logic errors. 186 console.error(`startAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 187 }); 188 } catch (paramError) { 189 // Process input parameter errors. 190 console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`); 191 } 192 } 193} 194``` 195 196## ServiceExtensionContext.startAbility 197 198startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void 199 200Starts an ability with the start options specified. This API uses an asynchronous callback to return the result. 201 202**System capability**: SystemCapability.Ability.AbilityRuntime.Core 203 204**System API**: This is a system API and cannot be called by third-party applications. 205 206**Parameters** 207 208| Name| Type| Mandatory| Description| 209| -------- | -------- | -------- | -------- | 210| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 211| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 212| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 213 214**Error codes** 215 216For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 217 218| ID| Error Message| 219| ------- | -------- | 220| 201 | The application does not have permission to call the interface. | 221| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 222| 16000001 | The specified ability does not exist. | 223| 16000002 | Incorrect ability type. | 224| 16000004 | Can not start invisible component. | 225| 16000005 | The specified process does not have the permission. | 226| 16000006 | Cross-user operations are not allowed. | 227| 16000008 | The crowdtesting application expires. | 228| 16000009 | An ability cannot be started or stopped in Wukong mode. | 229| 16000010 | The call with the continuation flag is forbidden. | 230| 16000011 | The context does not exist. | 231| 16000012 | The application is controlled. | 232| 16000013 | The application is controlled by EDM. | 233| 16000019 | Can not match any component. | 234| 16000050 | Internal error. | 235| 16000053 | The ability is not on the top of the UI. | 236| 16000055 | Installation-free timed out. | 237| 16200001 | The caller has been released. | 238| 16000073 | The app clone index is invalid. | 239 240**Example** 241 242```ts 243import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 244import { BusinessError } from '@kit.BasicServicesKit'; 245 246class EntryAbility extends ServiceExtensionAbility { 247 onCreate() { 248 let want: Want = { 249 deviceId: '', 250 bundleName: 'com.example.myapplication', 251 abilityName: 'EntryAbility' 252 }; 253 let options: StartOptions = { 254 windowMode: 0 255 }; 256 257 try { 258 this.context.startAbility(want, options, (error: BusinessError) => { 259 if (error.code) { 260 // Process service logic errors. 261 console.error(`startAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 262 return; 263 } 264 // Carry out normal service processing. 265 console.log('startAbility succeed'); 266 }); 267 } catch (paramError) { 268 // Process input parameter errors. 269 console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`); 270 } 271 } 272} 273``` 274 275## ServiceExtensionContext.startAbilityWithAccount 276 277startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void; 278 279Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result. 280 281> **NOTE** 282> 283> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 284 285**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 286 287**System capability**: SystemCapability.Ability.AbilityRuntime.Core 288 289**System API**: This is a system API and cannot be called by third-party applications. 290 291**Parameters** 292 293| Name| Type| Mandatory| Description| 294| -------- | -------- | -------- | -------- | 295| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 296| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getcreatedosaccountscountdeprecated).| 297| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 298 299**Error codes** 300 301For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 302 303| ID| Error Message| 304| ------- | -------- | 305| 201 | The application does not have permission to call the interface. | 306| 202 | The application is not system-app, can not use system-api. | 307| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 308| 16000001 | The specified ability does not exist. | 309| 16000002 | Incorrect ability type. | 310| 16000004 | Can not start invisible component. | 311| 16000005 | The specified process does not have the permission. | 312| 16000006 | Cross-user operations are not allowed. | 313| 16000008 | The crowdtesting application expires. | 314| 16000009 | An ability cannot be started or stopped in Wukong mode. | 315| 16000010 | The call with the continuation flag is forbidden. | 316| 16000011 | The context does not exist. | 317| 16000012 | The application is controlled. | 318| 16000013 | The application is controlled by EDM. | 319| 16000019 | Can not match any component. | 320| 16000050 | Internal error. | 321| 16000053 | The ability is not on the top of the UI. | 322| 16000055 | Installation-free timed out. | 323| 16200001 | The caller has been released. | 324| 16000073 | The app clone index is invalid. | 325 326**Example** 327 328```ts 329import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 330import { BusinessError } from '@kit.BasicServicesKit'; 331 332class EntryAbility extends ServiceExtensionAbility { 333 onCreate() { 334 let want: Want = { 335 deviceId: '', 336 bundleName: 'com.example.myapplication', 337 abilityName: 'EntryAbility' 338 }; 339 let accountId = 100; 340 341 try { 342 this.context.startAbilityWithAccount(want, accountId, (error: BusinessError) => { 343 if (error.code) { 344 // Process service logic errors. 345 console.error(`startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`); 346 return; 347 } 348 // Carry out normal service processing. 349 console.log('startAbilityWithAccount succeed'); 350 }); 351 } catch (paramError) { 352 // Process input parameter errors. 353 console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`); 354 } 355 } 356} 357``` 358 359## ServiceExtensionContext.startAbilityWithAccount 360 361startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\<void\>): void; 362 363Starts an ability with the account ID and start options specified. This API uses an asynchronous callback to return the result. 364 365> **NOTE** 366> 367> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 368 369**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 370 371**System capability**: SystemCapability.Ability.AbilityRuntime.Core 372 373**System API**: This is a system API and cannot be called by third-party applications. 374 375**Parameters** 376 377| Name| Type| Mandatory| Description| 378| -------- | -------- | -------- | -------- | 379| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 380| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getcreatedosaccountscountdeprecated).| 381| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 382| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 383 384**Error codes** 385 386For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 387 388| ID| Error Message| 389| ------- | -------- | 390| 201 | The application does not have permission to call the interface. | 391| 202 | The application is not system-app, can not use system-api. | 392| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 393| 16000001 | The specified ability does not exist. | 394| 16000002 | Incorrect ability type. | 395| 16000004 | Can not start invisible component. | 396| 16000005 | The specified process does not have the permission. | 397| 16000006 | Cross-user operations are not allowed. | 398| 16000008 | The crowdtesting application expires. | 399| 16000009 | An ability cannot be started or stopped in Wukong mode. | 400| 16000010 | The call with the continuation flag is forbidden. | 401| 16000011 | The context does not exist. | 402| 16000012 | The application is controlled. | 403| 16000013 | The application is controlled by EDM. | 404| 16000019 | Can not match any component. | 405| 16000050 | Internal error. | 406| 16000053 | The ability is not on the top of the UI. | 407| 16000055 | Installation-free timed out. | 408| 16200001 | The caller has been released. | 409| 16000073 | The app clone index is invalid. | 410 411**Example** 412 413```ts 414import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 415import { BusinessError } from '@kit.BasicServicesKit'; 416 417class EntryAbility extends ServiceExtensionAbility { 418 onCreate() { 419 let want: Want = { 420 deviceId: '', 421 bundleName: 'com.example.myapplication', 422 abilityName: 'EntryAbility' 423 }; 424 let accountId = 100; 425 let options: StartOptions = { 426 windowMode: 0 427 }; 428 429 try { 430 this.context.startAbilityWithAccount(want, accountId, options, (error: BusinessError) => { 431 if (error.code) { 432 // Process service logic errors. 433 console.error(`startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`); 434 return; 435 } 436 // Carry out normal service processing. 437 console.log('startAbilityWithAccount succeed'); 438 }); 439 } catch (paramError) { 440 // Process input parameter errors. 441 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 442 } 443 } 444} 445``` 446 447 448## ServiceExtensionContext.startAbilityWithAccount 449 450startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\<void>; 451 452Starts an ability with the account ID specified. This API uses a promise to return the result. 453 454> **NOTE** 455> 456> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 457 458**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 459 460**System capability**: SystemCapability.Ability.AbilityRuntime.Core 461 462**System API**: This is a system API and cannot be called by third-party applications. 463 464**Parameters** 465 466| Name| Type| Mandatory| Description| 467| -------- | -------- | -------- | -------- | 468| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 469| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getcreatedosaccountscountdeprecated-1).| 470| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 471 472**Return value** 473 474| Type| Description| 475| -------- | -------- | 476| Promise<void> | Promise used to return the result.| 477 478**Error codes** 479 480For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 481 482| ID| Error Message| 483| ------- | -------- | 484| 201 | The application does not have permission to call the interface. | 485| 202 | The application is not system-app, can not use system-api. | 486| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 487| 16000001 | The specified ability does not exist. | 488| 16000002 | Incorrect ability type. | 489| 16000004 | Can not start invisible component. | 490| 16000005 | The specified process does not have the permission. | 491| 16000006 | Cross-user operations are not allowed. | 492| 16000008 | The crowdtesting application expires. | 493| 16000009 | An ability cannot be started or stopped in Wukong mode. | 494| 16000010 | The call with the continuation flag is forbidden. | 495| 16000011 | The context does not exist. | 496| 16000012 | The application is controlled. | 497| 16000013 | The application is controlled by EDM. | 498| 16000019 | Can not match any component. | 499| 16000050 | Internal error. | 500| 16000053 | The ability is not on the top of the UI. | 501| 16000055 | Installation-free timed out. | 502| 16200001 | The caller has been released. | 503| 16000073 | The app clone index is invalid. | 504 505**Example** 506 507```ts 508import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 509import { BusinessError } from '@kit.BasicServicesKit'; 510 511class EntryAbility extends ServiceExtensionAbility { 512 onCreate() { 513 let want: Want = { 514 deviceId: '', 515 bundleName: 'com.example.myapplication', 516 abilityName: 'EntryAbility' 517 }; 518 let accountId = 100; 519 let options: StartOptions = { 520 windowMode: 0 521 }; 522 523 try { 524 this.context.startAbilityWithAccount(want, accountId, options) 525 .then((data: void) => { 526 // Carry out normal service processing. 527 console.log('startAbilityWithAccount succeed'); 528 }) 529 .catch((error: BusinessError) => { 530 // Process service logic errors. 531 console.error(`startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`); 532 }); 533 } catch (paramError) { 534 // Process input parameter errors. 535 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 536 } 537 } 538} 539``` 540 541## ServiceExtensionContext.startServiceExtensionAbility 542 543startServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void; 544 545Starts a new ServiceExtensionAbility. This API uses an asynchronous callback to return the result. 546 547**System capability**: SystemCapability.Ability.AbilityRuntime.Core 548 549**System API**: This is a system API and cannot be called by third-party applications. 550 551**Parameters** 552 553| Name| Type| Mandatory| Description| 554| -------- | -------- | -------- | -------- | 555| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 556| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 557 558**Error codes** 559 560For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 561 562| ID| Error Message| 563| ------- | -------- | 564| 201 | The application does not have permission to call the interface. | 565| 202 | The application is not system-app, can not use system-api. | 566| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 567| 16000001 | The specified ability does not exist. | 568| 16000002 | Incorrect ability type. | 569| 16000004 | Can not start invisible component. | 570| 16000005 | The specified process does not have the permission. | 571| 16000006 | Cross-user operations are not allowed. | 572| 16000008 | The crowdtesting application expires. | 573| 16000011 | The context does not exist. | 574| 16000012 | The application is controlled. | 575| 16000013 | The application is controlled by EDM. | 576| 16000019 | Can not match any component. | 577| 16000050 | Internal error. | 578| 16200001 | The caller has been released. | 579 580**Example** 581 582```ts 583import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 584import { BusinessError } from '@kit.BasicServicesKit'; 585 586class EntryAbility extends ServiceExtensionAbility { 587 onCreate() { 588 let want: Want = { 589 deviceId: '', 590 bundleName: 'com.example.myapplication', 591 abilityName: 'EntryAbility' 592 }; 593 594 try { 595 this.context.startServiceExtensionAbility(want, (error: BusinessError) => { 596 if (error.code) { 597 // Process service logic errors. 598 console.error(`startServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 599 return; 600 } 601 // Carry out normal service processing. 602 console.log('startServiceExtensionAbility succeed'); 603 }); 604 } catch (paramError) { 605 // Process input parameter errors. 606 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 607 } 608 } 609} 610``` 611 612## ServiceExtensionContext.startServiceExtensionAbility 613 614startServiceExtensionAbility(want: Want): Promise\<void>; 615 616Starts a new ServiceExtensionAbility. This API uses a promise to return the result. 617 618**System capability**: SystemCapability.Ability.AbilityRuntime.Core 619 620**System API**: This is a system API and cannot be called by third-party applications. 621 622**Parameters** 623 624| Name| Type| Mandatory| Description| 625| -------- | -------- | -------- | -------- | 626| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 627 628**Return value** 629 630| Type| Description| 631| -------- | -------- | 632| Promise<void> | Promise used to return the result.| 633 634**Error codes** 635 636For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 637 638| ID| Error Message| 639| ------- | -------- | 640| 201 | The application does not have permission to call the interface. | 641| 202 | The application is not system-app, can not use system-api. | 642| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 643| 16000001 | The specified ability does not exist. | 644| 16000002 | Incorrect ability type. | 645| 16000004 | Can not start invisible component. | 646| 16000005 | The specified process does not have the permission. | 647| 16000006 | Cross-user operations are not allowed. | 648| 16000008 | The crowdtesting application expires. | 649| 16000011 | The context does not exist. | 650| 16000012 | The application is controlled. | 651| 16000013 | The application is controlled by EDM. | 652| 16000019 | Can not match any component. | 653| 16000050 | Internal error. | 654| 16200001 | The caller has been released. | 655 656**Example** 657 658```ts 659import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 660import { BusinessError } from '@kit.BasicServicesKit'; 661 662class EntryAbility extends ServiceExtensionAbility { 663 onCreate() { 664 let want: Want = { 665 deviceId: '', 666 bundleName: 'com.example.myapplication', 667 abilityName: 'EntryAbility' 668 }; 669 670 try { 671 this.context.startServiceExtensionAbility(want) 672 .then((data) => { 673 // Carry out normal service processing. 674 console.log('startServiceExtensionAbility succeed'); 675 }) 676 .catch((error: BusinessError) => { 677 // Process service logic errors. 678 console.error(`startServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 679 }); 680 } catch (paramError) { 681 // Process input parameter errors. 682 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 683 } 684 } 685} 686``` 687 688## ServiceExtensionContext.startServiceExtensionAbilityWithAccount 689 690startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void; 691 692Starts a new ServiceExtensionAbility with the account ID specified. This API uses an asynchronous callback to return the result. 693 694> **NOTE** 695> 696> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 697> Permission verification is not required when **accountId** specifies the current user. 698 699**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 700 701**System capability**: SystemCapability.Ability.AbilityRuntime.Core 702 703**System API**: This is a system API and cannot be called by third-party applications. 704 705**Parameters** 706 707| Name| Type| Mandatory| Description| 708| -------- | -------- | -------- | -------- | 709| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 710| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getcreatedosaccountscountdeprecated).| 711| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 712 713**Error codes** 714 715For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 716 717| ID| Error Message| 718| ------- | -------- | 719| 201 | The application does not have permission to call the interface. | 720| 202 | The application is not system-app, can not use system-api. | 721| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 722| 16000001 | The specified ability does not exist. | 723| 16000002 | Incorrect ability type. | 724| 16000004 | Can not start invisible component. | 725| 16000005 | The specified process does not have the permission. | 726| 16000006 | Cross-user operations are not allowed. | 727| 16000008 | The crowdtesting application expires. | 728| 16000011 | The context does not exist. | 729| 16000012 | The application is controlled. | 730| 16000013 | The application is controlled by EDM. | 731| 16000019 | Can not match any component. | 732| 16000050 | Internal error. | 733| 16200001 | The caller has been released. | 734 735**Example** 736 737```ts 738import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 739import { BusinessError } from '@kit.BasicServicesKit'; 740 741class EntryAbility extends ServiceExtensionAbility { 742 onCreate() { 743 let want: Want = { 744 deviceId: '', 745 bundleName: 'com.example.myapplication', 746 abilityName: 'EntryAbility' 747 }; 748 let accountId = 100; 749 750 try { 751 this.context.startServiceExtensionAbilityWithAccount(want, accountId, (error: BusinessError) => { 752 if (error.code) { 753 // Process service logic errors. 754 console.error(`startServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`); 755 return; 756 } 757 // Carry out normal service processing. 758 console.log('startServiceExtensionAbilityWithAccount succeed'); 759 }); 760 } catch (paramError) { 761 // Process input parameter errors. 762 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 763 } 764 } 765} 766``` 767 768## ServiceExtensionContext.startServiceExtensionAbilityWithAccount 769 770startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void>; 771 772Starts a new ServiceExtensionAbility with the account ID specified. This API uses a promise to return the result. 773 774> **NOTE** 775> 776> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 777> Permission verification is not required when **accountId** specifies the current user. 778 779**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 780 781**System capability**: SystemCapability.Ability.AbilityRuntime.Core 782 783**System API**: This is a system API and cannot be called by third-party applications. 784 785**Parameters** 786 787| Name| Type| Mandatory| Description| 788| -------- | -------- | -------- | -------- | 789| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 790| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getcreatedosaccountscountdeprecated-1).| 791 792**Return value** 793 794| Type| Description| 795| -------- | -------- | 796| Promise<void> | Promise used to return the result.| 797 798**Error codes** 799 800For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 801 802| ID| Error Message| 803| ------- | -------- | 804| 201 | The application does not have permission to call the interface. | 805| 202 | The application is not system-app, can not use system-api. | 806| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 807| 16000001 | The specified ability does not exist. | 808| 16000002 | Incorrect ability type. | 809| 16000004 | Can not start invisible component. | 810| 16000005 | The specified process does not have the permission. | 811| 16000006 | Cross-user operations are not allowed. | 812| 16000008 | The crowdtesting application expires. | 813| 16000011 | The context does not exist. | 814| 16000012 | The application is controlled. | 815| 16000013 | The application is controlled by EDM. | 816| 16000019 | Can not match any component. | 817| 16000050 | Internal error. | 818| 16200001 | The caller has been released. | 819 820**Example** 821 822```ts 823import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 824import { BusinessError } from '@kit.BasicServicesKit'; 825 826class EntryAbility extends ServiceExtensionAbility { 827 onCreate() { 828 let want: Want = { 829 deviceId: '', 830 bundleName: 'com.example.myapplication', 831 abilityName: 'EntryAbility' 832 }; 833 let accountId = 100; 834 835 try { 836 this.context.startServiceExtensionAbilityWithAccount(want, accountId) 837 .then((data: void) => { 838 // Carry out normal service processing. 839 console.log('startServiceExtensionAbilityWithAccount succeed'); 840 }) 841 .catch((error: BusinessError) => { 842 // Process service logic errors. 843 console.error(`startServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`); 844 }); 845 } catch (paramError) { 846 // Process input parameter errors. 847 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 848 } 849 } 850} 851``` 852 853## ServiceExtensionContext.startAbilityAsCaller<sup>10+<sup> 854 855startAbilityAsCaller(want: Want, callback: AsyncCallback\<void>): void; 856 857Starts an ability with the caller information specified. The caller information is carried in **want** and identified at the system service layer. The ability can obtain the caller information from the **want** parameter in the **onCreate** lifecycle callback. When this API is used to start an ability, the caller information carried in **want** is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API uses an asynchronous callback to return the result. 858 859> **NOTE** 860> 861> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 862 863**System capability**: SystemCapability.Ability.AbilityRuntime.Core 864 865**System API**: This is a system API and cannot be called by third-party applications. 866 867**Parameters** 868 869| Name| Type| Mandatory| Description| 870| -------- | -------- | -------- | -------- | 871| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 872| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the ability is started, **err** is **undefined**; otherwise, **err** is an error object.| 873 874**Error codes** 875 876For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 877 878| ID| Error Message| 879| ------- | -------- | 880| 201 | The application does not have permission to call the interface. | 881| 202 | The application is not system-app, can not use system-api. | 882| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 883| 16000001 | The specified ability does not exist. | 884| 16000002 | Incorrect ability type. | 885| 16000004 | Can not start invisible component. | 886| 16000005 | The specified process does not have the permission. | 887| 16000006 | Cross-user operations are not allowed. | 888| 16000008 | The crowdtesting application expires. | 889| 16000009 | An ability cannot be started or stopped in Wukong mode. | 890| 16000010 | The call with the continuation flag is forbidden. | 891| 16000011 | The context does not exist. | 892| 16000012 | The application is controlled. | 893| 16000013 | The application is controlled by EDM. | 894| 16000050 | Internal error. | 895| 16000053 | The ability is not on the top of the UI. | 896| 16000055 | Installation-free timed out. | 897| 16200001 | The caller has been released. | 898| 16000073 | The app clone index is invalid. | 899 900**Example** 901 902```ts 903import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 904 905class EntryAbility extends ServiceExtensionAbility { 906 onCreate(want: Want) { 907 // want contains the information about the caller who starts the application. 908 let localWant: Want = want; 909 localWant.bundleName = 'com.example.demo'; 910 localWant.moduleName = 'entry'; 911 localWant.abilityName = 'TestAbility'; 912 913 // Start a new ability using the caller information. 914 this.context.startAbilityAsCaller(localWant, (err) => { 915 if (err && err.code != 0) { 916 console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err)); 917 } else { 918 console.log('startAbilityAsCaller success.'); 919 } 920 }) 921 } 922} 923``` 924 925## ServiceExtensionContext.startAbilityAsCaller<sup>10+<sup> 926 927startAbilityAsCaller(want: Want, options: StartOptions, callback: AsyncCallback\<void>): void; 928 929Starts an ability with the caller information and start options specified. The caller information is carried in **want** and identified at the system service layer. The ability can obtain the caller information from the **want** parameter in the **onCreate** lifecycle callback. When this API is used to start an ability, the caller information carried in **want** is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API uses an asynchronous callback to return the result. 930 931> **NOTE** 932> 933> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 934 935**System capability**: SystemCapability.Ability.AbilityRuntime.Core 936 937**System API**: This is a system API and cannot be called by third-party applications. 938 939**Parameters** 940 941| Name| Type| Mandatory| Description| 942| -------- | -------- | -------- | -------- | 943| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 944| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 945| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the ability is started, **err** is **undefined**; otherwise, **err** is an error object.| 946 947**Error codes** 948 949For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 950 951| ID| Error Message| 952| ------- | -------- | 953| 201 | The application does not have permission to call the interface. | 954| 202 | The application is not system-app, can not use system-api. | 955| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 956| 16000001 | The specified ability does not exist. | 957| 16000004 | Can not start invisible component. | 958| 16000005 | The specified process does not have the permission. | 959| 16000006 | Cross-user operations are not allowed. | 960| 16000008 | The crowdtesting application expires. | 961| 16000009 | An ability cannot be started or stopped in Wukong mode. | 962| 16000011 | The context does not exist. | 963| 16000012 | The application is controlled. | 964| 16000013 | The application is controlled by EDM. | 965| 16000050 | Internal error. | 966| 16000053 | The ability is not on the top of the UI. | 967| 16000055 | Installation-free timed out. | 968| 16200001 | The caller has been released. | 969| 16000073 | The app clone index is invalid. | 970 971**Example** 972 973```ts 974import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 975 976class EntryAbility extends ServiceExtensionAbility { 977 onCreate(want: Want) { 978 // want contains the information about the caller who starts the application. 979 let localWant: Want = want; 980 localWant.bundleName = 'com.example.demo'; 981 localWant.moduleName = 'entry'; 982 localWant.abilityName = 'TestAbility'; 983 984 let option: StartOptions = { 985 displayId: 0 986 } 987 988 // Start a new ability using the caller information. 989 this.context.startAbilityAsCaller(localWant, option, (err) => { 990 if (err && err.code != 0) { 991 console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err)); 992 } else { 993 console.log('startAbilityAsCaller success.'); 994 } 995 }) 996 } 997} 998``` 999 1000## ServiceExtensionContext.startAbilityAsCaller<sup>10+<sup> 1001 1002startAbilityAsCaller(want: Want, options?: StartOptions): Promise\<void>; 1003 1004Starts an ability with the caller information specified. The caller information is carried in **want** and identified at the system service layer. The ability can obtain the caller information from the **want** parameter in the **onCreate** lifecycle callback. When this API is used to start an ability, the caller information carried in **want** is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API uses a promise to return the result. 1005 1006> **NOTE** 1007> 1008> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 1009 1010**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1011 1012**System API**: This is a system API and cannot be called by third-party applications. 1013 1014**Parameters** 1015 1016| Name| Type| Mandatory| Description| 1017| -------- | -------- | -------- | -------- | 1018| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1019| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 1020 1021**Return value** 1022 1023| Type| Description| 1024| -------- | -------- | 1025| Promise<void> | Promise that returns no value.| 1026 1027**Error codes** 1028 1029For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1030 1031| ID| Error Message| 1032| ------- | -------- | 1033| 201 | The application does not have permission to call the interface. | 1034| 202 | The application is not system-app, can not use system-api. | 1035| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1036| 16000001 | The specified ability does not exist. | 1037| 16000002 | Incorrect ability type. | 1038| 16000004 | Can not start invisible component. | 1039| 16000005 | The specified process does not have the permission. | 1040| 16000006 | Cross-user operations are not allowed. | 1041| 16000008 | The crowdtesting application expires. | 1042| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1043| 16000010 | The call with the continuation flag is forbidden. | 1044| 16000011 | The context does not exist. | 1045| 16000012 | The application is controlled. | 1046| 16000013 | The application is controlled by EDM. | 1047| 16000050 | Internal error. | 1048| 16000053 | The ability is not on the top of the UI. | 1049| 16000055 | Installation-free timed out. | 1050| 16200001 | The caller has been released. | 1051| 16000073 | The app clone index is invalid. | 1052 1053**Example** 1054 1055```ts 1056import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 1057import { BusinessError } from '@kit.BasicServicesKit'; 1058 1059class EntryAbility extends ServiceExtensionAbility { 1060 onCreate(want: Want) { 1061 // want contains the information about the caller who starts the application. 1062 let localWant: Want = want; 1063 localWant.bundleName = 'com.example.demo'; 1064 localWant.moduleName = 'entry'; 1065 localWant.abilityName = 'TestAbility'; 1066 1067 let option: StartOptions = { 1068 displayId: 0 1069 }; 1070 1071 // Start a new ability using the caller information. 1072 this.context.startAbilityAsCaller(localWant, option) 1073 .then(() => { 1074 console.log('startAbilityAsCaller success.'); 1075 }) 1076 .catch((err: BusinessError) => { 1077 console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err)); 1078 }) 1079 } 1080} 1081``` 1082 1083## ServiceExtensionContext.stopServiceExtensionAbility 1084 1085stopServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void; 1086 1087Stops a ServiceExtensionAbility in the same application. This API uses an asynchronous callback to return the result. 1088 1089**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1090 1091**System API**: This is a system API and cannot be called by third-party applications. 1092 1093**Parameters** 1094 1095| Name| Type| Mandatory| Description| 1096| -------- | -------- | -------- | -------- | 1097| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1098| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 1099 1100**Error codes** 1101 1102For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1103 1104| ID| Error Message| 1105| ------- | -------- | 1106| 201 | The application does not have permission to call the interface. | 1107| 202 | The application is not system-app, can not use system-api. | 1108| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1109| 16000001 | The specified ability does not exist. | 1110| 16000002 | Incorrect ability type. | 1111| 16000004 | Can not start invisible component. | 1112| 16000005 | The specified process does not have the permission. | 1113| 16000006 | Cross-user operations are not allowed. | 1114| 16000011 | The context does not exist. | 1115| 16000050 | Internal error. | 1116| 16200001 | The caller has been released. | 1117 1118**Example** 1119 1120```ts 1121import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 1122import { BusinessError } from '@kit.BasicServicesKit'; 1123 1124class EntryAbility extends ServiceExtensionAbility { 1125 onCreate() { 1126 let want: Want = { 1127 deviceId: '', 1128 bundleName: 'com.example.myapplication', 1129 abilityName: 'EntryAbility' 1130 }; 1131 1132 try { 1133 this.context.stopServiceExtensionAbility(want, (error: BusinessError) => { 1134 if (error.code) { 1135 // Process service logic errors. 1136 console.error(`stopServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 1137 return; 1138 } 1139 // Carry out normal service processing. 1140 console.log('stopServiceExtensionAbility succeed'); 1141 }); 1142 } catch (paramError) { 1143 // Process input parameter errors. 1144 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1145 } 1146 } 1147} 1148``` 1149 1150## ServiceExtensionContext.stopServiceExtensionAbility 1151 1152stopServiceExtensionAbility(want: Want): Promise\<void>; 1153 1154Stops a ServiceExtensionAbility in the same application. This API uses a promise to return the result. 1155 1156**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1157 1158**System API**: This is a system API and cannot be called by third-party applications. 1159 1160**Parameters** 1161 1162| Name| Type| Mandatory| Description| 1163| -------- | -------- | -------- | -------- | 1164| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1165 1166**Return value** 1167 1168| Type| Description| 1169| -------- | -------- | 1170| Promise<void> | Promise used to return the result.| 1171 1172**Error codes** 1173 1174For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1175 1176| ID| Error Message| 1177| ------- | -------- | 1178| 201 | The application does not have permission to call the interface. | 1179| 202 | The application is not system-app, can not use system-api. | 1180| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1181| 16000001 | The specified ability does not exist. | 1182| 16000002 | Incorrect ability type. | 1183| 16000004 | Can not start invisible component. | 1184| 16000005 | The specified process does not have the permission. | 1185| 16000006 | Cross-user operations are not allowed. | 1186| 16000011 | The context does not exist. | 1187| 16000050 | Internal error. | 1188| 16200001 | The caller has been released. | 1189 1190**Example** 1191 1192```ts 1193import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 1194import { BusinessError } from '@kit.BasicServicesKit'; 1195 1196class EntryAbility extends ServiceExtensionAbility { 1197 onCreate() { 1198 let want: Want = { 1199 deviceId: '', 1200 bundleName: 'com.example.myapplication', 1201 abilityName: 'EntryAbility' 1202 }; 1203 1204 try { 1205 this.context.stopServiceExtensionAbility(want) 1206 .then(() => { 1207 // Carry out normal service processing. 1208 console.log('stopServiceExtensionAbility succeed'); 1209 }) 1210 .catch((error: BusinessError) => { 1211 // Process service logic errors. 1212 console.error(`stopServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 1213 }); 1214 } catch (paramError) { 1215 // Process input parameter errors. 1216 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1217 } 1218 } 1219} 1220``` 1221 1222## ServiceExtensionContext.stopServiceExtensionAbilityWithAccount 1223 1224stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void; 1225 1226Stops a ServiceExtensionAbility in the same application with the account ID specified. This API uses an asynchronous callback to return the result. 1227 1228> **NOTE** 1229> 1230> Permission verification is not required when **accountId** specifies the current user. 1231 1232**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1233 1234**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1235 1236**System API**: This is a system API and cannot be called by third-party applications. 1237 1238**Parameters** 1239 1240| Name| Type| Mandatory| Description| 1241| -------- | -------- | -------- | -------- | 1242| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1243| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getcreatedosaccountscountdeprecated).| 1244| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.| 1245 1246**Error codes** 1247 1248For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1249 1250| ID| Error Message| 1251| ------- | -------- | 1252| 201 | The application does not have permission to call the interface. | 1253| 202 | The application is not system-app, can not use system-api. | 1254| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1255| 16000001 | The specified ability does not exist. | 1256| 16000002 | Incorrect ability type. | 1257| 16000004 | Can not start invisible component. | 1258| 16000005 | The specified process does not have the permission. | 1259| 16000006 | Cross-user operations are not allowed. | 1260| 16000011 | The context does not exist. | 1261| 16000050 | Internal error. | 1262| 16200001 | The caller has been released. | 1263 1264**Example** 1265 1266```ts 1267import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 1268import { BusinessError } from '@kit.BasicServicesKit'; 1269 1270class EntryAbility extends ServiceExtensionAbility { 1271 onCreate() { 1272 let want: Want = { 1273 deviceId: '', 1274 bundleName: 'com.example.myapplication', 1275 abilityName: 'EntryAbility' 1276 }; 1277 let accountId = 100; 1278 1279 try { 1280 this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (error: BusinessError) => { 1281 if (error.code) { 1282 // Process service logic errors. 1283 console.error(`stopServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`); 1284 return; 1285 } 1286 // Carry out normal service processing. 1287 console.log('stopServiceExtensionAbilityWithAccount succeed'); 1288 }); 1289 } catch (paramError) { 1290 // Process input parameter errors. 1291 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1292 } 1293 } 1294} 1295``` 1296 1297## ServiceExtensionContext.stopServiceExtensionAbilityWithAccount 1298 1299stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void>; 1300 1301Stops a ServiceExtensionAbility in the same application with the account ID specified. This API uses a promise to return the result. 1302 1303> **NOTE** 1304> 1305> Permission verification is not required when **accountId** specifies the current user. 1306 1307**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1308 1309**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1310 1311**System API**: This is a system API and cannot be called by third-party applications. 1312 1313**Parameters** 1314 1315| Name| Type| Mandatory| Description| 1316| -------- | -------- | -------- | -------- | 1317| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1318| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getcreatedosaccountscountdeprecated-1).| 1319 1320**Return value** 1321 1322| Type| Description| 1323| -------- | -------- | 1324| Promise<void> | Promise used to return the result.| 1325 1326**Error codes** 1327 1328For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1329 1330| ID| Error Message| 1331| ------- | -------- | 1332| 201 | The application does not have permission to call the interface. | 1333| 202 | The application is not system-app, can not use system-api. | 1334| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1335| 16000001 | The specified ability does not exist. | 1336| 16000002 | Incorrect ability type. | 1337| 16000004 | Can not start invisible component. | 1338| 16000005 | The specified process does not have the permission. | 1339| 16000006 | Cross-user operations are not allowed. | 1340| 16000011 | The context does not exist. | 1341| 16000050 | Internal error. | 1342| 16200001 | The caller has been released. | 1343 1344**Example** 1345 1346```ts 1347import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 1348import { BusinessError } from '@kit.BasicServicesKit'; 1349 1350class EntryAbility extends ServiceExtensionAbility { 1351 onCreate() { 1352 let want: Want = { 1353 deviceId: '', 1354 bundleName: 'com.example.myapplication', 1355 abilityName: 'EntryAbility' 1356 }; 1357 let accountId = 100; 1358 1359 try { 1360 this.context.stopServiceExtensionAbilityWithAccount(want, accountId) 1361 .then(() => { 1362 // Carry out normal service processing. 1363 console.log('stopServiceExtensionAbilityWithAccount succeed'); 1364 }) 1365 .catch((error: BusinessError) => { 1366 // Process service logic errors. 1367 console.error(`stopServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`); 1368 }); 1369 } catch (paramError) { 1370 // Process input parameter errors. 1371 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1372 } 1373 } 1374} 1375``` 1376 1377## ServiceExtensionContext.terminateSelf 1378 1379terminateSelf(callback: AsyncCallback<void>): void; 1380 1381Terminates this ability. This API uses an asynchronous callback to return the result. 1382 1383**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1384 1385**System API**: This is a system API and cannot be called by third-party applications. 1386 1387**Parameters** 1388 1389| Name| Type| Mandatory| Description| 1390| -------- | -------- | -------- | -------- | 1391| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1392 1393**Error codes** 1394 1395For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1396 1397| ID| Error Message| 1398| ------- | -------- | 1399| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1400| 16000001 | The specified ability does not exist. | 1401| 16000004 | Can not start invisible component. | 1402| 16000005 | The specified process does not have the permission. | 1403| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1404| 16000011 | The context does not exist. | 1405| 16000050 | Internal error. | 1406 1407**Example** 1408 1409```ts 1410import { ServiceExtensionAbility } from '@kit.AbilityKit'; 1411import { BusinessError } from '@kit.BasicServicesKit'; 1412 1413class EntryAbility extends ServiceExtensionAbility { 1414 onCreate() { 1415 this.context.terminateSelf((error: BusinessError) => { 1416 if (error.code) { 1417 // Process service logic errors. 1418 console.error(`terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}`); 1419 return; 1420 } 1421 // Carry out normal service processing. 1422 console.log('terminateSelf succeed'); 1423 }); 1424 } 1425} 1426``` 1427 1428## ServiceExtensionContext.terminateSelf 1429 1430terminateSelf(): Promise<void>; 1431 1432Terminates this ability. This API uses a promise to return the result. 1433 1434**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1435 1436**System API**: This is a system API and cannot be called by third-party applications. 1437 1438**Return value** 1439 1440| Type| Description| 1441| -------- | -------- | 1442| Promise<void> | Promise used to return the result.| 1443 1444**Error codes** 1445 1446For details about the error codes, see [Ability Error Codes](errorcode-ability.md). 1447 1448| ID| Error Message| 1449| ------- | -------------------------------- | 1450| 16000001 | The specified ability does not exist. | 1451| 16000004 | Can not start invisible component. | 1452| 16000005 | The specified process does not have the permission. | 1453| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1454| 16000011 | The context does not exist. | 1455| 16000050 | Internal error. | 1456 1457**Example** 1458 1459```ts 1460import { ServiceExtensionAbility } from '@kit.AbilityKit'; 1461import { BusinessError } from '@kit.BasicServicesKit'; 1462 1463class EntryAbility extends ServiceExtensionAbility { 1464 onCreate() { 1465 this.context.terminateSelf().then(() => { 1466 // Carry out normal service processing. 1467 console.log('terminateSelf succeed'); 1468 }).catch((error: BusinessError) => { 1469 // Process service logic errors. 1470 console.error(`terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}`); 1471 }); 1472 } 1473} 1474``` 1475 1476## ServiceExtensionContext.connectServiceExtensionAbility 1477 1478connectServiceExtensionAbility(want: Want, options: ConnectOptions): number; 1479 1480Connects this ability to a ServiceExtensionAbility. 1481 1482> **NOTE** 1483> 1484> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 1485 1486**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1487 1488**System API**: This is a system API and cannot be called by third-party applications. 1489 1490**Parameters** 1491 1492| Name| Type| Mandatory| Description| 1493| -------- | -------- | -------- | -------- | 1494| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| 1495| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.| 1496 1497**Return value** 1498 1499| Type| Description| 1500| -------- | -------- | 1501| number | A number, based on which the connection will be interrupted.| 1502 1503**Error codes** 1504 1505For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1506 1507| ID| Error Message| 1508| ------- | -------- | 1509| 201 | The application does not have permission to call the interface. | 1510| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1511| 16000001 | The specified ability does not exist. | 1512| 16000002 | Incorrect ability type. | 1513| 16000004 | Can not start invisible component. | 1514| 16000005 | The specified process does not have the permission. | 1515| 16000006 | Cross-user operations are not allowed. | 1516| 16000008 | The crowdtesting application expires. | 1517| 16000053 | The ability is not on the top of the UI. | 1518| 16000055 | Installation-free timed out. | 1519| 16000011 | The context does not exist. | 1520| 16000050 | Internal error. | 1521 1522**Example** 1523 1524```ts 1525import { ServiceExtensionAbility, Want, common } from '@kit.AbilityKit'; 1526import { rpc } from '@kit.IPCKit'; 1527import { BusinessError } from '@kit.BasicServicesKit'; 1528 1529let commRemote: rpc.IRemoteObject; // Release the instance when the connection is disconnected. 1530 1531class EntryAbility extends ServiceExtensionAbility { 1532 onCreate() { 1533 let want: Want = { 1534 bundleName: 'com.example.myapp', 1535 abilityName: 'MyAbility' 1536 }; 1537 let options: common.ConnectOptions = { 1538 onConnect(elementName, remote) { 1539 commRemote = remote; 1540 console.log('----------- onConnect -----------'); 1541 }, 1542 onDisconnect(elementName) { 1543 console.log('----------- onDisconnect -----------'); 1544 }, 1545 onFailed(code) { 1546 console.error('----------- onFailed -----------'); 1547 } 1548 }; 1549 let connection: number; 1550 1551 try { 1552 connection = this.context.connectServiceExtensionAbility(want, options); 1553 } catch (paramError) { 1554 // Process input parameter errors. 1555 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1556 } 1557 } 1558} 1559``` 1560 1561## ServiceExtensionContext.connectServiceExtensionAbilityWithAccount 1562 1563connectServiceExtensionAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number; 1564 1565Connects this ability to a ServiceExtensionAbility of a given account. 1566 1567> **NOTE** 1568> 1569> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 1570> Permission verification is not required when **accountId** specifies the current user. 1571 1572**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1573 1574**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1575 1576**System API**: This is a system API and cannot be called by third-party applications. 1577 1578**Parameters** 1579 1580| Name| Type| Mandatory| Description| 1581| -------- | -------- | -------- | -------- | 1582| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1583| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getcreatedosaccountscountdeprecated).| 1584| options | ConnectOptions | Yes| Remote object instance.| 1585 1586**Return value** 1587 1588| Type| Description| 1589| -------- | -------- | 1590| number | Result code of the connection.| 1591 1592**Error codes** 1593 1594For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1595 1596| ID| Error Message| 1597| ------- | -------- | 1598| 201 | The application does not have permission to call the interface. | 1599| 202 | The application is not system-app, can not use system-api. | 1600| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1601| 16000001 | The specified ability does not exist. | 1602| 16000002 | Incorrect ability type. | 1603| 16000004 | Can not start invisible component. | 1604| 16000005 | The specified process does not have the permission. | 1605| 16000006 | Cross-user operations are not allowed. | 1606| 16000008 | The crowdtesting application expires. | 1607| 16000053 | The ability is not on the top of the UI. | 1608| 16000055 | Installation-free timed out. | 1609| 16000011 | The context does not exist. | 1610| 16000050 | Internal error. | 1611 1612**Example** 1613 1614```ts 1615import { ServiceExtensionAbility, Want, common } from '@kit.AbilityKit'; 1616import { rpc } from '@kit.IPCKit'; 1617import { BusinessError } from '@kit.BasicServicesKit'; 1618 1619let commRemote: rpc.IRemoteObject; // Release the instance when the connection is disconnected. 1620 1621class EntryAbility extends ServiceExtensionAbility { 1622 onCreate() { 1623 let want: Want = { 1624 deviceId: '', 1625 bundleName: 'com.example.myapplication', 1626 abilityName: 'EntryAbility' 1627 }; 1628 let accountId = 100; 1629 let options: common.ConnectOptions = { 1630 onConnect(elementName, remote) { 1631 commRemote = remote; 1632 console.log('----------- onConnect -----------'); 1633 }, 1634 onDisconnect(elementName) { 1635 console.log('----------- onDisconnect -----------'); 1636 }, 1637 onFailed(code) { 1638 console.log('----------- onFailed -----------'); 1639 } 1640 }; 1641 let connection: number; 1642 1643 try { 1644 connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options); 1645 } catch (paramError) { 1646 // Process input parameter errors. 1647 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1648 } 1649 } 1650} 1651``` 1652 1653## ServiceExtensionContext.disconnectServiceExtensionAbility 1654 1655disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback<void>): void; 1656 1657Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses an asynchronous callback to return the result. 1658 1659**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1660 1661**System API**: This is a system API and cannot be called by third-party applications. 1662 1663**Parameters** 1664 1665| Name| Type| Mandatory| Description| 1666| -------- | -------- | -------- | -------- | 1667| connection | number | Yes| Number returned after **connectServiceExtensionAbility** is called.| 1668| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 1669 1670**Error codes** 1671 1672For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1673 1674| ID| Error Message| 1675| ------- | -------- | 1676| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1677| 16000011 | The context does not exist. | 1678| 16000050 | Internal error. | 1679 1680**Example** 1681 1682```ts 1683import { ServiceExtensionAbility } from '@kit.AbilityKit'; 1684import { rpc } from '@kit.IPCKit'; 1685import { BusinessError } from '@kit.BasicServicesKit'; 1686 1687let commRemote: rpc.IRemoteObject | null; // Release the instance when the connection is disconnected. 1688 1689class EntryAbility extends ServiceExtensionAbility { 1690 onCreate() { 1691 // connection is the return value of connectServiceExtensionAbility. 1692 let connection = 1; 1693 try { 1694 this.context.disconnectServiceExtensionAbility(connection, (error: BusinessError) => { 1695 commRemote = null; 1696 if (error.code) { 1697 // Process service logic errors. 1698 console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 1699 return; 1700 } 1701 // Carry out normal service processing. 1702 console.log('disconnectServiceExtensionAbility succeed'); 1703 }); 1704 } catch (paramError) { 1705 commRemote = null; 1706 // Process input parameter errors. 1707 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1708 } 1709 } 1710} 1711``` 1712 1713## ServiceExtensionContext.disconnectServiceExtensionAbility 1714 1715disconnectServiceExtensionAbility(connection: number): Promise<void>; 1716 1717Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses a promise to return the result. 1718 1719**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1720 1721**System API**: This is a system API and cannot be called by third-party applications. 1722 1723**Parameters** 1724 1725| Name| Type| Mandatory| Description| 1726| -------- | -------- | -------- | -------- | 1727| connection | number | Yes| Number returned after **connectServiceExtensionAbility** is called.| 1728 1729**Return value** 1730 1731| Type| Description| 1732| -------- | -------- | 1733| Promise<void> | Promise used to return the result.| 1734 1735**Error codes** 1736 1737For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1738 1739| ID| Error Message| 1740| ------- | -------- | 1741| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1742| 16000011 | The context does not exist. | 1743| 16000050 | Internal error. | 1744 1745**Example** 1746 1747```ts 1748import { ServiceExtensionAbility } from '@kit.AbilityKit'; 1749import { rpc } from '@kit.IPCKit'; 1750import { BusinessError } from '@kit.BasicServicesKit'; 1751 1752let commRemote: rpc.IRemoteObject | null; // Release the instance when the connection is disconnected. 1753 1754class EntryAbility extends ServiceExtensionAbility { 1755 onCreate() { 1756 // connection is the return value of connectServiceExtensionAbility. 1757 let connection = 1; 1758 try { 1759 this.context.disconnectServiceExtensionAbility(connection) 1760 .then(() => { 1761 commRemote = null; 1762 // Carry out normal service processing. 1763 console.log('disconnectServiceExtensionAbility succeed'); 1764 }) 1765 .catch((error: BusinessError) => { 1766 commRemote = null; 1767 // Process service logic errors. 1768 console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 1769 }); 1770 } catch (paramError) { 1771 commRemote = null; 1772 // Process input parameter errors. 1773 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1774 } 1775 } 1776} 1777``` 1778 1779## ServiceExtensionContext.startAbilityByCall 1780 1781startAbilityByCall(want: Want): Promise<Caller>; 1782 1783Starts an ability in the foreground or background and obtains the caller object for communicating with the ability. 1784 1785Observe the following when using this API: 1786 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 1787 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 1788 - The rules for using this API in the same-device and cross-device scenarios are different. For details, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 1789 1790**Required permissions**: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION 1791 1792**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1793 1794**System API**: This is a system API and cannot be called by third-party applications. 1795 1796**Parameters** 1797 1798| Name| Type| Mandatory| Description| 1799| -------- | -------- | -------- | -------- | 1800| want | [Want](js-apis-app-ability-want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId**, and **parameters** (optional). If **parameters** is left blank or null, the ability is started in the background.| 1801 1802**Return value** 1803 1804| Type| Description| 1805| -------- | -------- | 1806| Promise<Caller> | Promise used to return the caller object to communicate with.| 1807 1808**Error codes** 1809 1810For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1811 1812| ID| Error Message| 1813| ------- | -------- | 1814| 201 | The application does not have permission to call the interface. | 1815| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1816| 16000001 | The specified ability does not exist. | 1817| 16000002 | Incorrect ability type. | 1818| 16000004 | Can not start invisible component. | 1819| 16000005 | Static permission denied. The specified process does not have the permission. | 1820| 16000006 | Cross-user operations are not allowed. | 1821| 16000008 | The crowdtesting application expires. | 1822| 16000011 | The context does not exist. | 1823| 16000050 | Internal error. | 1824| 16200001 | The caller has been released. | 1825 1826**Example** 1827 1828Start an ability in the background. 1829 1830```ts 1831import { ServiceExtensionAbility, Caller, Want } from '@kit.AbilityKit'; 1832import { BusinessError } from '@kit.BasicServicesKit'; 1833 1834class EntryAbility extends ServiceExtensionAbility { 1835 onCreate() { 1836 let caller: Caller; 1837 // Start an ability in the background by not passing parameters. 1838 let wantBackground: Want = { 1839 bundleName: 'com.example.myservice', 1840 moduleName: 'entry', 1841 abilityName: 'EntryAbility', 1842 deviceId: '' 1843 }; 1844 1845 try { 1846 this.context.startAbilityByCall(wantBackground) 1847 .then((obj: Caller) => { 1848 // Carry out normal service processing. 1849 caller = obj; 1850 console.log('startAbilityByCall succeed'); 1851 }).catch((error: BusinessError) => { 1852 // Process service logic errors. 1853 console.error(`startAbilityByCall failed, error.code: ${error.code}, error.message: ${error.message}`); 1854 }); 1855 } catch (paramError) { 1856 // Process input parameter errors. 1857 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1858 } 1859 } 1860} 1861``` 1862 1863Start an ability in the foreground. 1864 1865```ts 1866import { ServiceExtensionAbility, Caller, Want } from '@kit.AbilityKit'; 1867import { BusinessError } from '@kit.BasicServicesKit'; 1868 1869class EntryAbility extends ServiceExtensionAbility { 1870 onCreate() { 1871 let caller: Caller; 1872 // Start an ability in the foreground with 'ohos.aafwk.param.callAbilityToForeground' in parameters set to true. 1873 let wantForeground: Want = { 1874 bundleName: 'com.example.myservice', 1875 moduleName: 'entry', 1876 abilityName: 'EntryAbility', 1877 deviceId: '', 1878 parameters: { 1879 'ohos.aafwk.param.callAbilityToForeground': true 1880 } 1881 }; 1882 1883 try { 1884 this.context.startAbilityByCall(wantForeground) 1885 .then((obj: Caller) => { 1886 // Carry out normal service processing. 1887 caller = obj; 1888 console.log('startAbilityByCall succeed'); 1889 }).catch((error: BusinessError) => { 1890 // Process service logic errors. 1891 console.error(`startAbilityByCall failed, error.code: ${error.code}, error.message: ${error.message}`); 1892 }); 1893 } catch (paramError) { 1894 // Process input parameter errors. 1895 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 1896 } 1897 } 1898} 1899``` 1900## ServiceExtensionContext.startRecentAbility 1901 1902startRecentAbility(want: Want, callback: AsyncCallback\<void>): void; 1903 1904Starts an ability. If the ability has multiple instances, the latest instance is started. This API uses an asynchronous callback to return the result. 1905 1906> **NOTE** 1907> 1908> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 1909 1910**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1911 1912**System API**: This is a system API and cannot be called by third-party applications. 1913 1914**Parameters** 1915 1916| Name| Type| Mandatory| Description| 1917| -------- | -------- | -------- | -------- | 1918| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1919| callback | AsyncCallback\<void> | Yes| Callback used to return the result.| 1920 1921**Error codes** 1922 1923For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 1924 1925| ID| Error Message| 1926| ------- | -------- | 1927| 201 | The application does not have permission to call the interface. | 1928| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1929| 16000001 | The specified ability does not exist. | 1930| 16000002 | Incorrect ability type. | 1931| 16000004 | Can not start invisible component. | 1932| 16000005 | The specified process does not have the permission. | 1933| 16000006 | Cross-user operations are not allowed. | 1934| 16000008 | The crowdtesting application expires. | 1935| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1936| 16000010 | The call with the continuation flag is forbidden. | 1937| 16000011 | The context does not exist. | 1938| 16000050 | Internal error. | 1939| 16000053 | The ability is not on the top of the UI. | 1940| 16000055 | Installation-free timed out. | 1941| 16200001 | The caller has been released. | 1942 1943**Example** 1944 1945```ts 1946import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 1947import { BusinessError } from '@kit.BasicServicesKit'; 1948 1949class EntryAbility extends ServiceExtensionAbility { 1950 onCreate() { 1951 let want: Want = { 1952 bundleName: 'com.example.myapplication', 1953 abilityName: 'EntryAbility' 1954 }; 1955 1956 try { 1957 this.context.startRecentAbility(want, (err: BusinessError) => { 1958 if (err.code) { 1959 // Process service logic errors. 1960 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 1961 return; 1962 } 1963 // Carry out normal service processing. 1964 console.info('startRecentAbility succeed'); 1965 }); 1966 } catch (err) { 1967 // Process input parameter errors. 1968 let code = (err as BusinessError).code; 1969 let message = (err as BusinessError).message; 1970 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 1971 } 1972 } 1973} 1974``` 1975## ServiceExtensionContext.startRecentAbility 1976 1977startRecentAbility(want: Want, options: StartOptions, callback: AsyncCallback\<void>): void; 1978 1979Starts an ability with the start options specified. If the ability has multiple instances, the latest instance is started. This API uses an asynchronous callback to return the result. 1980You can use this API to carry start options. 1981 1982> **NOTE** 1983> 1984> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 1985 1986**System capability**: SystemCapability.Ability.AbilityRuntime.Core 1987 1988**System API**: This is a system API and cannot be called by third-party applications. 1989 1990**Parameters** 1991 1992| Name| Type| Mandatory| Description| 1993| -------- | -------- | -------- | -------- | 1994| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 1995| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| 1996| callback | AsyncCallback\<void> | Yes| Callback used to return the result.| 1997 1998**Error codes** 1999 2000For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 2001 2002| ID| Error Message| 2003| ------- | -------- | 2004| 201 | The application does not have permission to call the interface. | 2005| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2006| 16000001 | The specified ability does not exist. | 2007| 16000002 | Incorrect ability type. | 2008| 16000004 | Can not start invisible component. | 2009| 16000005 | The specified process does not have the permission. | 2010| 16000006 | Cross-user operations are not allowed. | 2011| 16000008 | The crowdtesting application expires. | 2012| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2013| 16000010 | The call with the continuation flag is forbidden. | 2014| 16000011 | The context does not exist. | 2015| 16000050 | Internal error. | 2016| 16000053 | The ability is not on the top of the UI. | 2017| 16000055 | Installation-free timed out. | 2018| 16200001 | The caller has been released. | 2019 2020**Example** 2021 2022```ts 2023import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 2024import { BusinessError } from '@kit.BasicServicesKit'; 2025 2026class EntryAbility extends ServiceExtensionAbility { 2027 onCreate() { 2028 let want: Want = { 2029 deviceId: '', 2030 bundleName: 'com.example.myapplication', 2031 abilityName: 'EntryAbility' 2032 }; 2033 let options: StartOptions = { 2034 windowMode: 0 2035 }; 2036 2037 try { 2038 this.context.startRecentAbility(want, options, (err: BusinessError) => { 2039 if (err.code) { 2040 // Process service logic errors. 2041 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 2042 return; 2043 } 2044 // Carry out normal service processing. 2045 console.info('startRecentAbility succeed'); 2046 }); 2047 } catch (err) { 2048 // Process input parameter errors. 2049 let code = (err as BusinessError).code; 2050 let message = (err as BusinessError).message; 2051 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 2052 } 2053 } 2054} 2055``` 2056## ServiceExtensionContext.startRecentAbility 2057 2058startRecentAbility(want: Want, options?: StartOptions): Promise\<void>; 2059 2060Starts an ability. If the ability has multiple instances, the latest instance is started. 2061This API uses a promise to return the result. 2062 2063> **NOTE** 2064> 2065> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2066 2067**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2068 2069**System API**: This is a system API and cannot be called by third-party applications. 2070 2071**Parameters** 2072 2073| Name| Type| Mandatory| Description| 2074| -------- | -------- | -------- | -------- | 2075| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| 2076| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| 2077 2078**Error codes** 2079 2080For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 2081 2082| ID| Error Message| 2083| ------- | -------- | 2084| 201 | The application does not have permission to call the interface. | 2085| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2086| 16000001 | The specified ability does not exist. | 2087| 16000002 | Incorrect ability type. | 2088| 16000004 | Can not start invisible component. | 2089| 16000005 | The specified process does not have the permission. | 2090| 16000006 | Cross-user operations are not allowed. | 2091| 16000008 | The crowdtesting application expires. | 2092| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2093| 16000010 | The call with the continuation flag is forbidden. | 2094| 16000011 | The context does not exist. | 2095| 16000050 | Internal error. | 2096| 16000053 | The ability is not on the top of the UI. | 2097| 16000055 | Installation-free timed out. | 2098| 16200001 | The caller has been released. | 2099 2100**Example** 2101 2102```ts 2103import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 2104import { BusinessError } from '@kit.BasicServicesKit'; 2105 2106class EntryAbility extends ServiceExtensionAbility { 2107 onCreate() { 2108 let want: Want = { 2109 bundleName: 'com.example.myapplication', 2110 abilityName: 'EntryAbility' 2111 }; 2112 let options: StartOptions = { 2113 windowMode: 0, 2114 }; 2115 2116 try { 2117 this.context.startRecentAbility(want, options) 2118 .then(() => { 2119 // Carry out normal service processing. 2120 console.info('startRecentAbility succeed'); 2121 }) 2122 .catch((err: BusinessError) => { 2123 // Process service logic errors. 2124 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 2125 }); 2126 } catch (err) { 2127 // Process input parameter errors. 2128 let code = (err as BusinessError).code; 2129 let message = (err as BusinessError).message; 2130 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 2131 } 2132 } 2133} 2134``` 2135 2136## ServiceExtensionContext.startAbilityByCallWithAccount<sup>10+</sup> 2137 2138startAbilityByCallWithAccount(want: Want, accountId: number): Promise<Caller>; 2139 2140Starts an ability with the account ID specified and obtains the caller object for communicating with the ability. 2141 2142Observe the following when using this API: 2143 - If an application needs to call this API to start an ability that belongs to another user, it must have the **ohos.permission.ABILITY_BACKGROUND_COMMUNICATION** and **ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS** permissions. 2144 - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. 2145 - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. 2146 - The rules for using this API in the same-device and cross-device scenarios are different. For details, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2147 2148**Required permissions**: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION and ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 2149 2150**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2151 2152**System API**: This is a system API and cannot be called by third-party applications. 2153 2154**Parameters** 2155 2156| Name| Type| Mandatory| Description| 2157| -------- | -------- | -------- | -------- | 2158| want | [Want](js-apis-app-ability-want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| 2159| accountId | number | Yes| ID of a system account. The value **-1** indicates the current user. For details, see [getCreatedOsAccountsCount](../apis-basic-services-kit/js-apis-osAccount.md#getcreatedosaccountscountdeprecated-1).| 2160 2161**Return value** 2162 2163| Type| Description| 2164| -------- | -------- | 2165| Promise<Caller> | Promise used to return the caller object to communicate with.| 2166 2167**Error codes** 2168 2169For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 2170 2171| ID| Error Message| 2172| ------- | -------- | 2173| 201 | The application does not have permission to call the interface. | 2174| 202 | The application is not system-app, can not use system-api. | 2175| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2176| 16000001 | The specified ability does not exist. | 2177| 16000002 | Incorrect ability type. | 2178| 16000004 | Can not start invisible component. | 2179| 16000005 | Static permission denied. The specified process does not have the permission. | 2180| 16000006 | Cross-user operations are not allowed. | 2181| 16000008 | The crowdtesting application expires. | 2182| 16000011 | The context does not exist. | 2183| 16000012 | The application is controlled. | 2184| 16000013 | The application is controlled by EDM. | 2185| 16000050 | Internal error. | 2186| 16200001 | The caller has been released. | 2187 2188**Example** 2189 2190```ts 2191import { ServiceExtensionAbility, Want, Caller } from '@kit.AbilityKit'; 2192import { BusinessError } from '@kit.BasicServicesKit'; 2193 2194class EntryAbility extends ServiceExtensionAbility { 2195 onCreate() { 2196 let caller: Caller; 2197 // ID of a system account. The value -1 indicates the current user. 2198 let accountId = -1; 2199 // Specify the ability to start. 2200 let want: Want = { 2201 bundleName: 'com.acts.actscalleeabilityrely', 2202 moduleName: 'entry', 2203 abilityName: 'EntryAbility', 2204 deviceId: '', 2205 parameters: { 2206 // If the value of 'ohos.aafwk.param.callAbilityToForeground' is true, the ability is started in the foreground. If the value is false or not set, the ability is started in the background. 2207 'ohos.aafwk.param.callAbilityToForeground': true 2208 } 2209 }; 2210 2211 try { 2212 this.context.startAbilityByCallWithAccount(want, accountId) 2213 .then((obj: Caller) => { 2214 // Carry out normal service processing. 2215 caller = obj; 2216 console.log('startAbilityByCallWithAccount succeed'); 2217 }).catch((error: BusinessError) => { 2218 // Process service logic errors. 2219 console.error(`startAbilityByCallWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`); 2220 }); 2221 } catch (paramError) { 2222 // Process input parameter errors. 2223 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 2224 } 2225 } 2226} 2227``` 2228 2229## ServiceExtensionContext.requestModalUIExtension<sup>11+<sup> 2230 2231requestModalUIExtension(pickerWant: Want): Promise\<void> 2232 2233Requests the specified foreground application to start the UIExtensionAbility of the corresponding type. The foreground application is specified by **bundleName** in **want.parameters**. If **bundleName** is left unspecified, or if the application specified by **bundleName** is not running in the foreground or does not exist, the UIExtensionAbility is directly started on the system UI. The UIExtensionAbility to start is determined by the combination of the **bundleName**, **abilityName**, and **moduleName** fields in **want**, and its type is determined by the **ability.want.params.uiExtensionType** field in **want.parameters**. This API uses a promise to return the result. 2234 2235Before starting the UIExtensionAbility, ensure that the foreground application has finished page initialization. Otherwise, the UIExtensionAbility fails to start and the error message "uiContent is nullptr" is displayed. The application can determine the time to start the UIExtensionAbility by listening for the page loading status. After the page initialization is successful, the key log information "UIContentImpl: focus again" is recorded. 2236 2237> **NOTE** 2238> 2239> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2240 2241**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2242 2243**System API**: This is a system API. 2244 2245**Parameters** 2246 2247| Name| Type| Mandatory| Description| 2248| -------- | -------- | -------- | -------- | 2249| pickerWant | [Want](js-apis-app-ability-want.md) | Yes| Want information used to start the UIExtensionAbility.| 2250 2251**Return value** 2252 2253| Type| Description| 2254| -------- | -------- | 2255| Promise<void> | Promise that returns no value.| 2256 2257**Error codes** 2258 2259For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 2260 2261| ID| Error Message| 2262| ------- | -------- | 2263| 202 | The application is not system-app, can not use system-api. | 2264| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2265| 16000050 | Internal error. | 2266 2267**Example** 2268 2269```ts 2270import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 2271import { BusinessError } from '@kit.BasicServicesKit'; 2272 2273class ServiceExtension extends ServiceExtensionAbility { 2274 onCreate() { 2275 let pickerWant: Want = { 2276 bundleName: 'com.example.myapplication', 2277 abilityName: 'UIExtAbility', 2278 moduleName: 'entry_test', 2279 parameters: { 2280 'bundleName': 'com.example.myapplication', 2281 // The value is the same as the value of type configured for com.example.myapplication.UIExtAbility. 2282 'ability.want.params.uiExtensionType': 'sys/commonUI' 2283 } 2284 }; 2285 2286 try { 2287 this.context.requestModalUIExtension(pickerWant) 2288 .then(() => { 2289 // Carry out normal service processing. 2290 console.info('requestModalUIExtension succeed'); 2291 }) 2292 .catch((err: BusinessError) => { 2293 // Process service logic errors. 2294 console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`); 2295 }); 2296 } catch (err) { 2297 // Process input parameter errors. 2298 let code = (err as BusinessError).code; 2299 let message = (err as BusinessError).message; 2300 console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`); 2301 } 2302 } 2303} 2304``` 2305 2306## ServiceExtensionContext.requestModalUIExtension<sup>11+<sup> 2307 2308requestModalUIExtension(pickerWant: Want, callback: AsyncCallback\<void>): void 2309 2310Requests the specified foreground application to start the UIExtensionAbility of the corresponding type. The foreground application is specified by **bundleName** in **want.parameters**. If **bundleName** is left unspecified, or if the application specified by **bundleName** is not running in the foreground or does not exist, the UIExtensionAbility is directly started on the system UI. The UIExtensionAbility to start is determined by the combination of the **bundleName**, **abilityName**, and **moduleName** fields in **want**, and its type is determined by the **ability.want.params.uiExtensionType** field in **want.parameters**. This API uses an asynchronous callback to return the result. 2311 2312Before starting the UIExtensionAbility, ensure that the foreground application has finished page initialization. Otherwise, the UIExtensionAbility fails to start and the error message "uiContent is nullptr" is displayed. The application can determine the time to start the UIExtensionAbility by listening for the page loading status. After the page initialization is successful, the key log information "UIContentImpl: focus again" is recorded. 2313 2314> **NOTE** 2315> 2316> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2317 2318**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2319 2320**System API**: This is a system API. 2321 2322**Parameters** 2323 2324| Name| Type| Mandatory| Description| 2325| -------- | -------- | -------- | -------- | 2326| pickerWant | [Want](js-apis-app-ability-want.md) | Yes| Want information used to start the UIExtensionAbility.| 2327| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the UIExtensionAbility is started, **err** is **undefined**; otherwise, **err** is an error object.| 2328 2329**Error codes** 2330 2331For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 2332 2333| ID| Error Message| 2334| ------- | -------- | 2335| 202 | The application is not system-app, can not use system-api. | 2336| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2337| 16000050 | Internal error. | 2338 2339**Example** 2340 2341```ts 2342import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 2343import { BusinessError } from '@kit.BasicServicesKit'; 2344 2345class ServiceExtension extends ServiceExtensionAbility { 2346 onCreate() { 2347 let pickerWant: Want = { 2348 bundleName: 'com.example.myapplication', 2349 abilityName: 'com.example.myapplication.UIExtAbility', 2350 moduleName: 'entry_test', 2351 parameters: { 2352 'bundleName': 'com.example.myapplication', 2353 // The value is the same as the value of type configured for com.example.myapplication.UIExtAbility. 2354 'ability.want.params.uiExtensionType': 'sys/commonUI' 2355 } 2356 }; 2357 2358 try { 2359 this.context.requestModalUIExtension(pickerWant, (err: BusinessError) => { 2360 if (err.code) { 2361 // Process service logic errors. 2362 console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`); 2363 return; 2364 } 2365 // Carry out normal service processing. 2366 console.info('requestModalUIExtension succeed'); 2367 }); 2368 } catch (err) { 2369 // Process input parameter errors. 2370 let code = (err as BusinessError).code; 2371 let message = (err as BusinessError).message; 2372 console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`); 2373 } 2374 } 2375} 2376``` 2377 2378## ServiceExtensionContext.openLink<sup>12+<sup> 2379openLink(link:string, options?: OpenLinkOptions): Promise<void> 2380 2381Starts a UIAbility through App Linking. This API uses a promise to return the result. 2382 2383A URL in the standard format is passed in to the **link** field to start the target UIAbility based on the implicit Want matching rules. The target UIAbility must have the following filter characteristics to process links of App Linking: 2384- The **actions** field contains **ohos.want.action.viewData**. 2385- The **entities** field contains **entity.system.browsable**. 2386- The **uris** field contains elements whose **scheme** is **https** and **domainVerify** is **true**. 2387 2388If an input parameter is invalid, for example, a mandatory parameter is not set or the URL set in **link** is not in the standard format, an exception is thrown. If the parameter verification is successful but an error occurs when starting the target UIAbility, the error information is returned through promise. 2389 2390> **NOTE** 2391> 2392> For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). 2393 2394**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2395 2396**System API**: This is a system API. 2397 2398**Parameters** 2399 2400| Name| Type| Mandatory| Description| 2401| -------- | -------- | -------- | -------- | 2402| link | string | Yes| URL to open, which must be in the standard format.| 2403| options | [OpenLinkOptions](js-apis-app-ability-openLinkOptions.md) | No| Options of the URL.| 2404 2405**Return value** 2406 2407| Type| Description| 2408| -------- | -------- | 2409| Promise<void> | Promise that returns no value.| 2410 2411**Error codes** 2412 2413For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 2414 2415| ID| Error Message| 2416| ------- | -------- | 2417| 201 | The application does not have permission to call the interface. | 2418| 202 | The application is not system-app, can not use system-api. | 2419| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2420| 16000001 | The specified ability does not exist. | 2421| 16000002 | Incorrect ability type. | 2422| 16000004 | Can not start invisible component. | 2423| 16000005 | The specified process does not have the permission. | 2424| 16000006 | Cross-user operations are not allowed. | 2425| 16000008 | The crowdtesting application expires. | 2426| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2427| 16000010 | The call with the continuation flag is forbidden. | 2428| 16000011 | The context does not exist. | 2429| 16000012 | The application is controlled. | 2430| 16000013 | The application is controlled by EDM. | 2431| 16000019 | Can not match any component. | 2432| 16200001 | The caller has been released. | 2433 2434**Example** 2435 2436```ts 2437import { ServiceExtensionAbility, Want, OpenLinkOptions } from '@kit.AbilityKit'; 2438import { BusinessError } from '@kit.BasicServicesKit'; 2439 2440function log(info: string) { 2441 console.error(`[ServiceExtApp]:: ${JSON.stringify(info)}`); 2442} 2443 2444export default class ServiceExtAbility extends ServiceExtensionAbility { 2445 onCreate(want: Want) { 2446 log(`ServiceExtAbility OnCreate`); 2447 } 2448 2449 onRequest(want: Want, startId: number) { 2450 log(`ServiceExtAbility onRequest`); 2451 let link: string = 'https://www.example.com'; 2452 let openLinkOptions: OpenLinkOptions = { 2453 appLinkingOnly: false 2454 }; 2455 try { 2456 this.context.openLink( 2457 link, 2458 openLinkOptions 2459 ).then(() => { 2460 log(`open link success.`); 2461 }).catch((err: BusinessError) => { 2462 log(`open link failed, errCode ${JSON.stringify(err.code)}`); 2463 }); 2464 } 2465 catch (e) { 2466 log(`exception occured, errCode ${JSON.stringify(e.code)}`); 2467 } 2468 } 2469 2470 onDestroy() { 2471 log(`ServiceExtAbility onDestroy`); 2472 } 2473} 2474``` 2475 2476## ServiceExtensionContext.preStartMission<sup>12+<sup> 2477preStartMission(bundleName:string, moduleName: string, abilitName: string, startTime: string): Promise<void> 2478 2479Starts an atomic service and pre-opens the window, with the loading box skipped. This API uses a promise to return the result. 2480 2481If parameter verification is successful but the atomic service fails to start, you need to implement an exception mechanism to capture the error. 2482 2483**Required permissions**: ohos.permission.PRE_START_ATOMIC_SERVICE 2484 2485**System capability**: SystemCapability.Ability.AbilityRuntime.Core 2486 2487**System API**: This is a system API. 2488 2489**Parameters** 2490 2491| Name| Type| Mandatory| Description| 2492| -------- | -------- | -------- | -------- | 2493| bundleName | string | Yes| Bundle name of the atomic service.| 2494| moduleName | string | Yes| Module name of the atomic service.| 2495| abilityName | string | Yes| Ability name of the atomic service.| 2496| startTime | string | Yes| Start time to open the atomic service, in milliseconds.| 2497 2498 2499**Return value** 2500 2501| Type| Description| 2502| -------- | -------- | 2503| Promise<void> | Promise that returns no value.| 2504 2505**Error codes** 2506 2507For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 2508 2509| ID| Error Message| 2510| ------- | -------- | 2511| 201 | The application does not have permission to call the interface. | 2512| 202 | The application is not system-app, can not use system-api. | 2513| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2514| 16300007 | The target free install task does not exist. | 2515| 16000011 | The context does not exist. | 2516 2517**Example** 2518 2519```ts 2520import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 2521import { BusinessError } from '@kit.BasicServicesKit'; 2522 2523function log(info: string) { 2524 console.error(`[ServiceExtApp]:: ${JSON.stringify(info)}`); 2525} 2526 2527export default class ServiceExtAbility extends ServiceExtensionAbility { 2528 onCreate(want: Want) { 2529 log(`ServiceExtAbility OnCreate`); 2530 } 2531 2532 onRequest(want: Want, startId: number) { 2533 log(`ServiceExtAbility onRequest`); 2534 try { 2535 this.context.preStartMission( 2536 want.bundleName, 2537 want.moduleName, 2538 want.abilityName, 2539 want.parameters["ohos.aafwk.param.startTime"] 2540 ).then(() => { 2541 log(`pre-start mission success.`); 2542 }).catch((err: BusinessError) => { 2543 log(`pre-start mission failed, errCode ${JSON.stringify(err.code)}`); 2544 }); 2545 } 2546 catch (e) { 2547 log(`exception occured, errCode ${JSON.stringify(e.code)}`); 2548 } 2549 } 2550 2551 onDestroy() { 2552 log(`ServiceExtAbility onDestroy`); 2553 } 2554} 2555``` 2556