application_context.h
Overview
The file declares the APIs related to the application-level context.
File to include: <AbilityKit/ability_runtime/application_context.h>
Library: libability_runtime.so
System capability: SystemCapability.Ability.AbilityRuntime.Core
Since: 13
Related module: AbilityRuntime
Summary
Functions
Function Description
OH_AbilityRuntime_ApplicationContextGetCacheDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCacheDir(char* buffer, int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level cache directory of the application.
Since: 13
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the application-level cache directory of the application. |
| int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetAreaMode()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetAreaMode(AbilityRuntime_AreaMode* areaMode)
Description
Obtains the application-level file data encryption level of the application.
Since: 13
Parameters
| Name | Description |
|---|---|
| AbilityRuntime_AreaMode* areaMode | Pointer to the encryption level of the received data. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetBundleName()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleName(char* buffer, int32_t bufferSize, int32_t* writeLength)
Description
Obtains the bundle name of the application.
Since: 13
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the bundle name. |
| int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetTempDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetTempDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level temporary file directory of the application.
Since: 16
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the temporary file directory. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetFilesDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level common file directory of the application.
Since: 16
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the common file directory. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetDatabaseDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDatabaseDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level database file directory of the application.
Since: 16
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the database file directory. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetPreferencesDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetPreferencesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level preferences file directory of the application.
Since: 16
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the preferences file directory. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetBundleCodeDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleCodeDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level installation file directory of the application.
Since: 16
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the installation file directory. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level distributed file directory of the application.
Since: 16
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the distributed file directory. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetCloudFileDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCloudFileDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level cloud file directory of the application.
Since: 16
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the cloud file directory. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetLogFileDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetLogFileDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level log file directory of the application.
Since: 22
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive the log file directory. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_ApplicationContextGetResourceDir()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetResourceDir(const char* moduleName, char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains the application-level resource directory of the application.
Since: 20
Parameters
| Name | Description |
|---|---|
| char* moduleName | Pointer to the module name. |
| char* buffer | Pointer to the buffer, which is used to receive the resource directory. |
| int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
OH_AbilityRuntime_StartSelfUIAbility()
AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbility(AbilityBase_Want *want)
Description
Starts the UIAbility of the current application.
Required permissions: ohos.permission.NDK_START_SELF_UI_ABILITY
Since: 15
Device behavior differences: This API can be properly called only on 2-in-1 devices and tablets. If it is called on other device types, error code ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED is returned.
Parameters
| Name | Description |
|---|---|
| AbilityBase_Want *want | Pointer to the Want information required for starting the UIAbility. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED: Permission verification for the caller fails. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: Parameter verification for the caller fails. ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED: The device type is not supported. ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY: The specified ability name does not exist. ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE: The ability type is incorrect. ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED: The crowdtesting application expires. ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE: The ability is started or stopped in Wukong mode. ABILITY_RUNTIME_ERROR_CODE_CONTROLLED: The application is under control. ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED: The application is under control by EDM. ABILITY_RUNTIME_ERROR_CODE_CROSS_APP: Redirecting to third-party applications is not allowed in API versions later than 11. ABILITY_RUNTIME_ERROR_CODE_INTERNAL: An internal error occurs. ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY: The application is not a top one. ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED (available since API version 17): The number of instances has reached the upper limit. ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED (available since API version 17): Setting APP_INSTANCE_KEY is not supported. For details, see AbilityRuntime_ErrorCode. |
Example
#include <AbilityKit/ability_base/want.h>
#include <AbilityKit/ability_runtime/application_context.h>
void startSelfUIAbilityTest()
{
AbilityBase_Element element;
element.abilityName = const_cast<char*>("EntryAbility");
element.bundleName = const_cast<char*>("com.example.myapplication");
element.moduleName = const_cast<char*>("entry");
AbilityBase_Want* want = OH_AbilityBase_CreateWant(element);
AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbility(want);
if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
// Record error logs and other service processing.
return;
}
// Destroy the Want to prevent memory leakage.
OH_AbilityBase_DestroyWant(want);
}
OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions()
AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(AbilityBase_Want *want,AbilityRuntime_StartOptions *options)
Description
Starts the UIAbility of the current application using StartOptions.
Required permissions: ohos.permission.NDK_START_SELF_UI_ABILITY
Since: 17
Device behavior differences: This API can be properly called only on 2-in-1 devices and tablets. If it is called on other device types, error code ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED is returned.
Parameters
| Name | Description |
|---|---|
| AbilityBase_Want *want | Pointer to the Want information required for starting the UIAbility. |
| AbilityRuntime_StartOptions *options | Pointer to StartOptions required for starting the UIAbility. If the value of startVisibility is not null, ensure that the current application has been added to the status bar. Otherwise, the ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED error code is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED: Permission verification for the caller fails. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: Parameter verification for the caller fails. ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED: The device type is not supported. ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY: The specified ability name does not exist. ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE: The ability type is incorrect. ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED: The crowdtesting application expires. ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE: The ability is started or stopped in Wukong mode. ABILITY_RUNTIME_ERROR_CODE_CONTROLLED: The application is under control. ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED: The application is under control by EDM. ABILITY_RUNTIME_ERROR_CODE_CROSS_APP: Redirecting to third-party applications is not allowed in API versions later than 11. ABILITY_RUNTIME_ERROR_CODE_INTERNAL: An internal error occurs. ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY: The application is not a top one. ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED: Setting the window visibility during startup is not allowed. ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED: The application does not support clone or multi-instance mode. ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY: The multi-instance key is invalid. ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED: The number of instances has reached the upper limit. ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED: The application does not support multi-instance mode. ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED: Setting APP_INSTANCE_KEY is not supported. For details, see AbilityRuntime_ErrorCode. |
Example
#include <AbilityKit/ability_base/want.h>
#include <AbilityKit/ability_runtime/application_context.h>
void demo()
{
AbilityBase_Element element;
element.abilityName = const_cast<char*>("EntryAbility");
element.bundleName = const_cast<char*>("com.example.myapplication");
element.moduleName = const_cast<char*>("entry");
AbilityBase_Want* want = OH_AbilityBase_CreateWant(element);
if (want == nullptr) {
// Record error logs and other service processing.
return;
}
AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions();
if (options == nullptr) {
// Record error logs and other service processing.
// Destroy the Want to prevent memory leakage.
OH_AbilityBase_DestroyWant(want);
return;
}
AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(want, options);
if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
// Record error logs and other service processing.
}
// Destroy the Want to prevent memory leakage.
OH_AbilityBase_DestroyWant(want);
// Destroy options to prevent memory leakage.
OH_AbilityRuntime_DestroyStartOptions(&options);
}
OH_AbilityRuntime_ApplicationContextGetVersionCode()
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetVersionCode(int64_t* versionCode)
Description
Obtains the application version code.
Since: 21
Parameters
| Name | Description |
|---|---|
| int64_t* versionCode | Pointer to the bundle's version code, which corresponds to the versionCode field in bundleInfo. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: versionCode is null. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. ABILITY_RUNTIME_ERROR_CODE_GET_APPLICATION_INFO_FAILED: Failed to obtain the application information. |
OH_AbilityRuntime_StartSelfUIAbilityWithPidResult()
AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbilityWithPidResult(AbilityBase_Want *want, AbilityRuntime_StartOptions *options, int32_t *targetPid)
Description
Starts the UIAbility of the current application using StartOptions and obtains the process ID of the target UIAbility.
This function cannot be called on the main thread of an application, but can be called on the main thread of a child process created by the application.
If it is called on the main thread of the application, error code ABILITY_RUNTIME_ERROR_CODE_MAIN_THREAD_NOT_SUPPORTED is returned.
Required permissions: ohos.permission.NDK_START_SELF_UI_ABILITY
Since: 21
Device behavior differences: This API can be properly called only on 2-in-1 devices and tablets. If it is called on other device types, error code ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED is returned.
Parameters
| Name | Description |
|---|---|
| AbilityBase_Want *want | Pointer to the Want information required for starting the UIAbility. |
| AbilityRuntime_StartOptions *options | Pointer to StartOptions required for starting the UIAbility. If the value of startVisibility is not null, ensure that the current application has been added to the status bar. Otherwise, the ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED error code is returned. |
| int32_t *targetPid | Pointer to the process ID of the target UIAbility. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED: Permission verification for the caller fails. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: Parameter verification for the caller fails. ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED: The device type is not supported. ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY: The specified ability name does not exist. ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE: The ability type is incorrect. ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED: The crowdtesting application expires. ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE: The ability is started or stopped in Wukong mode. ABILITY_RUNTIME_ERROR_CODE_CONTROLLED: The application is under control. ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED: The application is under control by EDM. ABILITY_RUNTIME_ERROR_CODE_CROSS_APP: Redirecting to third-party applications is not allowed in API versions later than 11. ABILITY_RUNTIME_ERROR_CODE_INTERNAL: An internal error occurs. ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY: The application is not a top one. ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED: Setting the window visibility during startup is not allowed. ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED: The application does not support clone or multi-instance mode. ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY: The multi-instance key is invalid. ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED: The number of instances has reached the upper limit. ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED: The application does not support multi-instance mode. ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED: Setting APP_INSTANCE_KEY is not supported. ABILITY_RUNTIME_ERROR_CODE_START_TIMEOUT: Starting the UIAbility times out. ABILITY_RUNTIME_ERROR_CODE_MAIN_THREAD_NOT_SUPPORTED: The function cannot be called on the main thread of the application. |
Example
#include <AbilityKit/ability_base/want.h>
#include <AbilityKit/ability_runtime/application_context.h>
void demo()
{
AbilityBase_Element element;
element.abilityName = const_cast<char*>("EntryAbility");
element.bundleName = const_cast<char*>("com.example.myapplication");
element.moduleName = const_cast<char*>("entry");
AbilityBase_Want* want = OH_AbilityBase_CreateWant(element);
if (want == nullptr) {
// Record error logs and other service processing.
return;
}
AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions();
if (options == nullptr) {
// Record error logs and other service processing.
// Destroy the Want to prevent memory leakage.
OH_AbilityBase_DestroyWant(want);
return;
}
int32_t pid = -1;
AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbilityWithPidResult(want, options, &pid);
if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
// Record error logs and other service processing.
}
// Destroy the Want to prevent memory leakage.
OH_AbilityBase_DestroyWant(want);
// Destroy options to prevent memory leakage.
OH_AbilityRuntime_DestroyStartOptions(&options);
}
OH_AbilityRuntime_ApplicationContextGetLaunchParameter
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetLaunchParameter(
char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains WantParams passed for the initial launch of the UIAbility of the current application. For details about WantParams, see parameters in Want.
Since: 21
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive WantParams. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
Example
#include "napi/native_api.h"
#include "AbilityKit/ability_runtime/application_context.h"
static napi_value GetLaunchParameter(napi_env env, napi_callback_info info)
{
const int32_t bufferSize = 2048; // Adjust the buffer size as required.
char buffer[bufferSize] = {0};
int32_t writeLength = 0;
int32_t ret = OH_AbilityRuntime_ApplicationContextGetLaunchParameter(buffer, bufferSize, &writeLength);
if (ret != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
// Handle exceptions.
}
// Create a JS string and return WantParams.
napi_value result;
napi_create_string_utf8(env, buffer, writeLength, &result);
return result;
}
OH_AbilityRuntime_ApplicationContextGetLatestParameter
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetLatestParameter(
char* buffer, const int32_t bufferSize, int32_t* writeLength)
Description
Obtains WantParams passed for the mose recent launch of the UIAbility of the current application. For details about WantParams, see parameters in Want.
Since: 21
Parameters
| Name | Description |
|---|---|
| char* buffer | Pointer to the buffer, which is used to receive WantParams. |
| const int32_t bufferSize | Buffer size, in bytes. |
| int32_t* writeLength | Pointer to the length of the string written to the buffer (measured in bytes) when ABILITY_RUNTIME_ERROR_CODE_NO_ERROR is returned. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The passed-in value of buffer or writeLength is null, or the buffer size is less than the size of the string to be written. ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST: The application context does not exist. For example, the application-level context does not exist in the child process created by the application. |
Example
#include "napi/native_api.h"
#include "AbilityKit/ability_runtime/application_context.h"
static napi_value GetLatestParameter(napi_env env, napi_callback_info info)
{
const int32_t bufferSize = 2048; // Adjust the buffer size as required.
char buffer[bufferSize] = {0};
int32_t writeLength = 0;
int32_t ret = OH_AbilityRuntime_ApplicationContextGetLatestParameter(buffer, bufferSize, &writeLength);
if (ret != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
// Handle exceptions.
}
// Create a JS string and return WantParams.
napi_value result;
napi_create_string_utf8(env, buffer, writeLength, &result);
return result;
}
OH_AbilityRuntime_ApplicationContextNotifyPageChanged
AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextNotifyPageChanged(
const char* targetPageName, int32_t targetPageNameLength, int32_t windowId)
Description
This API can be called only from third-party frameworks. Each time a third-party framework switches pages, it notifies the system of the target page information (including the target page path, the length of the target page path, and the window ID corresponding to the target page). The system can adjust or recover the page according to product policies.
Since: 23
Parameters
| Name | Description |
|---|---|
| const char* targetPageName | Target page path. |
| int32_t targetPageNameLength | Length of the target page path. |
| int32_t windowId | Window ID corresponding to the target page. |
Returns
| Type | Description |
|---|---|
| AbilityRuntime_ErrorCode | One of the following execution results: ABILITY_RUNTIME_ERROR_CODE_NO_ERROR: The operation is successful. ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID: The input parameter targetPageName is empty or the windowId is invalid. ABILITY_RUNTIME_ERROR_CODE_INTERNAL: An internal error occurs. |
Example
#include "napi/native_api.h"
#include "AbilityKit/ability_runtime/application_context.h"
static bool NotifyPageChanged(napi_env env, napi_callback_info info)
{
const char* testPageName = "https://home.taobao.com/homepage";
int32_t testPageNameLen = 32;
int32_t testWindowId = 12; // The sample value is for reference only. Use a valid window ID in actual development.
int32_t ret = OH_AbilityRuntime_ApplicationContextNotifyPageChanged(testPageName, testPageNameLen, testWindowId);
if (ret != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
// Handle exceptions.
return false;
}
return true;
}