• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ConnectOptions
2<!--Kit: Ability Kit-->
3<!--Subsystem: Ability-->
4<!--Owner: @yewei0794-->
5<!--Designer: @jsjzju-->
6<!--Tester: @lixueqing513-->
7<!--Adviser: @huipeizi-->
8
9**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#connectserviceextensionability) to connect to a ServiceExtensionAbility.
10
11> **NOTE**
12>
13> 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.
14
15## Modules to Import
16
17```ts
18import { common } from '@kit.AbilityKit';
19```
20
21## ConnectOptions
22
23### onConnect
24
25onConnect(elementName: ElementName, remote: rpc.IRemoteObject): void
26
27Callback invoked when a connection is set up.
28
29**System capability**: SystemCapability.Ability.AbilityRuntime.Core
30
31**Parameters**
32
33| Name      | Type                    | Mandatory  | Description           |
34| -------- | ---------------------- | ---- | ------------- |
35| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes   | Element name of the ability.|
36| remote | [rpc.IRemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | Yes   | IRemoteObject instance.|
37
38**Example**
39
40```ts
41import { UIAbility, common, Want, AbilityConstant } from '@kit.AbilityKit';
42import { bundleManager } from '@kit.AbilityKit';
43import { rpc } from '@kit.IPCKit';
44
45let connectWant: Want = {
46  bundleName: 'com.example.myapp',
47  abilityName: 'MyAbility'
48};
49
50let connectOptions: common.ConnectOptions = {
51  onConnect(elementName: bundleManager.ElementName, remote: rpc.IRemoteObject) {
52    console.log(`onConnect elementName: ${elementName}`);
53  },
54  onDisconnect(elementName: bundleManager.ElementName) {
55    console.log(`onDisconnect elementName: ${elementName}`);
56  },
57  onFailed(code: number) {
58    console.error(`onFailed code: ${code}`);
59  }
60};
61
62class EntryAbility extends UIAbility {
63  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
64    let connection: number = this.context.connectServiceExtensionAbility(connectWant, connectOptions);
65  }
66}
67```
68
69### onDisconnect
70
71onDisconnect(elementName: ElementName): void
72
73Callback invoked when a connection is interrupted.
74
75**System capability**: SystemCapability.Ability.AbilityRuntime.Core
76
77**Parameters**
78
79| Name      | Type                    | Mandatory  | Description           |
80| -------- | ---------------------- | ---- | ------------- |
81| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes   | Element name of the ability.|
82
83**Example**
84
85```ts
86import { UIAbility, common, Want, AbilityConstant } from '@kit.AbilityKit';
87import { bundleManager } from '@kit.AbilityKit';
88import { rpc } from '@kit.IPCKit';
89
90let connectWant: Want = {
91  bundleName: 'com.example.myapp',
92  abilityName: 'MyAbility'
93};
94
95let connectOptions: common.ConnectOptions = {
96  onConnect(elementName: bundleManager.ElementName, remote: rpc.IRemoteObject) {
97    console.log(`onConnect elementName: ${elementName}`);
98  },
99  onDisconnect(elementName: bundleManager.ElementName) {
100    console.log(`onDisconnect elementName: ${elementName}`);
101  },
102  onFailed(code: number) {
103    console.error(`onFailed code: ${code}`);
104  }
105};
106
107class EntryAbility extends UIAbility {
108  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
109    let connection: number = this.context.connectServiceExtensionAbility(connectWant, connectOptions);
110  }
111}
112```
113
114### onFailed
115
116onFailed(code: number): void
117
118Callback invoked when a connection fails.
119
120**System capability**: SystemCapability.Ability.AbilityRuntime.Core
121
122**Parameters**
123
124| Name      | Type                    | Mandatory  | Description           |
125| -------- | ---------------------- | ---- | ------------- |
126| 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.|
127
128**Example**
129
130```ts
131import { UIAbility, common, Want, AbilityConstant } from '@kit.AbilityKit';
132import { bundleManager } from '@kit.AbilityKit';
133import { rpc } from '@kit.IPCKit';
134
135let connectWant: Want = {
136  bundleName: 'com.example.myapp',
137  abilityName: 'MyAbility'
138};
139
140let connectOptions: common.ConnectOptions = {
141  onConnect(elementName: bundleManager.ElementName, remote: rpc.IRemoteObject) {
142    console.log(`onConnect elementName: ${elementName}`);
143  },
144  onDisconnect(elementName: bundleManager.ElementName) {
145    console.log(`onDisconnect elementName: ${elementName}`);
146  },
147  onFailed(code: number) {
148    console.error(`onFailed code: ${code}`);
149  }
150};
151
152class EntryAbility extends UIAbility {
153  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
154    let connection: number = this.context.connectServiceExtensionAbility(connectWant, connectOptions);
155  }
156}
157```
158