• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ServiceExtensionContext
2
3> **NOTE**
4>
5> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
6
7
8Implements the context that provides the capabilities and APIs of **ServiceExtension**. This class is inherited from **ExtensionContext**.
9
10
11## startAbility
12
13startAbility(want: Want, callback: AsyncCallback<void>): void;
14
15Starts an ability. This API uses a callback to return the result.
16
17**System capability**: SystemCapability.Ability.AbilityRuntime.Core
18
19**Parameters**
20
21| Name| Type| Mandatory| Description|
22| -------- | -------- | -------- | -------- |
23| want | [Want](js-apis-featureAbility.md#Want) | Yes| Information about the ability to start, such as the ability name and bundle name.|
24| callback | AsyncCallback<void> | No| Callback used to return the result indicating whether the API is successfully called.|
25
26**Example**
27
28  ```js
29  let want = {
30      "bundleName": "com.example.myapp",
31      "abilityName": "com.example.myapp.MyAbility"
32  };
33  this.context.startAbility(want, (err) => {
34      console.log('startAbility result:' + JSON.stringify(err));
35  });
36  ```
37
38
39## ServiceExtensionContext.startAbility
40
41startAbility(want: Want): Promise<void>;
42
43Starts an ability. This API uses a promise to return the result.
44
45**System capability**: SystemCapability.Ability.AbilityRuntime.Core
46
47**Parameters**
48
49| Name| Type| Mandatory| Description|
50| -------- | -------- | -------- | -------- |
51| want | [Want](js-apis-featureAbility.md#Want) | Yes| Information about the ability to start, such as the ability name and bundle name.|
52
53**Return value**
54
55| Type| Description|
56| -------- | -------- |
57| Promise<void> | Promise used to return the result indicating whether the API is successfully called.|
58
59**Example**
60
61  ```js
62  let want = {
63      "bundleName": "com.example.myapp",
64      "abilityName": "com.example.myapp.MyAbility"
65  };
66  this.context.startAbility(want).then((data) => {
67      console.log('success:' + JSON.stringify(data));
68  }).catch((error) => {
69      console.log('failed:' + JSON.stringify(error));
70  });
71  ```
72
73
74## ServiceExtensionContext.terminateSelf
75
76terminateSelf(callback: AsyncCallback<void>): void;
77
78Terminates this ability. This API uses a callback to return the result.
79
80**System capability**: SystemCapability.Ability.AbilityRuntime.Core
81
82**Parameters**
83
84| Name| Type| Mandatory| Description|
85| -------- | -------- | -------- | -------- |
86| callback | AsyncCallback<void> | No| Callback used to return the result indicating whether the API is successfully called.|
87
88**Example**
89
90  ```js
91  this.context.terminateSelf((err) => {
92      console.log('terminateSelf result:' + JSON.stringify(err));
93  });
94  ```
95
96
97## ServiceExtensionContext.terminateSelf
98
99terminateSelf(): Promise<void>;
100
101Terminates this ability. This API uses a promise to return the result.
102
103**System capability**: SystemCapability.Ability.AbilityRuntime.Core
104
105**Return value**
106
107| Type| Description|
108| -------- | -------- |
109| Promise<void> | Promise used to return the result indicating whether the API is successfully called.|
110
111**Example**
112
113  ```js
114  this.context.terminateSelf(want).then((data) => {
115      console.log('success:' + JSON.stringify(data));
116  }).catch((error) => {
117      console.log('failed:' + JSON.stringify(error));
118  });
119  ```
120
121
122## ServiceExtensionContext.connectAbility
123
124connectAbility(want: Want, options: ConnectOptions): number;
125
126Connects this ability to a Service ability.
127
128**System capability**: SystemCapability.Ability.AbilityRuntime.Core
129
130**Parameters**
131
132| Name| Type| Mandatory| Description|
133| -------- | -------- | -------- | -------- |
134| want | [Want](js-apis-featureAbility.md#Want) | Yes| Information about the ability to connect to, such as the ability name and bundle name.|
135| options | [ConnectOptions](#connectoptions) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.|
136
137**Return value**
138
139| Type| Description|
140| -------- | -------- |
141| number | A number, based on which the connection will be interrupted.|
142
143**Example**
144
145  ```js
146  let want = {
147      "bundleName": "com.example.myapp",
148      "abilityName": "com.example.myapp.MyAbility"
149  };
150  let options = {
151      onConnect: function(elementName, proxy) {},
152      onDisConnect: function(elementName) {},
153      onFailed: function(code) {}
154  }
155  let connection = this.context.connectAbility(want,options);
156  ```
157
158
159## ServiceExtensionContext.disconnectAbility
160
161disconnectAbility(connection: number, callback:AsyncCallback<void>): void;
162
163Disconnects this ability from the Service ability. This API uses a callback to return the result.
164
165**System capability**: SystemCapability.Ability.AbilityRuntime.Core
166
167**Parameters**
168
169| Name| Type| Mandatory| Description|
170| -------- | -------- | -------- | -------- |
171| connection | number | Yes| Number returned after **connectAbility** is called.|
172| callback | AsyncCallback<void> | No| Callback used to return the result indicating whether the API is successfully called.|
173
174**Example**
175
176  ```js
177  this.context.disconnectAbility(connection, (err) => { // connection is the return value of connectAbility.
178      console.log('terminateSelf result:' + JSON.stringify(err));
179  });
180  ```
181
182
183## ServiceExtensionContext.disconnectAbility
184
185disconnectAbility(connection: number): Promise<void>;
186
187Disconnects this ability from the Service ability. This API uses a promise to return the result.
188
189**System capability**: SystemCapability.Ability.AbilityRuntime.Core
190
191**Parameters**
192
193| Name| Type| Mandatory| Description|
194| -------- | -------- | -------- | -------- |
195| connection | number | Yes| Number returned after **connectAbility** is called.|
196
197**Return value**
198
199| Type| Description|
200| -------- | -------- |
201| Promise<void> | Promise used to return the result indicating whether the API is successfully called.|
202
203**Example**
204
205  ```js
206  this.context.disconnectAbility(connection).then((data) => { // connection is the return value of connectAbility.
207      console.log('success:' + JSON.stringify(data));
208  }).catch((error) => {
209      console.log('failed:' + JSON.stringify(error));
210  });
211  ```
212
213
214## ConnectOptions
215
216Defines the **ConnectOptions** data structure.
217
218**System capability**: SystemCapability.Ability.AbilityRuntime.Core
219
220| Name| Description|
221| -------- | -------- |
222| onConnect(elementName:ElementName, remote:IRemoteObject) | Called when this ability is connected to a Service ability.|
223| onDisconnect(elementName:ElementName) | Called when the peer service is abnormal or killed.|
224| onFailed(code: number) | Called when the connection fails.|
225