1# ConnectOptions
2
3**ConnectOptions** can be used as an input parameter to receive status changes during the connection to a background service. For example, it is used as an input parameter of [connectServiceExtensionAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectserviceextensionability) to connect to a ServiceExtensionAbility.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```ts
12import { common } from '@kit.AbilityKit';
13```
14
15## onConnect
16
17onConnect(elementName: ElementName, remote: rpc.IRemoteObject): void
18
19Callback invoked when a connection is set up.
20
21**System capability**: SystemCapability.Ability.AbilityRuntime.Core
22
23**Parameters**
24
25| Name      | Type                    | Mandatory  | Description           |
26| -------- | ---------------------- | ---- | ------------- |
27| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes   | Element name of the ability. |
28| remote | [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | Yes   | **IRemoteObject** instance. |
29
30**Example**
31
32```ts
33import { UIAbility, common, Want, AbilityConstant } from '@kit.AbilityKit';
34import { bundleManager } from '@kit.AbilityKit';
35import { rpc } from '@kit.IPCKit';
36
37let connectWant: Want = {
38  bundleName: 'com.example.myapp',
39  abilityName: 'MyAbility'
40};
41
42let connectOptions: common.ConnectOptions = {
43  onConnect(elementName: bundleManager.ElementName, remote: rpc.IRemoteObject) {
44    console.log(`onConnect elementName: ${elementName}`);
45  },
46  onDisconnect(elementName: bundleManager.ElementName) {
47    console.log(`onDisconnect elementName: ${elementName}`);
48  },
49  onFailed(code: number) {
50    console.error(`onFailed code: ${code}`);
51  }
52};
53
54class EntryAbility extends UIAbility {
55  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
56    let connection: number = this.context.connectServiceExtensionAbility(connectWant, connectOptions);
57  }
58}
59```
60
61## onDisconnect
62
63onDisconnect(elementName: ElementName): void
64
65Callback invoked when a connection is interrupted.
66
67**System capability**: SystemCapability.Ability.AbilityRuntime.Core
68
69**Parameters**
70
71| Name      | Type                    | Mandatory  | Description           |
72| -------- | ---------------------- | ---- | ------------- |
73| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes   | Element name of the ability. |
74
75**Example**
76
77```ts
78import { UIAbility, common, Want, AbilityConstant } from '@kit.AbilityKit';
79import { bundleManager } from '@kit.AbilityKit';
80import { rpc } from '@kit.IPCKit';
81
82let connectWant: Want = {
83  bundleName: 'com.example.myapp',
84  abilityName: 'MyAbility'
85};
86
87let connectOptions: common.ConnectOptions = {
88  onConnect(elementName: bundleManager.ElementName, remote: rpc.IRemoteObject) {
89    console.log(`onConnect elementName: ${elementName}`);
90  },
91  onDisconnect(elementName: bundleManager.ElementName) {
92    console.log(`onDisconnect elementName: ${elementName}`);
93  },
94  onFailed(code: number) {
95    console.error(`onFailed code: ${code}`);
96  }
97};
98
99class EntryAbility extends UIAbility {
100  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
101    let connection: number = this.context.connectServiceExtensionAbility(connectWant, connectOptions);
102  }
103}
104```
105
106## onFailed
107
108onFailed(code: number): void
109
110Callback invoked when a connection fails.
111
112**System capability**: SystemCapability.Ability.AbilityRuntime.Core
113
114**Parameters**
115
116| Name      | Type                    | Mandatory  | Description           |
117| -------- | ---------------------- | ---- | ------------- |
118| code | number | Yes   | Result code.<br>The value **0** means that the connection is successful, **-1** means that a parameter is incorrect, and **-2** means that the ability is not found. |
119
120**Example**
121
122```ts
123import { UIAbility, common, Want, AbilityConstant } from '@kit.AbilityKit';
124import { bundleManager } from '@kit.AbilityKit';
125import { rpc } from '@kit.IPCKit';
126
127let connectWant: Want = {
128  bundleName: 'com.example.myapp',
129  abilityName: 'MyAbility'
130};
131
132let connectOptions: common.ConnectOptions = {
133  onConnect(elementName: bundleManager.ElementName, remote: rpc.IRemoteObject) {
134    console.log(`onConnect elementName: ${elementName}`);
135  },
136  onDisconnect(elementName: bundleManager.ElementName) {
137    console.log(`onDisconnect elementName: ${elementName}`);
138  },
139  onFailed(code: number) {
140    console.error(`onFailed code: ${code}`);
141  }
142};
143
144class EntryAbility extends UIAbility {
145  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
146    let connection: number = this.context.connectServiceExtensionAbility(connectWant, connectOptions);
147  }
148}
149```
150