1# @ohos.app.ability.dialogSession (dialogSession) (System API)
2
3The **dialogSession** module provides APIs related to the dialog box.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs of this module can be used only in the stage model.
10>
11> The APIs provided by this module are system APIs.
12
13## Modules to Import
14
15```ts
16import { dialogSession } from '@kit.AbilityKit';
17```
18
19## DialogAbilityInfo
20
21Provides DialogAbility information, including the bundle name, module name, and ability name.
22
23**System capability**: SystemCapability.Ability.AbilityRuntime.Core
24
25| Name| Type| Read-only| Mandatory| Description|
26| -------- | -------- | -------- | -------- | -------- |
27| bundleName | string | Yes| Yes| Bundle name.|
28| moduleName | string | Yes| Yes| Module name.|
29| abilityName | string | Yes| Yes| Ability name.|
30| abilityIconId | number | Yes| Yes| ID of the ability icon.|
31| abilityLabelId | number | Yes| Yes| ID of the ability label.|
32| bundleIconId | number | Yes| Yes| ID of the bundle icon.|
33| bundleLabelId | number | Yes| Yes| ID of the bundle label.|
34| visible<sup>12+</sup> | boolean | Yes| Yes| Whether the ability is visible.|
35| appIndex<sup>12+</sup> | number | Yes| Yes| Index of the application clone.|
36| multiAppMode<sup>12+</sup> | [MultiAppMode](./js-apis-bundleManager-applicationInfo.md#multiappmode12) | Yes| Yes| Multi-app mode.|
37
38## DialogSessionInfo
39
40Provides session information, including the requester information, target application list, and other parameters.
41
42**System capability**: SystemCapability.Ability.AbilityRuntime.Core
43
44| Name| Type| Read-only| Mandatory| Description|
45| -------- | -------- | -------- | -------- | -------- |
46| callerAbilityInfo | [DialogAbilityInfo](#dialogabilityinfo)| Yes| Yes| Ability information of the requester.|
47| targetAbilityInfos | Array\<[DialogAbilityInfo](#dialogabilityinfo)\> | Yes| Yes| Target application list.|
48| parameters | Record<string, Object> | Yes| No| Other parameters.|
49
50## getDialogSessionInfo
51
52getDialogSessionInfo(dialogSessionId: string): [DialogSessionInfo](#dialogsessioninfo)
53
54Obtains the session information based on the session ID.
55
56**System API**: This is a system API.
57
58**System capability**: SystemCapability.Ability.AbilityRuntime.Core
59
60**Parameters**
61
62  | Name| Type| Mandatory| Description|
63  | -------- | -------- | -------- | -------- |
64  | dialogSessionId | string | Yes| Session ID.|
65
66**Return value**
67
68  | Type| Description|
69  | -------- | -------- |
70  | [DialogSessionInfo](#dialogsessioninfo) | Session information.|
71
72**Error codes**
73
74For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
75
76| ID| Error Message|
77| ------- | -------- |
78| 202 | Not System App. Interface caller is not a system app. |
79| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. 3. Parameter verification failed. |
80| 16000005 | The specified process does not have the permission. |
81| 16000006  | Cross-user operations are not allowed. |
82| 16000050  | Internal error. |
83
84**Example**
85
86```ts
87import { dialogSession, Want } from '@kit.AbilityKit';
88
89// want is specified by the system. dialogSessionId is a built-in parameter.
90let dialogSessionId: string = want?.parameters?.dialogSessionId;
91
92// Obtain DialogSessionInfo.
93let dialogSessionInfo: dialogSession.DialogSessionInfo = dialogSession.getDialogSessionInfo(dialogSessionId);
94```
95
96## sendDialogResult
97
98sendDialogResult(dialogSessionId: string, targetWant: Want, isAllowed: boolean, callback: AsyncCallback\<void\>): void
99
100Sends a request for a dialog box. This API uses an asynchronous callback to return the result.
101
102**System API**: This is a system API.
103
104**System capability**: SystemCapability.Ability.AbilityRuntime.Core
105
106**Parameters**
107
108  | Name| Type| Mandatory| Description|
109  | -------- | -------- | -------- | -------- |
110  | dialogSessionId | string | Yes| Session ID.|
111  | targetWant | Want | Yes| Target of the request.|
112  | isAllowed | boolean | Yes| Request result.|
113  | callback | AsyncCallback\<void\> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
114
115**Error codes**
116
117For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
118
119| ID| Error Message|
120| ------- | -------- |
121| 202 | Not System App. Interface caller is not a system app. |
122| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. 3. Parameter verification failed. |
123| 16000005 | The specified process does not have the permission. |
124| 16000006  | Cross-user operations are not allowed. |
125| 16000050  | Internal error. |
126
127**Example**
128
129```ts
130import { dialogSession, Want } from '@kit.AbilityKit';
131import { BusinessError } from '@kit.BasicServicesKit';
132
133// want is specified by the system. dialogSessionId is a built-in parameter.
134let dialogSessionId: string = want?.parameters?.dialogSessionId;
135
136// Obtain DialogSessionInfo.
137let dialogSessionInfo: dialogSession.DialogSessionInfo = dialogSession.getDialogSessionInfo(dialogSessionId);
138
139let isAllow: boolean = true;
140
141// When isAllow is true, targetWant is one of dialogSessionInfo.targetAbilityInfos.
142let targetWant: Want = {
143  bundleName: 'com.example.myapplication',
144  abilityName: 'EntryAbility'
145};
146
147try {
148  dialogSession.sendDialogResult(dialogSessionId, targetWant, isAllow, (err, data) => {
149    if (err) {
150      console.error(`sendDialogResult error, errorCode: ${err.code}`);
151    } else {
152      console.log(`sendDialogResult success`);
153    }
154  });
155} catch (err) {
156  console.error(`sendDialogResult error, errorCode: ${(err as BusinessError).code}`);
157}
158```
159
160## sendDialogResult
161
162sendDialogResult(dialogSessionId: string, targetWant: Want, isAllowed: boolean): Promise\<void\>
163
164Sends a request for a dialog box. This API uses a promise to return the result.
165
166**System API**: This is a system API.
167
168**System capability**: SystemCapability.Ability.AbilityRuntime.Core
169
170**Parameters**
171
172  | Name| Type| Mandatory| Description|
173  | -------- | -------- | -------- | -------- |
174  | dialogSessionId | string | Yes| Session ID.|
175  | targetWant | Want | Yes| Target of the request.|
176  | isAllowed | boolean | Yes| Request result.|
177
178**Return value**
179
180| Type| Description|
181| -------- | -------- |
182| Promise&lt;void&gt; | Promise that returns no value.|
183
184**Error codes**
185
186For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
187
188| ID| Error Message|
189| ------- | -------- |
190| 202 | Not System App. Interface caller is not a system app. |
191| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. 3. Parameter verification failed. |
192| 16000005 | The specified process does not have the permission. |
193| 16000006  | Cross-user operations are not allowed. |
194| 16000050  | Internal error. |
195
196**Example**
197
198```ts
199import { dialogSession, Want } from '@kit.AbilityKit';
200import { BusinessError } from '@kit.BasicServicesKit';
201
202// want is specified by the system. dialogSessionId is a built-in parameter.
203let dialogSessionId: string = want?.parameters?.dialogSessionId;
204
205// Obtain DialogSessionInfo.
206let dialogSessionInfo: dialogSession.DialogSessionInfo = dialogSession.getDialogSessionInfo(dialogSessionId);
207
208let isAllow: boolean = true;
209
210// When isAllow is true, targetWant is one of dialogSessionInfo.targetAbilityInfos.
211let targetWant: Want = {
212  bundleName: 'com.example.myapplication',
213  abilityName: 'EntryAbility'
214};
215
216try {
217  dialogSession.sendDialogResult(dialogSessionId, targetWant, isAllow)
218    .then((data) => {
219      console.log(`startChildProcess success, pid: ${data}`);
220    }, (err: BusinessError) => {
221      console.error(`startChildProcess error, errorCode: ${err.code}`);
222    })
223} catch (err) {
224  console.error(`sendDialogResult error, errorCode: ${(err as BusinessError).code}`);
225}
226```
227