> 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.
Provides ability running information.
## Usage
The ability running information is obtained by using the **getAbilityRunningInfos** method in **abilityManager**.
```
import abilitymanager from '@ohos.application.abilityManager';
> 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 context of an ability stage. This module is inherited from [Context](js-apis-application-context.md).
## Usage
The ability stage context is obtained through an **AbilityStage** instance.
```
import AbilityStage from '@ohos.application.AbilityStage';
> The 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.
| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.|
| data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.|
- Return value
| Type| Description|
| -------- | -------- |
| Promise<void> | Promise used to return a response.|
- Example
```
import Ability from '@ohos.application.Ability';
class MyMessageAble{ // Custom sequenceable data structure
Sends sequenceable data to the target ability and obtains the sequenceable data returned by the target ability.
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.|
| data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.|
- Return value
| Type| Description|
| -------- | -------- |
| Promise<rpc.MessageParcel> | Promise used to return the sequenceable data from the target ability.|
export default class MainAbility extends Ability {
onWindowStageCreate(windowStage) {
caller = await this.context.startAbilityByCall({
bundleName: "com.example.myservice",
abilityName: "com.example.myservice.MainAbility",
deviceId: ""
});
let msg = new MyMessageAble(1, "world");
caller.callWithResult(method, msg)
.then((data) => {
console.log('Caller call() called');
let retmsg = new MyMessageAble(0, "");
data.readSequenceable(retmsg);
}).catch((e) => {
console.log('Caller call() catch error ' + e);
});
}
}
```
### release
release(): void;
Releases the caller interface of the target ability.
- Example
```
import Ability from '@ohos.application.Ability';
var caller;
export default class MainAbility extends Ability {
onWindowStageCreate(windowStage) {
caller = await this.context.startAbilityByCall({
bundleName: "com.example.myservice",
abilityName: "com.example.myservice.MainAbility",
deviceId: ""
});
try {
caller.release();
} catch (e) {
console.log('Caller Release error ' + e);
}
}
}
```
### onRelease
onRelease(callback: function): void;
Registers a callback that is invoked when the Stub on the target ability is disconnected.
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | function | Yes| Callback used for the **onRelease** method.|
- Example
```
import Ability from '@ohos.application.Ability';
var caller;
export default class MainAbility extends Ability {
onWindowStageCreate(windowStage) {
caller = await this.context.startAbilityByCall({
bundleName: "com.example.myservice",
abilityName: "com.example.myservice.MainAbility",
deviceId: ""
});
try {
caller.onRelease((str) => {
console.log(' Caller OnRelease CallBack is called ' + str);
});
} catch (e) {
console.log('Caller Release error ' + e);
}
}
}
```
## Callee
Implements callbacks for caller notification registration and unregistration.
### on
on(method: string, callback: function): void;
Registers a caller notification callback, which is invoked when the target ability registers a function.
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| method | string | Yes| Notification message string negotiated between the two abilities.|
| callback | function | Yes| JS notification synchronization callback of the **rpc.MessageParcel** type. The callback must return at least one empty **rpc.Sequenceable** object. Otherwise, the function execution fails.|
> The initial APIs of this module are supported since API 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Runtime class for HAP files. It provides methods to notify you when a HAP file starts loading. You can then initialize the HAP file, for example, pre-load resources and create threads.
## Modules to Import
```
import AbilityStage from '@ohos.application.AbilityStage';
```
## onCreate
onCreate(): void
Called when the application is created.
- Example
```
class MyAbilityStage extends AbilityStage {
onCreate() {
console.log("MyAbilityStage.onCreate is called")
}
}
```
## onAcceptWant
onAcceptWant(want: Want): string;
Called when a specified ability is started.
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-featureAbility.md#Want)| Yes| Information about the ability to start, such as the ability name and bundle name.|
- Return value
| Type| Description|
| -------- | -------- |
| string | Returns an ability ID. If this ability has been started, no new instance is created and the ability is placed at the top of the stack. Otherwise, a new instance is created and started.|
| config | [Configuration](js-apis-configuration.md) | Yes| Callback invoked when the global configuration is updated. The global configuration indicates the configuration of the environment where the application is running and includes the language and color mode.|
> 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.
Provides the context for running code, including **applicationInfo** and **resourceManager**.
## Usage
You must extend **AbilityContext** to implement this module.
> The initial APIs of this module are supported since API 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> 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.
Provides the configuration for the environment where the ability is running.
## Modules to Import
```
import Configuration from '@ohos.application.Configuration';
| language | string | Yes| Yes| Language of the application.|
| colorMode | [ColorMode](js-apis-configurationconstant.md) | Yes| Yes| Color mode, which can be **COLOR_MODE_LIGHT** or **COLOR_MODE_DARK**. The default value is **COLOR_MODE_LIGHT**.|
| direction | Direction | Yes| No| Screen orientation, which can be **DIRECTION_HORIZONTAL** or **DIRECTION_VERTICAL**.|
| screenDensity | ScreenDensity | Yes| No| Screen resolution, which can be **SCREEN_DENSITY_SDPI** (120), **SCREEN_DENSITY_MDPI** (160), **SCREEN_DENSITY_LDPI** (240), **SCREEN_DENSITY_XLDPI** (320), **SCREEN_DENSITY_XXLDPI** (480), or **SCREEN_DENSITY_XXXLDPI** (640).|
| displayId | number | Yes| No| ID of the display where the application is located.|
> 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.
Defines enumerated values of the configuration for the environment where the ability is running.
## Modules to Import
```
import ConfigurationConstant from '@ohos.application.ConfigurationConstant';
```
## ColorMode
To obtain the value, use **ConfigurationConstant.ColorMode**, for example, **ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT**.
| Name| Value| Description|
| -------- | -------- | -------- |
| COLOR_MODE_NOT_SET | -1 | Unspecified color mode.|
| COLOR_MODE_DARK | 0 | Dark mode.|
| COLOR_MODE_LIGHT | 1 | Light mode.|
## Direction
To obtain the value, use **ConfigurationConstant.Direction**, for example, **ConfigurationConstant.Direction.DIRECTION_VERTICAL**.
> The initial APIs of this module are supported since API 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Implements event subscription, unsubscription, and triggering.
## Usage
Before using any methods in the **EventHub**, you must obtain an **EventHub** instance through the member variable **context** of the **Ability** instance.
```
import Ability from '@ohos.application.Ability'
export default class MainAbility extends Ability {
onForeground() {
this.context.eventHub.on("123", this.func1);
}
}
```
## on
on(event: string, callback: Function): void;
Subscribes to an event.
**System capabilities**:
SystemCapability.Ability.AbilityRuntime.Core
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| event | string | Yes| Event name.|
| callback | Function | Yes| Callback invoked when the event is triggered.|
- Example
```
import Ability from '@ohos.application.Ability'
export default class MainAbility extends Ability {
onForeground() {
this.context.eventHub.on("123", this.func1);
this.context.eventHub.on("123", () => {
console.log("call anonymous func 1");
});
// Result
// func1 is called
// call anonymous func 1
this.context.eventHub.emit("123");
}
func1() {
console.log("func1 is called");
}
}
```
## off
off(event: string, callback?: Function): void;
Unsubscribes from an event. If **callback** is specified, this method unsubscribes from the specified callback. If **callback** is not specified, this method unsubscribes from all callbacks in the event.
**System capabilities**:
SystemCapability.Ability.AbilityRuntime.Core
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| event | string | Yes| Event name.|
| callback | Function | No| Callback for the event. If **callback** is unspecified, all callbacks of the event are unsubscribed.|
- Example
```
import Ability from '@ohos.application.Ability'
export default class MainAbility extends Ability {
onForeground() {
this.context.eventHub.on("123", this.func1);
this.context.eventHub.off("123", this.func1); // Unsubscribe from func1.
this.context.eventHub.on("123", this.func1);
this.context.eventHub.on("123", this.func2);
this.context.eventHub.off("123"); // Unsubscribe from func1 and func2.
}
func1() {
console.log("func1 is called");
}
func2() {
console.log("func2 is called");
}
}
```
## emit
emit(event: string, ...args: Object[]): void;
Triggers an event.
**System capabilities**:
SystemCapability.Ability.AbilityRuntime.Core
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| event | string | Yes| Event name.|
| ...args | Object[] | Yes| Variable parameters, which are passed to the callback when the event is triggered.|
- Example
```
import Ability from '@ohos.application.Ability'
export default class MainAbility extends Ability {
> The initial APIs of this module are supported since API 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Provides extension running information.
## Usage
The extension running information is obtained through an **abilityManager** instance.
```
import abilitymanager from '@ohos.application.abilityManager';
| extension | ElementName | Yes| No| Information that matches an extension. <br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
| pid | number | Yes| No| Process ID. <br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
| uid | number | Yes| No| User ID. <br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
| clientPackage | Array<String> | Yes| No| Names of all packages in the process. <br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
| FORM | 0 | Extension information of the form type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
| WORK_SCHEDULER | 1 | Extension information of the work scheduler type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
| INPUT_METHOD | 2 | Extension information of the input method type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
| SERVICE | 3 | Extension information of the service type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
| ACCESSIBILITY | 4 | Extension information of the accessibility type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
| DATA_SHARE | 5 | Extension information of the data share type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
| FILE_SHARE | 6 | Extension information of the file share type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
| STATIC_SUBSCRIBER | 7 | Extension information of the static subscriber type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
| WALLPAPER | 8 | Extension information of the wallpaper type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
| UNSPECIFIED | 9 | Extension information of the unspecified type. <br><b>System capabilities: </b>SystemCapability.BundleManager.BundleFramework|
> The initial APIs of this module are supported since API 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
| authResults | Array<number> | Yes| No| Whether the requested permissions are granted or denied. The value **0** means that the requests permissions are granted, and **-1** means the opposite. <br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
> The initial APIs of this module are supported since API 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Provides process running information.
## Usage
The process running information is obtained through an **appManager** instance.
```
import appManager from '@ohos.application.appManager';
| bundleNames | Array<string> | Yes| No| Names of all bundles running in the process. <br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
> The initial APIs of this module are supported since API 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Implements URI permission management.
## Modules to Import
```
import UriPermissionManager from '@@ohos.application.UriPermissionManager';
Checks whether an application has the permission specified by **flag** for an URI. This method uses a callback to return the result.
**System capabilities**:
SystemCapability.Ability.AbilityRuntime.Core
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| uri | string | Yes| URI of a file, for example, **fileshare:///com.samples.filesharetest.FileShare/person/10**.|
| flag | wantConstant.Flags | Yes| Read or write permission on the file specified by the URI.|
| accessTokenId | number | Yes| Unique ID of an application, which is obtained through the **BundleManager** API.|
| callback | AsyncCallback<number> | Yes| Callback used to return the check result. The value **0** means that the application has the specified permission, and **-1** means the opposite.|
- Example
```
let uri = "fileshare:///com.samples.filesharetest.FileShare/person/10"
Checks whether an application has the permission specified by **flag** for an URI. This method uses a promise to return the result.
**System capabilities**:
SystemCapability.Ability.AbilityRuntime.Core
- Parameters
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| uri | string | Yes| URI of a file, for example, **fileshare:///com.samples.filesharetest.FileShare/person/10**.|
| flag | wantConstant.Flags | Yes| Read or write permission on the file specified by the URI.|
| accessTokenId | number | Yes| Unique ID of an application, which is obtained through the **BundleManager** API.|
- Return value
| Type| Description|
| -------- | -------- |
| Promise<number> | Promise used to return the check result. The value **0** means that the application has the specified permission, and **-1** means the opposite.|
- Example
```
let uri = "fileshare:///com.samples.filesharetest.FileShare/person/10"