Ability Framework Changelog

cl.ability.1 Application Component Startup Rule Change

The rules for starting application components are changed in the following scenarios:

• Start an application component when the application is in the background.
• Start an invisible application component across applications.
• Start a ServiceAbility and DataAbility of the FA model across applications.
• Use the startAbilityByCall API.

You need to adapt your application.

Change Impact

If new rules are not adapted, application components cannot be started in the previous scenarios.

NOTE

Starting application components refers to any behavior starting or connecting to an ability.

1. Start an ability using APIs such as startAbility, startServiceExtensionAbility, and startAbilityByCall.
2. Connect to an ability using APIs such as connectAbility, connectServiceExtensionAbility, acquireDataAbilityHelper, and createDataShareHelper.

Key API/Component Changes

• Involved application components
  • Stage model
    • Ability
    • ServiceExtension
    • DataShareExtension
  • FA model
    • PageAbility
    • ServiceAbility
    • DataAbility
• Involved APIs
  • Stage model
    • startAbility(want: Want, callback: AsyncCallback): void;
    • startAbility(want: Want, options: StartOptions, callback: AsyncCallback): void;
    • startAbility(want: Want, options?: StartOptions): Promise;
    • startAbilityByCall(want: Want): Promise;
    • startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback): void;
    • startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback): void;
    • startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise;
    • startAbilityForResult(want: Want, callback: AsyncCallback): void;
    • startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback): void;
    • startAbilityForResult(want: Want, options?: StartOptions): Promise;
    • startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback): void;
    • startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback): void;
    • startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise;
    • startServiceExtensionAbility(want: Want, callback: AsyncCallback): void;
    • startServiceExtensionAbility(want: Want): Promise;
    • startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback): void;
    • startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise;
    • stopServiceExtensionAbility(want: Want, callback: AsyncCallback): void;
    • stopServiceExtensionAbility(want: Want): Promise;
    • stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback): void;
    • stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise;
    • connectAbility(want: Want, options: ConnectOptions): number;
    • connectAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number;
    • createDataShareHelper(context: Context, uri: string, callback: AsyncCallback): void
  • FA model
    • startAbility(parameter: StartAbilityParameter, callback: AsyncCallback): void;
    • startAbility(parameter: StartAbilityParameter): Promise;
    • startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback): void;
    • startAbilityForResult(parameter: StartAbilityParameter): Promise;
    • acquireDataAbilityHelper(uri: string): DataAbilityHelper;
    • connectAbility(request: Want, options:ConnectOptions ): number;

Adaptation Guide

Startup rules for different scenarios are as follows:

• Starting an application component when the application is in the background

  • Rule in OpenHarmony 3.2 Beta3:

    • There is no restriction.

  • Rule in OpenHarmony 3.2 Beta4:

    • Authentication is required. The following permissions must be configured:

    • {
          "name": "ohos.permission.START_ABILITIES_FROM_BACKGROUND",
          "grantMode": "system_grant",
          "availableLevel": "system_basic",  
          "provisionEnable": true,
          "distributedSceneEnable": false
      }
      

      NOTE

      1. Starting an application component of the same application is also restricted by this rule.
      2. For SDKs of API version 8 or earlier, starting a ServiceAbility and DataAbility is not restricted by this rule.

• Starting an invisible application component across applications

  • Rule in OpenHarmony 3.2 Beta3:

    • For applications whose APL is normal, invisible application components cannot be started across applications.

  • Rule in OpenHarmony 3.2 Beta4:

    • For all applications, starting an invisible application component across applications requires authentication. The following permissions must be configured:

    •  {
           "name": "ohos.permission.START_INVISIBLE_ABILITY",
           "grantMode": "system_grant",
           "availableLevel": "system_core",
           "provisionEnable": true,
           "distributedSceneEnable": false
       }
      

• Starting a ServiceAbility and DataAbility of the FA model across applications

  • Rule in OpenHarmony 3.2 Beta3:
    • There is no restriction.
  • Rule in OpenHarmony 3.2 Beta4:
    • Associated startup must be configured for the provider of the ServiceAbility and DataAbility. Otherwise, they cannot be started across applications. (Associated startup cannot be configured for common applications.)

• Using the startAbilityByCall API

  • Rule in OpenHarmony 3.2 Beta3:

    • This is no restriction.

  • Rule in OpenHarmony 3.2 Beta4:

    • The startAbilityByCall API cannot be called by the same application.

  • Calling the startAbilityByCall API across applications requires authentication. The following permissions must be configured:

    • {
          "name": "ohos.permission.ABILITY_BACKGROUND_COMMUNICATION",
          "grantMode": "system_grant",
          "availableLevel": "system_basic",
          "provisionEnable": true,
          "distributedSceneEnable": false
      }
      

      NOTE

      Using the startAbilityByCall API is also restricted by the background startup and across-application invisible component startup rules.

cl.ability.2 Cross-Device Application Component Startup Rule Change (for System Applications Only)

The rules for starting cross-device application components are changed in the following scenarios:

• Start an application component when the application is in the background.
• Start an invisible application component across applications.
• Start a ServiceAbility of the FA model across applications.

You need to adapt your application.

Change Impact

If new rules are not adapted, application components cannot be started in the previous scenarios.

NOTE

Starting application components refers to any behavior starting or connecting to an ability.

1. Start an ability using APIs such as startAbility, startAbilityForResult, and startAbilityByCall.
2. Connect to an ability using APIs such as connectAbility.

Key API/Component Changes

• Involved application components
  • Stage model
    • Ability
    • ServiceExtension
  • FA model
    • PageAbility
    • ServiceAbility
• Involved APIs
  • Stage model
    • startAbility(want: Want, callback: AsyncCallback): void;
    • startAbilityByCall(want: Want): Promise;
    • startAbilityForResult(want: Want, callback: AsyncCallback): void;
    • connectAbility(want: Want, options: ConnectOptions): number;
  • FA model
    • startAbility(parameter: StartAbilityParameter, callback: AsyncCallback): void;
    • startAbility(parameter: StartAbilityParameter): Promise;
    • startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback): void;
    • startAbilityForResult(parameter: StartAbilityParameter): Promise;
    • connectAbility(request: Want, options:ConnectOptions ): number;

Adaptation Guide

Startup rules for different scenarios are as follows:

• Starting an application component when the application is in the background

  • Rule in OpenHarmony 3.2 Beta3:

    • There is no restriction.

  • Rule in OpenHarmony 3.2 Beta4:

    • Authentication is required. The following permissions must be configured:

    • {
          "name": "ohos.permission.START_ABILITIES_FROM_BACKGROUND",
          "grantMode": "system_grant",
          "availableLevel": "system_basic",  
          "provisionEnable": true,
          "distributedSceneEnable": false
      }
      

      NOTE 1. Starting an application component of the same application is also restricted by this rule. 2. For SDKs of API version 8 or earlier, starting a ServiceAbility is not restricted by this rule.

• Starting an invisible application component across applications

  • Rule in OpenHarmony 3.2 Beta3:

    • Invisible application components cannot be started across applications.

  • Rule in OpenHarmony 3.2 Beta4:

    • Authentication is required. The following permissions must be configured:

    •  {
           "name": "ohos.permission.START_INVISIBLE_ABILITY",
           "grantMode": "system_grant",
           "availableLevel": "system_core",
           "provisionEnable": true,
           "distributedSceneEnable": false
       }
      

• Starting a ServiceAbility of the FA model across applications

  • Rule in OpenHarmony 3.2 Beta3:

    • There is no restriction.

  • Rule in OpenHarmony 3.2 Beta4:

    • Associated startup needs to be configured for the provider of the ServiceAbility. Otherwise, the ServiceAbility cannot be started across applications. (Associated startup cannot be configured for common applications.)
    • Configure associated startup as follows:

    •  {
           "bundleName": "",
           "app_signature": ["xxxxxxxxxxxxxxxxxxx"],
           "associatedWakeUp": true
       }
      

cl.ability.3 API Exception Handling Method Change

Certain APIs of the ability subsystem use service logic return values to indicate error information, which does not comply with the API error code specifications of OpenHarmony.

Change Impact

The application developed based on earlier versions needs to be adapted. Otherwise, the service logic will be affected.

Key API/Component Changes

For adaptation to the unified API exception handling mode, certain ability subsystem APIs are deprecated (original APIs in the following table) and corresponding new APIs in the following table are added. (In the following table, original APIs in API version 9 will be deleted, and APIs in API version 8 and earlier will be deprecated.) The newly added APIs support unified error code handling specifications and function the same as the original APIs.

Adaptation Guide

The original APIs are only moved to the new namespace. Therefore, you can modify import to solve the adaptation problem.

If the original API uses @ohos.application.missionManager:

import missionManager from '@ohos.application.missionManager';

You can directly modify import to switch to the new namespace:

import missionManager from '@ohos.app.ability.missionManager';

In addition, exception handling is needed. For details, see the API reference for the new APIs.

cl.ability.4 API Change

The names of certain ability subsystem APIs are changed.

Key API/Component Changes