UIAbilityContext (System API)
UIAbilityContext, inherited from Context, provides the context environment for UIAbility that needs to store its status. UIAbilityContext provides UIAbility-related configuration and APIs for operating UIAbilities and ServiceExtensionAbilities. For example, you can use the APIs to start a UIAbility, terminate a UIAbility to which the UIAbilityContext belongs, and start, terminate, connect to, or disconnect from a ServiceExtensionAbility.
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.
- The APIs of this module must be used in the main thread, but not in sub-threads such as Worker and TaskPool.
- The APIs provided by this module are system APIs.
Modules to Import
import common from '@ohos.app.ability.common';
NOTE
In the sample code provided in this topic, this.context is used to obtain UIAbilityContext, where this indicates a UIAbility instance inherited from UIAbility. To use UIAbilityContext APIs on pages, see Obtaining the Context of UIAbility.
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.
NOTE
For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import common from '@ohos.app.ability.common';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let accountId = 100;
try {
this.context.startAbilityForResultWithAccount(want, accountId, (err: BusinessError, result: common.AbilityResult) => {
if (err.code) {
// Process service logic errors.
console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('startAbilityForResultWithAccount succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startAbilityForResultWithAccount failed, code is ${code}, message is ${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.
NOTE
For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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 invoked when the ability is terminated. |
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let accountId = 100;
let options: StartOptions = {
displayId: 0
};
try {
this.context.startAbilityForResultWithAccount(want, accountId, options, (err: BusinessError) => {
if (err.code) {
// Process service logic errors.
console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('startAbilityForResultWithAccount succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startAbilityForResultWithAccount failed, code is ${code}, message is ${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.
NOTE
For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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 ability result when the ability is terminated. |
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import common from '@ohos.app.ability.common';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let accountId = 100;
let options: StartOptions = {
displayId: 0
};
try {
this.context.startAbilityForResultWithAccount(want, accountId, options)
.then((result: common.AbilityResult) => {
// Carry out normal service processing.
console.info('startAbilityForResultWithAccount succeed');
})
.catch((err: BusinessError) => {
// Process service logic errors.
console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startAbilityForResultWithAccount failed, code is ${code}, message is ${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 ServiceExtensionAbility. |
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. |
16000011 | The context does not exist. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'ServiceExtensionAbility'
};
try {
this.context.startServiceExtensionAbility(want, (error: BusinessError) => {
if (error.code) {
// Process service logic errors.
console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startServiceExtensionAbility failed, code is ${code}, message is ${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 ServiceExtensionAbility. |
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'ServiceExtensionAbility'
};
try {
this.context.startServiceExtensionAbility(want)
.then(() => {
// Carry out normal service processing.
console.info('startServiceExtensionAbility succeed');
})
.catch((err: BusinessError) => {
// Process service logic errors.
console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startServiceExtensionAbility failed, code is ${code}, message is ${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.
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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 ServiceExtensionAbility. |
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. |
16000011 | The context does not exist. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'ServiceExtensionAbility'
};
let accountId = 100;
try {
this.context.startServiceExtensionAbilityWithAccount(want, accountId, (err: BusinessError) => {
if (err.code) {
// Process service logic errors.
console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('startServiceExtensionAbilityWithAccount succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${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.
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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. |
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'ServiceExtensionAbility'
};
let accountId = 100;
try {
this.context.startServiceExtensionAbilityWithAccount(want, accountId)
.then(() => {
// Carry out normal service processing.
console.info('startServiceExtensionAbilityWithAccount succeed');
})
.catch((err: BusinessError) => {
// Process service logic errors.
console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${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 ServiceExtensionAbility. |
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. |
16000011 | The context does not exist. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'ServiceExtensionAbility'
};
try {
this.context.stopServiceExtensionAbility(want, (err: BusinessError) => {
if (err.code) {
// Process service logic errors.
console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('stopServiceExtensionAbility succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`stopServiceExtensionAbility failed, code is ${code}, message is ${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 ServiceExtensionAbility. |
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. |
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
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'ServiceExtensionAbility'
};
try {
this.context.stopServiceExtensionAbility(want)
.then(() => {
// Carry out normal service processing.
console.info('stopServiceExtensionAbility succeed');
})
.catch((err: BusinessError) => {
// Process service logic errors.
console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`stopServiceExtensionAbility failed, code is ${code}, message is ${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.
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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 ServiceExtensionAbility. |
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. |
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
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'ServiceExtensionAbility'
};
let accountId = 100;
try {
this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (err: BusinessError) => {
if (err.code) {
// Process service logic errors.
console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('stopServiceExtensionAbilityWithAccount succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${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.
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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 ServiceExtensionAbility. |
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. |
16000004 | Can not start invisible component. |
16000005 | The specified process does not have the permission. |
16000006 | Cross-user operations are not allowed. |
16000011 | The context does not exist. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'ServiceExtensionAbility'
};
let accountId = 100;
try {
this.context.stopServiceExtensionAbilityWithAccount(want, accountId)
.then(() => {
// Carry out normal service processing.
console.info('stopServiceExtensionAbilityWithAccount succeed');
})
.catch((err: BusinessError) => {
// Process service logic errors.
console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${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.
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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 | Yes | Instance of the callback function after the connection to the ServiceExtensionAbility is set up. |
Return value
Type | Description |
---|---|
number | Result code of the ability connection. |
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. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16000011 | The context does not exist. |
16000050 | Internal error. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import common from '@ohos.app.ability.common';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
import rpc from '@ohos.rpc';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'ServiceExtensionAbility'
};
let accountId = 100;
let commRemote: rpc.IRemoteObject;
let options: common.ConnectOptions = {
onConnect(elementName, remote) {
commRemote = remote;
console.info('onConnect...')
},
onDisconnect(elementName) {
console.info('onDisconnect...')
},
onFailed(code) {
console.info('onFailed...')
}
};
let connection: number;
try {
connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options);
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`connectServiceExtensionAbility failed, code is ${code}, message is ${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.
NOTE
For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let accountId = 100;
try {
this.context.startAbilityWithAccount(want, accountId, (err: BusinessError) => {
if (err.code) {
// Process service logic errors.
console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('startAbilityWithAccount succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startAbilityWithAccount failed, code is ${code}, message is ${message}`);
}
}
}
UIAbilityContext.startAbilityWithAccount
startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback<void>): void
Starts an ability with the account ID and start options specified. This API uses an asynchronous callback to return the result.
NOTE
For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let accountId = 100;
let options: StartOptions = {
displayId: 0
};
try {
this.context.startAbilityWithAccount(want, accountId, options, (err: BusinessError) => {
if (err.code) {
// Process service logic errors.
console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('startAbilityWithAccount succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startAbilityWithAccount failed, code is ${code}, message is ${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.
NOTE
For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).
NOTE
The ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permission is not required when accountId specifies the current user.
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let accountId = 100;
let options: StartOptions = {
displayId: 0
};
try {
this.context.startAbilityWithAccount(want, accountId, options)
.then(() => {
// Carry out normal service processing.
console.info('startAbilityWithAccount succeed');
})
.catch((err: BusinessError) => {
// Process service logic errors.
console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startAbilityWithAccount failed, code is ${code}, message is ${message}`);
}
}
}
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. The maximum size of the icon is 600 MB.
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 UIAbility from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import image from '@ohos.multimedia.image';
export default class EntryAbility extends UIAbility {
onForeground() {
let imagePixelMap: image.PixelMap;
let color = new ArrayBuffer(0);
image.createPixelMap(color, {
size: {
height: 100,
width: 100
}
}).then((data) => {
imagePixelMap = data;
this.context.setMissionIcon(imagePixelMap, (err: BusinessError) => {
console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`);
})
})
.catch((err: BusinessError) => {
console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`);
});
}
}
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. The maximum size of the icon is 600 MB.
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 UIAbility from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import image from '@ohos.multimedia.image';
export default class EntryAbility extends UIAbility {
onForeground() {
let imagePixelMap: image.PixelMap;
let color = new ArrayBuffer(0);
image.createPixelMap(color, {
size: {
height: 100,
width: 100
}
}).then((data) => {
imagePixelMap = data;
this.context.setMissionIcon(imagePixelMap)
.then(() => {
console.info('setMissionIcon succeed');
})
.catch((err: BusinessError) => {
console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`);
});
})
.catch((err: BusinessError) => {
console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`);
});
}
}
UIAbilityContext.startRecentAbility
startRecentAbility(want: Want, callback: AsyncCallback<void>): void
Starts an ability. If the ability has multiple instances, the latest instance is started. This API uses an asynchronous callback to return the result.
NOTE
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 | Want information about the target ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see 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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
try {
this.context.startRecentAbility(want, (err: BusinessError) => {
if (err.code) {
// Process service logic errors.
console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('startRecentAbility succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startRecentAbility failed, code is ${code}, message is ${message}`);
}
}
}
UIAbilityContext.startRecentAbility
startRecentAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void
Starts an ability with the start options specified. If the ability has multiple instances, the latest instance is started. This API uses an asynchronous callback to return the result. You can use this API to carry start options.
NOTE
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 | 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
For details about the error codes, see 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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
deviceId: '',
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let options: StartOptions = {
displayId: 0
};
try {
this.context.startRecentAbility(want, options, (err: BusinessError) => {
if (err.code) {
// Process service logic errors.
console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('startRecentAbility succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startRecentAbility failed, code is ${code}, message is ${message}`);
}
}
}
UIAbilityContext.startRecentAbility
startRecentAbility(want: Want, options?: StartOptions): Promise<void>
Starts an ability. If the ability has multiple instances, the latest instance is started. This API uses a promise to return the result.
NOTE
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 | Want information about the target ability. |
options | StartOptions | No | Parameters used for starting the ability. |
Error codes
For details about the error codes, see 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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let options: StartOptions = {
displayId: 0,
};
try {
this.context.startRecentAbility(want, options)
.then(() => {
// Carry out normal service processing.
console.info('startRecentAbility succeed');
})
.catch((err: BusinessError) => {
// Process service logic errors.
console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startRecentAbility failed, code is ${code}, message is ${message}`);
}
}
}
UIAbilityContext.startAbilityByCallWithAccount10+
startAbilityByCallWithAccount(want: Want, accountId: number): Promise<Caller>
Starts an ability with the account ID specified and obtains the caller object for communicating with the ability.
Observe the following when using this API:
- If an application needs to call this API to start an ability that belongs to another user, it must have the ohos.permission.ABILITY_BACKGROUND_COMMUNICATION and ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS permissions.
- If an application running in the background needs to call this API to start an ability, it must have the ohos.permission.START_ABILITIES_FROM_BACKGROUND permission.
- If exported of the target ability is false in cross-application scenarios, the caller must have the ohos.permission.START_INVISIBLE_ABILITY permission.
- The rules for using this API in the same-device and cross-device scenarios are different. For details, see Component Startup Rules (Stage Model).
Required permissions: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION and ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API 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. |
accountId | number | Yes | ID of a system account. The value -1 indicates the current user. For details, see getCreatedOsAccountsCount. |
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 | Static permission denied. The specified process does not have the permission. |
16000006 | Cross-user operations are not allowed. |
16000008 | The crowdtesting application expires. |
16000011 | The context does not exist. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let caller: Caller;
// ID of a system account. The value -1 indicates the current user.
let accountId = -1;
// Specify the ability to start.
let want: Want = {
bundleName: 'com.acts.actscalleeabilityrely',
moduleName: 'entry',
abilityName: 'EntryAbility',
deviceId: '',
parameters: {
// If the value of 'ohos.aafwk.param.callAbilityToForeground' is true, the ability is started in the foreground. If the value is false or not set, the ability is started in the background.
'ohos.aafwk.param.callAbilityToForeground': true
}
};
try {
this.context.startAbilityByCallWithAccount(want, accountId)
.then((obj: Caller) => {
// Carry out normal service processing.
caller = obj;
console.log('startAbilityByCallWithAccount succeed');
}).catch((error: BusinessError) => {
// Process service logic errors.
console.error('startAbilityByCallWithAccount failed, error.code: ${error.code}, error.message: ${error.message}');
});
} catch (paramError) {
// Process input parameter errors.
console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
}
}
}
UIAbilityContext.startAbilityAsCaller10+
startAbilityAsCaller(want: Want, callback: AsyncCallback<void>): void
Starts an ability with the caller information specified. The caller information is carried in want and identified at the system service layer. The ability can obtain the caller information from the want parameter in the onCreate lifecycle callback. When this API is used to start an ability, the caller information carried in want is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API uses an asynchronous callback to return the result.
NOTE
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 | Want information about the target ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the ability is started, err is undefined. Otherwise, err is an error object. |
Error codes
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import Want from '@ohos.app.ability.Want';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
// want contains the information about the caller who starts the application.
let localWant: Want = want;
localWant.bundleName = 'com.example.demo';
localWant.moduleName = 'entry';
localWant.abilityName = 'TestAbility';
// Start a new ability using the caller information.
this.context.startAbilityAsCaller(localWant, (err) => {
if (err && err.code != 0) {
console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err));
} else {
console.log('startAbilityAsCaller success.');
}
})
}
}
UIAbilityContext.startAbilityAsCaller10+
startAbilityAsCaller(want: Want, options: StartOptions, callback: AsyncCallback<void>): void
Starts an ability with the caller information and start options specified. The caller information is carried in want and identified at the system service layer. The ability can obtain the caller information from the want parameter in the onCreate lifecycle callback. When this API is used to start an ability, the caller information carried in want is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API uses an asynchronous callback to return the result.
NOTE
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 | Want information about the target ability. |
options | StartOptions | Yes | Parameters used for starting the ability. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the ability is started, err is undefined. Otherwise, err is an error object. |
Error codes
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. |
16000006 | Cross-user operations are not allowed. |
16000008 | The crowdtesting application expires. |
16000009 | An ability cannot be started or stopped in Wukong mode. |
16000011 | The context does not exist. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import StartOptions from '@ohos.app.ability.StartOptions';
import Want from '@ohos.app.ability.Want';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
// want contains the information about the caller who starts the application.
let localWant: Want = want;
localWant.bundleName = 'com.example.demo';
localWant.moduleName = 'entry';
localWant.abilityName = 'TestAbility';
let option: StartOptions = {
displayId: 0
}
// Start a new ability using the caller information.
this.context.startAbilityAsCaller(localWant, option, (err) => {
if (err && err.code != 0) {
console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err));
} else {
console.log('startAbilityAsCaller success.');
}
})
}
}
UIAbilityContext.startAbilityAsCaller10+
startAbilityAsCaller(want: Want, options?: StartOptions): Promise<void>
Starts an ability with the caller information specified. The caller information is carried in want and identified at the system service layer. The ability can obtain the caller information from the want parameter in the onCreate lifecycle callback. When this API is used to start an ability, the caller information carried in want is not overwritten by the current application information. The system service layer can obtain the initial caller information. This API uses a promise to return the result.
NOTE
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 | Want information about the target ability. |
options | StartOptions | No | Parameters used for starting the ability. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
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. |
16000012 | The application is controlled. |
16000013 | The application is controlled by EDM. |
16000050 | Internal error. |
16000053 | The ability is not on the top of the UI. |
16000055 | Installation-free timed out. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import StartOptions from '@ohos.app.ability.StartOptions';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
// want contains the information about the caller who starts the application.
let localWant: Want = want;
localWant.bundleName = 'com.example.demo';
localWant.moduleName = 'entry';
localWant.abilityName = 'TestAbility';
let option: StartOptions = {
displayId: 0
}
// Start a new ability using the caller information.
this.context.startAbilityAsCaller(localWant, option)
.then(() => {
console.log('startAbilityAsCaller success.');
})
.catch((err: BusinessError) => {
console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err));
})
}
}
UIAbilityContext.requestModalUIExtension11+
requestModalUIExtension(pickerWant: Want): Promise<void>
Requests the specified foreground application to start the UIExtensionAbility of the corresponding type. The foreground application is specified by bundleName in want.parameters. If bundleName is left unspecified, or if the application specified by bundleName is not running in the foreground or does not exist, the UIExtensionAbility is directly started on the system UI. The UIExtensionAbility to start is determined by the combination of the bundleName, abilityName, and moduleName fields in want, and its type is determined by the ability.want.params.uiExtensionType field in want.parameters. This API uses a promise to return the result.
NOTE
For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model). If exported of the target ability is false in cross-application scenarios, the specified foreground application or the caller (when the UIExtensionAbility is directly started on the system UI) must have the ohos.permission.START_INVISIBLE_ABILITY permission.
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
pickerWant | Want | Yes | Want information used to start the modal window. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start invisible component. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
bundleName: 'com.example.myapplication',
abilityName: 'com.example.myapplication.UIExtAbility',
moduleName: 'entry_test',
parameters: {
'bundleName': 'com.example.myapplication',
// The value is the same as the value of type configured for com.example.myapplication.UIExtAbility.
'ability.want.params.uiExtensionType': 'sys/commonUI'
}
};
try {
this.context.requestModalUIExtension(want)
.then(() => {
// Carry out normal service processing.
console.info('requestModalUIExtension succeed');
})
.catch((err: BusinessError) => {
// Process service logic errors.
console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`);
}
}
}
UIAbilityContext.requestModalUIExtension11+
requestModalUIExtension(pickerWant: Want, callback: AsyncCallback<void>): void
Requests the specified foreground application to start the UIExtensionAbility of the corresponding type. The foreground application is specified by bundleName in want.parameters. If bundleName is left unspecified, or if the application specified by bundleName is not running in the foreground or does not exist, the UIExtensionAbility is directly started on the system UI. The UIExtensionAbility to start is determined by the combination of the bundleName, abilityName, and moduleName fields in want, and its type is determined by the ability.want.params.uiExtensionType field in want.parameters. This API uses an asynchronous callback to return the result.
NOTE
For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model). If exported of the target ability is false in cross-application scenarios, the specified foreground application or the caller (when the UIExtensionAbility is directly started on the system UI) must have the ohos.permission.START_INVISIBLE_ABILITY permission.
System capability: SystemCapability.Ability.AbilityRuntime.Core
System API: This is a system API.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
pickerWant | Want | Yes | Want information used to start the modal window. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the UIExtensionAbility is started, err is undefined; otherwise, err is an error object. |
Error codes
ID | Error Message |
---|---|
16000001 | The specified ability does not exist. |
16000002 | Incorrect ability type. |
16000004 | Can not start invisible component. |
16000050 | Internal error. |
16200001 | The caller has been released. |
For details about the error codes, see Ability Error Codes.
Example
import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';
export default class EntryAbility extends UIAbility {
onForeground() {
let want: Want = {
bundleName: 'com.example.myapplication',
abilityName: 'com.example.myapplication.UIExtAbility',
moduleName: 'entry_test',
parameters: {
'bundleName': 'com.example.myapplication',
// The value is the same as the value of type configured for com.example.myapplication.UIExtAbility.
'ability.want.params.uiExtensionType': 'sys/commonUI'
}
};
try {
this.context.requestModalUIExtension(want, (err: BusinessError) => {
if (err.code) {
// Process service logic errors.
console.error(`requestModalUIExtension failed, code is ${err.code}, message is ${err.message}`);
return;
}
// Carry out normal service processing.
console.info('requestModalUIExtension succeed');
});
} catch (err) {
// Process input parameter errors.
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`requestModalUIExtension failed, code is ${code}, message is ${message}`);
}
}
}