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

addAbilityMonitor⁹⁺

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");
});

addAbilityMonitor⁹⁺

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");
});

removeAbilityMonitor⁹⁺

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");
});

removeAbilityMonitor⁹⁺

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");
});

waitAbilityMonitor⁹⁺

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");
});

waitAbilityMonitor⁹⁺

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");
});

waitAbilityMonitor⁹⁺

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");
});

getAppContext⁹⁺

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();

getAbilityState⁹⁺

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);
});

getCurrentTopAbility⁹⁺

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;
});

getCurrentTopAbility⁹⁺

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;
});

doAbilityForeground⁹⁺

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");
    });
});

doAbilityForeground⁹⁺

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");
    });
});

doAbilityBackground⁹⁺

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");
    });
});

doAbilityBackground⁹⁺

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");
    });
});

startAbility⁹⁺

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");
});

startAbility⁹⁺

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

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

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");
});

AbilityDelegator

Modules to Import