ServiceExtensionContext (System API)

The ServiceExtensionContext module provides the context environment for the ServiceExtensionAbility. It inherits from ExtensionContext.

You can use the APIs of this module to start, terminate, connect, and disconnect an ability.

Modules to Import

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

Usage

Before using the ServiceExtensionContext module, you must define a child class that inherits from ServiceExtensionAbility.

Example

import { ServiceExtensionAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';

let commRemote: rpc.IRemoteObject | null; // Release the instance when the connection is disconnected.

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let context = this.context; // Obtain a ServiceExtensionContext instance.
  }
}

ServiceExtensionContext.startAbility

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

Starts an ability. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability, such as the ability name and bundle name.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapp',
      abilityName: 'MyAbility'
    };

    try {
      this.context.startAbility(want, (error: BusinessError) => {
        if (error.code) {
          // Process service logic errors.
          console.error(`startAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbility succeed');
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`);
    }
  }
}

ServiceExtensionContext.startAbility

startAbility(want: Want, options?: StartOptions): Promise<void>

Starts an ability. This API can be called only on the main thread. It uses a promise to return the result asynchronously.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability, such as the ability name and bundle name.
options	StartOptions	No	Parameters used for starting the ability.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapp',
      abilityName: 'MyAbility'
    };
    let options: StartOptions = {
      windowMode: 0,
    };

    try {
      this.context.startAbility(want, options)
        .then((data: void) => {
          // Carry out normal service processing.
          console.info('startAbility succeed');
        })
        .catch((error: BusinessError) => {
          // Process service logic errors.
          console.error(`startAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
        });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`);
    }
  }
}

ServiceExtensionContext.startAbility

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

Starts an ability. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
options	StartOptions	Yes	Parameters used for starting the ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      windowMode: 0
    };

    try {
      this.context.startAbility(want, options, (error: BusinessError) => {
        if (error.code) {
          // Process service logic errors.
          console.error(`startAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbility succeed');
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`);
    }
  }
}

ServiceExtensionContext.startAbilityWithAccount

startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback<void>): void

Starts an ability with the account ID specified. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
accountId	number	Yes	ID of the target system account.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

    try {
      this.context.startAbilityWithAccount(want, accountId, (error: BusinessError) => {
        if (error.code) {
          // Process service logic errors.
          console.error(`startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbilityWithAccount succeed');
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`);
    }
  }
}

ServiceExtensionContext.startAbilityWithAccount

startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback<void>): void

Starts an ability with the account ID and start options specified. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
accountId	number	Yes	ID of the target system account.
options	StartOptions	Yes	Parameters used for starting the ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;
    let options: StartOptions = {
      windowMode: 0
    };

    try {
      this.context.startAbilityWithAccount(want, accountId, options, (error: BusinessError) => {
        if (error.code) {
          // Process service logic errors.
          console.error(`startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbilityWithAccount succeed');
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.startAbilityWithAccount

startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise<void>

Starts an ability with the account ID specified. This API can be called only on the main thread. It uses a promise to return the result asynchronously.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
accountId	number	Yes	ID of the target system account.
options	StartOptions	No	Parameters used for starting the ability.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;
    let options: StartOptions = {
      windowMode: 0
    };

    try {
      this.context.startAbilityWithAccount(want, accountId, options)
        .then((data: void) => {
          // Carry out normal service processing.
          console.info('startAbilityWithAccount succeed');
        })
        .catch((error: BusinessError) => {
          // Process service logic errors.
          console.error(`startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`);
        });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.startServiceExtensionAbility

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

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

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ServiceExtensionAbility is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    try {
      this.context.startServiceExtensionAbility(want, (error: BusinessError) => {
        if (error.code) {
          // Process service logic errors.
          console.error(`startServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startServiceExtensionAbility succeed');
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.startServiceExtensionAbility

startServiceExtensionAbility(want: Want): Promise<void>

Starts a ServiceExtensionAbility. This API uses a promise to return the result asynchronously.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    try {
      this.context.startServiceExtensionAbility(want)
        .then((data) => {
          // Carry out normal service processing.
          console.info('startServiceExtensionAbility succeed');
        })
        .catch((error: BusinessError) => {
          // Process service logic errors.
          console.error(`startServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
        });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback<void>): void

Starts a ServiceExtensionAbility with the account ID specified. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
accountId	number	Yes	ID of the target system account.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ServiceExtensionAbility is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

    try {
      this.context.startServiceExtensionAbilityWithAccount(want, accountId, (error: BusinessError) => {
        if (error.code) {
          // Process service logic errors.
          console.error(`startServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startServiceExtensionAbilityWithAccount succeed');
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise<void>

Starts a ServiceExtensionAbility with the account ID specified. This API uses a promise to return the result asynchronously.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
accountId	number	Yes	ID of the target system account.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

    try {
      this.context.startServiceExtensionAbilityWithAccount(want, accountId)
        .then((data: void) => {
          // Carry out normal service processing.
          console.info('startServiceExtensionAbilityWithAccount succeed');
        })
        .catch((error: BusinessError) => {
          // Process service logic errors.
          console.error(`startServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`);
        });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.startAbilityAsCaller¹⁰⁺

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

Starts an ability with the caller information specified. The caller information is carried in Want and identified at the system service layer. The ability can obtain the caller information from the Want parameter in the onCreate lifecycle callback. When this API is used to start an ability, the caller information carried in Want is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate(want: Want) {
    // want contains the information about the caller who starts the application.
    let localWant: Want = want;
    localWant.bundleName = 'com.example.demo';
    localWant.moduleName = 'entry';
    localWant.abilityName = 'TestAbility';

    // Start a new ability using the caller information.
    this.context.startAbilityAsCaller(localWant, (err) => {
      if (err && err.code != 0) {
        console.error(`startAbilityAsCaller failed, err: ${JSON.stringify(err)}`);
      } else {
        console.info('startAbilityAsCaller success.');
      }
    })
  }
}

ServiceExtensionContext.startAbilityAsCaller¹⁰⁺

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

Starts an ability with the caller information and start options specified. The caller information is carried in Want and identified at the system service layer. The ability can obtain the caller information from the Want parameter in the onCreate lifecycle callback. When this API is used to start an ability, the caller information carried in Want is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
options	StartOptions	Yes	Parameters used for starting the ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate(want: Want) {
    // want contains the information about the caller who starts the application.
    let localWant: Want = want;
    localWant.bundleName = 'com.example.demo';
    localWant.moduleName = 'entry';
    localWant.abilityName = 'TestAbility';

    let option: StartOptions = {
      displayId: 0
    }

    // Start a new ability using the caller information.
    this.context.startAbilityAsCaller(localWant, option, (err) => {
      if (err && err.code != 0) {
        console.error(`startAbilityAsCaller failed, err: ${JSON.stringify(err)}`);
      } else {
        console.info('startAbilityAsCaller success.');
      }
    })
  }
}

ServiceExtensionContext.startAbilityAsCaller¹⁰⁺

startAbilityAsCaller(want: Want, options?: StartOptions): Promise<void>

Starts an ability with the start options specified. The caller information is carried in Want and identified at the system service layer. The ability can obtain the caller information from the Want parameter in the onCreate lifecycle callback. When this API is used to start an ability, the caller information carried in Want is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API can be called only on the main thread. It uses a promise to return the result asynchronously.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

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

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate(want: Want) {
    // want contains the information about the caller who starts the application.
    let localWant: Want = want;
    localWant.bundleName = 'com.example.demo';
    localWant.moduleName = 'entry';
    localWant.abilityName = 'TestAbility';

    let option: StartOptions = {
      displayId: 0
    };

    // Start a new ability using the caller information.
    this.context.startAbilityAsCaller(localWant, option)
      .then(() => {
        console.info('startAbilityAsCaller success.');
      })
      .catch((err: BusinessError) => {
        console.error(`startAbilityAsCaller failed, err: ${JSON.stringify(err)}`);
      })
  }
}

ServiceExtensionContext.stopServiceExtensionAbility

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

Stops a ServiceExtensionAbility. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ServiceExtensionAbility is stopped, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000011	The context does not exist.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    try {
      this.context.stopServiceExtensionAbility(want, (error: BusinessError) => {
        if (error.code) {
          // Process service logic errors.
          console.error(`stopServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('stopServiceExtensionAbility succeed');
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.stopServiceExtensionAbility

stopServiceExtensionAbility(want: Want): Promise<void>

Stops a ServiceExtensionAbility. This API uses a promise to return the result asynchronously.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000011	The context does not exist.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    try {
      this.context.stopServiceExtensionAbility(want)
        .then(() => {
          // Carry out normal service processing.
          console.info('stopServiceExtensionAbility succeed');
        })
        .catch((error: BusinessError) => {
          // Process service logic errors.
          console.error(`stopServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
        });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback<void>): void

Stops a ServiceExtensionAbility with the specified account. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
accountId	number	Yes	ID of the target system account.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ServiceExtensionAbility is stopped, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000011	The context does not exist.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

    try {
      this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (error: BusinessError) => {
        if (error.code) {
          // Process service logic errors.
          console.error(`stopServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('stopServiceExtensionAbilityWithAccount succeed');
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise<void>

Stops a ServiceExtensionAbility with the specified account. This API uses a promise to return the result asynchronously.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
accountId	number	Yes	ID of the target system account.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000011	The context does not exist.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

    try {
      this.context.stopServiceExtensionAbilityWithAccount(want, accountId)
        .then(() => {
          // Carry out normal service processing.
          console.info('stopServiceExtensionAbilityWithAccount succeed');
        })
        .catch((error: BusinessError) => {
          // Process service logic errors.
          console.error(`stopServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`);
        });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void

Terminates this ability. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is terminated, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000050	Internal error.

Example

import { ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    this.context.terminateSelf((error: BusinessError) => {
      if (error.code) {
        // Process service logic errors.
        console.error(`terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}`);
        return;
      }
      // Carry out normal service processing.
      console.info('terminateSelf succeed');
    });
  }
}

ServiceExtensionContext.terminateSelf

terminateSelf(): Promise<void>

Terminates this ability. This API can be called only on the main thread. It uses a promise to return the result asynchronously.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Ability Error Codes.

ID	Error Message
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000050	Internal error.

Example

import { ServiceExtensionAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    this.context.terminateSelf().then(() => {
      // Carry out normal service processing.
      console.info('terminateSelf succeed');
    }).catch((error: BusinessError) => {
      // Process service logic errors.
      console.error(`terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}`);
    });
  }
}

ServiceExtensionContext.connectServiceExtensionAbility

connectServiceExtensionAbility(want: Want, options: ConnectOptions): number

Connects this ability to a ServiceExtensionAbility. This API can be called only on the main thread.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability, such as the ability name and bundle name.
options	ConnectOptions	Yes	Callback used to return the information indicating that the connection is successful, interrupted, or failed.

Return value

Type	Description
number	A number, based on which the connection will be interrupted.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000011	The context does not exist.
16000050	Internal error.

Example

import { ServiceExtensionAbility, Want, common } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

let commRemote: rpc.IRemoteObject; // Release the instance when the connection is disconnected.

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapp',
      abilityName: 'MyAbility'
    };
    let options: common.ConnectOptions = {
      onConnect(elementName, remote) {
        commRemote = remote;
        console.info('----------- onConnect -----------');
      },
      onDisconnect(elementName) {
        console.info('----------- onDisconnect -----------');
      },
      onFailed(code) {
        console.error('----------- onFailed -----------');
      }
    };
    let connection: number;

    try {
      connection = this.context.connectServiceExtensionAbility(want, options);
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.connectServiceExtensionAbilityWithAccount

connectServiceExtensionAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number

Connects this ability to a ServiceExtensionAbility of a given account. This API can be called only on the main thread.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

Device behavior differences: This API can be properly called on phones and tablets. If it is called on other devices, error code 16000006 is returned.

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
accountId	number	Yes	ID of the target system account.
options	ConnectOptions	Yes	Remote object instance.

Return value

Type	Description
number	Result code of the connection.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000011	The context does not exist.
16000050	Internal error.

Example

import { ServiceExtensionAbility, Want, common } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

let commRemote: rpc.IRemoteObject; // Release the instance when the connection is disconnected.

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;
    let options: common.ConnectOptions = {
      onConnect(elementName, remote) {
        commRemote = remote;
        console.info('----------- onConnect -----------');
      },
      onDisconnect(elementName) {
        console.info('----------- onDisconnect -----------');
      },
      onFailed(code) {
        console.info('----------- onFailed -----------');
      }
    };
    let connection: number;

    try {
      connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options);
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback<void>): void

Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
connection	number	Yes	Number returned after connectServiceExtensionAbility is called.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is disconnected, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000011	The context does not exist.
16000050	Internal error.

Example

import { ServiceExtensionAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

let commRemote: rpc.IRemoteObject | null; // Release the instance when the connection is disconnected.

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    // connection is the return value of connectServiceExtensionAbility.
    let connection = 1;
    try {
      this.context.disconnectServiceExtensionAbility(connection, (error: BusinessError) => {
        commRemote = null;
        if (error.code) {
          // Process service logic errors.
          console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('disconnectServiceExtensionAbility succeed');
      });
    } catch (paramError) {
      commRemote = null;
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number): Promise<void>

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
connection	number	Yes	Number returned after connectServiceExtensionAbility is called.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000011	The context does not exist.
16000050	Internal error.

Example

import { ServiceExtensionAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

let commRemote: rpc.IRemoteObject | null; // Release the instance when the connection is disconnected.

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    // connection is the return value of connectServiceExtensionAbility.
    let connection = 1;
    try {
      this.context.disconnectServiceExtensionAbility(connection)
        .then(() => {
          commRemote = null;
          // Carry out normal service processing.
          console.info('disconnectServiceExtensionAbility succeed');
        })
        .catch((error: BusinessError) => {
          commRemote = null;
          // Process service logic errors.
          console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
        });
    } catch (paramError) {
      commRemote = null;
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.startAbilityByCall

startAbilityByCall(want: Want): Promise<Caller>

Starts an ability in the foreground or background and obtains the caller object for communicating with the ability. This API can be called only on the main thread. It uses a promise to return the result asynchronously.

This API cannot be used to start the UIAbility with the launch type set to specified.

Observe the following when using this API:

If an application running in the background needs to call this API to start an ability, it must have the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission.
If exported of the target ability is false in cross-application scenarios, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
The rules for using this API in the same-device and cross-device scenarios are different. For details, see Component Startup Rules (Stage Model).

Required permissions: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Information about the ability to start, including abilityName, moduleName, bundleName, deviceId, and parameters (optional). If parameters is left blank or null, the ability is started in the background.

Return value

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

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000050	Internal error.

Example

Start an ability in the background.

import { ServiceExtensionAbility, Caller, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let caller: Caller;
    // Start an ability in the background by not passing parameters.
    let wantBackground: Want = {
      bundleName: 'com.example.myservice',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      deviceId: ''
    };

    try {
      this.context.startAbilityByCall(wantBackground)
        .then((obj: Caller) => {
          // Carry out normal service processing.
          caller = obj;
          console.info('startAbilityByCall succeed');
        }).catch((error: BusinessError) => {
        // Process service logic errors.
        console.error(`startAbilityByCall failed, error.code: ${error.code}, error.message: ${error.message}`);
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

Start an ability in the foreground.

import { ServiceExtensionAbility, Caller, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let caller: Caller;
    // Start an ability in the foreground with ohos.aafwk.param.callAbilityToForeground in parameters set to true.
    let wantForeground: Want = {
      bundleName: 'com.example.myservice',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      deviceId: '',
      parameters: {
        'ohos.aafwk.param.callAbilityToForeground': true
      }
    };

    try {
      this.context.startAbilityByCall(wantForeground)
        .then((obj: Caller) => {
          // Carry out normal service processing.
          caller = obj;
          console.info('startAbilityByCall succeed');
        }).catch((error: BusinessError) => {
        // Process service logic errors.
        console.error(`startAbilityByCall failed, error.code: ${error.code}, error.message: ${error.message}`);
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.startRecentAbility

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

Starts an ability. If the ability has multiple instances, the latest instance is started. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    try {
      this.context.startRecentAbility(want, (err: BusinessError) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startRecentAbility succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startRecentAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

ServiceExtensionContext.startRecentAbility

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

Starts an ability. If the ability has multiple instances, the latest instance is started. This API can be called only on the main thread. It uses an asynchronous callback to return the result.

You can use this API to carry start options.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
options	StartOptions	Yes	Parameters used for starting the ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the ability is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      windowMode: 0
    };

    try {
      this.context.startRecentAbility(want, options, (err: BusinessError) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startRecentAbility succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startRecentAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

ServiceExtensionContext.startRecentAbility

startRecentAbility(want: Want, options?: StartOptions): Promise<void>

Starts an ability. If the ability has multiple instances, the latest instance is started. This API uses a promise to return the result asynchronously. It can be called only on the main thread.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

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

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      windowMode: 0,
    };

    try {
      this.context.startRecentAbility(want, options)
        .then(() => {
          // Carry out normal service processing.
          console.info('startRecentAbility succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startRecentAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

ServiceExtensionContext.startAbilityByCallWithAccount¹⁰⁺

startAbilityByCallWithAccount(want: Want, accountId: number): Promise<Caller>

Starts an ability with the account ID specified and obtains the caller object for communicating with the ability. This API can be called only on the main thread. It uses a promise to return the result asynchronously.

This API cannot be used to start the UIAbility with the launch type set to specified.

Observe the following when using this API:

If an application needs to call this API to start an ability that belongs to another user, it must have the ohos.permission.ABILITY_BACKGROUND_COMMUNICATION and ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permissions.
If an application running in the background needs to call this API to start an ability, it must have the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission.
If exported of the target ability is false in cross-application scenarios, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
The rules for using this API in the same-device and cross-device scenarios are different. For details, see Component Startup Rules (Stage Model).

Required permissions: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION and ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Information about the ability to start, including abilityName, moduleName, bundleName, deviceId (optional), and parameters (optional). If deviceId is left blank or null, the local ability is started. If parameters is left blank or null, the ability is started in the background.
accountId	number	Yes	ID of the target system account. The value -1 indicates the current user.

Return value

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

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	Static permission denied. The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, Want, Caller } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let caller: Caller;
    // ID of a system account. The value -1 indicates the current user.
    let accountId = -1;
    // Specify the ability to start.
    let want: Want = {
      bundleName: 'com.acts.actscalleeabilityrely',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      deviceId: '',
      parameters: {
        // If ohos.aafwk.param.callAbilityToForeground is set to true, the ability is launched in the foreground; if it is set to false or not set, the ability is launched in the background.
        'ohos.aafwk.param.callAbilityToForeground': true
      }
    };

    try {
      this.context.startAbilityByCallWithAccount(want, accountId)
        .then((obj: Caller) => {
          // Carry out normal service processing.
          caller = obj;
          console.info('startAbilityByCallWithAccount succeed');
        }).catch((error: BusinessError) => {
        // Process service logic errors.
        console.error(`startAbilityByCallWithAccount failed, error.code: ${error.code}, error.message: ${error.message}`);
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`);
    }
  }
}

ServiceExtensionContext.requestModalUIExtension¹¹⁺

requestModalUIExtension(pickerWant: Want): Promise<void>

Requests the specified focused application to start the UIExtensionAbility of the corresponding type. The focused application is specified by bundleName in want.parameters. If bundleName is left unspecified, or if the specified application does not gain focus, the UIExtensionAbility is directly started on the system UI. The UIExtensionAbility to start is determined by the combination of the bundleName, abilityName, and moduleName fields in Want, and its type is determined by the ability.want.params.uiExtensionType field in want.parameters. This API can be called only on the main thread. It uses a promise to return the result asynchronously.

Before starting the UIExtensionAbility, ensure that the focused application has finished page initialization. Otherwise, the UIExtensionAbility fails to start. The application can determine the time to start the UIExtensionAbility by listening for the page loading status.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
pickerWant	Want	Yes	Want information used to start the UIExtensionAbility.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class ServiceExtension extends ServiceExtensionAbility {
  onCreate() {
    let pickerWant: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'UIExtAbility',
      moduleName: 'entry_test',
      parameters: {
        'bundleName': 'com.example.myapplication',
        // The value is the same as the value of type configured for com.example.myapplication.UIExtAbility.
        'ability.want.params.uiExtensionType': 'sys/commonUI'
      }
    };

    try {
      this.context.requestModalUIExtension(pickerWant)
        .then(() => {
          // Carry out normal service processing.
          console.info('requestModalUIExtension succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`);
    }
  }
}

ServiceExtensionContext.requestModalUIExtension¹¹⁺

requestModalUIExtension(pickerWant: Want, callback: AsyncCallback<void>): void

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
pickerWant	Want	Yes	Want information used to start the UIExtensionAbility.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the UIExtensionAbility is started, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000050	Internal error.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

class ServiceExtension extends ServiceExtensionAbility {
  onCreate() {
    let pickerWant: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'com.example.myapplication.UIExtAbility',
      moduleName: 'entry_test',
      parameters: {
        'bundleName': 'com.example.myapplication',
        // The value is the same as the value of type configured for com.example.myapplication.UIExtAbility.
        'ability.want.params.uiExtensionType': 'sys/commonUI'
      }
    };

    try {
      this.context.requestModalUIExtension(pickerWant, (err: BusinessError) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('requestModalUIExtension succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`);
    }
  }
}

ServiceExtensionContext.openLink¹²⁺

openLink(link: string, options?: OpenLinkOptions): Promise<void>

Starts a UIAbility through App Linking. This API can be called only on the main thread. It uses a promise to return the result asynchronously.

A URL in the standard format is passed in to the link field to start the target UIAbility based on the implicit Want matching rules. The target UIAbility must have the following filter characteristics to process links of App Linking:

The actions field must contain ohos.want.action.viewData.
The entities field must contain entity.system.browsable.
The uris field must contain elements whose scheme is https and domainVerify is true.

If an input parameter is invalid, for example, a mandatory parameter is not set or the URL set in link is not in the standard format, an exception is thrown. If the parameter verification is successful but an error occurs when starting the target UIAbility, the error information is returned through promise.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
link	string	Yes	URL to open, which must be in the standard format.
options	OpenLinkOptions	No	Options of the URL.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16200001	The caller has been released.
16000136	The UIAbility is prohibited from launching itself via App Linking.

Example

import { ServiceExtensionAbility, Want, OpenLinkOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

function log(info: string) {
  console.error(`[ServiceExtApp]:: ${JSON.stringify(info)}`);
}

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onCreate(want: Want) {
    log(`ServiceExtAbility OnCreate`);
  }

  onRequest(want: Want, startId: number) {
    log(`ServiceExtAbility onRequest`);
    let link: string = 'https://www.example.com';
    let openLinkOptions: OpenLinkOptions = {
      appLinkingOnly: false
    };
    try {
      this.context.openLink(
        link,
        openLinkOptions
      ).then(() => {
        log(`open link success.`);
      }).catch((err: BusinessError) => {
        log(`open link failed, errCode ${JSON.stringify(err.code)}`);
      });
    }
    catch (e) {
      log(`exception occurred, errCode ${JSON.stringify(e.code)}`);
    }
  }

  onDestroy() {
    log(`ServiceExtAbility onDestroy`);
  }
}

ServiceExtensionContext.preStartMission¹²⁺

preStartMission(bundleName: string, moduleName: string, abilityName: string, startTime: string): Promise<void>

Starts an atomic service and pre-opens the window, with the loading box skipped. This API uses a promise to return the result.

If parameter verification is successful but the atomic service fails to start, you need to implement an exception mechanism to capture the error.

Required permissions: ohos.permission.PRE_START_ATOMIC_SERVICE

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
bundleName	string	Yes	Bundle name of the atomic service.
moduleName	string	Yes	Module name of the atomic service.
abilityName	string	Yes	Ability name of the atomic service.
startTime	string	Yes	Start time to open the atomic service, in milliseconds.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16300007	The target free-installation task does not exist.
16000011	The context does not exist.
16000050	Internal error.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

function log(info: string) {
  console.error(`[ServiceExtApp]:: ${JSON.stringify(info)}`);
}

export default class ServiceExtAbility extends ServiceExtensionAbility {
  onCreate(want: Want) {
    log(`ServiceExtAbility OnCreate, want: ${JSON.stringify(want)}.`);
  }

  onRequest(want: Want, startId: number) {
    log(`ServiceExtAbility onRequest`);
    try {
      if (want.parameters && want.parameters["ohos.aafwk.param.startTime"]) {
        this.context.preStartMission(
          want.bundleName,
          want.moduleName,
          want.abilityName,
          want.parameters["ohos.aafwk.param.startTime"] as string
        ).then(() => {
          log(`pre-start mission success.`);
        }).catch((err: BusinessError) => {
          log(`pre-start mission failed, errCode: ${err.code}, errMsg: ${err.message}.`);
        });
      }
    } catch (e) {
      let code = (e as BusinessError).code;
      let msg = (e as BusinessError).message;
      log(`exception occurred, errCode: ${code}, errMsg: ${msg}.`);
    }
  }

  onDestroy() {
    log(`ServiceExtAbility onDestroy`);
  }
}

ServiceExtensionContext.startUIServiceExtensionAbility¹⁴⁺

startUIServiceExtensionAbility(want: Want): Promise<void>

Starts a new UIServiceExtensionAbility. This API uses a promise to return the result asynchronously.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability, such as the ability name and bundle name.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	The application is not system-app, can not use system-api.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16200001	The caller has been released.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';

export default class MyServiceExtensionAbility extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    const startWant: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'UIServiceExtensionAbility'
    }
    // Start a UIServiceExtensionAbility.
    this.context.startUIServiceExtensionAbility(startWant).then(() => {
      console.info('succeeded');
    }).catch((error: BusinessError) => {
      console.error(`error code: ${error.code}, error message : ${error.message}`);
    })
  }
}

ServiceExtensionContext.openAtomicService¹⁸⁺

openAtomicService(appId: string, options?: AtomicServiceOptions): Promise<void>

Starts an atomic service based on an application ID. This API uses a promise to return the result asynchronously.

System capability: SystemCapability.Ability.AbilityRuntime.Core

System API: This is a system API.

Parameters

Name	Type	Mandatory	Description
appId	string	Yes	Unique ID of the application, which is allocated by the cloud.
options	AtomicServiceOptions	No	Parameter carried in the request for starting the atomic service in jump-out mode.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000002	Incorrect ability type.
16000004	Cannot start an invisible component.
16000011	The context does not exist.
16000012	The application is controlled.
16000050	Internal error.
16200001	The caller has been released.

Example

import { ServiceExtensionAbility, AtomicServiceOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class ServiceExtension extends ServiceExtensionAbility {
  onRequest(want: Want, startId: number) {
    let appId: string = '6918661953712445909';
    let options: AtomicServiceOptions = {
      displayId: 0,
    };
    try {
      this.context.openAtomicService(appId, options)
        .then(() => {
          console.info('openAtomicService succeed');
        })
        .catch((err: BusinessError) => {
          console.error(`openAtomicService failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`openAtomicService failed, code is ${code}, message is ${message}`);
    }
  }
}

ServiceExtensionContext.startUIAbilities²⁰⁺

startUIAbilities(wantList: Array<Want>): Promise<void>

Starts multiple UIAbility components simultaneously. This API uses a promise to return the result asynchronously.

You can pass the Want information of multiple UIAbility instances, which can point to one or more applications. If all the UIAbility instances can be started successfully, the system displays these UIAbility instances in multiple windows simultaneously. Depending on the window handling, different devices may have varying display effects (including window shape, quantity, and layout).

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Device behavior differences: This API can be properly called on phones and tablets. If it is called on other devices, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
wantList	Array<Want>	Yes	List of launch parameters for multiple UIAbility components to be started simultaneously. A maximum of four Want objects can be passed. The Want parameter does not support implicit launch, cross-user launch, distributed launch, instant installation, or on-demand loading. By default, the main application is launched unless specified otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Ability Error Codes.

ID	Error Message
201	The application does not have permission to call the interface.
202	Not system application.
801	Capability not supported.
16000001	The specified ability does not exist.
16000004	Cannot start an invisible component.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000050	Internal error.
16200001	The caller has been released.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000080	Creating a new instance is not supported.
16000120	A maximum of four UIAbility instances can be started simultaneously. The current parameter exceeds the maximum number or is less than 1.
16000121	The target component type is not a UIAbility.
16000122	The target component is blocked by the system module and does not support startup.
16000123	Implicit startup is not supported.
16000124	Starting a remote UIAbility is not supported.
16000125	Starting a plugin UIAbility is not supported.
16000126	Starting DLP files is not supported.

Example

import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryServiceExtAbility extends ServiceExtensionAbility {
  onRequest() {
    let want1: Want = {
      bundleName: 'com.example.myapplication1',
      abilityName: 'EntryAbility'
    };
    let want2: Want = {
      bundleName: 'com.example.myapplication2',
      abilityName: 'EntryAbility'
    };
    let wantList: Array<Want> = [want1, want2];
    try {
      this.context.startUIAbilities(wantList).then(() => {
        console.info(`TestTag:: start succeeded.`);
      }).catch((error: BusinessError) => {
        console.info(`TestTag:: startUIAbilities failed: ${JSON.stringify(error)}`);
      });
    } catch (paramError) {
      // Process input parameter errors.
      console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`);
    }
  }
}

ServiceExtensionContext (System API)

Modules to Import

Usage

ServiceExtensionContext.startAbility

ServiceExtensionContext.startAbility

ServiceExtensionContext.startAbility

ServiceExtensionContext.startAbilityWithAccount

ServiceExtensionContext.startAbilityWithAccount

ServiceExtensionContext.startAbilityWithAccount

ServiceExtensionContext.startServiceExtensionAbility

ServiceExtensionContext.startServiceExtensionAbility

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

ServiceExtensionContext.startAbilityAsCaller10+

ServiceExtensionContext.startAbilityAsCaller10+

ServiceExtensionContext.startAbilityAsCaller10+

ServiceExtensionContext.stopServiceExtensionAbility

ServiceExtensionContext.stopServiceExtensionAbility

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

ServiceExtensionContext.terminateSelf

ServiceExtensionContext.terminateSelf

ServiceExtensionContext.connectServiceExtensionAbility

ServiceExtensionContext.connectServiceExtensionAbilityWithAccount

ServiceExtensionContext.disconnectServiceExtensionAbility

ServiceExtensionContext.disconnectServiceExtensionAbility

ServiceExtensionContext.startAbilityByCall

ServiceExtensionContext.startRecentAbility

ServiceExtensionContext.startRecentAbility

ServiceExtensionContext.startRecentAbility

ServiceExtensionContext.startAbilityByCallWithAccount10+

ServiceExtensionContext.requestModalUIExtension11+

ServiceExtensionContext.requestModalUIExtension11+

ServiceExtensionContext.openLink12+

ServiceExtensionContext.preStartMission12+

ServiceExtensionContext.startUIServiceExtensionAbility14+

ServiceExtensionContext.openAtomicService18+

ServiceExtensionContext.startUIAbilities20+

ServiceExtensionContext.startAbilityAsCaller¹⁰⁺

ServiceExtensionContext.startAbilityAsCaller¹⁰⁺

ServiceExtensionContext.startAbilityAsCaller¹⁰⁺

ServiceExtensionContext.startAbilityByCallWithAccount¹⁰⁺

ServiceExtensionContext.requestModalUIExtension¹¹⁺

ServiceExtensionContext.requestModalUIExtension¹¹⁺

ServiceExtensionContext.openLink¹²⁺

ServiceExtensionContext.preStartMission¹²⁺

ServiceExtensionContext.startUIServiceExtensionAbility¹⁴⁺

ServiceExtensionContext.openAtomicService¹⁸⁺

ServiceExtensionContext.startUIAbilities²⁰⁺