1# @ohos.app.ability.ServiceExtensionAbility (ServiceExtensionAbility) (System API) 2<!--Kit: Ability Kit--> 3<!--Subsystem: Ability--> 4<!--Owner: @yewei0794--> 5<!--Designer: @jsjzju--> 6<!--Tester: @lixueqing513--> 7<!--Adviser: @huipeizi--> 8 9The ServiceExtensionAbility 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 9. 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> The APIs provided by this module are system APIs. 18 19## Modules to Import 20 21```ts 22import { ServiceExtensionAbility } from '@kit.AbilityKit'; 23``` 24 25## Required Permissions 26 27None. 28 29## ServiceExtensionAbility 30 31### Properties 32 33**System capability**: SystemCapability.Ability.AbilityRuntime.Core 34 35**System API**: This is a system API. 36 37| Name| Type| Read-Only| Optional| Description| 38| -------- | -------- | -------- | -------- | -------- | 39| context | [ServiceExtensionContext](js-apis-inner-application-serviceExtensionContext-sys.md) | No| No| Context of the ServiceExtensionAbility. This context inherits from **ExtensionContext**.| 40 41 42### onCreate 43 44onCreate(want: Want): void; 45 46Called to initialize the service logic when a ServiceExtensionAbility is being created. 47 48**System capability**: SystemCapability.Ability.AbilityRuntime.Core 49 50**System API**: This is a system API. 51 52**Parameters** 53 54| Name| Type| Mandatory| Description| 55| -------- | -------- | -------- | -------- | 56| want | [Want](js-apis-app-ability-want.md) | Yes| Want information related to this ServiceExtensionAbility, including the ability name and bundle name.| 57 58**Example** 59 60```ts 61import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 62 63class ServiceExt extends ServiceExtensionAbility { 64 onCreate(want: Want) { 65 console.info(`onCreate, want: ${want.abilityName}`); 66 } 67} 68``` 69 70 71### onDestroy 72 73onDestroy(): void; 74 75Called to clear resources when this ServiceExtensionAbility is being destroyed. 76 77**System capability**: SystemCapability.Ability.AbilityRuntime.Core 78 79**System API**: This is a system API. 80 81**Example** 82 83```ts 84import { ServiceExtensionAbility } from '@kit.AbilityKit'; 85 86class ServiceExt extends ServiceExtensionAbility { 87 onDestroy() { 88 console.info('onDestroy'); 89 } 90} 91``` 92 93 94### onRequest 95 96onRequest(want: Want, startId: number): void; 97 98Called following **onCreate()** when a ServiceExtensionAbility is started by calling **startAbility()** or **startServiceExtensionAbility()**. The value of **startId** is incremented for each ServiceExtensionAbility that is started. 99 100**System capability**: SystemCapability.Ability.AbilityRuntime.Core 101 102**System API**: This is a system API. 103 104**Parameters** 105 106| Name| Type| Mandatory| Description| 107| -------- | -------- | -------- | -------- | 108| want | [Want](js-apis-app-ability-want.md) | Yes| Want information related to this ServiceExtensionAbility, including the ability name and bundle name.| 109| 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.| 110 111**Example** 112 113```ts 114import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 115 116class ServiceExt extends ServiceExtensionAbility { 117 onRequest(want: Want, startId: number) { 118 console.info('onRequest, want: ${want.abilityName}'); 119 } 120} 121``` 122 123 124### onConnect 125 126onConnect(want: Want): rpc.RemoteObject | Promise<rpc.RemoteObject>; 127 128Called following **onCreate()** when a ServiceExtensionAbility is started by calling **connectAbility()**. A RemoteObject is returned for communication between the server and client. 129 130**System capability**: SystemCapability.Ability.AbilityRuntime.Core 131 132**System API**: This is a system API. 133 134**Parameters** 135 136| Name| Type| Mandatory| Description| 137| -------- | -------- | -------- | -------- | 138| want | [Want](js-apis-app-ability-want.md)| Yes| Want information related to this ServiceExtensionAbility, including the ability name and bundle name.| 139 140**Return value** 141 142| Type| Description| 143| -------- | -------- | 144| [rpc.RemoteObject](../apis-ipc-kit/js-apis-rpc.md#remoteobject) \| Promise\<[rpc.RemoteObject](../apis-ipc-kit/js-apis-rpc.md#remoteobject)> | RemoteObject or Promise used to return a RemoteObject, which is used for communication between the client and server.| 145 146**Example** 147 148```ts 149import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 150import { rpc } from '@kit.IPCKit'; 151 152class StubTest extends rpc.RemoteObject{ 153 constructor(des: string) { 154 super(des); 155 } 156 onConnect(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence, option: rpc.MessageOption) { 157 } 158} 159class ServiceExt extends ServiceExtensionAbility { 160 onConnect(want: Want) { 161 console.info('onConnect , want: ${want.abilityName}'); 162 return new StubTest('test'); 163 } 164} 165``` 166 167If the returned RemoteObject depends on an asynchronous API, you can use the asynchronous lifecycle. 168 169```ts 170import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 171import { rpc } from '@kit.IPCKit'; 172 173class StubTest extends rpc.RemoteObject{ 174 constructor(des: string) { 175 super(des); 176 } 177 onConnect(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence, option: rpc.MessageOption) { 178 } 179} 180async function getDescriptor() { 181 // Call the asynchronous function. 182 return "asyncTest" 183} 184class ServiceExt extends ServiceExtensionAbility { 185 async onConnect(want: Want) { 186 console.info(`onConnect , want: ${want.abilityName}`); 187 let descriptor = await getDescriptor(); 188 return new StubTest(descriptor); 189 } 190} 191``` 192 193### onDisconnect 194 195onDisconnect(want: Want): void | Promise\<void>; 196 197Called when a client is disconnected from this ServiceExtensionAbility. 198 199**System capability**: SystemCapability.Ability.AbilityRuntime.Core 200 201**System API**: This is a system API. 202 203**Parameters** 204 205| Name| Type| Mandatory| Description| 206| -------- | -------- | -------- | -------- | 207| want |[Want](js-apis-app-ability-want.md)| Yes| Want information related to this ServiceExtensionAbility, including the ability name and bundle name.| 208 209**Return value** 210 211| Type| Description| 212| -------- | -------- | 213| Promise\<void> | Promise that returns no value.| 214 215**Example** 216 217```ts 218import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 219 220class ServiceExt extends ServiceExtensionAbility { 221 onDisconnect(want: Want) { 222 console.info('onDisconnect, want: ${want.abilityName}'); 223 } 224} 225``` 226 227After the **onDisconnect()** lifecycle callback is executed, the application may exit. Consequently, the asynchronous function (for example, asynchronously writing data to the database) in **onDisconnect()** may fail to be executed. The asynchronous lifecycle can be used to ensure that the subsequent lifecycle continues after the asynchronous **onDisconnect()** is complete. 228 229```ts 230import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 231 232class ServiceExt extends ServiceExtensionAbility { 233 async onDisconnect(want: Want) { 234 console.info('onDisconnect, want: ${want.abilityName}'); 235 // Call the asynchronous function. 236 } 237} 238``` 239 240### onReconnect 241 242onReconnect(want: Want): void; 243 244Called when a new client attempts to connect to this ServiceExtensionAbility after all previous clients are disconnected. This capability is reserved. 245 246**System capability**: SystemCapability.Ability.AbilityRuntime.Core 247 248**System API**: This is a system API. 249 250**Parameters** 251 252| Name| Type| Mandatory| Description| 253| -------- | -------- | -------- | -------- | 254| want |[Want](js-apis-app-ability-want.md)| Yes| Want information related to this ServiceExtensionAbility, including the ability name and bundle name.| 255 256**Example** 257 258```ts 259import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 260 261class ServiceExt extends ServiceExtensionAbility { 262 onReconnect(want: Want) { 263 console.info('onReconnect, want: ${want.abilityName}'); 264 } 265} 266``` 267 268### onConfigurationUpdate 269 270onConfigurationUpdate(newConfig: Configuration): void; 271 272Called when the configuration of this ServiceExtensionAbility is updated. 273 274**System capability**: SystemCapability.Ability.AbilityRuntime.Core 275 276**System API**: This is a system API. 277 278**Parameters** 279 280| Name| Type| Mandatory| Description| 281| -------- | -------- | -------- | -------- | 282| newConfig | [Configuration](js-apis-app-ability-configuration.md) | Yes| New configuration.| 283 284**Example** 285 286```ts 287import { ServiceExtensionAbility, Configuration } from '@kit.AbilityKit'; 288 289class ServiceExt extends ServiceExtensionAbility { 290 onConfigurationUpdate(newConfig: Configuration) { 291 console.info(`onConfigurationUpdate, config: ${JSON.stringify(newConfig)}`); 292 } 293} 294``` 295 296### onDump 297 298onDump(params: Array\<string>): Array\<string>; 299 300Dumps the client information. 301 302**System capability**: SystemCapability.Ability.AbilityRuntime.Core 303 304**System API**: This is a system API. 305 306**Parameters** 307 308| Name| Type| Mandatory| Description| 309| -------- | -------- | -------- | -------- | 310| params | Array\<string> | Yes| Parameters in the form of a command.| 311 312**Return value** 313 314| Type| Description| 315| -------- | -------- | 316| Array\<string> | Array of client information.| 317 318**Example** 319 320```ts 321import { ServiceExtensionAbility } from '@kit.AbilityKit'; 322 323class ServiceExt extends ServiceExtensionAbility { 324 onDump(params: Array<string>) { 325 console.info(`dump, params: ${JSON.stringify(params)}`); 326 return ['params']; 327 } 328} 329``` 330