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 "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 struct AbilityBase_Want; 52 typedef struct AbilityBase_Want AbilityBase_Want; 53 54 /** 55 * @brief Obtain the cache directory of the application. 56 * 57 * @param buffer A pointer to a buffer that receives the cache directory of the application. 58 * @param bufferSize The length of the buffer. 59 * @param writeLength The string length actually written to the buffer, 60 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 61 * @return The error code. 62 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 63 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 64 * or the buffer size is less than the minimum buffer size. 65 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 66 * @since 13 67 */ 68 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCacheDir( 69 char* buffer, int32_t bufferSize, int32_t* writeLength); 70 71 /** 72 * @brief Obtain the area mode of the application. 73 * 74 * @param areaMode A pointer to the area mode. 75 * @return The error code. 76 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 77 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the areaMode is null. 78 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 79 * @since 13 80 */ 81 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetAreaMode(AbilityRuntime_AreaMode* areaMode); 82 83 /** 84 * @brief Obtain the bundle name. 85 * 86 * @param buffer A pointer to a buffer that receives the bundle name. 87 * @param bufferSize The length of the buffer. 88 * @param writeLength The string length actually written to the buffer, 89 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 90 * @return The error code. 91 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 92 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 93 * or the buffer size is less than the minimum buffer size. 94 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 95 * @since 13 96 */ 97 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleName( 98 char* buffer, int32_t bufferSize, int32_t* writeLength); 99 100 /** 101 * @brief Obtain the temp directory of the application. 102 * 103 * @param buffer A pointer to a buffer that receives the temp directory of the application. 104 * @param bufferSize The length of the buffer. 105 * @param writeLength The string length actually written to the buffer, 106 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 107 * @return The error code. 108 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 109 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 110 * or the buffer size is less than the minimum buffer size. 111 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 112 * @since 16 113 */ 114 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetTempDir( 115 char* buffer, const int32_t bufferSize, int32_t* writeLength); 116 117 /** 118 * @brief Obtain the files directory of the application. 119 * 120 * @param buffer A pointer to a buffer that receives the files directory of the application. 121 * @param bufferSize The length of the buffer. 122 * @param writeLength The string length actually written to the buffer, 123 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 124 * @return The error code. 125 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 126 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 127 * or the buffer size is less than the minimum buffer size. 128 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 129 * @since 16 130 */ 131 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetFilesDir( 132 char* buffer, const int32_t bufferSize, int32_t* writeLength); 133 134 /** 135 * @brief Obtain the database directory of the application. 136 * 137 * @param buffer A pointer to a buffer that receives the database directory of the application. 138 * @param bufferSize The length of the buffer. 139 * @param writeLength The string length actually written to the buffer, 140 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 141 * @return The error code. 142 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 143 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 144 * or the buffer size is less than the minimum buffer size. 145 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 146 * @since 16 147 */ 148 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDatabaseDir( 149 char* buffer, const int32_t bufferSize, int32_t* writeLength); 150 151 /** 152 * @brief Obtain the preferences directory of the application. 153 * 154 * @param buffer A pointer to a buffer that receives the preferences directory of the application. 155 * @param bufferSize The length of the buffer. 156 * @param writeLength The string length actually written to the buffer, 157 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 158 * @return The error code. 159 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 160 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 161 * or the buffer size is less than the minimum buffer size. 162 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 163 * @since 16 164 */ 165 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetPreferencesDir( 166 char* buffer, const int32_t bufferSize, int32_t* writeLength); 167 168 /** 169 * @brief Obtain the bundle code directory of the application. 170 * 171 * @param buffer A pointer to a buffer that receives the bundle code directory of the application. 172 * @param bufferSize The length of the buffer. 173 * @param writeLength The string length actually written to the buffer, 174 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 175 * @return The error code. 176 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 177 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 178 * or the buffer size is less than the minimum buffer size. 179 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 180 * @since 16 181 */ 182 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleCodeDir( 183 char* buffer, const int32_t bufferSize, int32_t* writeLength); 184 185 /** 186 * @brief Obtain the distributed files directory of the application. 187 * 188 * @param buffer A pointer to a buffer that receives the distributed files directory of the application. 189 * @param bufferSize The length of the buffer. 190 * @param writeLength The string length actually written to the buffer, 191 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 192 * @return The error code. 193 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 194 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 195 * or the buffer size is less than the minimum buffer size. 196 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 197 * @since 16 198 */ 199 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir( 200 char* buffer, const int32_t bufferSize, int32_t* writeLength); 201 202 /** 203 * @brief Obtain the cloud file directory of the application. 204 * 205 * @param buffer A pointer to a buffer that receives the cloud file directory of the application. 206 * @param bufferSize The length of the buffer. 207 * @param writeLength The string length actually written to the buffer, 208 * when returning {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}. 209 * @return The error code. 210 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 211 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the buffer or writeLength is null, 212 * or the buffer size is less than the minimum buffer size. 213 * {@link ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST} if the application context does not exist. 214 * @since 16 215 */ 216 AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCloudFileDir( 217 char* buffer, const int32_t bufferSize, int32_t* writeLength); 218 219 /** 220 * @brief Starts self UIAbility. 221 * 222 * @permission {@code ohos.permission.NDK_START_SELF_UI_ABILITY} 223 * @param want The arguments passed to start self UIAbility. 224 * For details, see {@link AbilityBase_Want}. 225 * @return Returns {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the call is successful. 226 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED} if the caller has no correct permission. 227 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the arguments provided is invalid. 228 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED} if the device does not support starting self uiability. 229 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY} if the target ability does not exist. 230 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE} if the ability type is incorrect. 231 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED} if the crowdtesting application expires. 232 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE} if the ability cannot be started in Wukong mode. 233 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CONTROLLED} if the app is controlled. 234 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED} if the app is controlled by EDM. 235 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CROSS_APP} if the caller tries to start a different application. 236 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INTERNAL} if internal error occurs. 237 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY} if the caller is not top ability. 238 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED} 239 * if the number of app instances reached the limit (since 17). 240 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED} 241 * if the APP_INSTANCE_KEY cannot be specified (since 17). 242 * For details, see {@link AbilityRuntime_ErrorCode}. 243 * @since 15 244 */ 245 AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbility(AbilityBase_Want *want); 246 247 /** 248 * @brief Starts self UIAbility with start options. 249 * 250 * @permission {@code ohos.permission.NDK_START_SELF_UI_ABILITY} 251 * @param want The arguments passed to start self UIAbility. 252 * For details, see {@link AbilityBase_Want}. 253 * @param options The start options passed to start self UIAbility. 254 * For details, see {@link AbilityRuntime_StartOptions}. 255 * @return Returns {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the call is successful. 256 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED} if the caller has no correct permission. 257 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the arguments provided is invalid. 258 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED} if the device does not support starting self uiability. 259 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY} if the target ability does not exist. 260 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE} if the ability type is incorrect. 261 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED} if the crowdtesting application expires. 262 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE} if the ability cannot be started in Wukong mode. 263 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CONTROLLED} if the app is controlled. 264 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED} if the app is controlled by EDM. 265 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_CROSS_APP} if the caller tries to start a different application. 266 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INTERNAL} if internal error occurs. 267 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY} if the caller is not foreground process. 268 * Returns {@link ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED} if setting visibility is disabled. 269 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED} 270 * if the app clone or multi-instance is not supported. 271 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY} if the app instance key is invalid. 272 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED} if the number of app instances reached the limit. 273 * Returns {@link ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED} if the multi-instance is not supported. 274 * Returns {@link ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED} 275 * if the APP_INSTANCE_KEY cannot be specified. 276 * For details, see {@link AbilityRuntime_ErrorCode}. 277 * @since 17 278 */ 279 AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(AbilityBase_Want *want, 280 AbilityRuntime_StartOptions *options); 281 282 #ifdef __cplusplus 283 } // extern "C" 284 #endif 285 286 /** @} */ 287 #endif // ABILITY_RUNTIME_APPLICATION_CONTEXT_H 288