@ohos.app.ability.insightIntentDriver (Executing InsightIntent Calls) (System API)

The insightIntentDriver module provides APIs for executing InsightIntent calls. The system executes InsightIntent calls based on user interaction and more.

NOTE

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.

The APIs of this module can be used only in the stage model.

The APIs provided by this module are system APIs.

Modules to Import

import { insightIntentDriver } from '@kit.AbilityKit';

ExecuteParam

Defines the parameter used to execute an InsightIntent call.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Type	Mandatory	Description
bundleName	string	Yes	Name of the bundle to which the ability to be called belongs.
moduleName	string	Yes	Name of the module to which the ability belongs.
abilityName	string	Yes	Name of the ability to be called.
insightIntentName	string	Yes	InsightIntent name.
insightIntentParam	string	Yes	InsightIntent call parameter.
executeMode	insightIntent.ExecuteMode	Yes	InsightIntent call execution mode.
displayId¹²⁺	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.

insightIntentDriver.execute

execute(param: ExecuteParam, callback: AsyncCallback<insightIntent.ExecuteResult>): void

Executes a call to an InsightIntent. This API uses an asynchronous callback to return the result.

When the caller is in the background, the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission is required.

When ExecuteMode of the InsightIntent call is set to UI_ABILITY_BACKGROUND, the ohos.permission.ABILITY_BACKGROUND_COMMUNICATION permission is required.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Required permissions: ohos.permission.EXECUTE_INSIGHT_INTENT

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
param	ExecuteParam	Yes	Parameter used to execute the InsightIntent call.
callback	AsyncCallback<insightIntent.ExecuteResult>	Yes	Callback used to return the InsightIntent call execution result.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.

Example

  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  function executeInsightIntentAsync() {
    let param: insightIntentDriver.ExecuteParam = {
      bundleName: 'com.ohos.intentexecutedemo',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      insightIntentName: 'PlayMusic',
      insightIntentParam: {
        songName: 'City Of Stars',
      },
      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
    };

    try {
      insightIntentDriver.execute(param, (error, data: insightIntent.ExecuteResult) => {
        if (error) {
          hilog.error(0x0000, 'testTag', 'execute insight intent failed with %{public}s', JSON.stringify(error));
        } else {
          hilog.info(0x0000, 'testTag', '%{public}s', 'execute insight intent succeed');
        }
        hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', data.code);
        hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(data.result));
      })
    } catch (error) {
      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
    }
  }

insightIntentDriver.execute

execute(param: ExecuteParam): Promise<insightIntent.ExecuteResult>

Executes a call to an InsightIntent. This API uses a promise to return the result.

When the caller is in the background, the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission is required.

When ExecuteMode of the InsightIntent call is set to UI_ABILITY_BACKGROUND, the ohos.permission.ABILITY_BACKGROUND_COMMUNICATION permission is required.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Required permissions: ohos.permission.EXECUTE_INSIGHT_INTENT

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
param	ExecuteParam	Yes	Parameter used to execute the InsightIntent call.

Return value

Type	Description
Promise<insightIntent.ExecuteResult>	Promise used to return the InsightIntent call execution result.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	Permission denied.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.

Example

  import { insightIntentDriver, insightIntent } from '@kit.AbilityKit';
  import { hilog } from '@kit.PerformanceAnalysisKit';

  async function executeSearchMusicIntentPromise() {
    let param: insightIntentDriver.ExecuteParam = {
      bundleName: 'com.ohos.intentexecutedemo',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      insightIntentName: 'PlayMusic',
      insightIntentParam: {
        songName: 'City Of Stars',
      },
      executeMode: insightIntent.ExecuteMode.UI_ABILITY_FOREGROUND,
    };

    try {
      let resultData: insightIntent.ExecuteResult = await insightIntentDriver.execute(param);
      hilog.info(0x0000, 'testTag', 'execute insight intent return %{public}d', resultData.code);
      hilog.info(0x0000, 'testTag', 'execute insight intent result %{public}s', JSON.stringify(resultData.result));
    } catch (error) {
      hilog.error(0x0000, 'testTag', 'execute insight intent error caught %{public}s', JSON.stringify(error));
    }
  }