1# @ohos.app.ability.insightIntentDriver (Executing InsightIntent Calls) (System API)
2
3The **insightIntentDriver** module provides APIs for executing InsightIntent calls. The system executes InsightIntent calls based on user interaction and more.
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 { insightIntentDriver } from '@kit.AbilityKit';
17```
18
19## ExecuteParam
20
21Defines the parameter used to execute an InsightIntent call.
22
23**Model restriction**: This API can be used only in the stage model.
24
25**System API**: This is a system API and cannot be called by third-party applications.
26
27**System capability**: SystemCapability.Ability.AbilityRuntime.Core
28
29| Name| Type| Mandatory| Description|
30| -------- | -------- | -------- | -------- |
31| bundleName | string | Yes| Name of the bundle to which the ability to be called belongs.|
32| moduleName | string | Yes| Name of the module to which the ability belongs.|
33| abilityName | string | Yes| Name of the ability to be called.|
34| insightIntentName | string | Yes| InsightIntent name.|
35| insightIntentParam | string | Yes| InsightIntent call parameter.|
36| executeMode | [insightIntent.ExecuteMode](js-apis-app-ability-insightIntent.md#executemode) | Yes| InsightIntent call execution mode.|
37| displayId<sup>12+</sup> | number | No| Physical screen ID specified during InsightIntent call. The value must be an integer. This parameter is valid only when **executeMode** is set to **UI_ABILITY_FOREGROUND**.|
38
39## insightIntentDriver.execute
40
41execute(param: ExecuteParam, callback: AsyncCallback<insightIntent.ExecuteResult>): void
42
43Executes a call to an InsightIntent. This API uses an asynchronous callback to return the result.
44
45When the caller is in the background, the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission is required.
46
47When [ExecuteMode](js-apis-app-ability-insightIntent.md#executemode) of the InsightIntent call is set to **UI_ABILITY_BACKGROUND**, the ohos.permission.ABILITY_BACKGROUND_COMMUNICATION permission is required.
48
49**Model restriction**: This API can be used only in the stage model.
50
51**System API**: This is a system API and cannot be called by third-party applications.
52
53**Required permissions**: ohos.permission.EXECUTE_INSIGHT_INTENT
54
55**System capability**: SystemCapability.Ability.AbilityRuntime.Core
56
57**Parameters**
58
59  | Name| Type| Mandatory| Description|
60  | -------- | -------- | -------- | -------- |
61  | param | [ExecuteParam](#executeparam) | Yes| Parameter used to execute the InsightIntent call.|
62  | callback | AsyncCallback<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Yes| Callback used to return the InsightIntent call execution result.|
63
64**Error codes**
65
66For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
67
68| ID| Error Message|
69| -------- | -------- |
70| 201      | Permission denied. |
71| 202      | Not system application. |
72| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
73| 16000001 | The specified ability does not exist. |
74| 16000002 | Incorrect ability type. |
75| 16000004 | Failed to start the invisible ability. |
76| 16000005 | The specified process does not have the permission. |
77| 16000006 | Cross-user operations are not allowed. |
78| 16000008 | The crowdtesting application expires. |
79| 16000009 | An ability cannot be started or stopped in Wukong mode. |
80| 16000010 | The call with the continuation flag is forbidden. |
81| 16000011 | The context does not exist.        |
82| 16000012 | The application is controlled.        |
83| 16000013 | The application is controlled by EDM.       |
84| 16000050 | Internal error. |
85| 16000053 | The ability is not on the top of the UI. |
86| 16000055 | Installation-free timed out. |
87
88**Example**
89
90```ts
91  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
92  import { hilog } from '@kit.PerformanceAnalysisKit';
93
94  function executeInsightIntentAsync() {
95    let param: insightIntentDriver.ExecuteParam = {
96      bundleName: 'com.ohos.intentexecutedemo',
97      moduleName: 'entry',
98      abilityName: 'EntryAbility',
99      insightIntentName: 'PlayMusic',
100      insightIntentParam: {
101        songName: 'City Of Stars',
102      },
103      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
104    };
105
106    try {
107      insightIntentDriver.execute(param, (error, data: insightIntent.ExecuteResult) => {
108        if (error) {
109          hilog.error(0x0000, 'testTag', 'execute insight intent failed with %{public}s', JSON.stringify(error));
110        } else {
111          hilog.info(0x0000, 'testTag', '%{public}s', 'execute insight intent succeed');
112        }
113        hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', data.code);
114        hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(data.result));
115      })
116    } catch (error) {
117      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
118    }
119  }
120```
121
122## insightIntentDriver.execute
123
124execute(param: ExecuteParam): Promise<insightIntent.ExecuteResult>
125
126Executes a call to an InsightIntent. This API uses a promise to return the result.
127
128When the caller is in the background, the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission is required.
129
130When [ExecuteMode](js-apis-app-ability-insightIntent.md#executemode) of the InsightIntent call is set to **UI_ABILITY_BACKGROUND**, the ohos.permission.ABILITY_BACKGROUND_COMMUNICATION permission is required.
131
132**Model restriction**: This API can be used only in the stage model.
133
134**System API**: This is a system API and cannot be called by third-party applications.
135
136**Required permissions**: ohos.permission.EXECUTE_INSIGHT_INTENT
137
138**System capability**: SystemCapability.Ability.AbilityRuntime.Core
139
140**Parameters**
141
142  | Name| Type| Mandatory| Description|
143  | -------- | -------- | -------- | -------- |
144  | param | [ExecuteParam](#executeparam) | Yes| Parameter used to execute the InsightIntent call.|
145
146**Return value**
147
148| Type| Description|
149| -------- | -------- |
150| Promise<[insightIntent.ExecuteResult](js-apis-app-ability-insightIntent.md#executeresult)> | Promise used to return the InsightIntent call execution result.|
151
152**Error codes**
153
154For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
155
156| ID| Error Message|
157| -------- | -------- |
158| 201      | Permission denied. |
159| 202      | Not system application. |
160| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
161| 16000001 | The specified ability does not exist. |
162| 16000002 | Incorrect ability type. |
163| 16000004 | Failed to start the invisible ability. |
164| 16000005 | The specified process does not have the permission. |
165| 16000006 | Cross-user operations are not allowed. |
166| 16000008 | The crowdtesting application expires. |
167| 16000009 | An ability cannot be started or stopped in Wukong mode. |
168| 16000010 | The call with the continuation flag is forbidden. |
169| 16000011 | The context does not exist.        |
170| 16000012 | The application is controlled.        |
171| 16000013 | The application is controlled by EDM.       |
172| 16000050 | Internal error. |
173| 16000053 | The ability is not on the top of the UI. |
174| 16000055 | Installation-free timed out. |
175
176**Example**
177
178```ts
179  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
180  import { hilog } from '@kit.PerformanceAnalysisKit';
181
182  async function executeSearchMusicIntentPromise() {
183    let param: insightIntentDriver.ExecuteParam = {
184      bundleName: 'com.ohos.intentexecutedemo',
185      moduleName: 'entry',
186      abilityName: 'EntryAbility',
187      insightIntentName: 'PlayMusic',
188      insightIntentParam: {
189        songName: 'City Of Stars',
190      },
191      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
192    };
193
194    try {
195      let resultData: insightIntent.ExecuteResult = await insightIntentDriver.execute(param);
196      hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', resultData.code);
197      hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(resultData.result));
198    } catch (error) {
199      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
200    }
201  }
202```
203