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