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