ServiceExtensionContext


ServiceExtensionContext

ServiceExtensionContext模块是ServiceExtensionAbility的上下文环境,继承自ExtensionContext。

ServiceExtensionContext模块提供ServiceExtensionAbility具有的能力和接口,包括启动、停止、绑定、解绑Ability。

说明:

  • 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
  • 本模块接口仅可在Stage模型下使用。

使用说明

在使用ServiceExtensionContext的功能前,需要通过ServiceExtensionAbility子类实例获取。

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

  let context = undefined;
  class MainAbility extends ServiceExtensionAbility {
    onCreate() {
      context = this.context; // 获取ServiceExtensionContext
    }
  }
1
2
3
4
5
6
7
8

ServiceExtensionContext.startAbility

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

启动Ability。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want Want类型参数,传入需要启动的ability的信息,如Ability名称,Bundle名称等。
callback AsyncCallback<void> 回调函数,返回接口调用是否成功的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000010 Can not operation with continue flag.
16000011 Context does not exist.
16000051 Network error. The network is abnormal.
16000052 Free install not support. The application does not support freeinstall
16000053 Not top ability. The application is not top ability.
16000054 Free install busyness. There are concurrent tasks, waiting for retry.
16000055 Free install timeout.
16000056 Can not free install other ability.
16000057 Not support cross device free install.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  bundleName: "com.example.myapp",
  abilityName: "MyAbility"
};

try {
  this.context.startAbility(want, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('startAbility succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

ServiceExtensionContext.startAbility

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

启动Ability。通过Promise返回结果。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want Want类型参数,传入需要启动的ability的信息,如Ability名称,Bundle名称等。
options StartOptions 启动Ability所携带的参数。

返回值:

类型 说明
Promise<void> 返回一个Promise,包含接口的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000010 Can not operation with continue flag.
16000011 Context does not exist.
16000051 Network error. The network is abnormal.
16000052 Free install not support. The application does not support freeinstall
16000053 Not top ability. The application is not top ability.
16000054 Free install busyness. There are concurrent tasks, waiting for retry.
16000055 Free install timeout.
16000056 Can not free install other ability.
16000057 Not support cross device free install.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  bundleName: "com.example.myapp",
  abilityName: "MyAbility"
};
var options = {
	windowMode: 0,
};

try {
  this.context.startAbility(want, options)
    .then((data) => {
      // 执行正常业务
      console.log('startAbility succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

ServiceExtensionContext.startAbility

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

启动Ability。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
options StartOptions 启动Ability所携带的参数。
callback AsyncCallback<void> callback形式返回启动结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000010 Can not operation with continue flag.
16000011 Context does not exist.
16000051 Network error. The network is abnormal.
16000052 Free install not support. The application does not support freeinstall
16000053 Not top ability. The application is not top ability.
16000054 Free install busyness. There are concurrent tasks, waiting for retry.
16000055 Free install timeout.
16000056 Can not free install other ability.
16000057 Not support cross device free install.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var options = {
  windowMode: 0
};

try {
  this.context.startAbility(want, options, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('startAbility succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

ServiceExtensionContext.startAbilityWithAccount

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

根据account启动Ability(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
callback AsyncCallback<void> 启动Ability的回调函数。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000006 Can not cross user operations.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000010 Can not operation with continue flag.
16000011 Context does not exist.
16000051 Network error. The network is abnormal.
16000052 Free install not support. The application does not support freeinstall
16000053 Not top ability. The application is not top ability.
16000054 Free install busyness. There are concurrent tasks, waiting for retry.
16000055 Free install timeout.
16000056 Can not free install other ability.
16000057 Not support cross device free install.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var accountId = 100;

try {
  this.context.startAbilityWithAccount(want, accountId, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('startAbilityWithAccount succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

ServiceExtensionContext.startAbilityWithAccount

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

根据account启动Ability(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
options StartOptions 启动Ability所携带的参数。
callback AsyncCallback<void> 启动Ability的回调函数。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000006 Can not cross user operations.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000010 Can not operation with continue flag.
16000011 Context does not exist.
16000051 Network error. The network is abnormal.
16000052 Free install not support. The application does not support freeinstall
16000053 Not top ability. The application is not top ability.
16000054 Free install busyness. There are concurrent tasks, waiting for retry.
16000055 Free install timeout.
16000056 Can not free install other ability.
16000057 Not support cross device free install.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var accountId = 100;
var options = {
  windowMode: 0
};

try {
  this.context.startAbilityWithAccount(want, accountId, options, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('startAbilityWithAccount succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

ServiceExtensionContext.startAbilityWithAccount

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

根据account启动Ability(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount。。
options StartOptions 启动Ability所携带的参数。

返回值:

类型 说明
Promise<void> 返回一个Promise,包含接口的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000006 Can not cross user operations.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000010 Can not operation with continue flag.
16000011 Context does not exist.
16000051 Network error. The network is abnormal.
16000052 Free install not support. The application does not support freeinstall
16000053 Not top ability. The application is not top ability.
16000054 Free install busyness. There are concurrent tasks, waiting for retry.
16000055 Free install timeout.
16000056 Can not free install other ability.
16000057 Not support cross device free install.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var accountId = 100;
var options = {
  windowMode: 0
};

try {
  this.context.startAbilityWithAccount(want, accountId, options)
    .then((data) => {
      // 执行正常业务
      console.log('startAbilityWithAccount succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('startAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

ServiceExtensionContext.startServiceExtensionAbility

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

启动一个新的ServiceExtensionAbility(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
callback AsyncCallback<void> 启动Ability的回调函数。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000011 Context does not exist.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};

try {
  this.context.startServiceExtensionAbility(want, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('startServiceExtensionAbility succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

ServiceExtensionContext.startServiceExtensionAbility

startServiceExtensionAbility(want: Want): Promise<void>;

启动一个新的ServiceExtensionAbility(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。

返回值:

类型 说明
Promise<void> 返回一个Promise,包含接口的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000011 Context does not exist.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};

try {
  this.context.startServiceExtensionAbility(want)
    .then((data) => {
      // 执行正常业务
      console.log('startServiceExtensionAbility succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('startServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

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

启动一个新的ServiceExtensionAbility(callback形式)。

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS,当accountId为当前用户时,不需要校验该权限。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
callback AsyncCallback<void> 启动Ability的回调函数。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000006 Can not cross user operations.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000011 Context does not exist.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var accountId = 100;

try {
  this.context.startServiceExtensionAbilityWithAccount(want, accountId, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('startServiceExtensionAbilityWithAccount succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

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

启动一个新的ServiceExtensionAbility(Promise形式)。

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS,当accountId为当前用户时,不需要校验该权限。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount

返回值:

类型 说明
Promise<void> 返回一个Promise,包含接口的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000006 Can not cross user operations.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000011 Context does not exist.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var accountId = 100;

try {
  this.context.startServiceExtensionAbilityWithAccount(want, accountId)
    .then((data) => {
      // 执行正常业务
      console.log('startServiceExtensionAbilityWithAccount succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('startServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

ServiceExtensionContext.stopServiceExtensionAbility

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

停止同一应用程序内的服务(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 停止Ability的want信息。
callback AsyncCallback<void> 停止Ability的回调函数。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000011 Context does not exist.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};

try {
  this.context.stopServiceExtensionAbility(want, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('stopServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('stopServiceExtensionAbility succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

ServiceExtensionContext.stopServiceExtensionAbility

stopServiceExtensionAbility(want: Want): Promise<void>;

停止同一应用程序内的服务(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 停止Ability的want信息。

返回值:

类型 说明
Promise<void> 返回一个Promise,包含接口的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000011 Context does not exist.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};

try {
  this.context.stopServiceExtensionAbility(want)
    .then((data) => {
      // 执行正常业务
      console.log('stopServiceExtensionAbility succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('stopServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

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

使用帐户停止同一应用程序内的服务(callback形式)。

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS,当accountId为当前用户时,不需要校验该权限。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 停止Ability的want信息。
accountId number 需要停止的系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
callback AsyncCallback<void> 停止Ability的回调函数。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000006 Can not cross user operations.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000011 Context does not exist.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var accountId = 100;

try {
  this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('stopServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('stopServiceExtensionAbilityWithAccount succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

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

使用帐户停止同一应用程序内的服务(Promise形式)。

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS,当accountId为当前用户时,不需要校验该权限。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 停止Ability的want信息。
accountId number 需要停止的系统帐号的帐号ID,详情参考getCreatedOsAccountsCount

返回值:

类型 说明
Promise<void> 返回一个Promise,包含接口的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000006 Can not cross user operations.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000011 Context does not exist.
16200001 Caller released. The caller has been released.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var accountId = 100;

try {
  this.context.stopServiceExtensionAbilityWithAccount(want, accountId)
    .then((data) => {
      // 执行正常业务
      console.log('stopServiceExtensionAbilityWithAccount succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('stopServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

ServiceExtensionContext.terminateSelf

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

停止Ability自身。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 回调函数,返回接口调用是否成功的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000011 Context does not exist.
16000050 Internal Error.

示例:

this.context.terminateSelf((error) => {
  if (error.code) {
    // 处理业务逻辑错误
    console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) +
      ' error.message: ' + JSON.stringify(error.message));
    return;
  }
  // 执行正常业务
  console.log('terminateSelf succeed');
});
1
2
3
4
5
6
7
8
9
10

ServiceExtensionContext.terminateSelf

terminateSelf(): Promise<void>;

停止自身。通过Promise返回结果。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

返回值:

类型 说明
Promise<void> 返回一个Promise,包含接口的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000011 Context does not exist.
16000050 Internal Error.

示例:

this.context.terminateSelf().then((data) => {
  // 执行正常业务
  console.log('terminateSelf succeed');
}).catch((error) => {
  // 处理业务逻辑错误
  console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) +
    ' error.message: ' + JSON.stringify(error.message));
});
1
2
3
4
5
6
7
8

ServiceExtensionContext.connectServiceExtensionAbility

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

将一个Ability与服务类型的Ability绑定。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want Want类型参数,传入需要启动的ability的信息,如Ability名称,Bundle名称等。
options ConnectOptions ConnectOptions类型的回调函数,返回服务连接成功、断开或连接失败后的信息。

返回值:

类型 说明
number 返回一个number,后续根据这个number去断开连接。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000011 Context does not exist.
16000050 Internal Error.

示例:

var want = {
  bundleName: "com.example.myapp",
  abilityName: "MyAbility"
};
var options = {
  onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
  onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
  onFailed(code) { console.log('----------- onFailed -----------') }
}

var connection = null;
try {
  connection = this.context.connectServiceExtensionAbility(want, options);
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

ServiceExtensionContext.connectServiceExtensionAbilityWithAccount

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

使用AbilityInfo.AbilityType.SERVICE模板和account将当前能力连接到一个能力。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
options ConnectOptions 远端对象实例。

返回值:

类型 说明
number 返回Ability连接的结果code。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000002 Ability type error. The specified ability type is wrong.
16000004 Visibility verification failed.
16000006 Can not cross user operations.
16000011 Context does not exist.
16000050 Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var accountId = 100;
var options = {
  onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
  onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
  onFailed(code) { console.log('----------- onFailed -----------') }
}

var connection = null;
try {
  connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options);
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

ServiceExtensionContext.disconnectServiceExtensionAbility

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

将一个Ability与绑定的服务类型的Ability解绑。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
connection number 在connectAbility中返回的number。
callback AsyncCallback<void> 回调函数,返回接口调用是否成功的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000003 Input error. The specified id does not exist.
16000011 Context does not exist.
16000050 Internal Error.

示例:

// connection为connectServiceExtensionAbility中的返回值
var connection = 1;

try {
  this.context.disconnectServiceExtensionAbility(connection, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('disconnectServiceExtensionAbility succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

ServiceExtensionContext.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number): Promise<void>;

将一个Ability与绑定的服务类型的Ability解绑。通过Promise返回结果。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API: 此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
connection number 在connectAbility中返回的number。

返回值:

类型 说明
Promise<void> 返回一个Promise,包含接口的结果。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000003 Input error. The specified id does not exist.
16000011 Context does not exist.
16000050 Internal Error.

示例:

// connection为connectAbility中的返回值
var connection = 1;

try {
  this.context.disconnectServiceExtensionAbility(connection)
    .then((data) => {
      // 执行正常业务
      console.log('disconnectServiceExtensionAbility succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

ServiceExtensionContext.startAbilityByCall

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

启动指定Ability至前台或后台,同时获取其Caller通信接口,调用方可使用Caller与被启动的Ability进行通信。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

系统API:此接口为系统接口,三方应用不支持调用。

参数:

参数名 类型 必填 说明
want Want 传入需要启动的Ability的信息,包含abilityName、moduleName、bundleName、deviceId(可选)、parameters(可选),其中deviceId缺省或为空表示启动本地Ability,parameters缺省或为空表示后台启动Ability。

返回值:

类型 说明
Promise<Caller> 获取要通讯的caller对象。

错误码:

错误码ID 错误信息
201 The application does not have permission to call the interface.
401 Invalid input parameter.
16000001 Input error. The specified ability name does not exist.
16000004 Visibility verification failed.
16000005 Static permission denied. The specified process does not have the permission.
16000007 Service busyness. There are concurrent tasks, waiting for retry.
16000008 Crowdtest App Expiration.
16000009 Can not start ability in wukong mode.
16000050 Internal Error.

示例:

后台启动:

var caller = undefined;

// 后台启动Ability,不配置parameters
var wantBackground = {
    bundleName: "com.example.myservice",
    moduleName: "entry",
    abilityName: "MainAbility",
    deviceId: ""
};

try {
  this.context.startAbilityByCall(wantBackground)
    .then((obj) => {
      // 执行正常业务
      caller = obj;
      console.log('startAbilityByCall succeed');
    }).catch((error) => {
      // 处理业务逻辑错误
      console.log('startAbilityByCall failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

前台启动:

var caller = undefined;

// 前台启动Ability,将parameters中的"ohos.aafwk.param.callAbilityToForeground"配置为true
var wantForeground = {
    bundleName: "com.example.myservice",
    moduleName: "entry",
    abilityName: "MainAbility",
    deviceId: "",
    parameters: {
      "ohos.aafwk.param.callAbilityToForeground": true
    }
};

try {
  this.context.startAbilityByCall(wantForeground)
    .then((obj) => {
      // 执行正常业务
      caller = obj;
      console.log('startAbilityByCall succeed');
    }).catch((error) => {
      // 处理业务逻辑错误
      console.log('startAbilityByCall failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29