@ohos.app.ability.abilityManager (AbilityManager) (System API)

The AbilityManager module provides APIs for obtaining, adding, and updating ability information and running status information.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. The APIs of this module are system APIs and cannot be called by third-party applications.

Modules to Import

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

UserStatus¹²⁺

Enumerates the assertion result for different user operations.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Value	Description
ASSERT_TERMINATE	0	Assertion result of the terminate operation.
ASSERT_CONTINUE	1	Assertion result of the continue operation.
ASSERT_RETRY	2	Assertion result of the retry operation.

updateConfiguration

updateConfiguration(config: Configuration, callback: AsyncCallback<void>): void

Updates the configuration. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
config	Configuration	Yes	New configuration. You only need to configure the items to be updated.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the API call is successful, err is undefined. Otherwise, err is an error object. You can perform error handling or other custom processing.

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; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager, Configuration, ConfigurationConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

const config: Configuration = {
  language: 'Zh-Hans',                 // Simplified Chinese
  colorMode: ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT,         // Light theme.
  direction: ConfigurationConstant.Direction.DIRECTION_VERTICAL,       // Vertical direction.
  screenDensity: ConfigurationConstant.ScreenDensity.SCREEN_DENSITY_SDPI,  // The screen pixel density is sdpi.
  displayId: 1,                        // The application is displayed on the display with ID 1.
  hasPointerDevice: true,              // A pointer device is connected.
};

try {
  abilityManager.updateConfiguration(config, (err: BusinessError) => {
    if (err) {
      console.error(`updateConfiguration fail, err: ${JSON.stringify(err)}`);
    } else {
      console.info('updateConfiguration success.');
    }
  });
} catch (paramError) {
  let code: number = (paramError as BusinessError).code;
  let message: string = (paramError as BusinessError).message;
  console.error(`error.code: ${code}, error.message: ${message}`);
}

updateConfiguration

updateConfiguration(config: Configuration): Promise<void>

Updates the configuration. This API uses a promise to return the result.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
config	Configuration	Yes	New configuration. You only need to configure the items to be updated.

Return value

Type	Description
Promise<void>	Promise that returns no value. You can perform error handling or other custom processing.

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; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager, Configuration, ConfigurationConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

const config: Configuration = {
  language: 'Zh-Hans',                 // Simplified Chinese
  colorMode: ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT,         // Light theme.
  direction: ConfigurationConstant.Direction.DIRECTION_VERTICAL,       // Vertical direction.
  screenDensity: ConfigurationConstant.ScreenDensity.SCREEN_DENSITY_SDPI,  // The screen pixel density is sdpi.
  displayId: 1,                        // The application is displayed on the display with ID 1.
  hasPointerDevice: true,              // A pointer device is connected.
};

try {
  abilityManager.updateConfiguration(config).then(() => {
    console.info('updateConfiguration success.');
  }).catch((err: BusinessError) => {
    console.error(`updateConfiguration fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code: number = (paramError as BusinessError).code;
  let message: string = (paramError as BusinessError).message;
  console.error(`error.code: ${code}, error.message: ${message}`);
}

getAbilityRunningInfos

getAbilityRunningInfos(callback: AsyncCallback<Array<AbilityRunningInfo>>): void

Obtains the UIAbility running information. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<AbilityRunningInfo>>	Yes	Callback used to return the result. If the API call is successful, err is undefined and data is the UIAbility running information obtained. Otherwise, err is an error object. You can perform error handling or other custom processing.

Error codes

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

NOTE

This API does not return error code 202 since API version 14.

ID	Error Message
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  abilityManager.getAbilityRunningInfos((err: BusinessError, data: Array<abilityManager.AbilityRunningInfo>) => {
    if (err) {
      console.error(`getAbilityRunningInfos fail, error: ${JSON.stringify(err)}`);
    } else {
      console.info(`getAbilityRunningInfos success, data: ${JSON.stringify(data)}`);
    }
  });
} catch (paramError) {
  let code: number = (paramError as BusinessError).code;
  let message: string = (paramError as BusinessError).message;
  console.error(`error.code: ${code}, error.message: ${message}`);
}

getExtensionRunningInfos

getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback<Array<ExtensionRunningInfo>>): void

Obtains the ExtensionAbility running information. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
upperLimit	number	Yes	Maximum number of messages that can be obtained. The maximum value is 2³¹-1.
callback	AsyncCallback<Array<ExtensionRunningInfo>>	Yes	Callback used to return the result. If the API call is successful, err is undefined and data is the ExtensionAbility running information obtained. Otherwise, err is an error object. You can perform error handling or other custom processing.

Error codes

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

ID	Error Message
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let upperLimit = 10;

try {
  abilityManager.getExtensionRunningInfos(upperLimit, (err: BusinessError, data: Array<abilityManager.ExtensionRunningInfo>) => {
    if (err) {
      console.error(`getExtensionRunningInfos fail, err: ${JSON.stringify(err)}`);
    } else {
      console.info(`getExtensionRunningInfos success, data: ${JSON.stringify(data)}`);
    }
  });
} catch (paramError) {
  let code: number = (paramError as BusinessError).code;
  let message: string = (paramError as BusinessError).message;
  console.error(`error.code: ${code}, error.message: ${message}`);
}

getExtensionRunningInfos

getExtensionRunningInfos(upperLimit: number): Promise<Array<ExtensionRunningInfo>>

Obtains the ExtensionAbility running information. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
upperLimit	number	Yes	Maximum number of messages that can be obtained. The maximum value is 2³¹-1.

Return value

Type	Description
Promise<Array<ExtensionRunningInfo>>	Promise used to return the API call result and the ExtensionAbility running information. You can perform error handling or other custom processing.

Error codes

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

ID	Error Message
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let upperLimit = 10;

try {
  abilityManager.getExtensionRunningInfos(upperLimit).then((data: Array<abilityManager.ExtensionRunningInfo>) => {
    console.info(`getExtensionRunningInfos success, data: ${JSON.stringify(data)}`);
  }).catch((err: BusinessError) => {
    console.error(`getExtensionRunningInfos fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code: number = (paramError as BusinessError).code;
  let message: string = (paramError as BusinessError).message;
  console.error(`error.code: ${code}, error.message: ${message}`);
}

getTopAbility

getTopAbility(callback: AsyncCallback<ElementName>): void

Obtains the top ability, which is the ability that has the window focus. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<ElementName>	Yes	Callback used to return the result. If the API call is successful, err is undefined and data is the top ability name obtained. Otherwise, err is an error object. You can perform error handling or other custom processing.

Error codes

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

ID	Error Message
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

abilityManager.getTopAbility((err: BusinessError, data) => {
  if (err) {
    console.error(`getTopAbility fail, err: ${JSON.stringify(err)}`);
  } else {
    console.info(`getTopAbility success, data: ${JSON.stringify(data)}`);
  }
});

getTopAbility

getTopAbility(): Promise<ElementName>

Obtains the top ability, which is the ability that has the window focus. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Type	Description
Promise<ElementName>	Promise used to return the API call result and the element name. You can perform error handling or other custom processing.

Error codes

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

ID	Error Message
202	Not System App. Interface caller is not a system app.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

abilityManager.getTopAbility().then((data) => {
  console.info(`getTopAbility success, data: ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`getTopAbility fail, err: ${JSON.stringify(err)}`);
});

acquireShareData¹⁰⁺

acquireShareData(missionId: number, callback: AsyncCallback<Record<string, Object>>): void

Called by a system dialog box to obtain shared data, which is set by the target UIAbility through onShare. This API uses an asynchronous callback to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
missionId	number	Yes	Mission ID on the target application. The maximum value is 2³¹-1.
callback	AsyncCallback<Record<string, Object>>	Yes	Callback used to return the result. If the API call is successful, err is undefined and data is the shared data obtained. Otherwise, err is an error object. You can perform error handling or other custom processing.

Error codes

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

ID	Error Message
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  abilityManager.acquireShareData(1, (err: BusinessError, wantParam: Record<string, Object>) => {
    if (err) {
      console.error(`acquireShareData fail, err: ${JSON.stringify(err)}`);
    } else {
      console.info(`acquireShareData success, data: ${JSON.stringify(wantParam)}`);
    }
  });
} catch (paramError) {
  let code: number = (paramError as BusinessError).code;
  let message: string = (paramError as BusinessError).message;
  console.error(`error.code: ${code}, error.message: ${message}`);
}

acquireShareData¹⁰⁺

acquireShareData(missionId: number): Promise<Record<string, Object>>

Called by a system dialog box to obtain shared data, which is set by the target UIAbility through onShare. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
missionId	number	Yes	Mission ID on the target application. The maximum value is 2³¹-1.

Return value

Type	Description
Promise<Record<string, Object>>	Promise used to return the API call result and the shared data. You can perform error handling or other custom processing.

Error codes

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

ID	Error Message
202	Not System App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  abilityManager.acquireShareData(1).then((wantParam: Record<string, Object>) => {
    console.info(`acquireShareData success, data: ${JSON.stringify(wantParam)}`);
  }).catch((err: BusinessError) => {
    console.error(`acquireShareData fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code: number = (paramError as BusinessError).code;
  let message: string = (paramError as BusinessError).message;
  console.error(`error.code: ${code}, error.message: ${message}`);
}

notifySaveAsResult¹⁰⁺

notifySaveAsResult(parameter: AbilityResult, requestCode: number, callback: AsyncCallback<void>): void

Used by the Data Loss Prevention (DLP) management application to notify a sandbox application of the data saving result. This API uses an asynchronous callback to return the result.

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

Parameters

Name	Type	Mandatory	Description
parameter	AbilityResult	Yes	Information returned to the caller.
requestCode	number	Yes	Request code passed in by the DLP management application.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the API call is successful, err is undefined; otherwise, err is an error object.

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 App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let want: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let resultCode = 100;
// AbilityResult information returned to the initiator of the save-as behavior.
let abilityResult: common.AbilityResult = {
  want,
  resultCode
};
let requestCode = 1;
try {
  abilityManager.notifySaveAsResult(abilityResult, requestCode, (err: BusinessError) => {
    if (err && err.code != 0) {
      console.error(`notifySaveAsResult fail, err: ${JSON.stringify(err)}`);
    } else {
      console.info(`notifySaveAsResult success`);
    }
  });
} catch (paramError) {
  let code: number = (paramError as BusinessError).code;
  let message: string = (paramError as BusinessError).message;
  console.error(`error.code: ${code}, error.message: ${message}`);
}

notifySaveAsResult¹⁰⁺

notifySaveAsResult(parameter: AbilityResult, requestCode: number): Promise<void>

Used by the Data Loss Prevention (DLP) management application to notify a sandbox application of the data saving result. This API uses a promise to return the result.

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

Parameters

Name	Type	Mandatory	Description
parameter	AbilityResult	Yes	Information returned to the caller.
requestCode	number	Yes	Request code passed in by the DLP management application.

Return value

Type	Description
Promise<void>	Promise that returns no value.

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 App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let want: Want = {
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let resultCode = 100;
// AbilityResult information returned to the initiator of the save-as behavior.
let abilityResult: common.AbilityResult = {
  want,
  resultCode
};
let requestCode = 1;
try {
  abilityManager.notifySaveAsResult(abilityResult, requestCode).then(() => {
    console.info(`notifySaveAsResult success`);
  }).catch((err: BusinessError) => {
    console.error(`notifySaveAsResult fail, err: ${JSON.stringify(err)}`);
  });
} catch (paramError) {
  let code: number = (paramError as BusinessError).code;
  let message: string = (paramError as BusinessError).message;
  console.error(`error.code: ${code}, error.message: ${message}`);
}

abilityManager.on('abilityForegroundState')¹¹⁺

on(type: 'abilityForegroundState', observer: AbilityForegroundStateObserver): void

Registers an observer to listen for ability start or exit events.

System API: This is a system API.

Required permissions: ohos.permission.RUNNING_STATE_OBSERVER

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'abilityForegroundState'.
observer	AbilityForegroundStateObserver	Yes	Observer used to listen for ability start or exit events.

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 App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let observer: abilityManager.AbilityForegroundStateObserver = {
  onAbilityStateChanged(abilityStateData) {
    console.info(`onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`);
  },
};
try {
  abilityManager.on('abilityForegroundState', observer);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message} `);
}

abilityManager.off('abilityForegroundState')¹¹⁺

off(type: 'abilityForegroundState', observer?: AbilityForegroundStateObserver): void

Unregisters the observer used to listen for ability start or exit events.

System API: This is a system API.

Required permissions: ohos.permission.RUNNING_STATE_OBSERVER

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. It is fixed at 'abilityForegroundState'.
observer	AbilityForegroundStateObserver	No	Observer used to listen for ability start or exit events. If this parameter is not set, all observers associated with the specified event are deregistered. If this parameter is set, only the specified observer is deregistered.

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 App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let observer_: abilityManager.AbilityForegroundStateObserver | undefined;
// 1. Register an observer to listen for ability start or exit events.
let observer: abilityManager.AbilityForegroundStateObserver = {
  onAbilityStateChanged(abilityStateData: abilityManager.AbilityStateData) {
    console.info(`onAbilityStateChanged: ${JSON.stringify(abilityStateData)}`);
  },
};
try {
  abilityManager.on('abilityForegroundState', observer);
  observer_ = observer;
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message} `);
}

// 2. Deregister the observer.
try {
  abilityManager.off('abilityForegroundState',  observer_);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message} `);
}

abilityManager.getForegroundUIAbilities¹¹⁺

getForegroundUIAbilities(callback: AsyncCallback<Array<AbilityStateData>>): void

Obtains the information about the UIAbility components of an application that is running in the foreground. This API uses an asynchronous callback to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Array<AbilityStateData>>	Yes	Callback used to return the API call result and the UIAbility information. You can perform error handling or custom processing in it.

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 App. Interface caller is not a system app.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

abilityManager.getForegroundUIAbilities((err: BusinessError, data: Array<abilityManager.AbilityStateData>) => {
  if (err) {
    console.error(`Get foreground ui abilities failed, error: ${JSON.stringify(err)}`);
  } else {
    console.info(`Get foreground ui abilities data is: ${JSON.stringify(data)}`);
  }
});

abilityManager.getForegroundUIAbilities¹¹⁺

getForegroundUIAbilities(): Promise<Array<AbilityStateData>>

Obtains the information about the UIAbility components of an application that is running in the foreground. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.GET_RUNNING_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Type	Description
Promise<Array<AbilityStateData>>	Promise used to return the API call result and the UIAbility information. You can perform error handling or custom processing in it.

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 App. Interface caller is not a system app.
16000050	Internal error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

abilityManager.getForegroundUIAbilities().then((data: Array<abilityManager.AbilityStateData>) => {
  console.info(`Get foreground ui abilities data is: ${JSON.stringify(data)}`);
}).catch((error: BusinessError) => {
  console.error(`Get foreground ui abilities failed, error: ${JSON.stringify(error)}`);
});

abilityManager.notifyDebugAssertResult¹²⁺

notifyDebugAssertResult(sessionId: string, status: UserStatus): Promise<void>

Notifies the application of the assertion result. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.NOTIFY_DEBUG_ASSERT_RESULT

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
sessionId	string	Yes	Session ID of the AssertFault.
status	UserStatus	Yes	Assertion result of the user operation.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
202	Not system application.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager, UIExtensionAbility, wantConstant, Want, UIExtensionContentSession } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class UiExtAbility extends UIExtensionAbility {
  onSessionCreate(want: Want, session: UIExtensionContentSession): void {
    let sessionId: string = '';
    if (want.parameters) {
      sessionId = want.parameters[wantConstant.Params.ASSERT_FAULT_SESSION_ID] as string;
    }
    let status = abilityManager.UserStatus.ASSERT_TERMINATE;
    abilityManager.notifyDebugAssertResult(sessionId, status).then(() => {
      console.info('notifyDebugAssertResult success.');
    }).catch((err: BusinessError) => {
      console.error(`notifyDebugAssertResult failed, error: ${JSON.stringify(err)}`);
    });
  }
}

abilityManager.isEmbeddedOpenAllowed¹²⁺

isEmbeddedOpenAllowed(context: Context, appId: string): Promise<boolean>

Checks whether the EmbeddableUIAbility can be started in embedded mode. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Context of the caller.
appId	string	Yes	Unique ID of the application, which is allocated by the cloud.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. true if embedded startup is allowed, false otherwise.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { abilityManager, UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let appId: string = '6918661953712445909';
    try {
      abilityManager.isEmbeddedOpenAllowed(this.context, appId).then((data) => {
        console.info(`isEmbeddedOpenAllowed data: ${JSON.stringify(data)}`);
      }).catch((err: BusinessError) => {
        console.error(`isEmbeddedOpenAllowed failed, code is ${err.code}, message is ${err.message}`);
      });
    } catch (err) {
      // Process input parameter errors.
      console.error(`param is invalid, code is ${err.code}, message is ${err.message}`);
    }
  }
}

abilityManager.setResidentProcessEnabled¹²⁺

setResidentProcessEnabled(bundleName: string, enable: boolean): Promise<void>

Enables or disables the resident process of an application.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name of the resident process.
enable	boolean	Yes	Whether to enable or disable the resident process. true to enable, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
202	Not a system application.
401	Parameter error. Possible cause: 1.Non empty package name needs to be provided, 2.The second parameter needs to provide a Boolean type setting value
16000050	Internal error.
16200006	The caller application can only set the resident status of the configured process.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  let residentProcessBundleName: string = 'com.xxx.xxxxxx';
  let enable: boolean = false;
  abilityManager.setResidentProcessEnabled(residentProcessBundleName, enable)
    .then(() => {
      console.info('setResidentProcessEnabled success.');
    })
    .catch((err: BusinessError) => {
      console.error(`setResidentProcessEnabled fail, err: ${JSON.stringify(err)}`);
    });
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error(`setResidentProcessEnabled failed, code is ${code}, message is ${message}`);
}

abilityManager.preloadUIExtensionAbility²³⁺

preloadUIExtensionAbility(want: Want): Promise<number>

Preloads a UIExtensionAbility instance and returns the instance ID. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.PRELOAD_UI_EXTENSION_ABILITY

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.

Return value

Type	Description
Promise<number>	Promise used to return the ID of the preloaded UIExtensionAbility instance for further clearing or management.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000050	Internal error. Possible causes: 1.Connect to system service failed; 2.Send restart message to system service failed; 3.System service failed to communicate with dependency module. 4.Preload UIExtensionAbility timeout.

Example

import { abilityManager, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  const preloadWant: Want = {
    bundleName: 'com.example.application',
    abilityName: 'EntryBackupAbility',
    moduleName: 'entry',
    parameters: {
      'ability.want.params.uiExtensionType': 'sys/commonUI'
    }
  };

  abilityManager.preloadUIExtensionAbility(preloadWant)
    .then((preloadId: number) => {
      console.info(`preloadUIExtensionAbility success, preloadId: ${preloadId}`);
    })
    .catch((err: BusinessError) => {
      console.error(`preloadUIExtensionAbility fail, err: ${JSON.stringify(err)}`);
    });
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error(`preloadUIExtensionAbility failed, code is ${code}, message is ${message}`);
}

abilityManager.clearPreloadedUIExtensionAbility²³⁺

clearPreloadedUIExtensionAbility(preloadId: number): Promise<void>

Clears a UIExtensionAbility instance. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.PRELOAD_UI_EXTENSION_ABILITY

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
preloadId	number	Yes	ID of a preloaded UIExtensionAbility instance.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
16000003	The specified ID does not exist. Possible causes: 1.The specified ID is incorrect; 2.The preloaded UIExtensionAbility has been loaded; 3.The preloaded UIExtensionAbility has been destroyed;
16000050	Internal error. Possible causes: 1. Connect to system service failed; 2. Send restart message to system service failed; 3. System service failed to communicate with dependency module.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  // ID returned after the preloadUIExtensionAbility API is called to preload a UIExtensionAbility instance.
  let preloadId: number = 1001;
  abilityManager.clearPreloadedUIExtensionAbility(preloadId)
    .then(() => {
      console.info('clearPreloadedUIExtensionAbility success.');
    })
    .catch((err: BusinessError) => {
      console.error(`clearPreloadedUIExtensionAbility fail, err: ${JSON.stringify(err)}`);
    });
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error(`clearPreloadedUIExtensionAbility failed, code is ${code}, message is ${message}`);
}

abilityManager.clearPreloadedUIExtensionAbilities²³⁺

clearPreloadedUIExtensionAbilities(): Promise<void>

Clears all preloaded UIExtensionAbility instances in the current process. This API uses a promise to return the result.

System API: This is a system API.

Required permissions: ohos.permission.PRELOAD_UI_EXTENSION_ABILITY

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
16000050	Internal error. Possible causes: 1. Connect to system service failed; 2. Send restart message to system service failed; 3. System service failed to communicate with dependency module.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  abilityManager.clearPreloadedUIExtensionAbilities()
    .then(() => {
      console.info('clearPreloadedUIExtensionAbilities success.');
    })
    .catch((err: BusinessError) => {
      console.error(`clearPreloadedUIExtensionAbilities fail, err: ${JSON.stringify(err)}`);
    });
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error(`clearPreloadedUIExtensionAbilities failed, code is ${code}, message is ${message}`);
}

abilityManager.onPreloadedUIExtensionAbilityLoaded²³⁺

onPreloadedUIExtensionAbilityLoaded(callback: PreloadedUIExtensionAbilityLoadedFn): void

Subscribes to loaded events of a preloaded UIExtensionAbility instance in the current process.

System API: This is a system API.

Required permissions: ohos.permission.PRELOAD_UI_EXTENSION_ABILITY

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
callback	PreloadedUIExtensionAbilityLoadedFn	Yes	Callback used to receive the ID of the preloaded UIExtensionAbility instance that is loaded.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
16000050	Internal error. Possible causes: Memory operation error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

function onPreloadLoaded(preloadId: number) {
  console.info(`Preloaded UIExtensionAbility loaded, preloadId: ${preloadId}`);
}

try {
  abilityManager.onPreloadedUIExtensionAbilityLoaded(onPreloadLoaded);
  console.info('onPreloadedUIExtensionAbilityLoaded success.');
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error(`onPreloadedUIExtensionAbilityLoaded failed, code is ${code}, message is ${message}`);
}

abilityManager.offPreloadedUIExtensionAbilityLoaded²³⁺

offPreloadedUIExtensionAbilityLoaded(callback?: PreloadedUIExtensionAbilityLoadedFn): void

Unsubscribes from loaded events of a preloaded UIExtensionAbility instance in the current process.

System API: This is a system API.

Required permissions: ohos.permission.PRELOAD_UI_EXTENSION_ABILITY

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
callback	PreloadedUIExtensionAbilityLoadedFn	No	Callback used for unsubscription. If this parameter is not specified, all callbacks associated with the specified event in the process will be unregistered.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
16000050	Internal error. Possible causes: Memory operation error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

function offPreloadLoaded(preloadId: number) {
  console.info(`Preloaded UIExtensionAbility loaded, preloadId: ${preloadId}`);
}

try {
  abilityManager.offPreloadedUIExtensionAbilityLoaded(offPreloadLoaded);
  console.info('offPreloadedUIExtensionAbilityLoaded success.');
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error(`offPreloadedUIExtensionAbilityLoaded failed, code is ${code}, message is ${message}`);
}

abilityManager.onPreloadedUIExtensionAbilityDestroyed²³⁺

onPreloadedUIExtensionAbilityDestroyed(callback: PreloadedUIExtensionAbilityDestroyedFn): void

Subscribes to destroyed events of a preloaded UIExtensionAbility instance in the current process.

System API: This is a system API.

Required permissions: ohos.permission.PRELOAD_UI_EXTENSION_ABILITY

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
callback	PreloadedUIExtensionAbilityDestroyedFn	Yes	Callback used to receive the ID of the preloaded UIExtensionAbility instance that is destroyed.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
16000050	Internal error. Possible causes: Memory operation error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

function onPreloadDestroyed(preloadId: number) {
  console.info(`Preloaded UIExtensionAbility destroyed, preloadId: ${preloadId}`);
}

try {
  abilityManager.onPreloadedUIExtensionAbilityDestroyed(onPreloadDestroyed);
  console.info('onPreloadedUIExtensionAbilityDestroyed success.');
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error(`onPreloadedUIExtensionAbilityDestroyed failed, code is ${code}, message is ${message}`);
}

abilityManager.offPreloadedUIExtensionAbilityDestroyed²³⁺

offPreloadedUIExtensionAbilityDestroyed(callback?: PreloadedUIExtensionAbilityDestroyedFn): void

Unsubscribes from loaded events of a preloaded UIExtensionAbility instance in the current process.

System API: This is a system API.

Required permissions: ohos.permission.PRELOAD_UI_EXTENSION_ABILITY

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
callback	PreloadedUIExtensionAbilityDestroyedFn	No	Callback used for unsubscription. If this parameter is not specified, all callbacks associated with the specified event in the process will be unregistered.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
16000050	Internal error. Possible causes: Memory operation error.

Example

import { abilityManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

function offPreloadDestroyed(preloadId: number) {
  console.info(`Preloaded UIExtensionAbility destroyed, preloadId: ${preloadId}`);
}

try {
  abilityManager.offPreloadedUIExtensionAbilityDestroyed(offPreloadDestroyed);
  console.info('offPreloadedUIExtensionAbilityDestroyed success.');
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error(`offPreloadedUIExtensionAbilityDestroyed failed, code is ${code}, message is ${message}`);
}

AtomicServiceStartupRule¹⁸⁺

Describes the rule for launching an embedded atomic service.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Type	Read-Only	Optional	Description
isOpenAllowed	boolean	No	No	Whether launching the atomic service is allowed. true if allowed, false otherwise.
isEmbeddedAllowed	boolean	No	No	Whether launching the embedded atomic service is allowed. true if allowed, false otherwise.

abilityManager.queryAtomicServiceStartupRule¹⁸⁺

queryAtomicServiceStartupRule(context: Context, appId: string): Promise<AtomicServiceStartupRule>

Obtains the rule for launching an EmbeddableUIAbility in embedded mode. This API uses a promise to return the result.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Device behavior differences: This API can be properly called only on phones and tablets. On other devices, it returns the error code 801.

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Context of the caller. Note: Currently, only UIAbilityContext is supported.
appId	string	Yes	Unique ID of the application, which is allocated by the cloud.

Return value

Type	Description
Promise<AtomicServiceStartupRule>	Promise used to return the rule for launching the embedded atomic service.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not support.
16000050	Internal error.

Example

import { abilityManager, UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let appId: string = '6918661953712445909';
    try {
      abilityManager.queryAtomicServiceStartupRule(this.context, appId).then((data: abilityManager.AtomicServiceStartupRule) => {
        console.info(`queryAtomicServiceStartupRule data: ${JSON.stringify(data)}`);
      }).catch((err: BusinessError) => {
        console.error(`queryAtomicServiceStartupRule failed, code is ${err.code}, message is ${err.message}`);
      });
    } catch (err) {
      // Process input parameter errors.
      console.error(`param is invalid, code is ${err.code}, message is ${err.message}`);
    }
  }
}

ExtensionRunningInfo

type ExtensionRunningInfo = _ExtensionRunningInfo

Defines the level-2 module ExtensionRunningInfo.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Type	Description
_ExtensionRunningInfo	ExtensionRunningInfo, a level-2 module that provides running information of an ExtensionAbility.

AbilityForegroundStateObserver¹¹⁺

type AbilityForegroundStateObserver = _AbilityForegroundStateObserver.default

Defines the level-2 module AbilityForegroundStateObserver.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Type	Description
_AbilityForegroundStateObserver.default	AbilityForegroundStateObserver, a level-2 module that defines a listener to observe application foreground and background state changes.

PreloadedUIExtensionAbilityDestroyedFn²³⁺

type PreloadedUIExtensionAbilityDestroyedFn = (preloadId: number) => void

Defines the callback function when the preloaded UIExtensionAbility instance is destroyed.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Type	Mandatory	Description
preloadId	number	Yes	ID of the preloaded UIExtensionAbility instance.

PreloadedUIExtensionAbilityLoadedFn²³⁺

type PreloadedUIExtensionAbilityLoadedFn = (preloadId: number) => void

Defines the callback function when the preloaded UIExtensionAbility instance is loaded.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Type	Mandatory	Description
preloadId	number	Yes	ID of the preloaded UIExtensionAbility instance.

@ohos.app.ability.abilityManager (AbilityManager) (System API)

Modules to Import

UserStatus12+

updateConfiguration

updateConfiguration

getAbilityRunningInfos

getExtensionRunningInfos

getExtensionRunningInfos

getTopAbility

getTopAbility

acquireShareData10+

acquireShareData10+

notifySaveAsResult10+

notifySaveAsResult10+

abilityManager.on('abilityForegroundState')11+

abilityManager.off('abilityForegroundState')11+

abilityManager.getForegroundUIAbilities11+

abilityManager.getForegroundUIAbilities11+

abilityManager.notifyDebugAssertResult12+

abilityManager.isEmbeddedOpenAllowed12+

abilityManager.setResidentProcessEnabled12+

abilityManager.preloadUIExtensionAbility23+

abilityManager.clearPreloadedUIExtensionAbility23+

abilityManager.clearPreloadedUIExtensionAbilities23+

abilityManager.onPreloadedUIExtensionAbilityLoaded23+

abilityManager.offPreloadedUIExtensionAbilityLoaded23+

abilityManager.onPreloadedUIExtensionAbilityDestroyed23+

abilityManager.offPreloadedUIExtensionAbilityDestroyed23+

AtomicServiceStartupRule18+

abilityManager.queryAtomicServiceStartupRule18+

ExtensionRunningInfo

AbilityForegroundStateObserver11+

PreloadedUIExtensionAbilityDestroyedFn23+

PreloadedUIExtensionAbilityLoadedFn23+

UserStatus¹²⁺

acquireShareData¹⁰⁺

acquireShareData¹⁰⁺

notifySaveAsResult¹⁰⁺

notifySaveAsResult¹⁰⁺

abilityManager.on('abilityForegroundState')¹¹⁺

abilityManager.off('abilityForegroundState')¹¹⁺

abilityManager.getForegroundUIAbilities¹¹⁺

abilityManager.getForegroundUIAbilities¹¹⁺

abilityManager.notifyDebugAssertResult¹²⁺

abilityManager.isEmbeddedOpenAllowed¹²⁺

abilityManager.setResidentProcessEnabled¹²⁺

abilityManager.preloadUIExtensionAbility²³⁺

abilityManager.clearPreloadedUIExtensionAbility²³⁺

abilityManager.clearPreloadedUIExtensionAbilities²³⁺

abilityManager.onPreloadedUIExtensionAbilityLoaded²³⁺

abilityManager.offPreloadedUIExtensionAbilityLoaded²³⁺

abilityManager.onPreloadedUIExtensionAbilityDestroyed²³⁺

abilityManager.offPreloadedUIExtensionAbilityDestroyed²³⁺

AtomicServiceStartupRule¹⁸⁺

abilityManager.queryAtomicServiceStartupRule¹⁸⁺

AbilityForegroundStateObserver¹¹⁺

PreloadedUIExtensionAbilityDestroyedFn²³⁺

PreloadedUIExtensionAbilityLoadedFn²³⁺