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