1# UIServiceExtensionContext (System API) 2 3The UIServiceExtensionContext module provides the context environment for a [UIServiceExtensionAbility](js-apis-app-ability-uiServiceExtensionAbility-sys.md). It inherits from [ExtensionContext](js-apis-inner-application-extensionContext.md). 4 5UIServiceExtensionContext provides access to a [UIServiceExtensionAbility](js-apis-app-ability-uiServiceExtensionAbility-sys.md) and APIs for operating the ability, for example, starting, terminating, connecting, and disconnecting ability. 6 7> **NOTE** 8> 9> - The initial APIs of this module are supported since API version 14. 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 child 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## How to Use 21 22Before using the APIs of UIServiceExtensionContext, you must obtain the context through a child class instance [UIServiceExtensionAbility](js-apis-app-ability-uiServiceExtensionAbility-sys.md). 23 24**Example** 25 26```ts 27import { common, UIServiceExtensionAbility } from '@kit.AbilityKit'; 28 29class UIServiceExtAbility extends UIServiceExtensionAbility { 30 onCreate() { 31 let context:common.UIServiceExtensionContext = this.context; // Obtain the UIServiceExtensionContext. 32 } 33} 34``` 35 36 37## UIServiceExtensionContext.startAbility 38 39startAbility(want: Want, options?: StartOptions): Promise<void> 40 41Starts an ability. This API uses a promise to return the result. 42 43> **NOTE** 44> 45> 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). 46 47**System capability**: SystemCapability.Ability.AbilityRuntime.Core 48 49**System API**: This is a system API. 50 51**Parameters** 52 53| Name| Type| Read Only| Optional| Description| 54| -------- | -------- | -------- | -------- | -------- | 55| want | [Want](js-apis-app-ability-want.md) | Yes| No| Want information about the target ability, such as the ability name and bundle name.| 56| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes|Yes| Parameters used for starting the ability.| 57 58**Return value** 59 60| Type| Description| 61| -------- | -------- | 62| Promise<void> | Promise that returns no value.| 63 64**Error codes** 65 66For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 67 68| ID| Error Message| 69| ------- | -------- | 70| 201 | The application does not have permission to call the interface. | 71| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 72| 16000001 | The specified ability does not exist. | 73| 16000002 | Incorrect ability type. | 74| 16000004 | Cannot start an invisible component. | 75| 16000005 | The specified process does not have the permission. | 76| 16000006 | Cross-user operations are not allowed. | 77| 16000008 | The crowdtesting application expires. | 78| 16000009 | An ability cannot be started or stopped in Wukong mode. | 79| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 80| 16000011 | The context does not exist. | 81| 16000012 | The application is controlled. | 82| 16000013 | The application is controlled by EDM. | 83| 16000019 | Can not match any component. | 84| 16000050 | Internal error. | 85| 16000053 | The ability is not on the top of the UI. | 86| 16000055 | Installation-free timed out. | 87| 16200001 | The caller has been released. | 88 89**Example** 90 91```ts 92import { UIServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 93import { BusinessError } from '@kit.BasicServicesKit'; 94 95class UIEntryAbility extends UIServiceExtensionAbility { 96 onCreate() { 97 let want: Want = { 98 bundleName: 'com.example.myapp', 99 abilityName: 'MyAbility' 100 }; 101 let options: StartOptions = { 102 windowMode: 0, 103 }; 104 105 try { 106 this.context.startAbility(want, options) 107 .then((data: void) => { 108 // Carry out normal service processing. 109 console.log('startAbility succeed'); 110 }) 111 .catch((error: BusinessError) => { 112 // Process service logic errors. 113 console.error(`startAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 114 }); 115 } catch (paramError) { 116 // Process input parameter errors. 117 console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`); 118 } 119 } 120} 121``` 122 123 124## UIServiceExtensionContext.terminateSelf 125 126terminateSelf(): Promise<void> 127 128Terminates this [UIServiceExtensionAbility](js-apis-app-ability-uiServiceExtensionAbility-sys.md). 129 130**System capability**: SystemCapability.Ability.AbilityRuntime.Core 131 132**System API**: This is a system API. 133 134**Return value** 135 136| Type| Description| 137| -------- | -------- | 138| Promise<void> | Promise that returns no value.| 139 140**Error codes** 141 142N/A 143 144**Example** 145 146```ts 147import { UIServiceExtensionAbility } from '@kit.AbilityKit'; 148import { BusinessError } from '@kit.BasicServicesKit'; 149 150class UIEntryAbility extends UIServiceExtensionAbility { 151 onCreate() { 152 this.context.terminateSelf().then(() => { 153 // Carry out normal service processing. 154 console.log('terminateSelf succeed'); 155 }).catch((error: BusinessError) => { 156 // Process service logic errors. 157 console.error(`terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}`); 158 }); 159 } 160} 161``` 162 163## UIServiceExtensionContext.startAbilityByType 164 165startAbilityByType(type: string, wantParam: Record<string, Object>, 166 abilityStartCallback: AbilityStartCallback): Promise<void> 167 168Starts a [UIAbility](js-apis-app-ability-uiAbility.md) or [UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md) based on the type of the target ability. This API can be called only by applications running in the foreground. 169 170 171> **NOTE** 172> 173> 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). 174 175**System capability**: SystemCapability.Ability.AbilityRuntime.Core 176 177**System API**: This is a system API. 178 179**Parameters** 180 181| Name| Type| Read Only| Optional| Description| 182| -------- | -------- | -------- | -------- | -------- | 183| type | string | Yes| No| Type of the target ability.| 184| wantParam | Record<string, Object>| Yes| No| Want parameter.| 185| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md)| Yes| No| Callback.| 186 187**Return value** 188 189| Type| Description| 190| -------- | -------- | 191| Promise<void> | Promise that returns no value.| 192 193**Error codes** 194 195For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 196 197| ID| Error Message| 198| ------- | -------- | 199| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 200| 16000050 | Internal error. | 201 202**Example** 203 204```ts 205import { common } from '@kit.AbilityKit'; 206import { BusinessError } from '@kit.BasicServicesKit'; 207 208const TAG: string = '[Extension_Sub] '; 209 210@Entry 211@Component 212struct SubIndex { 213 build() { 214 Row() { 215 Column() { 216 Button("startAbilityByType") 217 .fontSize(10) 218 .fontWeight(FontWeight.Bold) 219 .onClick(() => { 220 let context = this.getUIContext().getHostContext() as common.UIServiceExtensionContext; 221 let startWant: Record<string, Object> = { 222 'sceneType': 1, 223 'email': [encodeURI('xxx@example.com'), 224 encodeURI('xxx@example.com')], // Email address of the recipient. Multiple values are separated by commas (,). The array content is URL encoded using encodeURI(). 225 'cc': [encodeURI('xxx@example.com'), 226 encodeURI('xxx@example.com')], // Email address of the CC recipient. Multiple values are separated by commas (,). The array content is URL encoded using encodeURI(). 227 'bcc': [encodeURI('xxx@example.com'), 228 encodeURI('xxx@example.com')], // Email address of the BCC recipient. Multiple values are separated by commas (,). The array content is URL encoded using encodeURI(). 229 'subject': encodeURI('Email subject'), // Email subject. The content is URL encoded using encodeURI(). 230 'body': encodeURI('Email body'), // Email body. The content is URL encoded using encodeURI(). 231 'ability.params.stream': [encodeURI('Attachment URI 1'), 232 encodeURI('Attachment URI 2')], // Attachment URIs. Multiple values are separated by commas (,). The array content is URL encoded using encodeURI(). 233 'ability.want.params.uriPermissionFlag': 1 234 }; 235 let abilityStartCallback: common.AbilityStartCallback = { 236 onError: (code: number, name: string, message: string) => { 237 console.error(TAG + `code: ${code} name:${name} message:${message}`); 238 } 239 }; 240 try { 241 // Start a UIAbility or UIExtensionAbility based on the type of the target ability. 242 context.startAbilityByType("mail", startWant, abilityStartCallback) 243 .then(() => { 244 console.log(TAG + `Succeeded in windows starting ability`); 245 }).catch((err: BusinessError) => { 246 console.error(TAG + 247 `Failed to windows starting ability, Code is ${err.code}, message is ${err.message}.`); 248 }) 249 } catch (err) { 250 let code = (err as BusinessError).code; 251 let msg = (err as BusinessError).message; 252 console.error(TAG + `Failed to windows starting ability, Code is ${code}, message is ${msg}.`); 253 } 254 }) 255 } 256 .width('100%') 257 } 258 .height('100%') 259 } 260} 261``` 262 263## UIServiceExtensionContext.connectServiceExtensionAbility 264 265connectServiceExtensionAbility(want: Want, options: ConnectOptions): number 266 267Connects to a [UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md) and returns the connection ID. 268 269 270> **NOTE** 271> 272> 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). 273 274**System capability**: SystemCapability.Ability.AbilityRuntime.Core 275 276**System API**: This is a system API. 277 278**Parameters** 279 280| Name | Type | Read Only| Optional| Description | 281| -------------------- | ------------------------ | ---- | ---- |----------------- | 282| want | [Want](js-apis-app-ability-want.md) | Yes | No| Want parameter. | 283| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes|Yes | Connection options.| 284 285**Return value** 286 287| Type| Description| 288| -------- | -------- | 289| number | Connection ID.| 290 291**Error codes** 292 293For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 294 295| ID| Error Message | 296| -------- | --- | 297| 201 | Not system application. | 298| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 299| 16000001 | The specified ability does not exist. | 300| 16000002 | Incorrect ability type. | 301| 16000004 | Cannot start an invisible component. | 302| 16000005 | The specified process does not have the permission. | 303| 16000006 | Cross-user operations are not allowed. | 304| 16000008 | The crowdtesting application expires. | 305| 16000011 | The context does not exist. | 306| 16000050 | Internal error. | 307| 16000053 | The ability is not on the top of the UI. | 308| 16000055 | Installation-free timed out. | 309 310 311**Example** 312 313```ts 314import { common, Want } from '@kit.AbilityKit'; 315import { rpc } from '@kit.IPCKit'; 316import { hilog } from '@kit.PerformanceAnalysisKit'; 317// The client needs to import idl_service_ext_proxy.ts provided by the server to the local project. 318import IdlServiceExtProxy from '../IdlServiceExt/idl_service_ext_proxy'; 319 320const TAG: string = '[Page_ServiceExtensionAbility]'; 321const DOMAIN_NUMBER: number = 0xFF00; 322 323let connectionId: number; 324let want: Want = { 325 deviceId: '', 326 bundleName: 'com.samples.stagemodelabilitydevelop', 327 abilityName: 'ServiceExtAbility' 328}; 329 330let options: common.ConnectOptions = { 331 onConnect(elementName, remote: rpc.IRemoteObject): void { 332 hilog.info(DOMAIN_NUMBER, TAG, 'onConnect callback'); 333 if (remote === null) { 334 hilog.info(DOMAIN_NUMBER, TAG, `onConnect remote is null`); 335 return; 336 } 337 let serviceExtProxy: IdlServiceExtProxy = new IdlServiceExtProxy(remote); 338 // Communication is carried out by API calling, without exposing RPC details. 339 serviceExtProxy.processData(1, (errorCode: number, retVal: number) => { 340 hilog.info(DOMAIN_NUMBER, TAG, `processData, errorCode: ${errorCode}, retVal: ${retVal}`); 341 }); 342 serviceExtProxy.insertDataToMap('theKey', 1, (errorCode: number) => { 343 hilog.info(DOMAIN_NUMBER, TAG, `insertDataToMap, errorCode: ${errorCode}`); 344 }) 345 }, 346 onDisconnect(elementName): void { 347 hilog.info(DOMAIN_NUMBER, TAG, 'onDisconnect callback'); 348 }, 349 onFailed(code: number): void { 350 hilog.info(DOMAIN_NUMBER, TAG, 'onFailed callback', JSON.stringify(code)); 351 } 352}; 353@Entry 354@Component 355struct Page_UIServiceExtensionAbility { 356 build() { 357 Column() { 358 //... 359 List({ initialIndex: 0 }) { 360 ListItem() { 361 Row() { 362 //... 363 } 364 .onClick(() => { 365 let context: common.UIServiceExtensionContext = this.getUIContext().getHostContext() as common.UIServiceExtensionContext; 366 // The ID returned after the connection is set up must be saved. The ID will be used for disconnection. 367 connectionId = context.connectServiceExtensionAbility(want, options); 368 // The background service is connected. 369 this.getUIContext().getPromptAction().showToast({ 370 message: $r('app.string.SuccessfullyConnectBackendService') 371 }); 372 // connectionId = context.connectAbility(want, options); 373 hilog.info(DOMAIN_NUMBER, TAG, `connectionId is : ${connectionId}`); 374 }) 375 } 376 //... 377 } 378 //... 379 } 380 //... 381 } 382} 383``` 384 385## UIServiceExtensionContext.disconnectServiceExtensionAbility 386 387disconnectServiceExtensionAbility(connectionId: number): Promise<void> 388 389Disconnects from a [UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md). This API is opposite to [connectServiceExtensionAbility](#uiserviceextensioncontextconnectserviceextensionability). 390 391 392**System capability**: SystemCapability.Ability.AbilityRuntime.Core 393 394**System API**: This is a system API. 395 396**Parameters** 397 398| Name | Type | Read Only| Optional| Description | 399| -------------------- | ------------------------ | ---- | ----------------- | ----------------- | 400| connectionId | number | Yes | No| Connection ID returned by [connectServiceExtensionAbility](#uiserviceextensioncontextconnectserviceextensionability).| 401 402 403**Return value** 404 405| Type | Description | 406| ------------------- | ---------------------------------| 407| Promise<void> | Promise that returns no value.| 408 409**Error codes** 410 411For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md). 412 413| ID| Error Message| 414| -------- | --------------------- | 415| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 416| 16000011 | The context does not exist. | 417| 16000050 | Internal error. | 418 419**Example** 420 421```ts 422import { common } from '@kit.AbilityKit'; 423import { hilog } from '@kit.PerformanceAnalysisKit'; 424import { BusinessError } from '@kit.BasicServicesKit'; 425 426const TAG: string = '[Page_ServiceExtensionAbility]'; 427const DOMAIN_NUMBER: number = 0xFF00; 428 429let connectionId: number; 430@Entry 431@Component 432struct Page_UIServiceExtensionAbility { 433 build() { 434 Column() { 435 //... 436 List({ initialIndex: 0 }) { 437 ListItem() { 438 Row() { 439 //... 440 } 441 .onClick(() => { 442 let context: common.UIServiceExtensionContext = this.getUIContext().getHostContext() as common.UIServiceExtensionContext; 443 // connectionId is returned when connectServiceExtensionAbility is called and needs to be manually maintained. 444 context.disconnectServiceExtensionAbility(connectionId).then(() => { 445 hilog.info(DOMAIN_NUMBER, TAG, 'disconnectServiceExtensionAbility success'); 446 // The background service is disconnected. 447 this.getUIContext().getPromptAction().showToast({ 448 message: $r('app.string.SuccessfullyDisconnectBackendService') 449 }); 450 }).catch((error: BusinessError) => { 451 hilog.error(DOMAIN_NUMBER, TAG, 'disconnectServiceExtensionAbility failed'); 452 }); 453 }) 454 } 455 //... 456 } 457 //... 458 } 459 //... 460 } 461} 462``` 463