1# AbilityRuntime 2 3 4## Overview 5 6The 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 the context-related enums.<br>**File to include**: <AbilityKit/ability_runtime/context_constant.h><br>**Library**: libability_runtime.so| 23| [start_options.h](start__options_8h.md) | Declares the StartOptions struct and related functions.<br>**File to include**: <AbilityKit/ability_runtime/start_options.h><br>**Library**: libability_runtime.so| 24 25### Enums 26 27| Name | Description | 28| ------------------------------------------------------------ | ---------------------- | 29| [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> ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED = 16000067,<br> ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED = 16000072,<br> ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY = 16000076,<br> ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED = 16000077,<br> ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED = 16000078,<br> ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED = 16000079<br>} | Enumerates the error codes used by the ability framework.| 30| [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. | 31| [AbilityRuntime_StartVisibility](#abilityruntime_startvisibility) {<br> ABILITY_RUNTIME_HIDE_UPON_START = 0,<br> ABILITY_RUNTIME_SHOW_UPON_START = 1<br>} | Enumerates the visibility modes of the window and dock bar icons when the ability is started. | 32| [AbilityRuntime_WindowMode](#abilityruntime_windowmode) {<br> ABILITY_RUNTIME_WINDOW_MODE_UNDEFINED = 0,<br> ABILITY_RUNTIME_WINDOW_MODE_FULL_SCREEN = 1<br>} | Enumerates the window modes in which an ability can be displayed at startup. | 33| [AbilityRuntime_SupportedWindowMode](#abilityruntime_supportedwindowmode) {<br> ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FULL_SCREEN = 0,<br> ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_SPLIT = 1,<br> ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FLOATING = 2<br>} | Enumerates the window modes supported by an ability when it is started. | 34 35### Functions 36 37| Name| Description| 38| -------- | -------- | 39| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetCacheDir](#oh_abilityruntime_applicationcontextgetcachedir)(char* buffer, int32_t bufferSize, int32_t* writeLength) | Obtains the application-level cache directory of the application.| 40| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetAreaMode](#oh_abilityruntime_applicationcontextgetareamode)([AbilityRuntime_AreaMode](#abilityruntime_areamode)* areaMode) | Obtains the application-level data encryption level of the application.| 41| [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.| 42| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetTempDir](#oh_abilityruntime_applicationcontextgettempdir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | Obtains the application-level temporary file directory of the application.| 43| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetFilesDir](#oh_abilityruntime_applicationcontextgetfilesdir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | Obtains the application-level common file directory of the application.| 44| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetDatabaseDir](#oh_abilityruntime_applicationcontextgetdatabasedir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | Obtains the application-level database file directory of the application.| 45| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetPreferencesDir](#oh_abilityruntime_applicationcontextgetpreferencesdir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | Obtains the application-level preferences file directory of the application.| 46| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetBundleCodeDir](#oh_abilityruntime_applicationcontextgetbundlecodedir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | Obtains the application-level installation file directory of the application.| 47| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir](#oh_abilityruntime_applicationcontextgetdistributedfilesdir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | Obtains the application-level distributed file directory of the application.| 48| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetCloudFileDir](#oh_abilityruntime_applicationcontextgetcloudfiledir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | Obtains the application-level cloud file directory of the application.| 49| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetResourceDir](#oh_abilityruntime_applicationcontextgetresourcedir)(const char* moduleName, char* buffer, const int32_t bufferSize, int32_t* writeLength) | Obtains the application-level resource directory of the application.| 50| [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.| 51| [AbilityRuntime_StartOptions*](#abilityruntime_startoptions) [OH_AbilityRuntime_CreateStartOptions](#oh_abilityruntime_createstartoptions)(void) | Creates the StartOptions struct required for starting the UIAbility of the current application.| 52| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_DestroyStartOptions](#oh_abilityruntime_destroystartoptions)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) **startOptions) | Destroys a StartOptions struct.| 53| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowMode](#oh_abilityruntime_setstartoptionswindowmode)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_WindowMode](#abilityruntime_windowmode) windowMode) | Sets the window mode for starting an ability.| 54| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowMode](#oh_abilityruntime_getstartoptionswindowmode)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_WindowMode](#abilityruntime_windowmode) &windowMode) | Obtains the window mode for starting an ability.| 55| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsDisplayId](#oh_abilityruntime_setstartoptionsdisplayid)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t displayId) | Sets the ID of the display where the window is launched when the ability is started.| 56| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsDisplayId](#oh_abilityruntime_getstartoptionsdisplayid)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &displayId) | Obtains the ID of the display where the window is launched when the ability is started.| 57| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWithAnimation](#oh_abilityruntime_setstartoptionswithanimation)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, bool withAnimation) | Sets whether to use animation effects when an ability is started.| 58| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWithAnimation](#oh_abilityruntime_getstartoptionswithanimation)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, bool &withAnimation) | Checks whether animation effects are used when an ability is started.| 59| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowLeft](#oh_abilityruntime_setstartoptionswindowleft)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t windowLeft) | Sets the left position of the window when the ability is started, in px.| 60| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowLeft](#oh_abilityruntime_getstartoptionswindowleft)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &windowLeft) | Obtains the left position of the window when the ability is started, in px.| 61| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowTop](#oh_abilityruntime_setstartoptionswindowtop)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t windowTop) | Sets the top position of the window when the ability is started, in px.| 62| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowTop](#oh_abilityruntime_getstartoptionswindowtop)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &windowTop) | Obtains the top position of the window when the ability is started, in px.| 63| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowHeight](#oh_abilityruntime_setstartoptionswindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t windowHeight) | Sets the height of the window when the ability is started, in px.| 64| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowHeight](#oh_abilityruntime_getstartoptionswindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &windowHeight) | Obtains the height of the window when the ability is started, in px.| 65| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowWidth](#oh_abilityruntime_setstartoptionswindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t windowWidth) | Sets the width of the window when the ability is started, in px.| 66| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowWidth](#oh_abilityruntime_getstartoptionswindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &windowWidth) | Obtains the width of the window when the ability is started, in px.| 67| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsStartVisibility](#oh_abilityruntime_setstartoptionsstartvisibility)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_StartVisibility](#abilityruntime_startvisibility) startVisibility) | Sets the visibility of the window and dock bar icons when the ability is started.| 68| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsStartVisibility](#oh_abilityruntime_getstartoptionsstartvisibility)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_StartVisibility](#abilityruntime_startvisibility) &startVisibility) | Obtains the visibility of the window and dock bar icons when the ability is started.| 69| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsStartWindowIcon](#oh_abilityruntime_setstartoptionsstartwindowicon)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [OH_PixelmapNative](../apis-image-kit/capi-image-nativemodule-oh-pixelmapnative.md) *startWindowIcon) | Sets the startup icon of the window when the ability is started.| 70| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsStartWindowIcon](#oh_abilityruntime_getstartoptionsstartwindowicon)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [OH_PixelmapNative](../apis-image-kit/capi-image-nativemodule-oh-pixelmapnative.md) **startWindowIcon) | Obtains the startup icon of the window when the ability is started.| 71| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsStartWindowBackgroundColor](#oh_abilityruntime_setstartoptionsstartwindowbackgroundcolor)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, const char *startWindowBackgroundColor) | Sets the background color of the window when the ability is started.| 72| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsStartWindowBackgroundColor](#oh_abilityruntime_getstartoptionsstartwindowbackgroundcolor)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, char **startWindowBackgroundColor, size_t &size) | Obtains the background color of the window when the ability is started.| 73| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsSupportedWindowModes](#oh_abilityruntime_setstartoptionssupportedwindowmodes)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_SupportedWindowMode](#abilityruntime_supportedwindowmode) *supportedWindowModes, size_t size) | Sets the window modes supported by the ability when it is started.| 74| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsSupportedWindowModes](#oh_abilityruntime_getstartoptionssupportedwindowmodes)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_SupportedWindowMode](#abilityruntime_supportedwindowmode) **supportedWindowModes, size_t &size) | Obtains the window modes supported by the ability when it is started.| 75| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsMinWindowWidth](#oh_abilityruntime_setstartoptionsminwindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t minWindowWidth) | Sets the minimum window width for starting the ability, in vp.| 76| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsMinWindowWidth](#oh_abilityruntime_getstartoptionsminwindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &minWindowWidth) | Obtains the minimum window width for starting the ability, in vp.| 77| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsMaxWindowWidth](#oh_abilityruntime_setstartoptionsmaxwindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t maxWindowWidth) | Sets the maximum window width for starting the ability, in vp.| 78| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsMaxWindowWidth](#oh_abilityruntime_getstartoptionsmaxwindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &maxWindowWidth) | Obtains the maximum window width for starting the ability, in vp.| 79| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsMinWindowHeight](#oh_abilityruntime_setstartoptionsminwindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t minWindowHeight) | Sets the minimum window height for starting the ability, in vp.| 80| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsMinWindowHeight](#oh_abilityruntime_getstartoptionsminwindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &minWindowHeight) | Obtains the minimum window height for starting the ability, in vp.| 81| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsMaxWindowHeight](#oh_abilityruntime_setstartoptionsmaxwindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t maxWindowHeig) | Sets the maximum window height for starting the ability, in vp.| 82| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsMaxWindowHeight](#oh_abilityruntime_getstartoptionsmaxwindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &maxWindowHeight) | Obtains the maximum window height for starting the ability, in vp.| 83| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions](#oh_abilityruntime_startselfuiabilitywithstartoptions)([AbilityBase_Want](_ability_base.md#abilitybase_want) *want, [AbilityRuntime_StartOptions](#abilityruntime_startoptions) *options) | Starts the UIAbility of the current application.| 84 85## Structs 86 87### AbilityRuntime_StartOptions 88 89``` 90AbilityRuntime_StartOptions 91``` 92 93**Description** 94 95StartOptions struct. 96 97**Since**: 17 98 99## Enum Description 100 101### AbilityRuntime_ErrorCode 102 103``` 104enum AbilityRuntime_ErrorCode 105``` 106 107**Description** 108 109Enumerates the error codes used by the ability framework. 110 111**Since**: 13 112 113| Value | Description | 114| --------------------------------------------- | -------------- | 115| ABILITY_RUNTIME_ERROR_CODE_NO_ERROR | Operation successful. | 116| ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID | Invalid parameter. | 117| ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST | The context does not exist.| 118| ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED | Permission verification failed.<br>**Since**: 15| 119| ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED | The device type is not supported.<br>**Since**: 15| 120| ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY | The specified ability name does not exist.<br>**Since**: 15| 121| ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE | The ability type is incorrect.<br>**Since**: 15| 122| ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED | The crowdtesting application expires.<br>**Since**: 15| 123| ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE | An ability cannot be started or stopped in Wukong mode.<br>**Since**: 15| 124| ABILITY_RUNTIME_ERROR_CODE_CONTROLLED | The application is under control.<br>**Since**: 15| 125| ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED | The application is under control by EDM.<br>**Since**: 15| 126| ABILITY_RUNTIME_ERROR_CODE_CROSS_APP | Redirection to third-party applications is not allowed in API versions later than 11.<br>**Since**: 15| 127| ABILITY_RUNTIME_ERROR_CODE_INTERNAL | Internal error.<br>**Since**: 15| 128| ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY | The application is not on top.<br>**Since**: 15| 129| ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED | The window visibility cannot be set when the application is started.<br>**Since**: 17| 130| ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED | The application does not support clone or multi-instance mode.<br>**Since**: 17| 131| ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY | The instance key is invalid.<br>**Since**: 17| 132| ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED | The number of instances has reached the upper limit.<br>**Since**: 17| 133| ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED | The application does not support multi-instance mode.<br>**Since**: 17| 134| ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED | Setting **instanceKey** is not supported.<br>**Since**: 17| 135 136### AbilityRuntime_AreaMode 137 138``` 139enum AbilityRuntime_AreaMode 140``` 141 142**Description** 143 144Enumerates the data encryption levels. 145 146**Since**: 13 147 148| Value | Description | 149| ----------------------------- | ------------------------------------------------------------ | 150| 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.| 151| 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).| 152| 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.| 153| 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.| 154| 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.| 155 156### AbilityRuntime_StartVisibility 157 158``` 159enum AbilityRuntime_StartVisibility 160``` 161 162**Description** 163 164Enumerates the visibility modes of the window and dock bar icons when the ability is started. 165 166**Since**: 17 167 168| Value | Description | 169| ----------------------------- | ------------------------------------------------------------ | 170| ABILITY_RUNTIME_HIDE_UPON_START | Hides the window and dock bar icons. This mode takes effect only on 2-in-1 devices. | 171| ABILITY_RUNTIME_SHOW_UPON_START | Displays the window and dock bar icons. This mode takes effect only on 2-in-1 devices.| 172 173### AbilityRuntime_WindowMode 174 175``` 176enum AbilityRuntime_WindowMode 177``` 178 179**Description** 180 181Enumerates the window modes in which an ability can be displayed at startup. 182 183**Since**: 17 184 185| Value | Description | 186| ----------------------------- | ------------------------------------------------------------ | 187| ABILITY_RUNTIME_WINDOW_MODE_UNDEFINED | Undefined window mode.| 188| ABILITY_RUNTIME_WINDOW_MODE_FULL_SCREEN | Full-screen mode. This mode takes effect only on 2-in-1 devices.| 189 190### AbilityRuntime_SupportedWindowMode 191 192``` 193enum AbilityRuntime_SupportedWindowMode 194``` 195 196**Description** 197 198Enumerates the window modes supported by an ability when it is started. The supported window mode specifies whether to display the maximize, minimize, or split-screen button when the UIAbility is launched in an application. If this enum is not set, the value of **supportWindowMode** configured under [abilities](../../quick-start/module-configuration-file.md#abilities) in the [module.json5](../../quick-start/module-configuration-file.md) file corresponding to the UIAbility is used by default. 199 200**Since**: 17 201 202| Value | Description | 203| ----------------------------- | ------------------------------------------------------------ | 204| ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FULL_SCREEN | A window in full-screen mode is supported.| 205| ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_SPLIT | A window in split-screen mode is supported. Generally, **ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FULL_SCREEN** or **ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FLOATING** must be used together. You are not advised to configure only **ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_SPLIT**. If only **ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_SPLIT** is configured, the window on 2-in-1 devices is in floating window mode by default and can transition to the split-screen mode. | 206| ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FLOATING | A floating window is supported.| 207 208## Function Description 209 210 211### OH_AbilityRuntime_ApplicationContextGetCacheDir 212 213``` 214AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCacheDir(char* buffer, int32_t bufferSize, int32_t* writeLength) 215``` 216**Description** 217 218Obtains the application-level cache directory of the application. 219 220**Since**: 13 221 222**Parameters** 223 224| Name| Description| 225| -------- | -------- | 226| buffer | Pointer to the buffer. The cache directory string is written to this area.| 227| bufferSize | Buffer siz, in bytes.| 228| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 229 230**Returns** 231 232**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 233 234**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. 235 236**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 237 238### OH_AbilityRuntime_ApplicationContextGetAreaMode 239 240``` 241AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetAreaMode(AbilityRuntime_AreaMode* areaMode) 242``` 243 244**Description** 245 246Obtains the application-level data encryption level of the application. 247 248**Since**: 13 249 250**Parameters** 251 252| Name | Description | 253| -------- | ------------------------ | 254| areaMode | Pointer to the data encryption level.| 255 256**Returns** 257 258**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 259 260**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **areaMode** is null. 261 262**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 263 264### OH_AbilityRuntime_ApplicationContextGetBundleName 265 266``` 267AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleName(char* buffer, int32_t bufferSize, int32_t* writeLength) 268``` 269 270**Description** 271 272Obtains the bundle name of the application. 273 274**Since**: 13 275 276**Parameters** 277 278| Name | Description | 279| ----------- | ------------------------------------------------------------ | 280| buffer | Pointer to the buffer. The bundle name string is written to this area. | 281| bufferSize | Buffer siz, in bytes. | 282| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 283 284**Returns** 285 286**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 287 288**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. 289 290**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 291 292### OH_AbilityRuntime_ApplicationContextGetTempDir 293 294``` 295AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetTempDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 296``` 297 298**Description** 299 300Obtains the application-level temporary file directory of the application. 301 302**Since**: 16 303 304**Parameters** 305 306| Name | Description | 307| ----------- | ------------------------------------------------------------ | 308| buffer | Pointer to the buffer. The cache directory string is written to this area. | 309| bufferSize | Buffer siz, in bytes. | 310| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 311 312**Returns** 313 314**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 315 316**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. 317 318**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 319 320### OH_AbilityRuntime_ApplicationContextGetFilesDir 321 322``` 323AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 324``` 325 326**Description** 327 328Obtains the application-level common file directory of the application. 329 330**Since**: 16 331 332**Parameters** 333 334| Name | Description | 335| ----------- | ------------------------------------------------------------ | 336| buffer | Pointer to the buffer. The cache directory string is written to this area. | 337| bufferSize | Buffer siz, in bytes. | 338| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 339 340**Returns** 341 342**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 343 344**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. 345 346**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 347 348### OH_AbilityRuntime_ApplicationContextGetDatabaseDir 349 350``` 351AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDatabaseDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 352``` 353 354**Description** 355 356Obtains the application-level database file directory of the application. 357 358**Since**: 16 359 360**Parameters** 361 362| Name | Description | 363| ----------- | ------------------------------------------------------------ | 364| buffer | Pointer to the buffer. The cache directory string is written to this area. | 365| bufferSize | Buffer siz, in bytes. | 366| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 367 368**Returns** 369 370**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 371 372**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. 373 374**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 375 376### OH_AbilityRuntime_ApplicationContextGetPreferencesDir 377 378``` 379AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetPreferencesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 380``` 381 382**Description** 383 384Obtains the application-level preferences file directory of the application. 385 386**Since**: 16 387 388**Parameters** 389 390| Name | Description | 391| ----------- | ------------------------------------------------------------ | 392| buffer | Pointer to the buffer. The cache directory string is written to this area. | 393| bufferSize | Buffer siz, in bytes. | 394| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 395 396**Returns** 397 398**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 399 400**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. 401 402**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 403 404### OH_AbilityRuntime_ApplicationContextGetBundleCodeDir 405 406``` 407AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleCodeDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 408``` 409 410**Description** 411 412Obtains the application-level installation file directory of the application. 413 414**Since**: 16 415 416**Parameters** 417 418| Name | Description | 419| ----------- | ------------------------------------------------------------ | 420| buffer | Pointer to the buffer. The cache directory string is written to this area. | 421| bufferSize | Buffer siz, in bytes. | 422| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 423 424**Returns** 425 426**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 427 428**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. 429 430**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 431 432### OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir 433 434``` 435AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 436``` 437 438**Description** 439 440Obtains the application-level distributed file directory of the application. 441 442**Since**: 16 443 444**Parameters** 445 446| Name | Description | 447| ----------- | ------------------------------------------------------------ | 448| buffer | Pointer to the buffer. The cache directory string is written to this area. | 449| bufferSize | Buffer siz, in bytes. | 450| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 451 452**Returns** 453 454**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 455 456**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. 457 458**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 459 460### OH_AbilityRuntime_ApplicationContextGetCloudFileDir 461 462``` 463AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCloudFileDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 464``` 465 466**Description** 467 468Obtains the application-level cloud file directory of the application. 469 470**Since**: 16 471 472**Parameters** 473 474| Name | Description | 475| ----------- | ------------------------------------------------------------ | 476| buffer | Pointer to the buffer. The cache directory string is written to this area. | 477| bufferSize | Buffer siz, in bytes. | 478| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 479 480**Returns** 481 482**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 483 484**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. 485 486**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 487 488### OH_AbilityRuntime_ApplicationContextGetResourceDir 489 490``` 491AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetResourceDir(const char* moduleName, char* buffer, const int32_t bufferSize, int32_t* writeLength) 492``` 493 494**Description** 495 496Obtains the application-level resource directory of the application. 497 498**Since**: 20 499 500**Parameters** 501 502| Name | Description | 503| ----------- | ------------------------------------------------------------ | 504| moduleName | Pointer to the module name. | 505| buffer | Pointer to the buffer. The cache directory string is written to this area. | 506| bufferSize | Buffer siz, in bytes. | 507| writeLength | Pointer to the length of the string actually written to the buffer, in bytes.| 508 509**Returns** 510 511**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 512 513**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. 514 515**ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST**: 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. 516 517### OH_AbilityRuntime_StartSelfUIAbility 518 519``` 520AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbility(AbilityBase_Want *want) 521``` 522 523**Description** 524 525Starts the UIAbility of the current application. 526 527> **NOTE** 528> 529> This function is valid only for 2-in-1 devices. 530 531**Required permissions**: ohos.permission.NDK_START_SELF_UI_ABILITY 532 533**Since**: 15 534 535**Parameters** 536 537| Name | Description | 538| ----------- | ------------------------------------------------------------ | 539| want | Pointer to the Want information required for starting the UIAbility. | 540 541**Returns** 542 543**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The API call is successful. 544 545**ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED**: Permission verification fails. 546 547**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: The Want information is null, or if the bundleName or abilityName in the Want information is null. 548 549**ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED**: The device type is not supported. 550 551**ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY**: The specified ability name does not exist. 552 553**ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE**: The ability type is incorrect. 554 555**ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED**: The crowdtesting application expires. 556 557**ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE**: The ability is started or stopped in Wukong mode. 558 559**ABILITY_RUNTIME_ERROR_CODE_CONTROLLED**: The application is under control. 560 561**ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED**: The application is under control by EDM. 562 563**ABILITY_RUNTIME_ERROR_CODE_CROSS_APP**: Redirecting to third-party applications is not allowed in API versions later than 11. 564 565**ABILITY_RUNTIME_ERROR_CODE_INTERNAL**: An internal error occurs. 566 567**ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY**: The application is not a top one. 568 569**ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED**: The number of instances has reached the upper limit. 570 571**ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED**: **APP_INSTANCE_KEY** cannot be set. 572 573**Example** 574```cpp 575#include <AbilityKit/ability_base/want.h> 576#include <AbilityKit/ability_runtime/application_context.h> 577 578void startSelfUIAbilityTest() 579{ 580 AbilityBase_Element element; 581 element.abilityName = const_cast<char*>("EntryAbility"); 582 element.bundleName = const_cast<char*>("com.example.myapplication"); 583 element.moduleName = const_cast<char*>("entry"); 584 AbilityBase_Want* want = OH_AbilityBase_CreateWant(element); 585 586 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbility(want); 587 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 588 // Record error logs and other service processing. 589 return; 590 } 591 // Destroy the Want to prevent memory leakage. 592 OH_AbilityBase_DestroyWant(want); 593} 594``` 595 596### OH_AbilityRuntime_CreateStartOptions 597 598``` 599AbilityRuntime_StartOptions* OH_AbilityRuntime_CreateStartOptions(void) 600``` 601 602**Description** 603 604Creates the StartOptions struct required for starting the UIAbility of the current application. 605 606**Since**: 17 607 608**Returns** 609 610Pointer to **AbilityRuntime_StartOptions**, which is the StartOptions struct. 611 612**Example** 613```cpp 614#include <AbilityKit/ability_runtime/start_options.h> 615 616void createStartOptionsTest() 617{ 618 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 619 if (options == nullptr) { 620 // Record error logs and other service processing. 621 return; 622 } 623 624 // Destroy options to prevent memory leakage. 625 OH_AbilityRuntime_DestroyStartOptions(&options); 626} 627``` 628 629### OH_AbilityRuntime_DestroyStartOptions 630 631``` 632AbilityRuntime_ErrorCode OH_AbilityRuntime_DestroyStartOptions(AbilityRuntime_StartOptions **startOptions) 633``` 634 635**Description** 636 637Destroys a StartOptions struct. 638 639**Parameters** 640 641| Name | Description | 642| ----------- | ------------------------------------------------------------ | 643| startOptions | Double pointer to the StartOptions struct. | 644 645**Since**: 17 646 647**Returns** 648 649**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The struct is destroyed successfully. 650 651**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 652 653**Example** 654```cpp 655#include <AbilityKit/ability_runtime/start_options.h> 656 657void destroyStartOptionsTest() 658{ 659 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 660 if (options == nullptr) { 661 // Record error logs and other service processing. 662 return; 663 } 664 665 // Destroy options to prevent memory leakage. 666 OH_AbilityRuntime_DestroyStartOptions(&options); 667} 668``` 669 670### OH_AbilityRuntime_SetStartOptionsWindowMode 671 672``` 673AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowMode(AbilityRuntime_StartOptions *startOptions, 674 AbilityRuntime_WindowMode windowMode); 675``` 676 677**Description** 678 679Sets the window mode for starting an ability. 680 681**Parameters** 682 683| Name | Description | 684| ----------- | ------------------------------------------------------------ | 685| startOptions | Pointer to the StartOptions struct. | 686| windowMode | Window mode. For details about the available options, see [AbilityRuntime_WindowMode](_ability_runtime.md#abilityruntime_windowmode). | 687 688**Since**: 17 689 690**Returns** 691 692**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 693 694**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null or **WindowMode** is invalid. 695 696**Example** 697```cpp 698#include <AbilityKit/ability_runtime/start_options.h> 699 700void demo() 701{ 702 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 703 if (options == nullptr) { 704 // Record error logs and other service processing. 705 return; 706 } 707 708 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowMode(options, 709 ABILITY_RUNTIME_WINDOW_MODE_FULL_SCREEN); 710 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 711 // Record error logs and other service processing. 712 } 713 // Destroy options to prevent memory leakage. 714 OH_AbilityRuntime_DestroyStartOptions(&options); 715} 716``` 717 718### OH_AbilityRuntime_GetStartOptionsWindowMode 719 720``` 721AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowMode(AbilityRuntime_StartOptions *startOptions, 722 AbilityRuntime_WindowMode &windowMode); 723``` 724 725**Description** 726 727Obtains the window mode for starting an ability. 728 729**Parameters** 730 731| Name | Description | 732| ----------- | ------------------------------------------------------------ | 733| startOptions | Pointer to the StartOptions struct. | 734| windowMode | Window mode. For details about the available options, see [AbilityRuntime_WindowMode](_ability_runtime.md#abilityruntime_windowmode). | 735 736**Since**: 17 737 738**Returns** 739 740**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 741 742**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 743 744**Example** 745```cpp 746#include <AbilityKit/ability_runtime/start_options.h> 747 748void demo() 749{ 750 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 751 if (options == nullptr) { 752 // Record error logs and other service processing. 753 return; 754 } 755 756 AbilityRuntime_WindowMode windowMode = ABILITY_RUNTIME_WINDOW_MODE_UNDEFINED; 757 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowMode(options, windowMode); 758 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 759 // Record error logs and other service processing. 760 } 761 // Destroy options to prevent memory leakage. 762 OH_AbilityRuntime_DestroyStartOptions(&options); 763} 764``` 765 766### OH_AbilityRuntime_SetStartOptionsDisplayId 767 768``` 769AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsDisplayId(AbilityRuntime_StartOptions *startOptions, int32_t displayId); 770``` 771 772**Description** 773 774Sets the ID of the display where the window is launched when the ability is started. 775 776**Parameters** 777 778| Name | Description | 779| ----------- | ------------------------------------------------------------ | 780| startOptions | Pointer to the StartOptions struct. | 781| displayId | Display ID. | 782 783**Since**: 17 784 785**Returns** 786 787**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 788 789**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 790 791**Example** 792```cpp 793#include <AbilityKit/ability_runtime/start_options.h> 794 795void demo() 796{ 797 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 798 if (options == nullptr) { 799 // Record error logs and other service processing. 800 return; 801 } 802 803 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsDisplayId(options, 1); 804 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 805 // Record error logs and other service processing. 806 } 807 // Destroy options to prevent memory leakage. 808 OH_AbilityRuntime_DestroyStartOptions(&options); 809} 810``` 811 812### OH_AbilityRuntime_GetStartOptionsDisplayId 813 814``` 815AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsDisplayId(AbilityRuntime_StartOptions *startOptions, int32_t &displayId); 816``` 817 818**Description** 819 820Obtains the ID of the display where the window is launched when the ability is started. 821 822**Parameters** 823 824| Name | Description | 825| ----------- | ------------------------------------------------------------ | 826| startOptions | Pointer to the StartOptions struct. | 827| displayId | Display ID. | 828 829**Since**: 17 830 831**Returns** 832 833**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 834 835**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 836 837**Example** 838```cpp 839#include <AbilityKit/ability_runtime/start_options.h> 840 841void demo() 842{ 843 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 844 if (options == nullptr) { 845 // Record error logs and other service processing. 846 return; 847 } 848 849 int32_t displayId = 0; 850 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsDisplayId(options, displayId); 851 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 852 // Record error logs and other service processing. 853 } 854 // Destroy options to prevent memory leakage. 855 OH_AbilityRuntime_DestroyStartOptions(&options); 856} 857``` 858 859### OH_AbilityRuntime_SetStartOptionsWithAnimation 860 861``` 862AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWithAnimation(AbilityRuntime_StartOptions *startOptions, bool withAnimation); 863``` 864 865**Description** 866 867Sets whether to use animation effects when an ability is started. 868 869**Parameters** 870 871| Name | Description | 872| ----------- | ------------------------------------------------------------ | 873| startOptions | Pointer to the StartOptions struct. | 874| withAnimation | Whether to use animation effects.<br>**NOTE**<br>The value **true** means that the ability has an animation effect when being started.<br>The value **false** means that the ability does not have an animation effect when being started.<br> | 875 876**Since**: 17 877 878**Returns** 879 880**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 881 882**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 883 884**Example** 885```cpp 886#include <AbilityKit/ability_runtime/start_options.h> 887 888void demo() 889{ 890 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 891 if (options == nullptr) { 892 // Record error logs and other service processing. 893 return; 894 } 895 896 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWithAnimation(options, true); 897 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 898 // Record error logs and other service processing. 899 } 900 // Destroy options to prevent memory leakage. 901 OH_AbilityRuntime_DestroyStartOptions(&options); 902} 903``` 904 905### OH_AbilityRuntime_GetStartOptionsWithAnimation 906 907``` 908AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWithAnimation(AbilityRuntime_StartOptions *startOptions, bool &withAnimation); 909``` 910 911**Description** 912 913Checks whether animation effects are used when an ability is started. 914 915**Parameters** 916 917| Name | Description | 918| ----------- | ------------------------------------------------------------ | 919| startOptions | Pointer to the StartOptions struct. | 920| withAnimation | Whether animation effects are used.<br>**NOTE**<br>The value **true** means that the ability has an animation effect when being started.<br>The value **false** means that the ability does not have an animation effect when being started.<br> | 921 922**Since**: 17 923 924**Returns** 925 926**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 927 928**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 929 930**Example** 931```cpp 932#include <AbilityKit/ability_runtime/start_options.h> 933 934void demo() 935{ 936 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 937 if (options == nullptr) { 938 // Record error logs and other service processing. 939 return; 940 } 941 942 bool withAnimation = false; 943 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWithAnimation(options, withAnimation); 944 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 945 // Record error logs and other service processing. 946 } 947 // Destroy options to prevent memory leakage. 948 OH_AbilityRuntime_DestroyStartOptions(&options); 949} 950``` 951 952### OH_AbilityRuntime_SetStartOptionsWindowLeft 953 954``` 955AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowLeft(AbilityRuntime_StartOptions *startOptions, int32_t windowLeft); 956``` 957 958**Description** 959 960Sets the left position of the window when the ability is started, in px. 961 962**Parameters** 963 964| Name | Description | 965| ----------- | ------------------------------------------------------------ | 966| startOptions | Pointer to the StartOptions struct. | 967| windowLeft | Left position of the window, in px. | 968 969**Since**: 17 970 971**Returns** 972 973**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 974 975**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 976 977**Example** 978```cpp 979#include <AbilityKit/ability_runtime/start_options.h> 980 981void demo() 982{ 983 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 984 if (options == nullptr) { 985 // Record error logs and other service processing. 986 return; 987 } 988 989 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowLeft(options, 200); 990 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 991 // Record error logs and other service processing. 992 } 993 // Destroy options to prevent memory leakage. 994 OH_AbilityRuntime_DestroyStartOptions(&options); 995} 996``` 997 998### OH_AbilityRuntime_GetStartOptionsWindowLeft 999 1000``` 1001AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowLeft(AbilityRuntime_StartOptions *startOptions, int32_t &windowLeft); 1002``` 1003 1004**Description** 1005 1006Obtains the left position of the window when the ability is started, in px. 1007 1008**Parameters** 1009 1010| Name | Description | 1011| ----------- | ------------------------------------------------------------ | 1012| startOptions | Pointer to the StartOptions struct. | 1013| windowLeft | Left position of the window, in px. | 1014 1015**Since**: 17 1016 1017**Returns** 1018 1019**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1020 1021**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1022 1023**Example** 1024```cpp 1025#include <AbilityKit/ability_runtime/start_options.h> 1026 1027void demo() 1028{ 1029 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1030 if (options == nullptr) { 1031 // Record error logs and other service processing. 1032 return; 1033 } 1034 1035 int32_t windowLeft = 0; 1036 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowLeft(options, windowLeft); 1037 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1038 // Record error logs and other service processing. 1039 } 1040 // Destroy options to prevent memory leakage. 1041 OH_AbilityRuntime_DestroyStartOptions(&options); 1042} 1043``` 1044 1045### OH_AbilityRuntime_SetStartOptionsWindowTop 1046 1047``` 1048AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowTop(AbilityRuntime_StartOptions *startOptions, int32_t windowTop); 1049``` 1050 1051**Description** 1052 1053Sets the top position of the window when the ability is started, in px. 1054 1055**Parameters** 1056 1057| Name | Description | 1058| ----------- | ------------------------------------------------------------ | 1059| startOptions | Pointer to the StartOptions struct. | 1060| windowTop | Top position of the window, in px. | 1061 1062**Since**: 17 1063 1064**Returns** 1065 1066**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1067 1068**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1069 1070**Example** 1071```cpp 1072#include <AbilityKit/ability_runtime/start_options.h> 1073 1074void demo() 1075{ 1076 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1077 if (options == nullptr) { 1078 // Record error logs and other service processing. 1079 return; 1080 } 1081 1082 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowTop(options, 500); 1083 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1084 // Record error logs and other service processing. 1085 } 1086 // Destroy options to prevent memory leakage. 1087 OH_AbilityRuntime_DestroyStartOptions(&options); 1088} 1089``` 1090 1091### OH_AbilityRuntime_GetStartOptionsWindowTop 1092 1093``` 1094AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowTop(AbilityRuntime_StartOptions *startOptions, int32_t &windowTop); 1095``` 1096 1097**Description** 1098 1099Obtains the top position of the window when the ability is started, in px. 1100 1101**Parameters** 1102 1103| Name | Description | 1104| ----------- | ------------------------------------------------------------ | 1105| startOptions | Pointer to the StartOptions struct. | 1106| windowTop | Top position of the window, in px. | 1107 1108**Since**: 17 1109 1110**Returns** 1111 1112**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1113 1114**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1115 1116**Example** 1117```cpp 1118#include <AbilityKit/ability_runtime/start_options.h> 1119 1120void demo() 1121{ 1122 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1123 if (options == nullptr) { 1124 // Record error logs and other service processing. 1125 return; 1126 } 1127 1128 int32_t windowTop = 0; 1129 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowTop(options, windowTop); 1130 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1131 // Record error logs and other service processing. 1132 } 1133 // Destroy options to prevent memory leakage. 1134 OH_AbilityRuntime_DestroyStartOptions(&options); 1135} 1136``` 1137 1138### OH_AbilityRuntime_SetStartOptionsWindowHeight 1139 1140``` 1141AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowHeight(AbilityRuntime_StartOptions *startOptions, int32_t windowHeight); 1142``` 1143 1144**Description** 1145 1146Sets the height of the window when the ability is started, in px. 1147 1148**Parameters** 1149 1150| Name | Description | 1151| ----------- | ------------------------------------------------------------ | 1152| startOptions | Pointer to the StartOptions struct. | 1153| windowHeight | Window height, in px. | 1154 1155**Since**: 17 1156 1157**Returns** 1158 1159**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1160 1161**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1162 1163**Example** 1164```cpp 1165#include <AbilityKit/ability_runtime/start_options.h> 1166 1167void demo() 1168{ 1169 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1170 if (options == nullptr) { 1171 // Record error logs and other service processing. 1172 return; 1173 } 1174 1175 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowHeight(options, 500); 1176 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1177 // Record error logs and other service processing. 1178 } 1179 // Destroy options to prevent memory leakage. 1180 OH_AbilityRuntime_DestroyStartOptions(&options); 1181} 1182``` 1183 1184### OH_AbilityRuntime_GetStartOptionsWindowHeight 1185 1186``` 1187AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowHeight(AbilityRuntime_StartOptions *startOptions, int32_t &windowHeight); 1188``` 1189 1190**Description** 1191 1192Obtains the height of the window when the ability is started, in px. 1193 1194**Parameters** 1195 1196| Name | Description | 1197| ----------- | ------------------------------------------------------------ | 1198| startOptions | Pointer to the StartOptions struct. | 1199| windowHeight | Window height, in px. | 1200 1201**Since**: 17 1202 1203**Returns** 1204 1205**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1206 1207**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1208 1209**Example** 1210```cpp 1211#include <AbilityKit/ability_runtime/start_options.h> 1212 1213void demo() 1214{ 1215 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1216 if (options == nullptr) { 1217 // Record error logs and other service processing. 1218 return; 1219 } 1220 1221 int32_t windowHeight = 0; 1222 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowHeight(options, windowHeight); 1223 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1224 // Record error logs and other service processing. 1225 } 1226 // Destroy options to prevent memory leakage. 1227 OH_AbilityRuntime_DestroyStartOptions(&options); 1228} 1229``` 1230 1231### OH_AbilityRuntime_SetStartOptionsWindowWidth 1232 1233``` 1234AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowWidth(AbilityRuntime_StartOptions *startOptions, int32_t windowWidth); 1235``` 1236 1237**Description** 1238 1239Sets the width of the window when the ability is started, in px. 1240 1241**Parameters** 1242 1243| Name | Description | 1244| ----------- | ------------------------------------------------------------ | 1245| startOptions | Pointer to the StartOptions struct. | 1246| windowWidth | Window width, in px. | 1247 1248**Since**: 17 1249 1250**Returns** 1251 1252**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1253 1254**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1255 1256**Example** 1257```cpp 1258#include <AbilityKit/ability_runtime/start_options.h> 1259 1260void demo() 1261{ 1262 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1263 if (options == nullptr) { 1264 // Record error logs and other service processing. 1265 return; 1266 } 1267 1268 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowWidth(options, 500); 1269 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1270 // Record error logs and other service processing. 1271 } 1272 // Destroy options to prevent memory leakage. 1273 OH_AbilityRuntime_DestroyStartOptions(&options); 1274} 1275``` 1276 1277### OH_AbilityRuntime_GetStartOptionsWindowWidth 1278 1279``` 1280AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowWidth(AbilityRuntime_StartOptions *startOptions, int32_t &windowWidth); 1281``` 1282 1283**Description** 1284 1285Obtains the width of the window when the ability is started, in px. 1286 1287**Parameters** 1288 1289| Name | Description | 1290| ----------- | ------------------------------------------------------------ | 1291| startOptions | Pointer to the StartOptions struct. | 1292| windowWidth | Window width, in px. | 1293 1294**Since**: 17 1295 1296**Returns** 1297 1298**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1299 1300**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1301 1302**Example** 1303```cpp 1304#include <AbilityKit/ability_runtime/start_options.h> 1305 1306void demo() 1307{ 1308 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1309 if (options == nullptr) { 1310 // Record error logs and other service processing. 1311 return; 1312 } 1313 1314 int32_t windowWidth = 0; 1315 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowWidth(options, windowWidth); 1316 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1317 // Record error logs and other service processing. 1318 } 1319 // Destroy options to prevent memory leakage. 1320 OH_AbilityRuntime_DestroyStartOptions(&options); 1321} 1322``` 1323 1324### OH_AbilityRuntime_SetStartOptionsStartWindowIcon 1325 1326``` 1327AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsStartWindowIcon(AbilityRuntime_StartOptions *startOptions, OH_PixelmapNative *startWindowIcon) 1328``` 1329 1330**Description** 1331 1332Sets the startup icon of the window when the ability is started. The maximum size of an image used as the startup icon is 600 MB. 1333 1334**Parameters** 1335 1336| Name | Description | 1337| ----------- | ------------------------------------------------------------ | 1338| startOptions | Pointer to the StartOptions struct. | 1339| startWindowIcon | Startup icon. | 1340 1341**Since**: 17 1342 1343**Returns** 1344 1345**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1346 1347**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** or **OH_PixelmapNative** is null. 1348 1349**Example** 1350```cpp 1351#include <AbilityKit/ability_runtime/start_options.h> 1352 1353void demo() 1354{ 1355 uint8_t data[96]; 1356 size_t dataSize = 96; 1357 for (int i = 0; i < dataSize; i++) { 1358 data[i] = i + 1; 1359 } 1360 1361 // Create a parameter structure instance and set parameters. 1362 OH_Pixelmap_InitializationOptions *createOpts = nullptr; 1363 OH_PixelmapInitializationOptions_Create(&createOpts); 1364 OH_PixelmapInitializationOptions_SetWidth(createOpts, 6); 1365 OH_PixelmapInitializationOptions_SetHeight(createOpts, 4); 1366 OH_PixelmapInitializationOptions_SetPixelFormat(createOpts, PIXEL_FORMAT_RGBA_8888); 1367 OH_PixelmapInitializationOptions_SetAlphaType(createOpts, PIXELMAP_ALPHA_TYPE_UNKNOWN); 1368 1369 // Create a Pixelmap instance. 1370 OH_PixelmapNative *startWindowIcon = nullptr; 1371 Image_ErrorCode errCode = OH_PixelmapNative_CreatePixelmap(data, dataSize, createOpts, &startWindowIcon); 1372 if (errCode != IMAGE_SUCCESS) { 1373 // Record error logs and other service processing. 1374 1375 // Destroy createOpts to prevent memory leakage. 1376 OH_PixelmapInitializationOptions_Release(createOpts); 1377 return; 1378 } 1379 1380 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1381 if (options == nullptr) { 1382 // Record error logs and other service processing. 1383 1384 // Destroy createOpts to prevent memory leakage. 1385 OH_PixelmapInitializationOptions_Release(createOpts); 1386 1387 // Destroy startWindowIcon to prevent memory leakage. 1388 OH_PixelmapNative_Release(startWindowIcon); 1389 return; 1390 } 1391 1392 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsStartWindowIcon(options, startWindowIcon); 1393 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1394 // Record error logs and other service processing. 1395 } 1396 // Destroy createOpts to prevent memory leakage. 1397 OH_PixelmapInitializationOptions_Release(createOpts); 1398 1399 // Destroy startWindowIcon to prevent memory leakage. 1400 OH_PixelmapNative_Release(startWindowIcon); 1401 1402 // Destroy options to prevent memory leakage. 1403 OH_AbilityRuntime_DestroyStartOptions(&options); 1404} 1405``` 1406 1407### OH_AbilityRuntime_SetStartOptionsStartVisibility 1408 1409``` 1410AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsStartVisibility(AbilityRuntime_StartOptions *startOptions, AbilityRuntime_StartVisibility startVisibility); 1411``` 1412 1413**Description** 1414 1415Sets the visibility of the window and dock bar icons when the ability is started. 1416 1417**Parameters** 1418 1419| Name | Description | 1420| ----------- | ------------------------------------------------------------ | 1421| startOptions | Pointer to the StartOptions struct. | 1422| startVisibility | Visibility. For details about the available options, see [AbilityRuntime_StartVisibility](#abilityruntime_startvisibility). | 1423 1424**Since**: 17 1425 1426**Returns** 1427 1428**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1429 1430**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null or **startVisibility** is not an enumerated value of **AbilityRuntime_StartVisibility**. 1431 1432**Example** 1433```cpp 1434#include <AbilityKit/ability_runtime/start_options.h> 1435 1436void demo() 1437{ 1438 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1439 if (options == nullptr) { 1440 // Record error logs and other service processing. 1441 return; 1442 } 1443 1444 AbilityRuntime_StartVisibility visibility = AbilityRuntime_StartVisibility::ABILITY_RUNTIME_SHOW_UPON_START; 1445 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsStartVisibility(options, visibility); 1446 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1447 // Record error logs and other service processing. 1448 } 1449 // Destroy options to prevent memory leakage. 1450 OH_AbilityRuntime_DestroyStartOptions(&options); 1451} 1452``` 1453 1454### OH_AbilityRuntime_GetStartOptionsStartVisibility 1455 1456``` 1457AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsStartVisibility(AbilityRuntime_StartOptions *startOptions, AbilityRuntime_StartVisibility &startVisibility); 1458``` 1459 1460**Description** 1461 1462Obtains the visibility of the window and dock bar icons when the ability is started. 1463 1464**Parameters** 1465 1466| Name | Description | 1467| ----------- | ------------------------------------------------------------ | 1468| startOptions | Pointer to the StartOptions struct. | 1469| startVisibility | Visibility. For details about the available options, see [AbilityRuntime_StartVisibility](#abilityruntime_startvisibility). | 1470 1471**Since**: 17 1472 1473**Returns** 1474 1475**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1476 1477**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** or **startVisibility** is null. 1478 1479**Example** 1480```cpp 1481#include <AbilityKit/ability_runtime/start_options.h> 1482 1483void demo() 1484{ 1485 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1486 if (options == nullptr) { 1487 // Record error logs and other service processing. 1488 return; 1489 } 1490 1491 AbilityRuntime_StartVisibility visibility; 1492 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsStartVisibility(options, visibility); 1493 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1494 // Record error logs and other service processing. 1495 } 1496 // Destroy options to prevent memory leakage. 1497 OH_AbilityRuntime_DestroyStartOptions(&options); 1498} 1499``` 1500 1501### OH_AbilityRuntime_GetStartOptionsStartWindowIcon 1502 1503``` 1504AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsStartWindowIcon(AbilityRuntime_StartOptions *startOptions, 1505 OH_PixelmapNative **startWindowIcon) 1506``` 1507 1508**Description** 1509 1510Obtains the startup icon of the window when the ability is started. 1511 1512**Parameters** 1513 1514| Name | Description | 1515| ----------- | ------------------------------------------------------------ | 1516| startOptions | Pointer to the StartOptions struct. | 1517| startWindowIcon | Startup icon. | 1518 1519**Since**: 17 1520 1521**Returns** 1522 1523**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1524 1525**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null or **OH_PixelmapNative** is not nullptr. 1526 1527**Example** 1528```cpp 1529#include <AbilityKit/ability_runtime/start_options.h> 1530 1531void demo() 1532{ 1533 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1534 if (options == nullptr) { 1535 // Record error logs and other service processing. 1536 return; 1537 } 1538 1539 OH_PixelmapNative *startWindowIcon = nullptr; 1540 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsStartWindowIcon(options, &startWindowIcon); 1541 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1542 // Record error logs and other service processing. 1543 } 1544 1545 // Destroy startWindowIcon to prevent memory leakage. 1546 OH_PixelmapNative_Release(startWindowIcon); 1547 1548 // Destroy options to prevent memory leakage. 1549 OH_AbilityRuntime_DestroyStartOptions(&options); 1550} 1551``` 1552 1553### OH_AbilityRuntime_SetStartOptionsStartWindowBackgroundColor 1554 1555``` 1556AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsStartWindowBackgroundColor(AbilityRuntime_StartOptions *startOptions, const char *startWindowBackgroundColor) 1557``` 1558 1559**Description** 1560 1561Sets the background color of the window when the ability is started. Background color of the window. If this function is not called, the value of **startWindowBackground** configured under [abilities](../../quick-start/module-configuration-file.md#abilities) in the [module.json5](../../quick-start/module-configuration-file.md) file corresponding to the UIAbility is used by default. 1562 1563**Parameters** 1564 1565| Name | Description | 1566| ----------- | ------------------------------------------------------------ | 1567| startOptions | Pointer to the StartOptions struct. | 1568| startWindowBackgroundColor | Background color of the window. The value is in ARGB format, for example, **#E5FFFFFF**.| 1569 1570**Since**: 17 1571 1572**Returns** 1573 1574**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1575 1576**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** or **StartWindowBackgroundColor** is null. 1577 1578**Example** 1579```cpp 1580#include <AbilityKit/ability_runtime/start_options.h> 1581 1582void demo() 1583{ 1584 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1585 if (options == nullptr) { 1586 // Record error logs and other service processing. 1587 return; 1588 } 1589 1590 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsStartWindowBackgroundColor(options, "#00000000"); 1591 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1592 // Record error logs and other service processing. 1593 } 1594 1595 // Destroy options to prevent memory leakage. 1596 OH_AbilityRuntime_DestroyStartOptions(&options); 1597} 1598``` 1599 1600### OH_AbilityRuntime_GetStartOptionsStartWindowBackgroundColor 1601 1602``` 1603AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsStartWindowBackgroundColor(AbilityRuntime_StartOptions *startOptions, char **startWindowBackgroundColor, size_t &size) 1604``` 1605 1606**Description** 1607 1608Obtains the background color of the window when the ability is started. 1609 1610**Parameters** 1611 1612| Name | Description | 1613| ----------- | ------------------------------------------------------------ | 1614| startOptions | Pointer to the StartOptions struct. | 1615| startWindowBackgroundColor | Background color of the window. The value is in ARGB format, for example, **#E5FFFFFF**.| 1616| size | Size of the background color. | 1617 1618**Since**: 17 1619 1620**Returns** 1621 1622**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1623 1624**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null or **StartWindowBackgroundColor** is not mullptr. 1625 1626**ABILITY_RUNTIME_ERROR_CODE_INTERNAL**: An internal error that cannot be rectified, such as internal malloc error or string copy function error, occurs. 1627 1628**Example** 1629```cpp 1630#include <cstdlib> 1631 1632#include <AbilityKit/ability_runtime/start_options.h> 1633 1634void demo() 1635{ 1636 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1637 if (options == nullptr) { 1638 // Record error logs and other service processing. 1639 return; 1640 } 1641 1642 char *startWindowBackgroundColor = nullptr; 1643 size_t size = 0; 1644 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsStartWindowBackgroundColor(options, 1645 &startWindowBackgroundColor, size); 1646 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1647 // Record error logs and other service processing. 1648 } 1649 1650 if (startWindowBackgroundColor != nullptr) { 1651 // Destroy startWindowBackgroundColor to prevent memory leakage. 1652 free(startWindowBackgroundColor); 1653 startWindowBackgroundColor = nullptr; 1654 } 1655 1656 // Destroy options to prevent memory leakage. 1657 OH_AbilityRuntime_DestroyStartOptions(&options); 1658} 1659``` 1660 1661### OH_AbilityRuntime_SetStartOptionsSupportedWindowModes 1662 1663``` 1664AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsSupportedWindowModes(AbilityRuntime_StartOptions *startOptions, 1665 AbilityRuntime_SupportedWindowMode *supportedWindowModes, size_t size) 1666``` 1667 1668**Description** 1669 1670Sets the window modes supported by the ability when it is started. 1671 1672**Parameters** 1673 1674| Name | Description | 1675| ----------- | ------------------------------------------------------------ | 1676| startOptions | Pointer to the StartOptions struct. | 1677| supportedWindowModes | Window modes supported. For details about the available options, see [AbilityRuntime_SupportedWindowMode](#abilityruntime_supportedwindowmode). | 1678| size | Size of the window modes supported. | 1679 1680**Since**: 17 1681 1682**Returns** 1683 1684**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1685 1686**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** or **SupportedWindowModes** is null, or **Size** is **0**. 1687 1688**Example** 1689```cpp 1690#include <AbilityKit/ability_runtime/start_options.h> 1691 1692void demo() 1693{ 1694 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1695 if (options == nullptr) { 1696 // Record error logs and other service processing. 1697 return; 1698 } 1699 1700 size_t supportedWindowModesSize = 3; 1701 AbilityRuntime_SupportedWindowMode supportedWindowModes[3] = { 1702 ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FULL_SCREEN, 1703 ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_SPLIT, 1704 ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FLOATING, 1705 }; 1706 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsSupportedWindowModes(options, 1707 supportedWindowModes, supportedWindowModesSize); 1708 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1709 // Record error logs and other service processing. 1710 } 1711 1712 // Destroy options to prevent memory leakage. 1713 OH_AbilityRuntime_DestroyStartOptions(&options); 1714} 1715``` 1716 1717### OH_AbilityRuntime_GetStartOptionsSupportedWindowModes 1718 1719``` 1720AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsSupportedWindowModes(AbilityRuntime_StartOptions *startOptions, 1721 AbilityRuntime_SupportedWindowMode **supportedWindowModes, size_t &size) 1722``` 1723 1724**Description** 1725 1726Obtains the window modes supported by the ability when it is started. 1727 1728**Parameters** 1729 1730| Name | Description | 1731| ----------- | ------------------------------------------------------------ | 1732| startOptions | Pointer to the StartOptions struct. | 1733| supportedWindowModes | Window modes supported. For details about the available options, see [AbilityRuntime_SupportedWindowMode](#abilityruntime_supportedwindowmode). | 1734| size | Size of the window modes supported. | 1735 1736**Since**: 17 1737 1738**Returns** 1739 1740**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1741 1742**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null or **SupportWindowMode** is not nullptr. 1743 1744**ABILITY_RUNTIME_ERROR_CODE_INTERNAL**: An internal error that cannot be rectified, such as internal malloc error, occurs. 1745 1746**Example** 1747```cpp 1748#include <cstdlib> 1749 1750#include <AbilityKit/ability_runtime/start_options.h> 1751 1752void demo() 1753{ 1754 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1755 if (options == nullptr) { 1756 // Record error logs and other service processing. 1757 return; 1758 } 1759 1760 AbilityRuntime_SupportedWindowMode *supportedWindowModes = nullptr; 1761 size_t size = 0; 1762 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsSupportedWindowModes(options, 1763 &supportedWindowModes, size); 1764 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1765 // Record error logs and other service processing. 1766 } 1767 1768 if (supportedWindowModes != nullptr) { 1769 // Destroy supportedWindowModes to prevent memory leakage. 1770 free(supportedWindowModes); 1771 } 1772 1773 // Destroy options to prevent memory leakage. 1774 OH_AbilityRuntime_DestroyStartOptions(&options); 1775} 1776``` 1777 1778### OH_AbilityRuntime_SetStartOptionsMinWindowWidth 1779 1780``` 1781AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMinWindowWidth(AbilityRuntime_StartOptions *startOptions, 1782 int32_t minWindowWidth) 1783``` 1784 1785**Description** 1786 1787Sets the minimum window width for starting the ability, in vp. 1788 1789**Parameters** 1790 1791| Name | Description | 1792| ----------- | ------------------------------------------------------------ | 1793| startOptions | Pointer to the StartOptions struct. | 1794| minWindowWidth | Minimum window width, in vp. | 1795 1796**Since**: 17 1797 1798**Returns** 1799 1800**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1801 1802**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1803 1804**Example** 1805```cpp 1806#include <AbilityKit/ability_runtime/start_options.h> 1807 1808void demo() 1809{ 1810 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1811 if (options == nullptr) { 1812 // Record error logs and other service processing. 1813 return; 1814 } 1815 1816 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsMinWindowWidth(options, 100); 1817 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1818 // Record error logs and other service processing. 1819 } 1820 1821 // Destroy options to prevent memory leakage. 1822 OH_AbilityRuntime_DestroyStartOptions(&options); 1823} 1824``` 1825 1826### OH_AbilityRuntime_GetStartOptionsMinWindowWidth 1827 1828``` 1829AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMinWindowWidth(AbilityRuntime_StartOptions *startOptions, 1830 int32_t &minWindowWidth) 1831``` 1832 1833**Description** 1834 1835Obtains the minimum window width for starting the ability, in vp. 1836 1837**Parameters** 1838 1839| Name | Description | 1840| ----------- | ------------------------------------------------------------ | 1841| startOptions | Pointer to the StartOptions struct. | 1842| minWindowWidth | Minimum window width, in vp. | 1843 1844**Since**: 17 1845 1846**Returns** 1847 1848**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1849 1850**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1851 1852**Example** 1853```cpp 1854#include <AbilityKit/ability_runtime/start_options.h> 1855 1856void demo() 1857{ 1858 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1859 if (options == nullptr) { 1860 // Record error logs and other service processing. 1861 return; 1862 } 1863 1864 int32_t minWindowWidth = 0; 1865 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsMinWindowWidth(options, minWindowWidth); 1866 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1867 // Record error logs and other service processing. 1868 } 1869 1870 // Destroy options to prevent memory leakage. 1871 OH_AbilityRuntime_DestroyStartOptions(&options); 1872} 1873``` 1874 1875### OH_AbilityRuntime_SetStartOptionsMaxWindowWidth 1876 1877``` 1878AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMaxWindowWidth(AbilityRuntime_StartOptions *startOptions, 1879 int32_t maxWindowWidth) 1880``` 1881 1882**Description** 1883 1884Sets the maximum window width for starting the ability, in vp. 1885 1886**Parameters** 1887 1888| Name | Description | 1889| ----------- | ------------------------------------------------------------ | 1890| startOptions | Pointer to the StartOptions struct. | 1891| maxWindowWidth | Maximum window width, in vp. | 1892 1893**Since**: 17 1894 1895**Returns** 1896 1897**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1898 1899**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1900 1901**Example** 1902```cpp 1903#include <AbilityKit/ability_runtime/start_options.h> 1904 1905void demo() 1906{ 1907 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1908 if (options == nullptr) { 1909 // Record error logs and other service processing. 1910 return; 1911 } 1912 1913 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsMaxWindowWidth(options, 100); 1914 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1915 // Record error logs and other service processing. 1916 } 1917 1918 // Destroy options to prevent memory leakage. 1919 OH_AbilityRuntime_DestroyStartOptions(&options); 1920} 1921``` 1922 1923### OH_AbilityRuntime_GetStartOptionsMaxWindowWidth 1924 1925``` 1926AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMaxWindowWidth(AbilityRuntime_StartOptions *startOptions, 1927 int32_t &maxWindowWidth) 1928``` 1929 1930**Description** 1931 1932Obtains the maximum window width for starting the ability, in vp. 1933 1934**Parameters** 1935 1936| Name | Description | 1937| ----------- | ------------------------------------------------------------ | 1938| startOptions | Pointer to the StartOptions struct. | 1939| maxWindowWidth | Maximum window width, in vp. | 1940 1941**Since**: 17 1942 1943**Returns** 1944 1945**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 1946 1947**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1948 1949**Example** 1950```cpp 1951#include <AbilityKit/ability_runtime/start_options.h> 1952 1953void demo() 1954{ 1955 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1956 if (options == nullptr) { 1957 // Record error logs and other service processing. 1958 return; 1959 } 1960 1961 int32_t maxWindowWidth = 0; 1962 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsMaxWindowWidth(options, maxWindowWidth); 1963 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1964 // Record error logs and other service processing. 1965 } 1966 1967 // Destroy options to prevent memory leakage. 1968 OH_AbilityRuntime_DestroyStartOptions(&options); 1969} 1970``` 1971 1972### OH_AbilityRuntime_SetStartOptionsMinWindowHeight 1973 1974``` 1975AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMinWindowHeight(AbilityRuntime_StartOptions *startOptions, 1976 int32_t minWindowHeight) 1977``` 1978 1979**Description** 1980 1981Sets the minimum window height for starting the ability, in vp. 1982 1983**Parameters** 1984 1985| Name | Description | 1986| ----------- | ------------------------------------------------------------ | 1987| startOptions | Pointer to the StartOptions struct. | 1988| minWindowHeight | Minimum window height, in vp. | 1989 1990**Since**: 17 1991 1992**Returns** 1993 1994**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 1995 1996**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 1997 1998**Example** 1999```cpp 2000#include <AbilityKit/ability_runtime/start_options.h> 2001 2002void demo() 2003{ 2004 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 2005 if (options == nullptr) { 2006 // Record error logs and other service processing. 2007 return; 2008 } 2009 2010 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsMinWindowHeight(options, 100); 2011 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 2012 // Record error logs and other service processing. 2013 } 2014 2015 // Destroy options to prevent memory leakage. 2016 OH_AbilityRuntime_DestroyStartOptions(&options); 2017} 2018``` 2019 2020### OH_AbilityRuntime_GetStartOptionsMinWindowHeight 2021 2022``` 2023AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMinWindowHeight(AbilityRuntime_StartOptions *startOptions, 2024 int32_t &minWindowHeight) 2025``` 2026 2027**Description** 2028 2029Obtains the minimum window height for starting the ability, in vp. 2030 2031**Parameters** 2032 2033| Name | Description | 2034| ----------- | ------------------------------------------------------------ | 2035| startOptions | Pointer to the StartOptions struct. | 2036| minWindowHeight | Minimum window height, in vp. | 2037 2038**Since**: 17 2039 2040**Returns** 2041 2042**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 2043 2044**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 2045 2046**Example** 2047```cpp 2048#include <AbilityKit/ability_runtime/start_options.h> 2049 2050void demo() 2051{ 2052 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 2053 if (options == nullptr) { 2054 // Record error logs and other service processing. 2055 return; 2056 } 2057 2058 int32_t minWindowHeight = 0; 2059 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsMinWindowHeight(options, minWindowHeight); 2060 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 2061 // Record error logs and other service processing. 2062 } 2063 2064 // Destroy options to prevent memory leakage. 2065 OH_AbilityRuntime_DestroyStartOptions(&options); 2066} 2067``` 2068 2069### OH_AbilityRuntime_SetStartOptionsMaxWindowHeight 2070 2071``` 2072AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMaxWindowHeight(AbilityRuntime_StartOptions *startOptions, 2073 int32_t maxWindowHeight) 2074``` 2075 2076**Description** 2077 2078Sets the maximum window height for starting the ability, in vp. 2079 2080**Parameters** 2081 2082| Name | Description | 2083| ----------- | ------------------------------------------------------------ | 2084| startOptions | Pointer to the StartOptions struct. | 2085| maxWindowHeight | Maximum window height, in vp. | 2086 2087**Since**: 17 2088 2089**Returns** 2090 2091**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The setting is successful. 2092 2093**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 2094 2095**Example** 2096```cpp 2097#include <AbilityKit/ability_runtime/start_options.h> 2098 2099void demo() 2100{ 2101 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 2102 if (options == nullptr) { 2103 // Record error logs and other service processing. 2104 return; 2105 } 2106 2107 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsMaxWindowHeight(options, 100); 2108 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 2109 // Record error logs and other service processing. 2110 } 2111 2112 // Destroy options to prevent memory leakage. 2113 OH_AbilityRuntime_DestroyStartOptions(&options); 2114} 2115``` 2116 2117### OH_AbilityRuntime_GetStartOptionsMaxWindowHeight 2118 2119``` 2120AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMaxWindowHeight(AbilityRuntime_StartOptions *startOptions, 2121 int32_t &maxWindowHeight) 2122``` 2123 2124**Description** 2125 2126Obtains the maximum window height for starting the ability, in vp. 2127 2128**Parameters** 2129 2130| Name | Description | 2131| ----------- | ------------------------------------------------------------ | 2132| startOptions | Pointer to the StartOptions struct. | 2133| maxWindowHeight | Maximum window height, in vp. | 2134 2135**Since**: 17 2136 2137**Returns** 2138 2139**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The information is obtained successfully. 2140 2141**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: **startOptions** is null. 2142 2143**Example** 2144```cpp 2145#include <AbilityKit/ability_runtime/start_options.h> 2146 2147void demo() 2148{ 2149 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 2150 if (options == nullptr) { 2151 // Record error logs and other service processing. 2152 return; 2153 } 2154 2155 int32_t maxWindowHeight = 0; 2156 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsMaxWindowHeight(options, maxWindowHeight); 2157 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 2158 // Record error logs and other service processing. 2159 } 2160 2161 // Destroy options to prevent memory leakage. 2162 OH_AbilityRuntime_DestroyStartOptions(&options); 2163} 2164``` 2165 2166### OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions 2167 2168``` 2169AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(AbilityBase_Want *want, AbilityRuntime_StartOptions *options) 2170``` 2171 2172**Description** 2173 2174Starts the UIAbility of the current application. 2175 2176> **NOTE** 2177> 2178> This function is valid only for 2-in-1 devices. 2179 2180**Required permissions**: ohos.permission.NDK_START_SELF_UI_ABILITY 2181 2182**Since**: 17 2183 2184**Parameters** 2185 2186| Name | Description | 2187| ----------- | ------------------------------------------------------------ | 2188| want | Pointer to the Want information required for starting the UIAbility. | 2189| options | Pointer to the StartOptions required for starting the UIAbility.<br>**NOTE**<br>If the value of [startVisibility](#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** error code is returned.| 2190 2191**Returns** 2192 2193**ABILITY_RUNTIME_ERROR_CODE_NO_ERROR**: The operation is successful. 2194 2195**ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED**: Permission verification fails. 2196 2197**ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID**: The Want or StartOptions information is null, or if the bundleName or abilityName in the Want information is null. 2198 2199**ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED**: The device type is not supported. 2200 2201**ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY**: The specified ability name does not exist. 2202 2203**ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE**: The ability type is incorrect. 2204 2205**ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED**: The crowdtesting application expires. 2206 2207**ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE**: The ability is started or stopped in Wukong mode. 2208 2209**ABILITY_RUNTIME_ERROR_CODE_CONTROLLED**: The application is under control. 2210 2211**ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED**: The application is under control by EDM. 2212 2213**ABILITY_RUNTIME_ERROR_CODE_CROSS_APP**: It is forbidden to start other applications. 2214 2215**ABILITY_RUNTIME_ERROR_CODE_INTERNAL**: An internal error occurs. 2216 2217**ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY**: The application is not in the foreground. 2218 2219**ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED**: It is forbidden to set the application visibility. 2220 2221**ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED**: The application does not support clone and multi-instance mode. 2222 2223**ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY**: The instance key is invalid. 2224 2225**ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED**: The number of instances has reached the upper limit. 2226 2227**ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED**: The application does not support multi-instance mode. 2228 2229**ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED**: APP_INSTANCE_KEY cannot be assigned a value. 2230 2231**Example** 2232```cpp 2233#include <AbilityKit/ability_base/want.h> 2234#include <AbilityKit/ability_runtime/application_context.h> 2235 2236void demo() 2237{ 2238 AbilityBase_Element element; 2239 element.abilityName = const_cast<char*>("EntryAbility"); 2240 element.bundleName = const_cast<char*>("com.example.myapplication"); 2241 element.moduleName = const_cast<char*>("entry"); 2242 AbilityBase_Want* want = OH_AbilityBase_CreateWant(element); 2243 if (want == nullptr) { 2244 // Record error logs and other service processing. 2245 return; 2246 } 2247 2248 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 2249 if (options == nullptr) { 2250 // Record error logs and other service processing. 2251 2252 // Destroy the Want to prevent memory leakage. 2253 OH_AbilityBase_DestroyWant(want); 2254 return; 2255 } 2256 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(want, options); 2257 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 2258 // Record error logs and other service processing. 2259 } 2260 // Destroy the Want to prevent memory leakage. 2261 OH_AbilityBase_DestroyWant(want); 2262 2263 // Destroy options to prevent memory leakage. 2264 OH_AbilityRuntime_DestroyStartOptions(&options); 2265} 2266``` 2267