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