@ohos.app.ability.AppServiceExtensionAbility (ExtensionAbility for Application Background Services)

The AppServiceExtensionAbility module provides extended capabilities for background services, including lifecycle callbacks for creating, destroying, connecting, and disconnecting background services.

NOTE

The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs of this module can be used only in the stage model.

Constraints

• Currently, only 2-in-1 devices are supported.
• To integrate an AppServiceExtensionAbility, applications must request the ACL permission (ohos.permission.SUPPORT_APP_SERVICE_EXTENSION). Currently, the ACL permission is available only to common enterprise applications. For details about how to apply for the permission, see Declaring Permissions.

Lifecycle

The AppServiceExtensionAbility provides the following lifecycle callbacks: onCreate(), onRequest(), onConnect(), onDisconnect(), and onDestroy(). You can override the callback methods as required. The following figure shows the AppServiceExtensionAbility lifecycle.

• onCreate

  Called when an AppServiceExtensionAbility instance is created.

• onDestroy

  Called when an AppServiceExtensionAbility instance is destroyed.

• onRequest

  Called when an AppServiceExtensionAbility instance is started by calling startAppServiceExtensionAbility().

• onConnect

  Called when an AppServiceExtensionAbility instance is connected by calling connectAppServiceExtensionAbility.

• onDisconnect

  Called when all connections to an AppServiceExtensionAbility instance are interrupted.

Modules to Import

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

AppServiceExtensionAbility

The AppServiceExtensionAbility module provides extended capabilities for background services, including lifecycle callbacks for creating, destroying, connecting, and disconnecting background services.

Properties

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Type	Read-Only	Optional	Description
context	AppServiceExtensionContext	No	No	Context environment for an AppServiceExtensionAbility. This context inherits from ExtensionContext.

onCreate

onCreate(want: Want): void

Called when an AppServiceExtensionAbility instance is created. Applications can perform initialization operations, such as registering common event listeners, in this callback.

NOTE

If an AppServiceExtensionAbility instance has already been created, the onCreate() callback is not invoked again when the instance is started or connected.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target AppServiceExtensionAbility instance, including the ability name and bundle name.

Example

import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[AppServiceExtAbility]';

export default class AppServiceExtAbility extends AppServiceExtensionAbility {
  onCreate(want: Want) {
    hilog.info(0x0000, TAG, `onCreate, want: ${want.abilityName}`);
  }
}

onDestroy

onDestroy(): void

Called when an AppServiceExtensionAbility instance is destroyed. Applications can perform resource cleanup operations, such as unregistering listeners, in this callback.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Example

import { AppServiceExtensionAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[AppServiceExtAbility]';

export default class AppServiceExtAbility extends AppServiceExtensionAbility {
  onDestroy() {
    hilog.info(0x0000, TAG, `onDestroy`);
  }
}

onRequest

onRequest(want: Want, startId: number): void

Called each time an AppServiceExtensionAbility instance is started by calling startAppServiceExtensionAbility().

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target AppServiceExtensionAbility instance, including the ability name and bundle name.
startId	number	Yes	Number of times the instance has been started. The initial value is 1 for the first start, and it increments automatically for subsequent starts.

Example

import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[AppServiceExtAbility]';

export default class AppServiceExtAbility extends AppServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    hilog.info(0x0000, TAG, `onRequest, want: ${want.abilityName}, startId: ${startId}`);
  }
}

onConnect

onConnect(want: Want): rpc.RemoteObject

Called when an AppServiceExtensionAbility instance is connected by calling connectAppServiceExtensionAbility.

Applications need to return a RemoteObject in this callback for communication between the client and the server. When an AppServiceExtensionAbility instance is in a connected state, if the caller initiates a new connection, the system returns the cached RemoteObject instead of calling onConnect() again.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target AppServiceExtensionAbility instance, including the ability name and bundle name.

Return value

Type	Description
rpc.RemoteObject	A RemoteObject used for communication between the server and client.

Example

import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[AppServiceExtAbility]';

class StubTest extends rpc.RemoteObject {
  constructor(des: string) {
    super(des);
  }

  onConnect(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence, option: rpc.MessageOption) {
  }
}

export default class AppServiceExtAbility extends AppServiceExtensionAbility {
  onConnect(want: Want) {
    hilog.info(0x0000, TAG, `onConnect, want: ${want.abilityName}`);
    return new StubTest('test');
  }
}

onDisconnect

onDisconnect(want: Want): void

Called when all connections to an AppServiceExtensionAbility instance are interrupted.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information passed by the caller when the AppServiceExtensionAbility instance was most recently started or connected. This includes information such as the ability name and bundle name.

Example

import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG: string = '[AppServiceExtAbility]';

export default class AppServiceExtAbility extends AppServiceExtensionAbility {
  onDisconnect(want: Want) {
    hilog.info(0x0000, TAG, `onDisconnect, want: ${want.abilityName}`);
  }
}