1# FormExtensionContext (System API)
2
3The FormExtensionContext module, inherited from [ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md), provides the context environment for the [FormExtensionAbility](js-apis-app-form-formExtensionAbility.md).
4
5You can use the APIs of this module to start a FormExtensionAbility.
6
7> **NOTE**
8>
9> 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.
10> The APIs of this module can be used only in the stage model.
11> The APIs provided by this module are system APIs.
12
13
14
15## Modules to Import
16
17```ts
18import { common } from '@kit.AbilityKit';
19```
20
21## FormExtensionContext.startAbility
22
23startAbility(want: Want, callback: AsyncCallback<void>): void
24
25Starts an ability. This API uses an asynchronous callback to return the result.
26
27**System API**: This is a system API.
28
29**System capability**: SystemCapability.Ability.Form
30
31**Error codes**
32
33| ID| Error Message|
34| -------- | -------- |
35| 202 | The application is not a system application. |
36| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
37| 16500050 | IPC connection error. |
38| 16500100 | Failed to obtain the configuration information. |
39| 16501000 | An internal functional error occurred. |
40
41For details about the error codes, see [Form Error Codes](errorcode-form.md).
42
43**Parameters**
44
45| Name|                Type              | Mandatory|              Description              |
46| ------| --------------------------------- | ---- | -------------------------------------- |
47| want| [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Information about the ability to start, such as the bundle name, ability name, and custom parameters.|
48| callback| AsyncCallback<void>       | Yes | Callback used to return the result. If the ability is started, **err** is undefined; otherwise, **err** is an error object.|
49
50**Example**
51
52```ts
53import { FormExtensionAbility } from '@kit.FormKit';
54import { Want } from '@kit.AbilityKit';
55import { BusinessError } from '@kit.BasicServicesKit';
56
57export default class MyFormExtensionAbility extends FormExtensionAbility {
58  onFormEvent(formId: string, message: string) {
59    // Call startAbility() when the message event is triggered.
60    console.log(`FormExtensionAbility onFormEvent, formId: ${formId}, message:${message}`);
61    let want: Want = {
62      deviceId: '',
63      bundleName: 'com.example.formstartability',
64      abilityName: 'EntryAbility',
65      parameters: {
66        'message': message
67      }
68    };
69    this.context.startAbility(want, (error: BusinessError) => {
70      if (error) {
71        console.error(`FormExtensionContext startAbility, error:${JSON.stringify(error)}`);
72      } else {
73        console.log('FormExtensionContext startAbility success');
74      }
75    });
76  }
77};
78```
79
80## FormExtensionContext.startAbility
81
82startAbility(want: Want): Promise<void>
83
84Starts an ability. This API uses a promise to return the result.
85
86**System API**: This is a system API.
87
88**System capability**: SystemCapability.Ability.Form
89
90**Parameters**
91
92| Name|                Type              | Mandatory|              Description              |
93| ------| --------------------------------- | ---- | -------------------------------------- |
94| want| [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Information about the ability to start, such as the bundle name, ability name, and custom parameters.|
95
96**Return value**
97
98| Type         | Description                               |
99| ------------ | ---------------------------------- |
100| Promise<void> | Promise that returns no value.|
101
102**Error codes**
103
104| ID| Error Message|
105| -------- | -------- |
106| 202 | The application is not a system application. |
107| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
108| 16500050 | IPC connection error. |
109| 16500100 | Failed to obtain the configuration information. |
110| 16501000 | An internal functional error occurred. |
111
112For details about the error codes, see [Form Error Codes](errorcode-form.md).
113
114**Example**
115
116```ts
117import { FormExtensionAbility } from '@kit.FormKit';
118import { Want } from '@kit.AbilityKit';
119import { BusinessError } from '@kit.BasicServicesKit';
120
121export default class MyFormExtensionAbility extends FormExtensionAbility {
122  onFormEvent(formId: string, message: string) {
123    // Call startAbility() when the message event is triggered.
124    console.log(`FormExtensionAbility onFormEvent, formId:${formId}, message:${message}`);
125    let want: Want = {
126      deviceId: '',
127      bundleName: 'com.example.formstartability',
128      abilityName: 'EntryAbility',
129      parameters: {
130        'message': message
131      }
132    };
133    this.context.startAbility(want).then(() => {
134      console.info('StartAbility Success');
135    }).catch((error: BusinessError) => {
136      console.error(`StartAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
137    });
138  }
139};
140```
141
142## FormExtensionContext.connectServiceExtensionAbility<sup>10+</sup>
143
144connectServiceExtensionAbility(want: Want, options: ConnectOptions): number
145
146Connects this ability to a ServiceExtensionAbility.
147
148**System capability**: SystemCapability.Ability.Form
149
150**System API**: This is a system API and cannot be called by third-party applications.
151
152**Parameters**
153
154| Name| Type| Mandatory| Description|
155| -------- | -------- | -------- | -------- |
156| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md)  | Yes| Want information about the target ability, such as the ability name and bundle name.|
157| options | [ConnectOptions](../apis-ability-kit/js-apis-inner-ability-connectOptions.md) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.|
158
159**Return value**
160
161| Type| Description|
162| -------- | -------- |
163| number | Returns a connect ID, which will be used for the disconnection.|
164
165**Error codes**
166
167| ID| Error Message|
168| ------- | -------------------------------- |
169| 201      | Permissions denied.             |
170| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
171| 16000001 | The specified ability does not exist. |
172| 16000002 | Incorrect ability type. |
173| 16000004 | Can not start invisible component. |
174| 16000005 | The specified process does not have the permission. |
175| 16000006 | Cross-user operations are not allowed. |
176| 16000008 | The crowdtesting application expires. |
177| 16000053 | The ability is not on the top of the UI. |
178| 16000055 | Installation-free timed out. |
179| 16000011 | The context does not exist.        |
180| 16000050 | Internal error. |
181
182For details about the error codes, see [Ability Error Codes](../apis-ability-kit/errorcode-ability.md).
183
184**Example**
185
186```ts
187import { rpc } from '@kit.IPCKit';
188import { FormExtensionAbility } from '@kit.FormKit';
189import { common, Want } from '@kit.AbilityKit';
190import { BusinessError } from '@kit.BasicServicesKit';
191
192let commRemote: rpc.IRemoteObject | null = null;
193
194export default class MyFormExtensionAbility extends FormExtensionAbility {
195  onFormEvent(formId: string, message: string) {
196    // Call connectServiceExtensionAbility() when the message event is triggered.
197    console.log(`FormExtensionAbility onFormEvent, formId:${formId}, message:${message}`);
198    let want: Want = {
199      deviceId: '',
200      bundleName: 'com.example.formstartability',
201      abilityName: 'EntryAbility',
202      parameters: {
203        'message': message
204      }
205    };
206    let options: common.ConnectOptions = {
207      onConnect(elementName, remote) {
208        commRemote = remote; // remote is used to communicate with the ServiceExtensionAbility.
209        console.log('----------- onConnect -----------');
210      },
211      onDisconnect(elementName) {
212        console.log('----------- onDisconnect -----------')
213      },
214      onFailed(code) {
215        console.error('----------- onFailed -----------')
216      }
217    };
218
219    let connection: number | null = null;
220    try {
221      connection = this.context.connectServiceExtensionAbility(want, options);
222    } catch (paramError) {
223      // Process input parameter errors.
224      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
225    }
226  }
227};
228```
229
230## FormExtensionContext.disconnectServiceExtensionAbility<sup>10+</sup>
231
232disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback&lt;void&gt;): void
233
234Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses an asynchronous callback to return the result.
235
236**System capability**: SystemCapability.Ability.Form
237
238**System API**: This is a system API and cannot be called by third-party applications.
239
240**Parameters**
241
242| Name| Type| Mandatory| Description|
243| -------- | -------- | -------- | -------- |
244| connection | number | Yes| Number returned after [connectServiceExtensionAbility](#formextensioncontextconnectserviceextensionability10) is called.|
245| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the result. If the ability is disconnected, **err** is **undefined**; otherwise, **err** is an error object.|
246
247**Error codes**
248
249| ID| Error Message|
250| ------- | -------------------------------- |
251| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
252| 16000011 | The context does not exist.        |
253| 16000050 | Internal error. |
254
255For details about the error codes, see [Ability Error Codes](../apis-ability-kit/errorcode-ability.md).
256
257**Example**
258
259```ts
260import { FormExtensionAbility } from '@kit.FormKit';
261import { rpc } from '@kit.IPCKit';
262import { BusinessError } from '@kit.BasicServicesKit';
263
264// commRemote is the remote object returned in the onConnect() callback. The value null is meaningless and is only an example.
265let commRemote: rpc.IRemoteObject | null = null;
266export default class MyFormExtensionAbility extends FormExtensionAbility {
267  onFormEvent(formId: string, message: string) {
268    // In actual use, connection is the return value of connectServiceExtensionAbility(). The value 1 is meaningless and is only an example.
269    let connection: number = 1;
270
271    try {
272      this.context.disconnectServiceExtensionAbility(connection, (error: BusinessError) => {
273        commRemote = null;
274        if (error.code) {
275          // Process service logic errors.
276          console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
277          return;
278        }
279        // Carry out normal service processing.
280        console.log('disconnectServiceExtensionAbility succeed');
281      });
282    } catch (paramError) {
283      commRemote = null;
284      // Process input parameter errors.
285      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
286    }
287  }
288};
289```
290
291## FormExtensionContext.disconnectServiceExtensionAbility<sup>10+</sup>
292
293disconnectServiceExtensionAbility(connection: number): Promise&lt;void&gt;
294
295Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses a promise to return the result.
296
297**System capability**: SystemCapability.Ability.Form
298
299**System API**: This is a system API and cannot be called by third-party applications.
300
301**Parameters**
302
303| Name| Type| Mandatory| Description|
304| -------- | -------- | -------- | -------- |
305| connection | number | Yes| Number returned after [connectServiceExtensionAbility](#formextensioncontextconnectserviceextensionability10) is called.|
306
307**Return value**
308
309| Type| Description|
310| -------- | -------- |
311| Promise&lt;void&gt; | Promise that returns no value.|
312
313**Error codes**
314
315| ID| Error Message|
316| ------- | -------------------------------- |
317| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
318| 16000011 | The context does not exist.        |
319| 16000050 | Internal error. |
320
321For details about the error codes, see [Ability Error Codes](../apis-ability-kit/errorcode-ability.md).
322
323**Example**
324
325```ts
326import { FormExtensionAbility } from '@kit.FormKit';
327import { rpc } from '@kit.IPCKit';
328import { BusinessError } from '@kit.BasicServicesKit';
329
330// commRemote is the remote object returned in the onConnect() callback. The value null is meaningless and is only an example.
331let commRemote: rpc.IRemoteObject | null = null;
332export default class MyFormExtensionAbility extends FormExtensionAbility {
333  onFormEvent(formId: string, message: string) {
334    // In actual use, connection is the return value of connectServiceExtensionAbility(). The value 1 is meaningless and is only an example.
335    let connection: number = 1;
336
337    try {
338      this.context.disconnectServiceExtensionAbility(connection)
339        .then(() => {
340          commRemote = null;
341          // Carry out normal service processing.
342          console.log('disconnectServiceExtensionAbility succeed');
343        })
344        .catch((error: BusinessError) => {
345          commRemote = null;
346          // Process service logic errors.
347          console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
348        });
349    } catch (paramError) {
350      commRemote = null;
351      // Process input parameter errors.
352      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
353    }
354  }
355};
356```
357