1 /* 2 * Copyright (c) 2024-2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup AbilityRuntime 18 * @{ 19 * 20 * @brief Describe the functions provided by the application context. 21 * 22 * @syscap SystemCapability.Ability.AbilityRuntime.Core 23 * @since 13 24 */ 25 26 /** 27 * @file application_context.h 28 * 29 * @brief Defines the application context APIs. 30 * 31 * @library libability_runtime.so 32 * @kit AbilityKit 33 * @syscap SystemCapability.Ability.AbilityRuntime.Core 34 * @since 13 35 */ 36 37 #ifndef ABILITY_RUNTIME_APPLICATION_CONTEXT_H 38 #define ABILITY_RUNTIME_APPLICATION_CONTEXT_H 39 40 #include <stdint.h> 41 #include <stddef.h> 42 #include <AbilityKit/ability_base/want.h> 43 #include "ability_runtime_common.h" 44 #include "context_constant.h" 45 #include "start_options.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Obtain the cache directory of the application. 53 * 54 * @param buffer A pointer to a buffer that receives the cache directory of the application. 55 * @param bufferSize The length of the buffer. 56 * @param writeLength The string length actually written to the buffer, 57 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 58 * @return The error code. 59 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 60 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 61 * or the buffer size is less than the minimum buffer size. 62 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 63 * @since 13 64 */ 65 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCacheDir( 66 char* buffer, int32_t bufferSize, int32_t* writeLength); 67 68 /** 69 * @brief Obtain the area mode of the application. 70 * 71 * @param areaMode A pointer to the area mode. 72 * @return The error code. 73 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 74 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the areaMode is null. 75 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 76 * @since 13 77 */ 78 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetAreaMode(AbilityRuntime_AreaMode* areaMode); 79 80 /** 81 * @brief Obtain the bundle name. 82 * 83 * @param buffer A pointer to a buffer that receives the bundle name. 84 * @param bufferSize The length of the buffer. 85 * @param writeLength The string length actually written to the buffer, 86 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 87 * @return The error code. 88 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 89 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 90 * or the buffer size is less than the minimum buffer size. 91 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 92 * @since 13 93 */ 94 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleName( 95 char* buffer, int32_t bufferSize, int32_t* writeLength); 96 97 /** 98 * @brief Obtain the temp directory of the application. 99 * 100 * @param buffer A pointer to a buffer that receives the temp directory of the application. 101 * @param bufferSize The length of the buffer. 102 * @param writeLength The string length actually written to the buffer, 103 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 104 * @return The error code. 105 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 106 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 107 * or the buffer size is less than the minimum buffer size. 108 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 109 * @since 16 110 */ 111 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetTempDir( 112 char* buffer, const int32_t bufferSize, int32_t* writeLength); 113 114 /** 115 * @brief Obtain the files directory of the application. 116 * 117 * @param buffer A pointer to a buffer that receives the files directory of the application. 118 * @param bufferSize The length of the buffer. 119 * @param writeLength The string length actually written to the buffer, 120 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 121 * @return The error code. 122 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 123 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 124 * or the buffer size is less than the minimum buffer size. 125 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 126 * @since 16 127 */ 128 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetFilesDir( 129 char* buffer, const int32_t bufferSize, int32_t* writeLength); 130 131 /** 132 * @brief Obtain the database directory of the application. 133 * 134 * @param buffer A pointer to a buffer that receives the database directory of the application. 135 * @param bufferSize The length of the buffer. 136 * @param writeLength The string length actually written to the buffer, 137 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 138 * @return The error code. 139 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 140 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 141 * or the buffer size is less than the minimum buffer size. 142 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 143 * @since 16 144 */ 145 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDatabaseDir( 146 char* buffer, const int32_t bufferSize, int32_t* writeLength); 147 148 /** 149 * @brief Obtain the preferences directory of the application. 150 * 151 * @param buffer A pointer to a buffer that receives the preferences directory of the application. 152 * @param bufferSize The length of the buffer. 153 * @param writeLength The string length actually written to the buffer, 154 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 155 * @return The error code. 156 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 157 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 158 * or the buffer size is less than the minimum buffer size. 159 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 160 * @since 16 161 */ 162 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetPreferencesDir( 163 char* buffer, const int32_t bufferSize, int32_t* writeLength); 164 165 /** 166 * @brief Obtain the bundle code directory of the application. 167 * 168 * @param buffer A pointer to a buffer that receives the bundle code directory of the application. 169 * @param bufferSize The length of the buffer. 170 * @param writeLength The string length actually written to the buffer, 171 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 172 * @return The error code. 173 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 174 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 175 * or the buffer size is less than the minimum buffer size. 176 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 177 * @since 16 178 */ 179 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleCodeDir( 180 char* buffer, const int32_t bufferSize, int32_t* writeLength); 181 182 /** 183 * @brief Obtain the distributed files directory of the application. 184 * 185 * @param buffer A pointer to a buffer that receives the distributed files directory of the application. 186 * @param bufferSize The length of the buffer. 187 * @param writeLength The string length actually written to the buffer, 188 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 189 * @return The error code. 190 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 191 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 192 * or the buffer size is less than the minimum buffer size. 193 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 194 * @since 16 195 */ 196 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir( 197 char* buffer, const int32_t bufferSize, int32_t* writeLength); 198 199 /** 200 * @brief Obtain the cloud file directory of the application. 201 * 202 * @param buffer A pointer to a buffer that receives the cloud file directory of the application. 203 * @param bufferSize The length of the buffer. 204 * @param writeLength The string length actually written to the buffer, 205 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 206 * @return The error code. 207 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 208 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 209 * or the buffer size is less than the minimum buffer size. 210 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 211 * @since 16 212 */ 213 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCloudFileDir( 214 char* buffer, const int32_t bufferSize, int32_t* writeLength); 215 216 /** 217 * @brief Obtain the resource directory of the target module. 218 * 219 * @param moduleName The module name. 220 * @param buffer A pointer to a buffer that receives the resource directory of the target module. 221 * @param bufferSize The length of the buffer. 222 * @param writeLength The string length actually written to the buffer, 223 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 224 * @return The error code. 225 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 226 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 227 * or the buffer size is less than the minimum buffer size. 228 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 229 * @since 20 230 */ 231 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetResourceDir(const char* moduleName, 232 char* buffer, const int32_t bufferSize, int32_t* writeLength); 233 234 /** 235 * @brief Starts self UIAbility. 236 * 237 * @permission {@code ohos.permission.NDK_START_SELF_UI_ABILITY} 238 * @param want The arguments passed to start self UIAbility. 239 * For details, see {@link AbilityBase_Want}. 240 * @return Returns {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the call is successful. 241 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED} if the caller has no correct permission. 242 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the arguments provided is invalid. 243 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED} if the device does not support starting self uiability. 244 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY} if the target ability does not exist. 245 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE} if the ability type is incorrect. 246 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED} if the crowdtesting application expires. 247 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE} if the ability cannot be started in Wukong mode. 248 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CONTROLLED} if the app is controlled. 249 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED} if the app is controlled by EDM. 250 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CROSS_APP} if the caller tries to start a different application. 251 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INTERNAL} if internal error occurs. 252 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY} if the caller is not top ability. 253 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED} 254 * if the number of app instances reached the limit (since 17). 255 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED} 256 * if the APP_INSTANCE_KEY cannot be specified (since 17). 257 * For details, see {@link AbilityRuntime_ErrorCode}. 258 * @since 15 259 */ 260 AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbility(AbilityBase_Want *want); 261 262 /** 263 * @brief Starts self UIAbility with start options. 264 * 265 * @permission {@code ohos.permission.NDK_START_SELF_UI_ABILITY} 266 * @param want The arguments passed to start self UIAbility. 267 * For details, see {@link AbilityBase_Want}. 268 * @param options The start options passed to start self UIAbility. 269 * For details, see {@link AbilityRuntime_StartOptions}. 270 * @return Returns {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the call is successful. 271 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED} if the caller has no correct permission. 272 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the arguments provided is invalid. 273 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED} if the device does not support starting self uiability. 274 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY} if the target ability does not exist. 275 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE} if the ability type is incorrect. 276 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED} if the crowdtesting application expires. 277 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE} if the ability cannot be started in Wukong mode. 278 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CONTROLLED} if the app is controlled. 279 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED} if the app is controlled by EDM. 280 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CROSS_APP} if the caller tries to start a different application. 281 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INTERNAL} if internal error occurs. 282 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY} if the caller is not foreground process. 283 * Returns {@link ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED} if setting visibility is disabled. 284 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED} 285 * if the app clone or multi-instance is not supported. 286 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY} if the app instance key is invalid. 287 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED} if the number of app instances reached the limit. 288 * Returns {@link ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED} if the multi-instance is not supported. 289 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED} 290 * if the APP_INSTANCE_KEY cannot be specified. 291 * For details, see {@link AbilityRuntime_ErrorCode}. 292 * @since 17 293 */ 294 AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(AbilityBase_Want *want, 295 AbilityRuntime_StartOptions *options); 296 297 #ifdef __cplusplus 298 } // extern "C" 299 #endif 300 301 /** @} */ 302 #endif // ABILITY_RUNTIME_APPLICATION_CONTEXT_H 303