• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ServiceExtensionContext
2
3> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
4> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
5
6
7ServiceExtension的上下文环境，提供ServiceExtension具有的能力和接口，继承自ExtensionContext。
8
9
10## startAbility
11
12startAbility(want: Want, callback: AsyncCallback<void>): void;
13
14启动Ability。
15
16**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
17
18**参数：**
19
20  | 参数名 | 类型 | 必填 | 说明 |
21  | -------- | -------- | -------- | -------- |
22  | want | [Want](js-apis-featureAbility.md#Want类型说明)  | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 |
23  | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 |
24
25**示例：**
26
27  ```js
28  let want = {
29      "bundleName": "com.example.myapp",
30      "abilityName": "com.example.myapp.MyAbility"
31  };
32  this.context.startAbility(want, (err) => {
33      console.log('startAbility result:' + JSON.stringify(err));
34  });
35  ```
36
37
38## ServiceExtensionContext.startAbility
39
40startAbility(want: Want): Promise<void>;
41
42启动Ability。通过Promise返回结果。
43
44**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
45
46**参数：**
47
48  | 参数名 | 类型 | 必填 | 说明 |
49  | -------- | -------- | -------- | -------- |
50  | want | [Want](js-apis-featureAbility.md#Want类型说明)  | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 |
51
52**返回值：**
53
54  | 类型 | 说明 |
55  | -------- | -------- |
56  | Promise<void> | 返回一个Promise，包含接口的结果。 |
57
58**示例：**
59
60  ```js
61  let want = {
62      "bundleName": "com.example.myapp",
63      "abilityName": "com.example.myapp.MyAbility"
64  };
65  this.context.startAbility(want).then((data) => {
66      console.log('success:' + JSON.stringify(data));
67  }).catch((error) => {
68      console.log('failed:' + JSON.stringify(error));
69  });
70  ```
71
72
73## ServiceExtensionContext.terminateSelf
74
75terminateSelf(callback: AsyncCallback<void>): void;
76
77停止Ability自身。
78
79**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
80
81**参数：**
82
83  | 参数名 | 类型 | 必填 | 说明 |
84  | -------- | -------- | -------- | -------- |
85  | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 |
86
87**示例：**
88
89  ```js
90  this.context.terminateSelf((err) => {
91      console.log('terminateSelf result:' + JSON.stringify(err));
92  });
93  ```
94
95
96## ServiceExtensionContext.terminateSelf
97
98terminateSelf(): Promise<void>;
99
100停止自身。通过Promise返回结果。
101
102**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
103
104**返回值：**
105
106  | 类型 | 说明 |
107  | -------- | -------- |
108  | Promise<void> | 返回一个Promise，包含接口的结果。 |
109
110**示例：**
111
112  ```js
113  this.context.terminateSelf(want).then((data) => {
114      console.log('success:' + JSON.stringify(data));
115  }).catch((error) => {
116      console.log('failed:' + JSON.stringify(error));
117  });
118  ```
119
120
121## ServiceExtensionContext.connectAbility
122
123connectAbility(want: Want, options: ConnectOptions): number;
124
125将一个Ability与服务类型的Ability绑定。
126
127**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
128
129**参数：**
130
131  | 参数名 | 类型 | 必填 | 说明 |
132  | -------- | -------- | -------- | -------- |
133  | want | [Want](js-apis-featureAbility.md#Want类型说明)  | 是 | Want类型参数，传入需要启动的ability的信息，如ability名称，包名等。 |
134  | options | [ConnectOptions](#connectoptions) | 是 | ConnectOptions类型的回调函数，返回服务连接成功、断开或连接失败后的信息。 |
135
136**返回值：**
137
138  | 类型 | 说明 |
139  | -------- | -------- |
140  | number | 返回一个number，后续根据这个number去断开连接。 |
141
142**示例：**
143
144  ```js
145  let want = {
146      "bundleName": "com.example.myapp",
147      "abilityName": "com.example.myapp.MyAbility"
148  };
149  let options = {
150      onConnect: function(elementName, proxy) {},
151      onDisConnect: function(elementName) {},
152      onFailed: function(code) {}
153  }
154  let connection = this.context.connectAbility(want,options);
155  ```
156
157
158## ServiceExtensionContext.disconnectAbility
159
160disconnectAbility(connection: number, callback:AsyncCallback<void>): void;
161
162将一个Ability与绑定的服务类型的Ability解绑。
163
164**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
165
166**参数：**
167
168  | 参数名 | 类型 | 必填 | 说明 |
169  | -------- | -------- | -------- | -------- |
170  | connection | number | 是 | 在connectAbility中返回的number。 |
171  | callback | AsyncCallback<void> | 否 | 回调函数，返回接口调用是否成功的结果。 |
172
173**示例：**
174
175  ```js
176  this.context.disconnectAbility(connection, (err) => { // connection为connectAbility中的返回值
177      console.log('terminateSelf result:' + JSON.stringify(err));
178  });
179  ```
180
181
182## ServiceExtensionContext.disconnectAbility
183
184disconnectAbility(connection: number): Promise<void>;
185
186将一个Ability与绑定的服务类型的Ability解绑。通过Promise返回结果。
187
188**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
189
190**参数：**
191
192  | 参数名 | 类型 | 必填 | 说明 |
193  | -------- | -------- | -------- | -------- |
194  | connection | number | 是 | 在connectAbility中返回的number。 |
195
196**返回值：**
197
198  | 类型 | 说明 |
199  | -------- | -------- |
200  | Promise<void> | 返回一个Promise，包含接口的结果。 |
201
202**示例：**
203
204  ```js
205  this.context.disconnectAbility(connection).then((data) => { // connection为connectAbility中的返回值
206      console.log('success:' + JSON.stringify(data));
207  }).catch((error) => {
208      console.log('failed:' + JSON.stringify(error));
209  });
210  ```
211
212
213## ConnectOptions
214
215ConnectOptions数据结构。
216
217**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core
218
219| 名称 | 说明 |
220| -------- | -------- |
221| onConnect(elementName:ElementName, remote:IRemoteObject) | Ability成功连接一个服务类型Ability的回调接口。 |
222| onDisconnect(elementName:ElementName) | 对端服务发生异常或者被杀死回调该接口。 |
223| onFailed(code: number) | 连接失败时回调该接口。 |
224