1# @ohos.app.ability.AppServiceExtensionAbility (ExtensionAbility for Application Background Services) 2<!--Kit: Ability Kit--> 3<!--Subsystem: Ability--> 4<!--Owner: @yewei0794--> 5<!--Designer: @jsjzju--> 6<!--Tester: @lixueqing513--> 7<!--Adviser: @huipeizi--> 8 9The AppServiceExtensionAbility module provides extended capabilities for background services, including lifecycle callbacks for creating, destroying, connecting, and disconnecting background services. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14> 15> The APIs of this module can be used only in the stage model. 16 17## Constraints 18 19- Currently, only 2-in-1 devices are supported. 20- To integrate an AppServiceExtensionAbility, applications must request the ACL permission (ohos.permission.SUPPORT_APP_SERVICE_EXTENSION). This ACL permission is available only for enterprise applications. 21 22## Lifecycle 23 24The AppServiceExtensionAbility provides the following lifecycle callbacks: [onCreate()](#oncreate), [onRequest()](#onrequest), [onConnect()](#onconnect), [onDisconnect()](#ondisconnect), and [onDestroy()](#ondestroy). You can override the callback methods as required. The following figure shows the AppServiceExtensionAbility lifecycle. 25 26 27 28- **onCreate** 29 Called when an AppServiceExtensionAbility instance is created. 30 31- **onDestroy** 32 Called when an AppServiceExtensionAbility instance is destroyed. 33 34- **onRequest** 35 Called when an AppServiceExtensionAbility instance is started by calling [startAppServiceExtensionAbility()](js-apis-inner-application-uiAbilityContext.md#startappserviceextensionability20). 36 37- **onConnect** 38 Called when an AppServiceExtensionAbility instance is connected by calling [connectAppServiceExtensionAbility](js-apis-inner-application-uiAbilityContext.md#connectappserviceextensionability20). 39 40- **onDisconnect** 41 Called when all connections to an AppServiceExtensionAbility instance are interrupted. 42 43## Modules to Import 44 45```ts 46import { AppServiceExtensionAbility } from '@kit.AbilityKit'; 47``` 48 49## AppServiceExtensionAbility 50 51AppServiceExtensionAbility provides extended capabilities for background services, including lifecycle callbacks for creating, destroying, connecting, and disconnecting background services. 52 53### Properties 54 55**System capability**: SystemCapability.Ability.AbilityRuntime.Core 56 57| Name| Type| Read-Only| Optional| Description| 58| -------- | -------- | -------- | -------- | -------- | 59| context | [AppServiceExtensionContext](js-apis-inner-application-appServiceExtensionContext.md) | No| No| Context environment for an AppServiceExtensionAbility. This context inherits from [ExtensionContext](js-apis-inner-application-extensionContext.md).| 60 61 62### onCreate 63 64onCreate(want: Want): void 65 66Called when an AppServiceExtensionAbility instance is created. Applications can perform initialization operations, such as registering common event listeners, in this callback. 67 68> **NOTE** 69> 70> If an AppServiceExtensionAbility instance has already been created, the **onCreate()** callback is not invoked again when the instance is started or connected. 71 72**System capability**: SystemCapability.Ability.AbilityRuntime.Core 73 74**Parameters** 75 76| Name| Type| Mandatory| Description| 77| -------- | -------- | -------- | -------- | 78| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target AppServiceExtensionAbility instance, including the ability name and bundle name.| 79 80**Example** 81 82 ```ts 83 import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit'; 84 import { hilog } from '@kit.PerformanceAnalysisKit'; 85 86 const TAG: string = '[AppServiceExtAbility]'; 87 88 class AppServiceExtAbility extends AppServiceExtensionAbility { 89 onCreate(want: Want) { 90 hilog.info(0x0000, TAG, `onCreate, want: ${want.abilityName}`); 91 } 92 } 93 ``` 94 95### onDestroy 96 97onDestroy(): void 98 99Called when an AppServiceExtensionAbility instance is destroyed. Applications can perform resource cleanup operations, such as unregistering listeners, in this callback. 100 101**System capability**: SystemCapability.Ability.AbilityRuntime.Core 102 103**Example** 104 105 ```ts 106 import { AppServiceExtensionAbility } from '@kit.AbilityKit'; 107 import { hilog } from '@kit.PerformanceAnalysisKit'; 108 109 const TAG: string = '[AppServiceExtAbility]'; 110 111 class AppServiceExtAbility extends AppServiceExtensionAbility { 112 onDestroy() { 113 hilog.info(0x0000, TAG, `onDestroy`); 114 } 115 } 116 ``` 117 118### onRequest 119 120onRequest(want: Want, startId: number): void 121 122Called when an AppServiceExtensionAbility instance is started by calling [startAppServiceExtensionAbility()](js-apis-inner-application-uiAbilityContext.md#startappserviceextensionability20). 123 124- If the instance has already been created, this callback is invoked directly. 125- If the instance has not been created before, the system first creates the instance and triggers the [onCreate()](#oncreate) callback, followed by this callback. 126 127**System capability**: SystemCapability.Ability.AbilityRuntime.Core 128 129**Parameters** 130 131| Name| Type| Mandatory| Description| 132| -------- | -------- | -------- | -------- | 133| want | [Want](js-apis-app-ability-want.md) | Yes| Want information about the target AppServiceExtensionAbility instance, including the ability name and bundle name.| 134| startId | number | Yes| Number of times the instance has been started. The initial value is **1** for the first start, and it increments automatically for subsequent starts.| 135 136**Example** 137 138 ```ts 139 import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit'; 140 import { hilog } from '@kit.PerformanceAnalysisKit'; 141 142 const TAG: string = '[AppServiceExtAbility]'; 143 144 class AppServiceExtAbility extends AppServiceExtensionAbility { 145 onRequest(want: Want, startId: number) { 146 hilog.info(0x0000, TAG, `onRequest, want: ${want.abilityName}, startId: ${startId}`); 147 } 148 } 149 ``` 150 151### onConnect 152 153onConnect(want: Want): rpc.RemoteObject 154 155Called when an AppServiceExtensionAbility instance is connected by calling [connectAppServiceExtensionAbility](js-apis-inner-application-uiAbilityContext.md#connectappserviceextensionability20). 156 157- If the instance has already been created, this callback is invoked directly. 158- If the instance has not been created before, the system first creates the instance and triggers the [onCreate()](#oncreate) callback, followed by this callback. 159 160Applications need to return a RemoteObject in this callback for communication between the client and the server. When an AppServiceExtensionAbility instance is in a connected state, if the caller initiates a new connection, the system returns the cached RemoteObject instead of calling **onConnect()** again. 161 162**System capability**: SystemCapability.Ability.AbilityRuntime.Core 163 164**Parameters** 165 166| Name| Type| Mandatory| Description| 167| -------- | -------- | -------- | -------- | 168| want | [Want](js-apis-app-ability-want.md)| Yes| Want information about the target AppServiceExtensionAbility instance, including the ability name and bundle name.| 169 170**Return value** 171 172| Type| Description| 173| -------- | -------- | 174| [rpc.RemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | A RemoteObject used for communication between the server and client.| 175 176**Example** 177 178 ```ts 179 import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit'; 180 import { rpc } from '@kit.IPCKit'; 181 import { hilog } from '@kit.PerformanceAnalysisKit'; 182 183 const TAG: string = '[AppServiceExtAbility]'; 184 185 class StubTest extends rpc.RemoteObject { 186 constructor(des: string) { 187 super(des); 188 } 189 190 onConnect(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence, option: rpc.MessageOption) { 191 } 192 } 193 194 class AppServiceExtAbility extends AppServiceExtensionAbility { 195 onConnect(want: Want) { 196 hilog.info(0x0000, TAG, `onConnect, want: ${want.abilityName}`); 197 return new StubTest('test'); 198 } 199 } 200 ``` 201 202### onDisconnect 203 204onDisconnect(want: Want): void 205 206Called when all connections to an AppServiceExtensionAbility instance are interrupted. 207 208**System capability**: SystemCapability.Ability.AbilityRuntime.Core 209 210**Parameters** 211 212| Name| Type| Mandatory| Description| 213| -------- | -------- | -------- | -------- | 214| want |[Want](js-apis-app-ability-want.md)| Yes| Want information about the target AppServiceExtensionAbility instance, including the ability name and bundle name.| 215 216**Example** 217 218 ```ts 219 import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit'; 220 import { hilog } from '@kit.PerformanceAnalysisKit'; 221 222 const TAG: string = '[AppServiceExtAbility]'; 223 224 class AppServiceExtAbility extends AppServiceExtensionAbility { 225 onDisconnect(want: Want) { 226 hilog.info(0x0000, TAG, `onDisconnect, want: ${want.abilityName}`); 227 } 228 } 229 ``` 230
