UIAbilityContext
The UIAbilityContext module, inherited from Context, implements the context for UIAbilities.
This module provides APIs for accessing UIAbility-specific resources. You can use the APIs to start and terminate a UIAbility, obtain the caller interface, and request permissions from users by displaying a dialog box.
NOTE
- The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
- The APIs of this module can be used only in the stage model.
Attributes
System capability: SystemCapability.Ability.AbilityRuntime.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
abilityInfo | AbilityInfo | Yes | No | Ability information. |
currentHapModuleInfo | HapModuleInfo | Yes | No | Information about the current HAP. |
config | Configuration | Yes | No | Configuration information. |
UIAbilityContext.startAbility
startAbility(want: Want, callback: AsyncCallback<void>): void;
Starts an ability. This API uses an asynchronous callback to return the result.
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, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
- For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
bundleName: 'com.example.myapp',
abilityName: 'MyAbility'
};
try {
this.context.startAbility(want, (error) => {
if (error.code) {
// Process service logic errors.
console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startAbility succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbility
startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void;
Starts an ability with the start options specified. This API uses an asynchronous callback to return the result.
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, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
- For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
System capability: SystemCapability.Ability.AbilityRuntime.Core
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. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let options = {
windowMode: 0
};
try {
this.context.startAbility(want, options, (error) => {
if (error.code) {
// Process service logic errors.
console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startAbility succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbility
startAbility(want: Want, options?: StartOptions): Promise<void>;
Starts an ability. This API uses a promise to return the result.
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, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
- For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
System capability: SystemCapability.Ability.AbilityRuntime.Core
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 used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
bundleName: 'com.example.myapp',
abilityName: 'MyAbility'
};
let options = {
windowMode: 0,
};
try {
this.context.startAbility(want, options)
.then((data) => {
// Carry out normal service processing.
console.log('startAbility succeed');
})
.catch((error) => {
// Process service logic errors.
console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityForResult
startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void;
Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability:
- Normally, you can call terminateSelfWithResult to terminate the ability. The result is returned to the caller.
- If an exception occurs, for example, the ability is killed, an error message, in which resultCode is -1, is returned to the caller.
- If different applications call this API to start an ability that uses the singleton mode and then call terminateSelfWithResult to terminate the ability, the normal result is returned to the last caller, and an error message, in which resultCode is -1, is returned to others.
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, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
- For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
callback | AsyncCallback<AbilityResult> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
try {
this.context.startAbilityForResult(want, (error, result) => {
if (error.code) {
// Process service logic errors.
console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startAbilityForResult succeed, result.resultCode = ' +
result.resultCode)
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityForResult
startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void;
Starts an ability with the start options specified. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability:
- Normally, you can call terminateSelfWithResult to terminate the ability. The result is returned to the caller.
- If an exception occurs, for example, the ability is killed, an error message, in which resultCode is -1, is returned to the caller.
- If different applications call this API to start an ability that uses the singleton mode and then call terminateSelfWithResult to terminate the ability, the normal result is returned to the last caller, and an error message, in which resultCode is -1, is returned to others.
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, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
- For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
System capability: SystemCapability.Ability.AbilityRuntime.Core
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<AbilityResult> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let options = {
windowMode: 0,
};
try {
this.context.startAbilityForResult(want, options, (error, result) => {
if (error.code) {
// Process service logic errors.
console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startAbilityForResult succeed, result.resultCode = ' +
result.resultCode)
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityForResult
startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>;
Starts an ability. This API uses a promise to return the result when the ability is terminated. The following situations may be possible to an ability after it is started:
- Normally, you can call terminateSelfWithResult to terminate the ability. The result is returned to the caller.
- If an exception occurs, for example, the ability is killed, an error message, in which resultCode is -1, is returned to the caller.
- If different applications call this API to start an ability that uses the singleton mode and then call terminateSelfWithResult to terminate the ability, the normal result is returned to the last caller, and an error message, in which resultCode is -1, is returned to others.
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, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
- For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
System capability: SystemCapability.Ability.AbilityRuntime.Core
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<AbilityResult> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
bundleName: 'com.example.myapp',
abilityName: 'MyAbility'
};
let options = {
windowMode: 0,
};
try {
this.context.startAbilityForResult(want, options)
.then((result) => {
// Carry out normal service processing.
console.log('startAbilityForResult succeed, result.resultCode = ' + result.resultCode);
})
.catch((error) => {
// Process service logic errors.
console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityForResultWithAccount
startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback<AbilityResult>): void;
Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated.
Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
callback | AsyncCallback<AbilityResult> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
try {
this.context.startAbilityForResultWithAccount(want, accountId, (error, result) => {
if (error.code) {
// Process service logic errors.
console.log('startAbilityForResultWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startAbilityForResultWithAccount succeed, result.resultCode = ' +
result.resultCode)
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityForResultWithAccount
startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback<void>): void;
Starts an ability with the start options and account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated.
Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
options | StartOptions | Yes | Parameters used for starting the ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
let options = {
windowMode: 0
};
try {
this.context.startAbilityForResultWithAccount(want, accountId, options, (error, result) => {
if (error.code) {
// Process service logic errors.
console.log('startAbilityForResultWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startAbilityForResultWithAccount succeed, result.resultCode = ' +
result.resultCode)
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityForResultWithAccount
startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise<AbilityResult>;
Starts an ability with the account ID specified. This API uses a promise to return the result when the ability is terminated.
Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
options | StartOptions | No | Parameters used for starting the ability. |
Return value
Type | Description |
---|---|
Promise<AbilityResult> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
let options = {
windowMode: 0
};
try {
this.context.startAbilityForResultWithAccount(want, accountId, options)
.then((result) => {
// Carry out normal service processing.
console.log('startAbilityForResultWithAccount succeed, result.resultCode = ' +
result.resultCode)
})
.catch((error) => {
// Process service logic errors.
console.log('startAbilityForResultWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.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 and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
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. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
try {
this.context.startServiceExtensionAbility(want, (error) => {
if (error.code) {
// Process service logic errors.
console.log('startServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startServiceExtensionAbility succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startServiceExtensionAbility
startServiceExtensionAbility(want: Want): Promise<void>;
Starts a ServiceExtensionAbility. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
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. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
try {
this.context.startServiceExtensionAbility(want)
.then((data) => {
// Carry out normal service processing.
console.log('startServiceExtensionAbility succeed');
})
.catch((error) => {
// Process service logic errors.
console.log('startServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.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 and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
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. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
try {
this.context.startServiceExtensionAbilityWithAccount(want, accountId, (error) => {
if (error.code) {
// Process service logic errors.
console.log('startServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startServiceExtensionAbilityWithAccount succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.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.
Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
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. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
try {
this.context.startServiceExtensionAbilityWithAccount(want, accountId)
.then((data) => {
// Carry out normal service processing.
console.log('startServiceExtensionAbilityWithAccount succeed');
})
.catch((error) => {
// Process service logic errors.
console.log('startServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.stopServiceExtensionAbility
stopServiceExtensionAbility(want: Want, callback: AsyncCallback<void>): void;
Stops a ServiceExtensionAbility in the same application. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
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. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
try {
this.context.stopServiceExtensionAbility(want, (error) => {
if (error.code) {
// Process service logic errors.
console.log('stopServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('stopServiceExtensionAbility succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.stopServiceExtensionAbility
stopServiceExtensionAbility(want: Want): Promise<void>;
Stops a ServiceExtensionAbility in the same application. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
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. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
try {
this.context.stopServiceExtensionAbility(want)
.then((data) => {
// Carry out normal service processing.
console.log('stopServiceExtensionAbility succeed');
})
.catch((error) => {
// Process service logic errors.
console.log('stopServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.stopServiceExtensionAbilityWithAccount
stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback<void>): void;
Stops a ServiceExtensionAbility with the account ID specified in the same application. 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 and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
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. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
try {
this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (error) => {
if (error.code) {
// Process service logic errors.
console.log('stopServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('stopServiceExtensionAbilityWithAccount succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.stopServiceExtensionAbilityWithAccount
stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise<void>;
Stops a ServiceExtensionAbility with the account ID specified in the same application. This API uses a promise 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 and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
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. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
try {
this.context.stopServiceExtensionAbilityWithAccount(want, accountId)
.then((data) => {
// Carry out normal service processing.
console.log('stopServiceExtensionAbilityWithAccount succeed');
})
.catch((error) => {
// Process service logic errors.
console.log('stopServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.terminateSelf
terminateSelf(callback: AsyncCallback<void>): void;
Terminates this ability. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000004 | Can not start invisible component. |
16000005 | The specified process does not have the permission. |
16000009 | An ability cannot be started or stopped in Wukong mode. |
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
this.context.terminateSelf((error) => {
if (error.code) {
// Process service logic errors.
console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('terminateSelf succeed');
});
UIAbilityContext.terminateSelf
terminateSelf(): Promise<void>;
Terminates this ability. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000004 | Can not start invisible component. |
16000005 | The specified process does not have the permission. |
16000009 | An ability cannot be started or stopped in Wukong mode. |
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
this.context.terminateSelf().then((data) => {
// Carry out normal service processing.
console.log('terminateSelf succeed');
}).catch((error) => {
// Process service logic errors.
console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
UIAbilityContext.terminateSelfWithResult
terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void;
Terminates this ability. If the ability is started by calling startAbilityForResult, the result is returned to the caller in the form of an asynchronous callback when terminateSelfWithResult is called. Otherwise, no result is returned to the caller when terminateSelfWithResult is called.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | AbilityResult | Yes | Information returned to the caller. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000004 | Can not start invisible component. |
16000005 | The specified process does not have the permission. |
16000009 | An ability cannot be started or stopped in Wukong mode. |
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
bundleName: 'com.extreme.myapplication',
abilityName: 'SecondAbility'
}
let resultCode = 100;
// AbilityResult information returned to the caller.
let abilityResult = {
want,
resultCode
}
try {
this.context.terminateSelfWithResult(abilityResult, (error) => {
if (error.code) {
// Process service logic errors.
console.log('terminateSelfWithResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('terminateSelfWithResult succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.terminateSelfWithResult
terminateSelfWithResult(parameter: AbilityResult): Promise<void>;
Terminates this ability. If the ability is started by calling startAbilityForResult, the result is returned to the caller in the form of a promise when terminateSelfWithResult is called. Otherwise, no result is returned to the caller when terminateSelfWithResult is called.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | AbilityResult | Yes | Information returned to the caller. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000004 | Can not start invisible component. |
16000005 | The specified process does not have the permission. |
16000009 | An ability cannot be started or stopped in Wukong mode. |
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
bundleName: 'com.extreme.myapplication',
abilityName: 'SecondAbility'
}
let resultCode = 100;
// AbilityResult information returned to the caller.
let abilityResult = {
want,
resultCode
}
try {
this.context.terminateSelfWithResult(abilityResult)
.then((data) => {
// Carry out normal service processing.
console.log('terminateSelfWithResult succeed');
})
.catch((error) => {
// Process service logic errors.
console.log('terminateSelfWithResult failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.connectServiceExtensionAbility
connectServiceExtensionAbility(want: Want, options: ConnectOptions): number;
Connects this ability to an ability that uses the AbilityInfo.AbilityType.SERVICE template.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
options | ConnectOptions | No | Parameters for the connection. |
Return value
Type | Description |
---|---|
number | Result code of the ability connection. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000005 | The specified process does not have the permission. |
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let options = {
onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
onFailed(code) { console.log('----------- onFailed -----------') }
}
let connection = null;
try {
connection = this.context.connectServiceExtensionAbility(want, options);
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.connectServiceExtensionAbilityWithAccount
connectServiceExtensionAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number;
Connects this ability to an ability that uses the AbilityInfo.AbilityType.SERVICE template, with the account ID specified.
Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
options | ConnectOptions | No | Parameters for the connection. |
Return value
Type | Description |
---|---|
number | Result code of the ability connection. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000005 | The specified process does not have the permission. |
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
let options = {
onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
onFailed(code) { console.log('----------- onFailed -----------') }
}
let connection = null;
try {
connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options);
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.disconnectServiceExtensionAbility
disconnectServiceExtensionAbility(connection: number): Promise<void>;
Disconnects a connection. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
connection | number | Yes | Result code of the ability connection. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
// connection is the return value of connectServiceExtensionAbility.
let connection = 1;
try {
this.context.disconnectServiceExtensionAbility(connection)
.then((data) => {
// Carry out normal service processing.
console.log('disconnectServiceExtensionAbility succeed');
})
.catch((error) => {
// Process service logic errors.
console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.disconnectServiceExtensionAbility
disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback<void>): void;
Disconnects a connection. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
connection | number | Yes | Result code of the ability connection. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
// connection is the return value of connectServiceExtensionAbility.
let connection = 1;
try {
this.context.disconnectServiceExtensionAbility(connection, (error) => {
if (error.code) {
// Process service logic errors.
console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('disconnectServiceExtensionAbility succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityByCall
startAbilityByCall(want: Want): Promise<Caller>;
Starts an ability in the foreground or background and obtains the caller object for communicating with the ability.
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, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
- For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
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. |
Return value
Type | Description |
---|---|
Promise<Caller> | Promise used to return the caller object to communicate with. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
Start an ability in the background.
let caller = undefined;
// Start an ability in the background by not passing parameters.
let wantBackground = {
bundleName: 'com.example.myservice',
moduleName: 'entry',
abilityName: 'MainAbility',
deviceId: ''
};
try {
this.context.startAbilityByCall(wantBackground)
.then((obj) => {
// Carry out normal service processing.
caller = obj;
console.log('startAbilityByCall succeed');
}).catch((error) => {
// Process service logic errors.
console.log('startAbilityByCall failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
Start an ability in the foreground.
let caller = undefined;
// Start an ability in the foreground with 'ohos.aafwk.param.callAbilityToForeground' in parameters set to true.
let wantForeground = {
bundleName: 'com.example.myservice',
moduleName: 'entry',
abilityName: 'MainAbility',
deviceId: '',
parameters: {
'ohos.aafwk.param.callAbilityToForeground': true
}
};
try {
this.context.startAbilityByCall(wantForeground)
.then((obj) => {
// Carry out normal service processing.
caller = obj;
console.log('startAbilityByCall succeed');
}).catch((error) => {
// Process service logic errors.
console.log('startAbilityByCall failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback<void>): void;
Starts an ability 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 and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
try {
this.context.startAbilityWithAccount(want, accountId, (error) => {
if (error.code) {
// Process service logic errors.
console.log('startAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startAbilityWithAccount succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback<void>): void;
Starts an ability 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 and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
options | StartOptions | No | Parameters used for starting the ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
let options = {
windowMode: 0
};
try {
this.context.startAbilityWithAccount(want, accountId, options, (error) => {
if (error.code) {
// Process service logic errors.
console.log('startAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
return;
}
// Carry out normal service processing.
console.log('startAbilityWithAccount succeed');
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise<void>;
Starts an ability with the account ID specified. This API uses a promise 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 and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
want | Want | Yes | Want information about the target ability. |
accountId | number | Yes | ID of a system account. For details, see getCreatedOsAccountsCount. |
options | StartOptions | No | Parameters used for starting the ability. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start 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 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. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
let want = {
deviceId: '',
bundleName: 'com.extreme.test',
abilityName: 'MainAbility'
};
let accountId = 100;
let options = {
windowMode: 0
};
try {
this.context.startAbilityWithAccount(want, accountId, options)
.then((data) => {
// Carry out normal service processing.
console.log('startAbilityWithAccount succeed');
})
.catch((error) => {
// Process service logic errors.
console.log('startAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) +
' error.message: ' + JSON.stringify(error.message));
});
} catch (paramError) {
// Process input parameter errors.
console.log('error.code: ' + JSON.stringify(paramError.code) +
' error.message: ' + JSON.stringify(paramError.message));
}
UIAbilityContext.requestPermissionsFromUser
requestPermissionsFromUser(permissions: Array<string>, requestCallback: AsyncCallback<PermissionRequestResult>) : void;
Requests permissions from the user by displaying a dialog box. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
permissions | Array<string> | Yes | Permissions to request. |
callback | AsyncCallback<PermissionRequestResult> | Yes | Callback used to return the result. |
Example
let permissions=['com.example.permission']
this.context.requestPermissionsFromUser(permissions,(result) => {
console.log('requestPermissionsFromUserresult:' + JSON.stringify(result));
});
UIAbilityContext.requestPermissionsFromUser
requestPermissionsFromUser(permissions: Array<string>) : Promise<PermissionRequestResult>;
Requests permissions from the user by displaying a dialog box. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
permissions | Array<string> | Yes | Permissions to request. |
Return value
Type | Description |
---|---|
Promise<PermissionRequestResult> | Promise used to return the result. |
Example
let permissions=['com.example.permission']
this.context.requestPermissionsFromUser(permissions).then((data) => {
console.log('success:' + JSON.stringify(data));
}).catch((error) => {
console.log('failed:' + JSON.stringify(error));
});
UIAbilityContext.setMissionLabel
setMissionLabel(label: string, callback:AsyncCallback<void>): void;
Sets a label for this ability in the mission. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
label | string | Yes | Label of the ability to set. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
this.context.setMissionLabel('test',(result) => {
console.log('requestPermissionsFromUserresult:' + JSON.stringify(result));
});
UIAbilityContext.setMissionLabel
setMissionLabel(label: string): Promise<void>;
Sets a label for this ability in the mission. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
label | string | Yes | Label of the ability to set. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
this.context.setMissionLabel('test').then(() => {
console.log('success');
}).catch((error) => {
console.log('failed:' + JSON.stringify(error));
});
UIAbilityContext.setMissionIcon
setMissionIcon(icon: image.PixelMap, callback:AsyncCallback<void>): void;
Sets an icon for this ability in the mission. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
icon | image.PixelMap | Yes | Icon of the ability to set. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
import image from '@ohos.multimedia.image';
let imagePixelMap;
let color = new ArrayBuffer(0);
let initializationOptions = {
size: {
height: 100,
width: 100
}
};
image.createPixelMap(color, initializationOptions)
.then((data) => {
imagePixelMap = data;
})
.catch((err) => {
console.log('--------- createPixelMap fail, err: ---------', err)
});
this.context.setMissionIcon(imagePixelMap, (err) => {
console.log('---------- setMissionIcon fail, err: -----------', err);
})
UIAbilityContext.setMissionIcon
setMissionIcon(icon: image.PixelMap): Promise<void>;
Sets an icon for this ability in the mission. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API and cannot be called by third-party applications.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
icon | image.PixelMap | Yes | Icon of the ability to set. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
import image from '@ohos.multimedia.image';
let imagePixelMap;
let color = new ArrayBuffer(0);
let initializationOptions = {
size: {
height: 100,
width: 100
}
};
image.createPixelMap(color, initializationOptions)
.then((data) => {
imagePixelMap = data;
})
.catch((err) => {
console.log('--------- createPixelMap fail, err: ---------', err)
});
this.context.setMissionIcon(imagePixelMap)
.then(() => {
console.log('-------------- setMissionIcon success -------------');
})
.catch((err) => {
console.log('-------------- setMissionIcon fail, err: -------------', err);
});
UIAbilityContext.restoreWindowStage
restoreWindowStage(localStorage: LocalStorage) : void;
Restores the window stage data for this ability.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
localStorage | image.LocalStorage | Yes | Storage used to store the restored window stage. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
let storage = new LocalStorage();
this.context.restoreWindowStage(storage);
UIAbilityContext.isTerminating
isTerminating(): boolean;
Checks whether this ability is in the terminating state.
System capability: SystemCapability.Ability.AbilityRuntime.Core
Return value
Type | Description |
---|---|
boolean | The value true means that the UIAbility is in the terminating state, and false means the opposite. |
Error codes
ID | Error Message |
---|---|
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
let isTerminating = this.context.isTerminating();
console.log('ability state :' + isTerminating);