AbilityDelegator
NOTE
The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
API version 9 is a canary version for trial use. The APIs of this version may be unstable.
Modules to Import
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
AbilityDelegator
addAbilityMonitor9+
addAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback<void>): void
Adds an AbilityMonitor instance. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
monitor | AbilityMonitor | Yes | AbilityMonitor instance. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
var abilityDelegator;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.addAbilityMonitor(monitor, (err : any) => {
console.info("addAbilityMonitor callback");
});
addAbilityMonitor9+
addAbilityMonitor(monitor: AbilityMonitor): Promise<void>
Adds an AbilityMonitor instance. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
monitor | AbilityMonitor | Yes | AbilityMonitor instance. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
var abilityDelegator;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.addAbilityMonitor(monitor).then(() => {
console.info("addAbilityMonitor promise");
});
removeAbilityMonitor9+
removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback<void>): void
Removes an AbilityMonitor instance. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
monitor | AbilityMonitor | Yes | AbilityMonitor instance. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
var abilityDelegator;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.removeAbilityMonitor(monitor, (err : any) => {
console.info("removeAbilityMonitor callback");
});
removeAbilityMonitor9+
removeAbilityMonitor(monitor: AbilityMonitor): Promise<void>
Removes an AbilityMonitor instance. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
monitor | AbilityMonitor | Yes | AbilityMonitor instance. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
var abilityDelegator;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.removeAbilityMonitor(monitor).then(() => {
console.info("removeAbilityMonitor promise");
});
waitAbilityMonitor9+
waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback<Ability>): void
Waits for the ability that matches the AbilityMonitor instance to reach the OnCreate lifecycle and returns the Ability instance. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
monitor | AbilityMonitor | Yes | AbilityMonitor instance. |
callback | AsyncCallback<Ability> | Yes | Callback used to return the result. |
Example
var abilityDelegator;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityMonitor(monitor, (err : any, data : any) => {
console.info("waitAbilityMonitor callback");
});
waitAbilityMonitor9+
waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback<Ability>): void
Waits a period of time for the ability that matches the AbilityMonitor instance to reach the OnCreate lifecycle and returns the Ability instance. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
monitor | AbilityMonitor | Yes | AbilityMonitor instance. |
timeout | number | Yes | Maximum waiting time, in milliseconds. |
callback | AsyncCallback<Ability> | Yes | Callback used to return the result. |
Example
var abilityDelegator;
var timeout = 100;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityMonitor(monitor, timeout, (err : any, data : any) => {
console.info("waitAbilityMonitor callback");
});
waitAbilityMonitor9+
waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise<Ability>
Waits a period of time for the ability that matches the AbilityMonitor instance to reach the OnCreate lifecycle and returns the Ability instance. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
monitor | AbilityMonitor | Yes | AbilityMonitor instance. |
timeout | number | No | Maximum waiting time, in milliseconds. |
Return value
Type | Description |
---|---|
Promise<Ability> | Promise used to return the Ability instance. |
Example
var abilityDelegator;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityMonitor(monitor).then((data : any) => {
console.info("waitAbilityMonitor promise");
});
getAppContext9+
getAppContext(): Context
Obtains the application context.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
Type | Description |
---|---|
Context | Context of the application. |
Example
var abilityDelegator;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
var context = abilityDelegator.getAppContext();
getAbilityState9+
getAbilityState(ability: Ability): number
Obtains the lifecycle state of an ability.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
ability | Ability | Yes | Target ability. |
Return value
Type | Description |
---|---|
number | Lifecycle state of the ability. For details about the available enumerated values, see AbilityLifecycleState. |
Example
var abilityDelegator;
var ability;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
console.info("getCurrentTopAbility callback");
ability = data;
var state = abilityDelegator.getAbilityState(ability);
console.info("getAbilityState" + state);
});
getCurrentTopAbility9+
getCurrentTopAbility(callback: AsyncCallback<Ability>): void
Obtains the top ability of the application. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<Ability> | Yes | Callback used to return the result. |
Example
var abilityDelegator;
var ability;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
console.info("getCurrentTopAbility callback");
ability = data;
});
getCurrentTopAbility9+
getCurrentTopAbility(): Promise<Ability>
Obtains the top ability of the application. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
Type | Description |
---|---|
Promise<Ability> | Promise used to return the top ability. |
Example
var abilityDelegator;
var ability;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility().then((data : any) => {
console.info("getCurrentTopAbility promise");
ability = data;
});
doAbilityForeground9+
doAbilityForeground(ability: Ability, callback: AsyncCallback<boolean>): void
Schedules the lifecycle state of an ability to Foreground. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
ability | Ability | Yes | Target ability. |
callback | AsyncCallback<boolean> | Yes | Callback used to return the result. - true: The operation is successful. - false: The operation fails. |
Example
var abilityDelegator;
var ability;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
console.info("getCurrentTopAbility callback");
ability = data;
abilityDelegator.doAbilityForeground(ability, (err : any, data : any) => {
console.info("doAbilityForeground callback");
});
});
doAbilityForeground9+
doAbilityForeground(ability: Ability): Promise<boolean>
Schedules the lifecycle state of an ability to Foreground. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
ability | Ability | Yes | Target ability. |
Return value
Type | Description |
---|---|
Promise<boolean> | Promise used to return the result. - true: The operation is successful. - false: The operation fails. |
Example
var abilityDelegator;
var ability;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
console.info("getCurrentTopAbility callback");
ability = data;
abilityDelegator.doAbilityForeground(ability).then((data : any) => {
console.info("doAbilityForeground promise");
});
});
doAbilityBackground9+
doAbilityBackground(ability: Ability, callback: AsyncCallback<boolean>): void
Schedules the lifecycle state of an ability to Background. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
ability | Ability | Yes | Target ability. |
callback | AsyncCallback<boolean> | Yes | Callback used to return the result. - true: The operation is successful. - false: The operation fails. |
Example
var abilityDelegator;
var ability;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
console.info("getCurrentTopAbility callback");
ability = data;
abilityDelegator.doAbilityBackground(ability, (err : any, data : any) => {
console.info("doAbilityBackground callback");
});
});
doAbilityBackground9+
doAbilityBackground(ability: Ability): Promise<boolean>
Schedules the lifecycle state of an ability to Background. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
ability | Ability | Yes | Target ability. |
Return value
Type | Description |
---|---|
Promise<boolean> | Promise used to return the result. - true: The operation is successful. - false: The operation fails. |
Example
var abilityDelegator;
var ability;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.getCurrentTopAbility((err : any, data : any) => {
console.info("getCurrentTopAbility callback");
ability = data;
abilityDelegator.doAbilityBackground(ability).then((data : any) => {
console.info("doAbilityBackground promise");
});
});
startAbility9+
startAbility(want: Want, callback: AsyncCallback<void>): void
Starts an ability. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want parameter for starting the ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
var abilityDelegator;
var want = {
bundleName: "bundleName",
abilityName: "abilityName"
};
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.startAbility(want, (err, data) => {
console.info("startAbility callback");
});
startAbility9+
startAbility(want: Want): Promise<void>
Starts an ability. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want parameter for starting the ability. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
var abilityDelegator;
var want = {
bundleName: "bundleName",
abilityName: "abilityName"
};
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.startAbility(want).then((data: any) => {
console.info("startAbility promise");
});
print(msg: string, callback: AsyncCallback<void>): void
Prints log information to the unit test console. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
msg | string | Yes | Log string. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Example
var abilityDelegator;
var msg = "msg";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.print(msg, (err) => {
console.info("print callback");
});
print(msg: string): Promise<void>
Prints log information to the unit test console. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
msg | string | Yes | Log string. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Example
var abilityDelegator;
var msg = "msg";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.print(msg).then(() => {
console.info("print promise");
});
executeShellCommand
executeShellCommand(cmd: string, callback: AsyncCallback<ShellCmdResult>): void
Executes a shell command. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
cmd | string | Yes | Shell command string. |
callback | AsyncCallback<ShellCmdResult> | Yes | Callback used to return the result. |
Example
var abilityDelegator;
var cmd = "cmd";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.executeShellCommand(cmd, (err, data) => {
console.info("executeShellCommand callback");
});
executeShellCommand
executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback<ShellCmdResult>): void
Executes a shell command with the timeout period specified. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
cmd | string | Yes | Shell command string. |
timeoutSecs | number | Yes | Command timeout period, in seconds. |
callback | AsyncCallback<ShellCmdResult> | Yes | Callback used to return the result. |
Example
var abilityDelegator;
var cmd = "cmd";
var timeout = 100;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.executeShellCommand(cmd, timeout, (err, data) => {
console.info("executeShellCommand callback");
});
executeShellCommand
executeShellCommand(cmd: string, timeoutSecs?: number): Promise<ShellCmdResult>;
Executes a shell command with the timeout period specified. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
cmd | string | Yes | Shell command string. |
timeoutSecs | number | No | Command timeout period, in seconds. |
Return value
Type | Description |
---|---|
Promise<ShellCmdResult> | Promise used to return a ShellCmdResult object. |
Example
var abilityDelegator;
var cmd = "cmd";
var timeout = 100;
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.executeShellCommand(cmd, timeout).then((data : any) => {
console.info("executeShellCommand promise");
});