1# application_context.h 2 3## Overview 4 5The file declares the APIs related to the application-level context. 6 7**File to include**: <AbilityKit/ability_runtime/application_context.h> 8 9**Library**: libability_runtime.so 10 11**System capability**: SystemCapability.Ability.AbilityRuntime.Core 12 13**Since**: 13 14 15**Related module**: [AbilityRuntime](capi-abilityruntime.md) 16 17## Summary 18 19### Functions 20 21| Name| Description| 22| -- | -- | 23| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCacheDir(char* buffer, int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgetcachedir) | Obtains the application-level cache directory of the application.| 24| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetAreaMode(AbilityRuntime_AreaMode* areaMode)](#oh_abilityruntime_applicationcontextgetareamode) | Obtains the application-level file data encryption level of the application.| 25| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleName(char* buffer, int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgetbundlename) | Obtains the bundle name of the application.| 26| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetTempDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgettempdir) | Obtains the application-level temporary file directory of the application.| 27| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgetfilesdir) | Obtains the application-level common file directory of the application.| 28| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDatabaseDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgetdatabasedir) | Obtains the application-level database file directory of the application.| 29| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetPreferencesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgetpreferencesdir) | Obtains the application-level preferences file directory of the application.| 30| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleCodeDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgetbundlecodedir) | Obtains the application-level installation file directory of the application.| 31| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgetdistributedfilesdir) | Obtains the application-level distributed file directory of the application.| 32| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCloudFileDir(char* buffer, const int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgetcloudfiledir) | Obtains the application-level cloud file directory of the application.| 33| [AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetResourceDir(const char* moduleName, char* buffer, const int32_t bufferSize, int32_t* writeLength)](#oh_abilityruntime_applicationcontextgetresourcedir) | Obtains the application-level resource directory of the application. | 34| [AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbility(AbilityBase_Want *want)](#oh_abilityruntime_startselfuiability) | Starts the UIAbility of the current application.| 35| [AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(AbilityBase_Want *want,AbilityRuntime_StartOptions *options)](#oh_abilityruntime_startselfuiabilitywithstartoptions) | Starts the UIAbility of the current application using **StartOptions**.| 36 37## Function Description 38 39### OH_AbilityRuntime_ApplicationContextGetCacheDir() 40 41``` 42AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCacheDir(char* buffer, int32_t bufferSize, int32_t* writeLength) 43``` 44 45**Description** 46 47Obtains the application-level cache directory of the application. 48 49**Since**: 13 50 51**Parameters** 52 53| Name| Description| 54| -- | -- | 55| char* buffer | Pointer to the buffer, which is used to receive the application-level cache directory of the application.| 56| int32_t bufferSize | Buffer size, in bytes.| 57| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 58 59**Returns** 60 61| Type| Description| 62| -- | -- | 63| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 64 65### OH_AbilityRuntime_ApplicationContextGetAreaMode() 66 67``` 68AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetAreaMode(AbilityRuntime_AreaMode* areaMode) 69``` 70 71**Description** 72 73Obtains the application-level file data encryption level of the application. 74 75**Since**: 13 76 77**Parameters** 78 79| Name| Description| 80| -- | -- | 81| [AbilityRuntime_AreaMode](capi-context-constant-h.md#abilityruntime_areamode)* areaMode | Pointer to the encryption level of the received data.| 82 83**Returns** 84 85| Type| Description| 86| -- | -- | 87| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 88 89### OH_AbilityRuntime_ApplicationContextGetBundleName() 90 91``` 92AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleName(char* buffer, int32_t bufferSize, int32_t* writeLength) 93``` 94 95**Description** 96 97Obtains the bundle name of the application. 98 99**Since**: 13 100 101**Parameters** 102 103| Name| Description| 104| -- | -- | 105| char* buffer | Pointer to the buffer, which is used to receive the bundle name.| 106| int32_t bufferSize | Buffer size, in bytes.| 107| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 108 109**Returns** 110 111| Type| Description| 112| -- | -- | 113| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 114 115### OH_AbilityRuntime_ApplicationContextGetTempDir() 116 117``` 118AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetTempDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 119``` 120 121**Description** 122 123Obtains the application-level temporary file directory of the application. 124 125**Since**: 16 126 127**Parameters** 128 129| Name| Description| 130| -- | -- | 131| char* buffer | Pointer to the buffer, which is used to receive the bundle name.| 132| const int32_t bufferSize | Buffer size, in bytes.| 133| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 134 135**Returns** 136 137| Type| Description| 138| -- | -- | 139| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 140 141### OH_AbilityRuntime_ApplicationContextGetFilesDir() 142 143``` 144AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 145``` 146 147**Description** 148 149Obtains the application-level common file directory of the application. 150 151**Since**: 16 152 153**Parameters** 154 155| Name| Description| 156| -- | -- | 157| char* buffer | Pointer to the buffer, which is used to receive the bundle name.| 158| const int32_t bufferSize | Buffer size, in bytes.| 159| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 160 161**Returns** 162 163| Type| Description| 164| -- | -- | 165| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 166 167### OH_AbilityRuntime_ApplicationContextGetDatabaseDir() 168 169``` 170AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDatabaseDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 171``` 172 173**Description** 174 175Obtains the application-level database file directory of the application. 176 177**Since**: 16 178 179**Parameters** 180 181| Name| Description| 182| -- | -- | 183| char* buffer | Pointer to the buffer, which is used to receive the bundle name.| 184| const int32_t bufferSize | Buffer size, in bytes.| 185| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 186 187**Returns** 188 189| Type| Description| 190| -- | -- | 191| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 192 193### OH_AbilityRuntime_ApplicationContextGetPreferencesDir() 194 195``` 196AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetPreferencesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 197``` 198 199**Description** 200 201Obtains the application-level preferences file directory of the application. 202 203**Since**: 16 204 205**Parameters** 206 207| Name| Description| 208| -- | -- | 209| char* buffer | Pointer to the buffer, which is used to receive the bundle name.| 210| const int32_t bufferSize | Buffer size, in bytes.| 211| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 212 213**Returns** 214 215| Type| Description| 216| -- | -- | 217| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 218 219### OH_AbilityRuntime_ApplicationContextGetBundleCodeDir() 220 221``` 222AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleCodeDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 223``` 224 225**Description** 226 227Obtains the application-level installation file directory of the application. 228 229**Since**: 16 230 231**Parameters** 232 233| Name| Description| 234| -- | -- | 235| char* buffer | Pointer to the buffer, which is used to receive the bundle name.| 236| const int32_t bufferSize | Buffer size, in bytes.| 237| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 238 239**Returns** 240 241| Type| Description| 242| -- | -- | 243| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 244 245### OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir() 246 247``` 248AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 249``` 250 251**Description** 252 253Obtains the application-level distributed file directory of the application. 254 255**Since**: 16 256 257**Parameters** 258 259| Name| Description| 260| -- | -- | 261| char* buffer | Pointer to the buffer, which is used to receive the bundle name.| 262| const int32_t bufferSize | Buffer size, in bytes.| 263| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 264 265**Returns** 266 267| Type| Description| 268| -- | -- | 269| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 270 271### OH_AbilityRuntime_ApplicationContextGetCloudFileDir() 272 273``` 274AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCloudFileDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 275``` 276 277**Description** 278 279Obtains the application-level cloud file directory of the application. 280 281**Since**: 16 282 283**Parameters** 284 285| Name| Description| 286| -- | -- | 287| char* buffer | Pointer to the buffer, which is used to receive the bundle name.| 288| const int32_t bufferSize | Buffer size, in bytes.| 289| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 290 291**Returns** 292 293| Type| Description| 294| -- | -- | 295| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 296 297### OH_AbilityRuntime_ApplicationContextGetResourceDir() 298 299``` 300AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetResourceDir(const char* moduleName, char* buffer, const int32_t bufferSize, int32_t* writeLength) 301``` 302 303**Description** 304 305Obtains the application-level resource directory of the application. 306 307**Since**: 20 308 309**Parameters** 310 311| Name| Description| 312| -- | -- | 313| char* moduleName | Pointer to the module name.| 314| char* buffer | Pointer to the buffer, which is used to receive the bundle name.| 315| int32_t bufferSize | Buffer size, in bytes.| 316| int32_t* writeLength | Pointer to the length of the string written to the buffer when [ABILITY_RUNTIME_ERROR_CODE_NO_ERROR](capi-ability-runtime-common-h.md#abilityruntime_errorcode) is returned.| 317 318**Returns** 319 320| Type| Description| 321| -- | -- | 322| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | One of the following execution results:<br>**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful.<br>**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.<br>**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](capi-childprocess.md) created by the application.| 323 324### OH_AbilityRuntime_StartSelfUIAbility() 325 326``` 327AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbility(AbilityBase_Want *want) 328``` 329 330**Description** 331 332Starts the UIAbility of the current application. 333 334> **NOTE** 335> 336> This function is valid only for 2-in-1 devices. 337 338**Required permissions**: ohos.permission.NDK_START_SELF_UI_ABILITY 339 340**Since**: 15 341 342**Parameters** 343 344| Name| Description| 345| -- | -- | 346| [AbilityBase_Want](capi-abilitybase-want.md) *want | Pointer to the Want information required for starting the UIAbility.| 347 348**Returns** 349 350| Type| Description| 351| -- | -- | 352| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | **ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The API call is successful.<br>**ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED**: Permission verification for the caller fails.<br>**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: Parameter verification for the caller fails.<br>**ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED**: The device type is not supported.<br>**ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY**: The specified ability name does not exist.<br>**ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE**: The ability type is incorrect.<br>**ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED**: The crowdtesting application expires.<br>**ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE**: The ability is started or stopped in Wukong mode.<br>**ABILITY_RUNTIME_ERROR_CODE_CONTROLLED**: The application is under control.<br>**ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED**: The application is under control by EDM.<br>**ABILITY_RUNTIME_ERROR_CODE_CROSS_APP**: Redirecting to third-party applications is not allowed in API versions later than 11.<br>**ABILITY_RUNTIME_ERROR_CODE_INTERNAL**: An internal error occurs.<br>**ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY**: The application is not a top one.<br>**ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED** (available since API version 17): The number of instances has reached the upper limit.<br>**ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED** (available since API version 17): Setting **APP_INSTANCE_KEY** is not supported.<br>For details, see **AbilityRuntime_ErrorCode**.| 353 354**Example** 355 356```cpp 357#include <AbilityKit/ability_base/want.h> 358#include <AbilityKit/ability_runtime/application_context.h> 359 360void startSelfUIAbilityTest() 361{ 362 AbilityBase_Element element; 363 element.abilityName = const_cast<char*>("EntryAbility"); 364 element.bundleName = const_cast<char*>("com.example.myapplication"); 365 element.moduleName = const_cast<char*>("entry"); 366 AbilityBase_Want* want = OH_AbilityBase_CreateWant(element); 367 368 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbility(want); 369 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 370 // Record error logs and other service processing. 371 return; 372 } 373 // Destroy the Want to prevent memory leakage. 374 OH_AbilityBase_DestroyWant(want); 375} 376``` 377 378### OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions() 379 380``` 381AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(AbilityBase_Want *want,AbilityRuntime_StartOptions *options) 382``` 383 384**Description** 385 386Starts the UIAbility of the current application using **StartOptions**. 387 388> **NOTE** 389> 390> This function is valid only for 2-in-1 devices. 391 392**Required permissions**: ohos.permission.NDK_START_SELF_UI_ABILITY 393 394**Since**: 17 395 396**Parameters** 397 398| Name| Description| 399| -- | -- | 400| [AbilityBase_Want](capi-abilitybase-want.md) *want | Pointer to the Want information required for starting the UIAbility.| 401| [AbilityRuntime_StartOptions](capi-abilityruntime-startoptions.md) *options | Pointer to **StartOptions** required for starting the UIAbility. If the value of [startVisibility](capi-context-constant-h.md#abilityruntime_startvisibility) is not null, ensure that the current application has been added to the status bar. Otherwise, the [ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED](capi-ability-runtime-common-h.md#abilityruntime_errorcode) error code is returned.| 402 403**Returns** 404 405| Type| Description| 406| -- | -- | 407| [AbilityRuntime_ErrorCode](capi-ability-runtime-common-h.md#abilityruntime_errorcode) | **ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The API call is successful.<br>**ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED**: Permission verification for the caller fails.<br>**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: Parameter verification for the caller fails.<br>**ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED**: The device type is not supported.<br>**ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY**: The specified ability name does not exist.<br>**ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE**: The ability type is incorrect.<br>**ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED**: The crowdtesting application expires.<br>**ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE**: The ability is started or stopped in Wukong mode.<br>**ABILITY_RUNTIME_ERROR_CODE_CONTROLLED**: The application is under control.<br>**ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED**: The application is under control by EDM.<br>**ABILITY_RUNTIME_ERROR_CODE_CROSS_APP**: Redirecting to third-party applications is not allowed in API versions later than 11.<br>**ABILITY_RUNTIME_ERROR_CODE_INTERNAL**: An internal error occurs.<br>**ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY**: The application is not a top one.<br>**ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED**: Setting the window visibility during startup is not allowed.<br>**ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED**: The application does not support clone or multi-instance mode.<br>**ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY**: The multi-instance key is invalid.<br> **ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED**: The number of instances has reached the upper limit.<br>**ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED**: The application does not support multi-instance mode.<br>**ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED**: Setting **APP_INSTANCE_KEY** is not supported.<br>For details, see **AbilityRuntime_ErrorCode**.| 408 409**Example** 410 411```cpp 412#include <AbilityKit/ability_base/want.h> 413#include <AbilityKit/ability_runtime/application_context.h> 414 415void demo() 416{ 417 AbilityBase_Element element; 418 element.abilityName = const_cast<char*>("EntryAbility"); 419 element.bundleName = const_cast<char*>("com.example.myapplication"); 420 element.moduleName = const_cast<char*>("entry"); 421 AbilityBase_Want* want = OH_AbilityBase_CreateWant(element); 422 if (want == nullptr) { 423 // Record error logs and other service processing. 424 return; 425 } 426 427 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 428 if (options == nullptr) { 429 // Record error logs and other service processing. 430 431 // Destroy the Want to prevent memory leakage. 432 OH_AbilityBase_DestroyWant(want); 433 return; 434 } 435 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(want, options); 436 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 437 // Record error logs and other service processing. 438 } 439 // Destroy the Want to prevent memory leakage. 440 OH_AbilityBase_DestroyWant(want); 441 442 // Destroy options to prevent memory leakage. 443 OH_AbilityRuntime_DestroyStartOptions(&options); 444} 445``` 446