# UIExtensionContext **UIExtensionContext**, inherited from [ExtensionContext](js-apis-inner-application-extensionContext.md), provides the context environment for [UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md). It provides UIExtensionAbility-related configuration and APIs for operating the UIExtensionAbility. For example, you can use the APIs to start a UIExtensionAbility. > **NOTE** > > - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. > - The APIs of this module can be used only in the stage model. ## Modules to Import ```ts import common from '@ohos.app.ability.common'; ``` ## UIExtensionContext.startAbility startAbility(want: Want, callback: AsyncCallback<void>): void Starts an ability. This API uses an asynchronous callback to return the result. Observe the following when using this API: - 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. - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - 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). **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | | 16000001 | The specified ability does not exist. | | 16000002 | Incorrect ability type. | | 16000004 | Can not start invisible component. | | 16000005 | The specified process does not have the permission. | | 16000006 | Cross-user operations are not allowed. | | 16000008 | The crowdtesting application expires. | | 16000009 | An ability cannot be started or stopped in Wukong mode. | | 16000010 | The call with the continuation flag is forbidden. | | 16000011 | The context does not exist. | | 16000012 | The application is controlled. | | 16000013 | The application is controlled by EDM. | | 16000050 | Internal error. | | 16000053 | The ability is not on the top of the UI. | | 16000055 | Installation-free timed out. | | 16200001 | The caller has been released. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). ## UIExtensionContext.startAbility startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void Starts an ability with the start options specified. This API uses an asynchronous callback to return the result. Observe the following when using this API: - 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. - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - 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). **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| | options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | | 16000001 | The specified ability does not exist. | | 16000004 | Can not start invisible component. | | 16000005 | The specified process does not have the permission. | | 16000006 | Cross-user operations are not allowed. | | 16000008 | The crowdtesting application expires. | | 16000009 | An ability cannot be started or stopped in Wukong mode. | | 16000011 | The context does not exist. | | 16000012 | The application is controlled. | | 16000013 | The application is controlled by EDM. | | 16000050 | Internal error. | | 16000053 | The ability is not on the top of the UI. | | 16000055 | Installation-free timed out. | | 16200001 | The caller has been released. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). ## UIExtensionContext.startAbility startAbility(want: Want, options?: StartOptions): Promise<void> Starts an ability. This API uses a promise to return the result. Observe the following when using this API: - 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. - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - 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). **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| | options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| **Return value** | Type| Description| | -------- | -------- | | Promise<void> | Promise used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | | 16000001 | The specified ability does not exist. | | 16000002 | Incorrect ability type. | | 16000004 | Can not start invisible component. | | 16000005 | The specified process does not have the permission. | | 16000006 | Cross-user operations are not allowed. | | 16000008 | The crowdtesting application expires. | | 16000009 | An ability cannot be started or stopped in Wukong mode. | | 16000010 | The call with the continuation flag is forbidden. | | 16000011 | The context does not exist. | | 16000012 | The application is controlled. | | 16000013 | The application is controlled by EDM. | | 16000050 | Internal error. | | 16000053 | The ability is not on the top of the UI. | | 16000055 | Installation-free timed out. | | 16200001 | The caller has been released. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). ## UIExtensionContext.startAbilityForResult startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability: - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an exception message, in which **resultCode** is **-1**, is returned to others. Observe the following when using this API: - 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. - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - 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). **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | want |[Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| | callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | | 16000001 | The specified ability does not exist. | | 16000002 | Incorrect ability type. | | 16000004 | Can not start invisible component. | | 16000005 | The specified process does not have the permission. | | 16000006 | Cross-user operations are not allowed. | | 16000008 | The crowdtesting application expires. | | 16000009 | An ability cannot be started or stopped in Wukong mode. | | 16000010 | The call with the continuation flag is forbidden. | | 16000011 | The context does not exist. | | 16000012 | The application is controlled. | | 16000013 | The application is controlled by EDM. | | 16000050 | Internal error. | | 16000053 | The ability is not on the top of the UI. | | 16000055 | Installation-free timed out. | | 16200001 | The caller has been released. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). ## UIExtensionContext.startAbilityForResult startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void Starts an ability with the start options specified. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability: - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an exception message, in which **resultCode** is **-1**, is returned to others. Observe the following when using this API: - 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. - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - 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). **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | want |[Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| | options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | | 16000001 | The specified ability does not exist. | | 16000004 | Can not start invisible component. | | 16000005 | The specified process does not have the permission. | | 16000006 | Cross-user operations are not allowed. | | 16000008 | The crowdtesting application expires. | | 16000009 | An ability cannot be started or stopped in Wukong mode. | | 16000011 | The context does not exist. | | 16000012 | The application is controlled. | | 16000013 | The application is controlled by EDM. | | 16000050 | Internal error. | | 16000053 | The ability is not on the top of the UI. | | 16000055 | Installation-free timed out. | | 16200001 | The caller has been released. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). ## UIExtensionContext.startAbilityForResult startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult> Starts an ability. This API uses a promise to return the result when the ability is terminated. The following situations may be possible for a started ability: - Normally, you can call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an exception message, in which **resultCode** is **-1**, is returned to others. Observe the following when using this API: - 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. - If **exported** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - 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). **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target ability.| | options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| **Return value** | Type| Description| | -------- | -------- | | Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | | 16000001 | The specified ability does not exist. | | 16000002 | Incorrect ability type. | | 16000004 | Can not start invisible component. | | 16000005 | The specified process does not have the permission. | | 16000006 | Cross-user operations are not allowed. | | 16000008 | The crowdtesting application expires. | | 16000009 | An ability cannot be started or stopped in Wukong mode. | | 16000010 | The call with the continuation flag is forbidden. | | 16000011 | The context does not exist. | | 16000012 | The application is controlled. | | 16000013 | The application is controlled by EDM. | | 16000050 | Internal error. | | 16000053 | The ability is not on the top of the UI. | | 16000055 | Installation-free timed out. | | 16200001 | The caller has been released. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). ## UIExtensionContext.connectServiceExtensionAbility connectServiceExtensionAbility(want: Want, options: ConnectOptions): number Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERVICE** template. **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | want | [Want](js-apis-app-ability-want.md) | Yes| Want information for connecting to the ServiceExtensionAbility.| | options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Instance of the callback function after the connection to the ServiceExtensionAbility is set up.| **Return value** | Type| Description| | -------- | -------- | | number | Result code of the ability connection.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | | 16000001 | The specified ability does not exist. | | 16000002 | Incorrect ability type. | | 16000004 | Can not start invisible component. | | 16000005 | The specified process does not have the permission. | | 16000006 | Cross-user operations are not allowed. | | 16000008 | The crowdtesting application expires. | | 16000053 | The ability is not on the top of the UI. | | 16000055 | Installation-free timed out. | | 16000011 | The context does not exist. | | 16000050 | Internal error. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). ## UIExtensionContext.disconnectServiceExtensionAbility disconnectServiceExtensionAbility(connection: number): Promise\ Disconnects 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. **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | connection | number | Yes| Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by **connectServiceExtensionAbility**.| **Return value** | Type| Description| | -------- | -------- | | Promise\ | Promise used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | | 16000011 | The context does not exist. | | 16000050 | Internal error. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). ## UIExtensionContext.disconnectServiceExtensionAbility disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback\): void Disconnects 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. **System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | connection | number | Yes| Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by **connectServiceExtensionAbility**.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | | 16000011 | The context does not exist. | | 16000050 | Internal error. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).