AbilityContext

icon-note.gif 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.

Implements the ability context. This module is inherited from Context.

Usage

Before using the AbilityContext module, you must define a child class that inherits from Ability.

import Ability from '@ohos.application.Ability'
class MainAbility extends Ability {
    onWindowStageCreate(windowStage) {
        let context = this.context;
    }
}

Attributes

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name Type Readable Writable Description
abilityInfo AbilityInfo Yes No Ability information.
currentHapModuleInfo HapModuleInfo Yes No Information about the current HAP.

AbilityContext.startAbility

startAbility(want: Want, callback: AsyncCallback<void>): void

Starts an ability. This API uses a callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
want Want Yes Information about the Want used for starting an ability.
callback AsyncCallback<void> Yes Callback used to return the result.

Example

var want = {
	"deviceId": "",
	"bundleName": "com.extreme.test",
	"abilityName": "com.extreme.test.MainAbility"
};
this.context.startAbility(want, (error) => {
    console.log("error.code = " + error.code)
})

AbilityContext.startAbility

startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void

Starts an ability. This API uses a callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
want Want Yes Information about the Want used for starting an ability.
options StartOptions Yes Parameters used for starting the ability.
callback AsyncCallback<void> Yes Callback used to return the result.

Example

var want = {
	"deviceId": "",
	"bundleName": "com.extreme.test",
	"abilityName": "com.extreme.test.MainAbility"
};
var options = {
	windowMode: 0,
};
this.context.startAbility(want, options, (error) => {
    console.log("error.code = " + error.code)
})

AbilityContext.startAbility

startAbility(want: Want, options?: StartOptions): 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 Information about the Want used for starting an ability.
options StartOptions No Parameters used for starting the ability.

Return value

Type Description
Promise<void> Promise used to return the result.

Example

var want = {
	"deviceId": "",
	"bundleName": "com.extreme.test",
	"abilityName": "com.extreme.test.MainAbility"
};
var options = {
	windowMode: 0,
};
this.context.startAbility(want, options)
.then((data) => {
    console.log('Operation successful.')
}).catch((error) => {
    console.log('Operation failed.');
})

AbilityContext.startAbilityForResult

startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void;

Starts an ability. This API uses a callback to return the execution result when the ability is terminated.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
want Want Yes Information about the Want used for starting an ability.
callback AsyncCallback<AbilityResult> Yes Callback used to return the result.

Example

this.context.startAbilityForResult(
    {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo2"},
    (error, result) => {
        console.log("startAbilityForResult AsyncCallback is called, error.code = " + error.code)
        console.log("startAbilityForResult AsyncCallback is called, result.resultCode = " + result.resultCode)
     }
);

AbilityContext.startAbilityForResult

startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void;

Starts an ability. This API uses a callback to return the execution result when the ability is terminated.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
want Want Yes Information about the Want used for starting an ability.
options StartOptions Yes Parameters used for starting the ability.
callback AsyncCallback<AbilityResult> Yes Callback used to return the result.

Example

var options = {
  windowMode: 0,
};
this.context.startAbilityForResult(
    {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo2"}, options,
    (error, result) => {
        console.log("startAbilityForResult AsyncCallback is called, error.code = " + error.code)
        console.log("startAbilityForResult AsyncCallback is called, result.resultCode = " + result.resultCode)
     }
);

AbilityContext.startAbilityForResult

startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>;

Starts an ability. This API uses a promise to return the execution result when the ability is terminated.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
want Want Yes Information about the Want used for starting an ability.
options StartOptions No Parameters used for starting the ability.

Return value

Type Description
Promise<AbilityResult> Promise used to return the result.

Example

var options = {
  windowMode: 0,
};
this.context.startAbilityForResult({bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo2"}, options).then((result) => {
    console.log("startAbilityForResult Promise.resolve is called, result.resultCode = " + result.resultCode)
}, (error) => {
    console.log("startAbilityForResult Promise.Reject is called, error.code = " + error.code)
})

AbilityContext.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void;

Terminates this ability. This API uses a callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result indicating whether the API is successfully called.

Example

this.context.terminateSelf((err) => {
    console.log('terminateSelf result:' + JSON.stringify(err));
});

AbilityContext.terminateSelf

terminateSelf(): Promise<void>;

Terminates this ability. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Type Description
Promise<void> Promise used to return the result indicating whether the API is successfully called.

Example

this.context.terminateSelf(want).then((data) => {
    console.log('success:' + JSON.stringify(data));
}).catch((error) => {
    console.log('failed:' + JSON.stringify(error));
});

AbilityContext.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void;

Terminates this ability. This API uses a callback to return the information to the caller of startAbilityForResult.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
parameter AbilityResult Yes Information returned to the caller.
callback AsyncCallback<void> Yes Callback used to return the result.

Example

this.context.terminateSelfWithResult(
   {
        want: {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo"},
        resultCode: 100
    }, (error) => {
        console.log("terminateSelfWithResult is called = " + error.code)
    }
);

AbilityContext.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult): Promise<void>;

Terminates this ability. This API uses a promise to return information to the caller of startAbilityForResult.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
parameter AbilityResult Yes Information returned to the caller.

Return value

Type Description
Promise<void> Promise used to return the result.

Example

this.context.terminateSelfWithResult(
{
    want: {bundleName: "com.extreme.myapplication", abilityName: "MainAbilityDemo"},
    resultCode: 100
}).then((result) => {
    console.log("terminateSelfWithResult")
}
)

AbilityContext.startAbilityByCall

startAbilityByCall(want: Want): Promise<Caller>;

Obtains the caller interface of the specified ability, and if the specified ability is not started, starts the ability in the background.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
want Want Yes Information about the ability to start, including the ability name, bundle name, and device ID. If the device ID is left blank or the default value is used, the local ability will be started.

Return value

Type Description
Promise<Caller> Promise used to return the caller object to communicate with.

Example

import Ability from '@ohos.application.Ability';
var caller;
export default class MainAbility extends Ability {
    onWindowStageCreate(windowStage) {
        this.context.startAbilityByCall({
            bundleName: "com.example.myservice",
            abilityName: "com.example.myservice.MainAbility",
            deviceId: ""
        }).then((obj) => {
            caller = obj;
            console.log('Caller GetCaller Get ' + call);
        }).catch((e) => {
            console.log('Caller GetCaller error ' + e);
        });
    }
}

AbilityContext.requestPermissionsFromUser

requestPermissionsFromUser(permissions: Array<string>, requestCallback: AsyncCallback<PermissionRequestResult>) : void;

Requests permissions from the user by displaying a pop-up window. This API uses a callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
permissions Array<string> Yes Permissions to request.
callback AsyncCallback<PermissionRequestResult> Yes Callback used to return the result indicating whether the API is successfully called.

Example

this.context.requestPermissionsFromUser(permissions,(result) => {
    console.log('requestPermissionsFromUserresult:' + JSON.stringify(result));
});

AbilityContext.requestPermissionsFromUser

requestPermissionsFromUser(permissions: Array<string>) : Promise<PermissionRequestResult>;

Requests permissions from the user by displaying a pop-up window. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
permissions Array<string> Yes Permissions to request.

Return value

Type Description
Promise<PermissionRequestResult> Promise used to return the result indicating whether the API is successfully called.

Example

this.context.requestPermissionsFromUser(permissions).then((data) => {
    console.log('success:' + JSON.stringify(data));
}).catch((error) => {
    console.log('failed:' + JSON.stringify(error));
});

AbilityContext.setMissionLabel

setMissionLabel(label: string, callback:AsyncCallback<void>): void;

Sets the label of the ability displayed in the task. This API uses a callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
label string Yes Label of the ability to set.
callback AsyncCallback<void> Yes Callback used to return the result indicating whether the API is successfully called.

Example

this.context.setMissionLabel("test",(result) => {
    console.log('requestPermissionsFromUserresult:' + JSON.stringify(result));
});

AbilityContext.setMissionLabel

setMissionLabel(label: string): Promise<void>

Sets the label of the ability displayed in the task. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name Type Mandatory Description
label string Yes Label of the ability to set.

Return value

Type Description
Promise<void> Promise used to return the result indicating whether the API is successfully called.

Example

this.context.setMissionLabel("test").then((data) => {
    console.log('success:' + JSON.stringify(data));
}).catch((error) => {
    console.log('failed:' + JSON.stringify(error));
});