1# ConnectOptions
2
3在连接指定的后台服务时作为入参，用于接收连接过程中的状态变化，如作为[connectServiceExtensionAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectserviceextensionability)的入参，连接指定的ServiceExtensionAbility。
4
5> **说明：**
6>
7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { common } from '@kit.AbilityKit';
13```
14
15## onConnect
16
17onConnect(elementName: ElementName, remote: rpc.IRemoteObject): void
18
19建立连接时的回调函数。
20
21**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
22
23**参数：**
24
25| 参数名       | 类型                     | 必填   | 说明            |
26| -------- | ---------------------- | ---- | ------------- |
27| elementName | [ElementName](js-apis-bundleManager-elementName.md) | 是    | Ability的elementName。 |
28| remote | [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | 是    | IRemoteObject实例。 |
29
30**示例：**
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
65断开连接时的回调函数。
66
67**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
68
69**参数：**
70
71| 参数名       | 类型                     | 必填   | 说明            |
72| -------- | ---------------------- | ---- | ------------- |
73| elementName | [ElementName](js-apis-bundleManager-elementName.md) | 是    | Ability的elementName。 |
74
75**示例：**
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
110连接失败时的回调函数。
111
112**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
113
114**参数：**
115
116| 参数名       | 类型                     | 必填   | 说明            |
117| -------- | ---------------------- | ---- | ------------- |
118| code | number | 是    | 连接指定Ability返回的结果code。<br>值为0表示连接成功，值为-1表示参数错误，值为-2表示未找到对应Ability。 |
119
120**示例：**
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