• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# AbilityRuntime
2
3
4## Overview
5
6The AbilityRuntime module provides capabilities related to the ability framework.
7
8**System capability**: SystemCapability.Ability.AbilityRuntime.Core
9
10**Since**: 13
11
12
13## Summary
14
15
16### Files
17
18| Name| Description|
19| -------- | -------- |
20| [ability_runtime_common.h](ability__runtime__common_8h.md) | Declares the error codes of the ability framework.<br>**File to include**: <AbilityKit/ability_runtime/ability_runtime_common.h><br>**Library**: libability_runtime.so|
21| [application_context.h](application__context_8h.md) | Declares the context capability at the application level.<br>**File to include**: <AbilityKit/ability_runtime/application_context.h><br>**Library**: libability_runtime.so|
22| [context_constant.h](context__constant_8h.md) | Declares context-related enums.<br>**File to include**: <AbilityKit/ability_runtime/context_constant.h><br>**Library**: libability_runtime.so|
23
24### Enums
25
26| Name                                                        | Description                  |
27| ------------------------------------------------------------ | ---------------------- |
28| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) {<br>    ABILITY_RUNTIME_ERROR_CODE_NO_ERROR = 0,<br>    ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED = 201,<br>    ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID = 401,<br>    ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED = 801,<br>    ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY = 16000001,<br>    ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE = 16000002,<br>    ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED = 16000008,<br>    ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE = 16000009,<br>    ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST = 16000011,<br>    ABILITY_RUNTIME_ERROR_CODE_CONTROLLED = 16000012,<br>    ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED = 16000013,<br>    ABILITY_RUNTIME_ERROR_CODE_CROSS_APP = 16000018,<br>    ABILITY_RUNTIME_ERROR_CODE_INTERNAL = 16000050,<br>    ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY = 16000053,<br>} | Enumerates the error codes used by the ability framework.|
29| [AbilityRuntime_AreaMode](#abilityruntime_areamode) {<br>    ABILITY_RUNTIME_AREA_MODE_EL1 = 0,<br>    ABILITY_RUNTIME_AREA_MODE_EL2 = 1,<br>    ABILITY_RUNTIME_AREA_MODE_EL3 = 2,<br>    ABILITY_RUNTIME_AREA_MODE_EL4 = 3,<br>    ABILITY_RUNTIME_AREA_MODE_EL5 = 4<br>} | Enumerates the data encryption levels.    |
30
31### Functions
32
33| Name| Description|
34| -------- | -------- |
35| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetCacheDir](#oh_abilityruntime_applicationcontextgetcachedir)(char* buffer, int32_t bufferSize, int32_t* writeLength) | Obtains the application-level cache directory.|
36| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetAreaMode](#oh_abilityruntime_applicationcontextgetareamode)([AbilityRuntime_AreaMode](#abilityruntime_areamode)* areaMode) | Obtains the application-level data encryption level.|
37| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetBundleName](#oh_abilityruntime_applicationcontextgetbundlename)(char* buffer, int32_t bufferSize, int32_t* writeLength) | Obtains the bundle name of the application.|
38| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_StartSelfUIAbility](#oh_abilityruntime_startselfuiability)([AbilityBase_Want](_ability_base.md#abilitybase_want) *want) | Starts the UIAbility of the current application.|
39
40## Enum Description
41
42### AbilityRuntime_ErrorCode
43
44```
45enum AbilityRuntime_ErrorCode
46```
47
48**Description**
49
50Enumerates the error codes used by the ability framework.
51
52**Since**: 13
53
54| Value                                       | Description          |
55| --------------------------------------------- | -------------- |
56| ABILITY_RUNTIME_ERROR_CODE_NO_ERROR           | Operation successful.    |
57| ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID | Invalid parameter.    |
58| ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST  | The context does not exist.|
59| ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED | Permission verification failed.<br>**Since**: 15|
60| ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED | The device type is not supported.<br>**Since**: 15|
61| ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY | The specified ability name does not exist.<br>**Since**: 15|
62| ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE | The ability type is incorrect.<br>**Since**: 15|
63| ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED | The crowdtesting application expires.<br>**Since**: 15|
64| ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE | An ability cannot be started or stopped in Wukong mode.<br>**Since**: 15|
65| ABILITY_RUNTIME_ERROR_CODE_CONTROLLED | The application is under control.<br>**Since**: 15|
66| ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED | The application is under control by EDM.<br>**Since**: 15|
67| ABILITY_RUNTIME_ERROR_CODE_CROSS_APP | Redirection to third-party applications is not allowed in API versions later than 11.<br>**Since**: 15|
68| ABILITY_RUNTIME_ERROR_CODE_INTERNAL | Internal error.<br>**Since**: 15|
69| ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY | The application is not on top.<br>**Since**: 15|
70
71### AbilityRuntime_AreaMode
72
73```
74enum AbilityRuntime_AreaMode
75```
76
77**Description**
78
79Enumerates the data encryption levels.
80
81**Since**: 13
82
83| Value                       | Description                                                        |
84| ----------------------------- | ------------------------------------------------------------ |
85| ABILITY_RUNTIME_AREA_MODE_EL1 | For private files, such as alarms and wallpapers, the application can place them in a directory with the device-level encryption (EL1) to ensure that they can be accessed before the user enters the password.|
86| ABILITY_RUNTIME_AREA_MODE_EL2 | For sensitive files, such as personal privacy data, the application can place them in a directory with the user-level encryption (EL2).|
87| ABILITY_RUNTIME_AREA_MODE_EL3 | For step recording, file download, or music playback that needs to read, write, and create files when the screen is locked, the application can place these files in EL3.|
88| ABILITY_RUNTIME_AREA_MODE_EL4 | For files that are related to user security information and do not need to be read, written, or created when the screen is locked, the application can place them in EL4.|
89| ABILITY_RUNTIME_AREA_MODE_EL5 | By default, sensitive user privacy files cannot be read or written on the lock screen. If such files need to be read or written on the lock screen, you can call [Access](js-apis-screenLockFileManager.md#screenlockfilemanageracquireaccess) to apply for reading or writing files before the screen is locked or create new files that can be read and written after the screen is locked. It is more appropriate to place these files in EL5.|
90
91## Function Description
92
93
94### OH_AbilityRuntime_ApplicationContextGetCacheDir
95
96```
97AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCacheDir(char* buffer, int32_t bufferSize, int32_t* writeLength)
98```
99**Description**
100
101Obtains the application-level cache directory.
102
103**Since**: 13
104
105**Parameters**
106
107| Name| Description|
108| -------- | -------- |
109| buffer | Pointer to the buffer. The cache directory string is written to this area.|
110| bufferSize | Buffer size.|
111| writeLength | Pointer to the length of the string written to the buffer when **ABILITY_RUNTIME_ERROR_CODE_NO_ERROR** is returned.|
112
113**Returns**
114
115Returns **ABILITY_RUNTIME_ERROR_CODE_NO_ERROR** if the operation is successful.
116
117Returns **ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID** if 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.
118
119Returns **ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST** if the context of the current environment does not exist. For example, the application-level context does not exist in the [child process](c-apis-ability-childprocess.md) created by the application.
120
121### OH_AbilityRuntime_ApplicationContextGetAreaMode
122
123```
124AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetAreaMode(AbilityRuntime_AreaMode* areaMode)
125```
126
127**Description**
128
129Obtains the application-level data encryption level.
130
131**Since**: 13
132
133**Parameters**
134
135| Name    | Description                    |
136| -------- | ------------------------ |
137| areaMode | Pointer to the data encryption level.|
138
139**Returns**
140
141Returns **ABILITY_RUNTIME_ERROR_CODE_NO_ERROR** if the operation is successful.
142
143Returns **ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID** if **areaMode** is a null pointer.
144
145Returns **ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST** if the context of the current environment does not exist. For example, the application-level context does not exist in the [child process](c-apis-ability-childprocess.md) created by the application.
146
147### OH_AbilityRuntime_ApplicationContextGetBundleName
148
149```
150AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleName(char* buffer, int32_t bufferSize, int32_t* writeLength)
151```
152
153**Description**
154
155Obtains the bundle name of the application.
156
157**Since**: 13
158
159**Parameters**
160
161| Name       | Description                                                        |
162| ----------- | ------------------------------------------------------------ |
163| buffer      | Pointer to the buffer. The bundle name string is written to this area.                          |
164| bufferSize  | Buffer size.                                                |
165| writeLength | Pointer to the length of the string written to the buffer when **ABILITY_RUNTIME_ERROR_CODE_NO_ERROR** is returned.|
166
167**Returns**
168
169Returns **ABILITY_RUNTIME_ERROR_CODE_NO_ERROR** if the operation is successful.
170
171Returns **ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID** if 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.
172
173Returns **ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST** if the context of the current environment does not exist. For example, the application-level context does not exist in the [child process](c-apis-ability-childprocess.md) created by the application.
174
175### OH_AbilityRuntime_StartSelfUIAbility
176
177```
178AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbility(AbilityBase_Want *want)
179```
180
181**Description**
182
183Starts the UIAbility of the current application.
184
185> **NOTE**
186>
187> This function is valid only for 2-in-1 devices.
188
189**Required permissions**: ohos.permission.NDK_START_SELF_UI_ABILITY
190
191**Since**: 15
192
193**Parameters**
194
195| Name       | Description                                                        |
196| ----------- | ------------------------------------------------------------ |
197| want      | Pointer to the Want information required for starting the UIAbility.                          |
198
199**Returns**
200
201Returns **ABILITY_RUNTIME_ERROR_CODE_NO_ERROR** if the operation is successful.
202
203Returns **ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED** if permission verification failed.
204
205Returns **ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID** if the Want information is empty, or if the bundleName or abilityName in the Want information is empty.
206
207Returns **ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED** if the device type is not supported.
208
209Returns **ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY** if the specified ability name does not exist.
210
211Returns **ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE** if the ability type is incorrect.
212
213Returns **ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED** if the crowdtesting application expires.
214
215Returns **ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE** if the ability is started or stopped in Wukong mode.
216
217Returns **ABILITY_RUNTIME_ERROR_CODE_CONTROLLED** if the application is under control.
218
219Returns **ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED** if the application is under control by EDM.
220
221Returns **ABILITY_RUNTIME_ERROR_CODE_CROSS_APP** for an attempt to redirection to third-party applications in API versions later than 11.
222
223Returns **ABILITY_RUNTIME_ERROR_CODE_INTERNAL** if an internal error occurs.
224
225Returns **ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY** if the application is not a top one.
226
227**Example**
228```cpp
229#include <AbilityKit/ability_base/want.h>
230#include <AbilityKit/ability_runtime/application_context.h>
231
232void startSelfUIAbilityTest()
233{
234    AbilityBase_Element element;
235    element.abilityName = const_cast<char*>("EntryAbility");
236    element.bundleName = const_cast<char*>("com.exampl.myapplication");
237    element.moduleName = const_cast<char*>("entry");
238    AbilityBase_Want* want = OH_AbilityBase_CreateWant(element);
239
240    AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbility(want);
241    if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) {
242        // Record error logs and other service processing.
243        return;
244    }
245    // Destroy the Want to prevent memory leakage.
246    OH_AbilityBase_DestroyWant(want);
247}
248```
249