1# AbilityRuntime 2 3 4## 概述 5 6提供元能力基础框架的相关能力。 7 8**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 9 10**起始版本**：13 11 12 13## 汇总 14 15 16### 文件 17 18| 名称 | 描述 | 19| -------- | -------- | 20| [ability_runtime_common.h](ability__runtime__common_8h.md) | 声明元能力子系统的相关错误码。<br/>**引用文件**：<AbilityKit/ability_runtime/ability_runtime_common.h><br/>**库**：libability_runtime.so | 21| [application_context.h](application__context_8h.md) | 声明应用级别的上下文能力。<br/>**引用文件**：<AbilityKit/ability_runtime/application_context.h><br/>**库**：libability_runtime.so | 22| [context_constant.h](context__constant_8h.md) | 声明上下文相关的枚举。<br/>**引用文件**：<AbilityKit/ability_runtime/context_constant.h><br/>**库**：libability_runtime.so | 23| [start_options.h](start__options_8h.md) | 声明StartOptions结构体以及结构体相关函数。<br/>**引用文件**：<AbilityKit/ability_runtime/start_options.h><br/>**库**：libability_runtime.so | 24 25### 枚举 26 27| 名称 | 描述 | 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/>} | 定义元能力模块错误码。 | 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/>} | 定义数据加密等级。 | 31| [AbilityRuntime_StartVisibility](#abilityruntime_startvisibility) {<br/> ABILITY_RUNTIME_HIDE_UPON_START = 0,<br/> ABILITY_RUNTIME_SHOW_UPON_START = 1<br/>} | 定义启动Ability时的窗口和dock栏图标显示模式。 | 32| [AbilityRuntime_WindowMode](#abilityruntime_supportedwindowmode) {<br/> ABILITY_RUNTIME_WINDOW_MODE_UNDEFINED = 0,</br> ABILITY_RUNTIME_WINDOW_MODE_FULL_SCREEN = 1<br/>} | 定义启动应用时支持的窗口模式。 | 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/>} | 定义启动应用时支持的窗口模式。 | 34 35### 函数 36 37| 名称 | 描述 | 38| -------- | -------- | 39| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetCacheDir](#oh_abilityruntime_applicationcontextgetcachedir)(char* buffer, int32_t bufferSize, int32_t* writeLength) | 获取应用级别的缓存目录。 | 40| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetAreaMode](#oh_abilityruntime_applicationcontextgetareamode)([AbilityRuntime_AreaMode](#abilityruntime_areamode)* areaMode) | 获取应用级别的数据加密等级。 | 41| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetBundleName](#oh_abilityruntime_applicationcontextgetbundlename)(char* buffer, int32_t bufferSize, int32_t* writeLength) | 获取应用包名。 | 42| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetTempDir](#oh_abilityruntime_applicationcontextgettempdir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | 获取应用级别的临时文件目录。 | 43| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetFilesDir](#oh_abilityruntime_applicationcontextgetfilesdir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | 获取应用级别的通用文件目录。 | 44| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetDatabaseDir](#oh_abilityruntime_applicationcontextgetdatabasedir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | 获取应用级别的数据库文件目录。 | 45| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetPreferencesDir](#oh_abilityruntime_applicationcontextgetpreferencesdir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | 获取应用级别的首选项文件目录。 | 46| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetBundleCodeDir](#oh_abilityruntime_applicationcontextgetbundlecodedir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | 获取应用级别的安装文件目录。 | 47| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir](#oh_abilityruntime_applicationcontextgetdistributedfilesdir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | 获取应用级别的分布式文件目录。 | 48| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_ApplicationContextGetCloudFileDir](#oh_abilityruntime_applicationcontextgetcloudfiledir)(char* buffer, const int32_t bufferSize, int32_t* writeLength) | 获取应用级别的云文件目录。 | 49| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_StartSelfUIAbility](#oh_abilityruntime_startselfuiability)([AbilityBase_Want](_ability_base.md#abilitybase_want) *want) | 启动当前应用的UIAbility。 | 50| [AbilityRuntime_StartOptions*](#abilityruntime_startoptions) [OH_AbilityRuntime_CreateStartOptions](#oh_abilityruntime_createstartoptions)(void) | 创建启动当前应用的UIAbility所需要的StartOptions结构体。 | 51| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_DestroyStartOptions](#oh_abilityruntime_destroystartoptions)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) **startOptions) | 销毁StartOptions结构体。 | 52| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowMode](#oh_abilityruntime_setstartoptionswindowmode)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_WindowMode](#abilityruntime_windowmode) windowMode) | 设置启动Ability时的窗口模式。 | 53| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowMode](#oh_abilityruntime_getstartoptionswindowmode)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_WindowMode](#abilityruntime_windowmode) &windowMode) | 获取启动Ability时的窗口模式。 | 54| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsDisplayId](#oh_abilityruntime_setstartoptionsdisplayid)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t displayId) | 设置启动Ability时窗口所在的屏幕ID。 | 55| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsDisplayId](#oh_abilityruntime_getstartoptionsdisplayid)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &displayId) | 获取启动Ability时窗口所在的屏幕ID。 | 56| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWithAnimation](#oh_abilityruntime_setstartoptionswithanimation)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, bool withAnimation) | 设置启动Ability时是否具有动画效果。 | 57| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWithAnimation](#oh_abilityruntime_getstartoptionswithanimation)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, bool &withAnimation) | 获取启动Ability时是否具有动画效果。 | 58| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowLeft](#oh_abilityruntime_setstartoptionswindowleft)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t windowLeft) | 设置启动Ability时的窗口左侧位置，单位为px。 | 59| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowLeft](#oh_abilityruntime_getstartoptionswindowleft)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &windowLeft) | 获取启动Ability时的窗口左侧位置，单位为px。 | 60| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowTop](#oh_abilityruntime_setstartoptionswindowtop)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t windowTop) | 设置启动Ability时的窗口顶部位置，单位为px。 | 61| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowTop](#oh_abilityruntime_getstartoptionswindowtop)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &windowTop) | 获取启动Ability时的窗口顶部位置，单位为px。 | 62| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowHeight](#oh_abilityruntime_setstartoptionswindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t windowHeight) | 设置启动Ability时的窗口高度，单位为px。 | 63| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowHeight](#oh_abilityruntime_getstartoptionswindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &windowHeight) | 获取启动Ability时的窗口高度，单位为px。 | 64| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsWindowWidth](#oh_abilityruntime_setstartoptionswindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t windowWidth) | 设置启动Ability时的窗口宽度，单位为px。 | 65| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsWindowWidth](#oh_abilityruntime_getstartoptionswindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &windowWidth) | 获取启动Ability时的窗口宽度，单位为px。 | 66| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsStartVisibility](#oh_abilityruntime_setstartoptionsstartvisibility)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_StartVisibility](#abilityruntime_startvisibility) startVisibility) | 设置启动Ability时窗口和dock栏图标的显示模式。 | 67| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsStartVisibility](#oh_abilityruntime_getstartoptionsstartvisibility)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_StartVisibility](#abilityruntime_startvisibility) &startVisibility) | 获取启动Ability时窗口和dock栏图标的显示模式。| 68| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsStartWindowIcon](#oh_abilityruntime_setstartoptionsstartwindowicon)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [OH_PixelmapNative](../apis-image-kit/_image___native_module.md#oh_pixelmapnative) *startWindowIcon) | 设置启动Ability时的窗口启动图标。 | 69| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsStartWindowIcon](#oh_abilityruntime_getstartoptionsstartwindowicon)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [OH_PixelmapNative](../apis-image-kit/_image___native_module.md#oh_pixelmapnative) **startWindowIcon) | 获取启动Ability时的窗口启动图标。 | 70| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsStartWindowBackgroundColor](#oh_abilityruntime_setstartoptionsstartwindowbackgroundcolor)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, const char *startWindowBackgroundColor) | 设置启动Ability时的窗口背景颜色。 | 71| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsStartWindowBackgroundColor](#oh_abilityruntime_getstartoptionsstartwindowbackgroundcolor)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, char **startWindowBackgroundColor, size_t &size) | 获取启动Ability时的窗口背景颜色。 | 72| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsSupportedWindowModes](#oh_abilityruntime_setstartoptionssupportedwindowmodes)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_SupportedWindowMode](#abilityruntime_supportedwindowmode) *supportedWindowModes, size_t size) | 设置启动Ability时组件所支持的窗口模式。 | 73| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsSupportedWindowModes](#oh_abilityruntime_getstartoptionssupportedwindowmodes)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, [AbilityRuntime_SupportedWindowMode](#abilityruntime_supportedwindowmode) **supportedWindowModes, size_t &size) | 获取启动Ability时组件所支持的窗口模式。 | 74| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsMinWindowWidth](#oh_abilityruntime_setstartoptionsminwindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t minWindowWidth) | 设置启动Ability时的最小窗口宽度，单位为vp。 | 75| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsMinWindowWidth](#oh_abilityruntime_getstartoptionsminwindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &minWindowWidth) | 获取启动Ability时的最小窗口宽度，单位为vp。 | 76| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsMaxWindowWidth](#oh_abilityruntime_setstartoptionsmaxwindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t maxWindowWidth) | 设置启动Ability时的最大窗口宽度，单位为vp。 | 77| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsMaxWindowWidth](#oh_abilityruntime_getstartoptionsmaxwindowwidth)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &maxWindowWidth) | 获取启动Ability时的最大窗口宽度，单位为vp。 | 78| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsMinWindowHeight](#oh_abilityruntime_setstartoptionsminwindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t minWindowHeight) | 设置启动Ability时的最小窗口高度，单位为vp。 | 79| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsMinWindowHeight](#oh_abilityruntime_getstartoptionsminwindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &minWindowHeight) | 获取启动Ability时的最小窗口高度，单位为vp。 | 80| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_SetStartOptionsMaxWindowHeight](#oh_abilityruntime_setstartoptionsmaxwindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t maxWindowHeig) | 设置启动Ability时的最大窗口高度，单位为vp。 | 81| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_GetStartOptionsMaxWindowHeight](#oh_abilityruntime_getstartoptionsmaxwindowheight)([AbilityRuntime_StartOptions](#abilityruntime_startoptions) *startOptions, int32_t &maxWindowHeight) | 获取启动Ability时的最大窗口高度，单位为vp。 | 82| [AbilityRuntime_ErrorCode](#abilityruntime_errorcode) [OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions](#oh_abilityruntime_startselfuiabilitywithstartoptions)([AbilityBase_Want](_ability_base.md#abilitybase_want) *want, [AbilityRuntime_StartOptions](#abilityruntime_startoptions) *options) | 启动当前应用的UIAbility。 | 83 84## 结构体 85 86### AbilityRuntime_StartOptions 87 88``` 89AbilityRuntime_StartOptions 90``` 91 92**描述** 93 94StartOptions数据结构。 95 96**起始版本：** 17 97 98## 枚举类型说明 99 100### AbilityRuntime_ErrorCode 101 102``` 103enum AbilityRuntime_ErrorCode 104``` 105 106**描述** 107 108定义元能力模块错误码。 109 110**起始版本**：13 111 112| 枚举值 | 描述 | 113| --------------------------------------------- | -------------- | 114| ABILITY_RUNTIME_ERROR_CODE_NO_ERROR | 操作成功。 | 115| ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID | 无效参数。 | 116| ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST | 上下文不存在。 | 117| ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED | 权限校验失败。<br/>**起始版本：** 15 | 118| ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED | 设备类型不支持。<br/>**起始版本：** 15 | 119| ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY | 指定的Ability名称不存在。<br/>**起始版本：** 15 | 120| ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE | 接口调用Ability类型错误。<br/>**起始版本：** 15 | 121| ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED | 众测应用到期。<br/>**起始版本：** 15 | 122| ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE | wukong模式，不允许启动/停止ability。<br/>**起始版本：** 15 | 123| ABILITY_RUNTIME_ERROR_CODE_CONTROLLED | 应用被管控。<br/>**起始版本：** 15 | 124| ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED | 应用被EDM管控。<br/>**起始版本：** 15 | 125| ABILITY_RUNTIME_ERROR_CODE_CROSS_APP | 限制API 11以上版本三方应用跳转。<br/>**起始版本：** 15 | 126| ABILITY_RUNTIME_ERROR_CODE_INTERNAL | 内部错误。<br/>**起始版本：** 15 | 127| ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY | 非顶层应用。<br/>**起始版本：** 15 | 128| ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED | 不支持设置应用启动时窗口可见性。<br/>**起始版本：** 17 | 129| ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED | 应用既不支持分身也不支持多实例。<br/>**起始版本：** 17 | 130| ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY | 传入的instanceKey无效。<br/>**起始版本：** 17 | 131| ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED | 多实例数量已达到上限。<br/>**起始版本：** 17 | 132| ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED | 应用不支持多实例。<br/>**起始版本：** 17 | 133| ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED | 不支持设置instanceKey。<br/>**起始版本：** 17 | 134 135### AbilityRuntime_AreaMode 136 137``` 138enum AbilityRuntime_AreaMode 139``` 140 141**描述** 142 143定义数据加密等级。 144 145**起始版本**：13 146 147| 枚举值 | 描述 | 148| ----------------------------- | ------------------------------------------------------------ | 149| ABILITY_RUNTIME_AREA_MODE_EL1 | 对于私有文件，如闹铃、壁纸等，应用可以将这些文件放到设备级加密分区（EL1）中，以保证在用户输入密码前就可以被访问。 | 150| ABILITY_RUNTIME_AREA_MODE_EL2 | 对于更敏感的文件，如个人隐私信息等，应用可以将这些文件放到更高级别的加密分区（EL2）中，以保证更高的安全性。 | 151| ABILITY_RUNTIME_AREA_MODE_EL3 | 对于应用中的记录步数、文件下载、音乐播放，需要在锁屏时读写和创建新文件，放在（EL3）的加密分区比较合适。 | 152| ABILITY_RUNTIME_AREA_MODE_EL4 | 对于用户安全信息相关的文件，锁屏时不需要读写文件、也不能创建文件，放在（EL4）的加密分区更合适。 | 153| ABILITY_RUNTIME_AREA_MODE_EL5 | 对于用户隐私敏感数据文件，锁屏后默认不可读写，如果锁屏后需要读写文件，则锁屏前可以调用[Access](js-apis-screenLockFileManager.md#screenlockfilemanageracquireaccess)接口申请继续读写文件，或者锁屏后也需要创建新文件且可读写，放在（EL5）的应用级加密分区更合适。 | 154 155### AbilityRuntime_StartVisibility 156 157``` 158enum AbilityRuntime_StartVisibility 159``` 160 161**描述** 162 163启动Ability时的窗口和dock栏图标的显示模式。 164 165**起始版本：** 17 166 167| 枚举值 | 描述 | 168| ----------------------------- | ------------------------------------------------------------ | 169| ABILITY_RUNTIME_HIDE_UPON_START | 隐藏窗口及dock栏图标。仅在2in1设备上生效。 | 170| ABILITY_RUNTIME_SHOW_UPON_START | 显示窗口及dock栏图标。仅在2in1设备上生效。 | 171 172### AbilityRuntime_WindowMode 173 174``` 175enum AbilityRuntime_WindowMode 176``` 177 178**描述** 179 180启动Ability时的窗口模式。 181 182**起始版本：** 17 183 184| 枚举值 | 描述 | 185| ----------------------------- | ------------------------------------------------------------ | 186| ABILITY_RUNTIME_WINDOW_MODE_UNDEFINED | 未定义窗口模式。 | 187| ABILITY_RUNTIME_WINDOW_MODE_FULL_SCREEN | 全屏模式。仅在2in1设备上生效。 | 188 189### AbilityRuntime_SupportedWindowMode 190 191``` 192enum AbilityRuntime_SupportedWindowMode 193``` 194 195**描述** 196 197在应用内启动UIAbility时，指定窗口是否显示最大化/窗口化/分屏按键。如果未配置该字段，则默认采用该UIAbility对应的[module.json5配置文件](../../quick-start/module-configuration-file.md)中[abilities标签](../../quick-start/module-configuration-file.md#abilities标签)的supportWindowMode字段取值。 198 199**起始版本：** 17 200 201| 枚举值 | 描述 | 202| ----------------------------- | ------------------------------------------------------------ | 203| ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FULL_SCREEN | 窗口支持全屏显示。 | 204| ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_SPLIT | 窗口支持分屏显示。通常需要配合ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FULL_SCREEN或ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FLOATING一起使用，不建议只配置ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_SPLIT。当仅配置ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_SPLIT时，2in1设备上的窗口默认为悬浮窗模式，支持进入分屏模式。 | 205| ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FLOATING | 支持窗口化显示。 | 206 207## 函数说明 208 209 210### OH_AbilityRuntime_ApplicationContextGetCacheDir 211 212``` 213AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCacheDir(char* buffer, int32_t bufferSize, int32_t* writeLength) 214``` 215**描述** 216 217获取应用级别的缓存目录。 218 219**起始版本**：13 220 221**参数：** 222 223| 名称 | 描述 | 224| -------- | -------- | 225| buffer | 缓冲区，缓存目录字符串写入该区域。 | 226| bufferSize | 缓冲区大小。 | 227| writeLength | 在返回ABILITY_RUNTIME_ERROR_CODE_NO_ERROR时，表示实际写入到缓冲区的字符串长度。 | 228 229**返回：** 230 231ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 232 233ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参buffer或者writeLength为空，或者缓冲区大小小于需要写入的大小。 234 235ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 236 237### OH_AbilityRuntime_ApplicationContextGetAreaMode 238 239``` 240AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetAreaMode(AbilityRuntime_AreaMode* areaMode) 241``` 242 243**描述** 244 245获取应用级别的数据加密等级。 246 247**起始版本**：13 248 249**参数：** 250 251| 名称 | 描述 | 252| -------- | ------------------------ | 253| areaMode | 用于接受加密等级的指针。 | 254 255**返回：** 256 257ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 258 259ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参areaMode为空。 260 261ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 262 263### OH_AbilityRuntime_ApplicationContextGetBundleName 264 265``` 266AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleName(char* buffer, int32_t bufferSize, int32_t* writeLength) 267``` 268 269**描述** 270 271获取应用包名。 272 273**起始版本**：13 274 275**参数：** 276 277| 名称 | 描述 | 278| ----------- | ------------------------------------------------------------ | 279| buffer | 缓冲区，应用包名字符串写入该区域。 | 280| bufferSize | 缓冲区大小。 | 281| writeLength | 在返回ABILITY_RUNTIME_ERROR_CODE_NO_ERROR时，表示实际写入到缓冲区的字符串长度。 | 282 283**返回：** 284 285ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 286 287ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参buffer或者writeLength为空，或者缓冲区大小小于需要写入的大小。 288 289ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 290 291### OH_AbilityRuntime_ApplicationContextGetTempDir 292 293``` 294AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetTempDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 295``` 296 297**描述** 298 299获取应用级别的临时文件目录。 300 301**起始版本：** 16 302 303**参数：** 304 305| 名称 | 描述 | 306| ----------- | ------------------------------------------------------------ | 307| buffer | 缓冲区，缓存目录字符串写入该区域。 | 308| bufferSize | 缓冲区大小。 | 309| writeLength | 在返回ABILITY_RUNTIME_ERROR_CODE_NO_ERROR时，表示实际写入到缓冲区的字符串长度。 | 310 311**返回：** 312 313ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 314 315ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参buffer或者writeLength为空，或者缓冲区大小小于需要写入的大小。 316 317ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 318 319### OH_AbilityRuntime_ApplicationContextGetFilesDir 320 321``` 322AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 323``` 324 325**描述** 326 327获取应用级别的通用文件目录。 328 329**起始版本：** 16 330 331**参数：** 332 333| 名称 | 描述 | 334| ----------- | ------------------------------------------------------------ | 335| buffer | 缓冲区，缓存目录字符串写入该区域。 | 336| bufferSize | 缓冲区大小。 | 337| writeLength | 在返回ABILITY_RUNTIME_ERROR_CODE_NO_ERROR时，表示实际写入到缓冲区的字符串长度。 | 338 339**返回：** 340 341ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 342 343ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参buffer或者writeLength为空，或者缓冲区大小小于需要写入的大小。 344 345ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 346 347### OH_AbilityRuntime_ApplicationContextGetDatabaseDir 348 349``` 350AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDatabaseDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 351``` 352 353**描述** 354 355获取应用级别的数据库文件目录。 356 357**起始版本：** 16 358 359**参数：** 360 361| 名称 | 描述 | 362| ----------- | ------------------------------------------------------------ | 363| buffer | 缓冲区，缓存目录字符串写入该区域。 | 364| bufferSize | 缓冲区大小。 | 365| writeLength | 在返回ABILITY_RUNTIME_ERROR_CODE_NO_ERROR时，表示实际写入到缓冲区的字符串长度。 | 366 367**返回：** 368 369ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 370 371ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参buffer或者writeLength为空，或者缓冲区大小小于需要写入的大小。 372 373ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 374 375### OH_AbilityRuntime_ApplicationContextGetPreferencesDir 376 377``` 378AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetPreferencesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 379``` 380 381**描述** 382 383获取应用级别的首选项文件目录。 384 385**起始版本：** 16 386 387**参数：** 388 389| 名称 | 描述 | 390| ----------- | ------------------------------------------------------------ | 391| buffer | 缓冲区，缓存目录字符串写入该区域。 | 392| bufferSize | 缓冲区大小。 | 393| writeLength | 在返回ABILITY_RUNTIME_ERROR_CODE_NO_ERROR时，表示实际写入到缓冲区的字符串长度。 | 394 395**返回：** 396 397ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 398 399ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参buffer或者writeLength为空，或者缓冲区大小小于需要写入的大小。 400 401ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 402 403### OH_AbilityRuntime_ApplicationContextGetBundleCodeDir 404 405``` 406AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleCodeDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 407``` 408 409**描述** 410 411获取应用级别的安装文件目录。 412 413**起始版本：** 16 414 415**参数：** 416 417| 名称 | 描述 | 418| ----------- | ------------------------------------------------------------ | 419| buffer | 缓冲区，缓存目录字符串写入该区域。 | 420| bufferSize | 缓冲区大小。 | 421| writeLength | 在返回ABILITY_RUNTIME_ERROR_CODE_NO_ERROR时，表示实际写入到缓冲区的字符串长度。 | 422 423**返回：** 424 425ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 426 427ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参buffer或者writeLength为空，或者缓冲区大小小于需要写入的大小。 428 429ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 430 431### OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir 432 433``` 434AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetDistributedFilesDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 435``` 436 437**描述** 438 439获取应用级别的分布式文件目录。 440 441**起始版本：** 16 442 443**参数：** 444 445| 名称 | 描述 | 446| ----------- | ------------------------------------------------------------ | 447| buffer | 缓冲区，缓存目录字符串写入该区域。 | 448| bufferSize | 缓冲区大小。 | 449| writeLength | 在返回ABILITY_RUNTIME_ERROR_CODE_NO_ERROR时，表示实际写入到缓冲区的字符串长度。 | 450 451**返回：** 452 453ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 454 455ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参buffer或者writeLength为空，或者缓冲区大小小于需要写入的大小。 456 457ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 458 459### OH_AbilityRuntime_ApplicationContextGetCloudFileDir 460 461``` 462AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCloudFileDir(char* buffer, const int32_t bufferSize, int32_t* writeLength) 463``` 464 465**描述** 466 467获取应用级别的云文件目录。 468 469**起始版本：** 16 470 471**参数：** 472 473| 名称 | 描述 | 474| ----------- | ------------------------------------------------------------ | 475| buffer | 缓冲区，缓存目录字符串写入该区域。 | 476| bufferSize | 缓冲区大小。 | 477| writeLength | 在返回ABILITY_RUNTIME_ERROR_CODE_NO_ERROR时，表示实际写入到缓冲区的字符串长度。 | 478 479**返回：** 480 481ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 查询成功。 482 483ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - 入参buffer或者writeLength为空，或者缓冲区大小小于需要写入的大小。 484 485ABILITY_RUNTIME_ERROR_CODE_CONTEXT_NOT_EXIST - 当前环境的上下文不存在，如在应用创建的[子进程](c-apis-ability-childprocess.md)中应用级别上下文不存在。 486 487### OH_AbilityRuntime_StartSelfUIAbility 488 489``` 490AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbility(AbilityBase_Want *want) 491``` 492 493**描述** 494 495启动当前应用的UIAbility。 496 497> **说明：** 498> 499> 当前仅支持2in1设备。 500 501**需要权限**：ohos.permission.NDK_START_SELF_UI_ABILITY 502 503**起始版本：** 15 504 505**参数：** 506 507| 名称 | 描述 | 508| ----------- | ------------------------------------------------------------ | 509| want | 启动当前应用UIAbility时需要的Want信息。 | 510 511**返回：** 512 513ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 接口调用成功。 514 515ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED - 权限校验失败。 516 517ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - Want信息为空，或者Want信息里bundleName或abilityName为空。 518 519ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED - 设备类型不支持。 520 521ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY - 指定的Ability名称不存在。 522 523ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE - 接口调用Ability类型错误。 524 525ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED - 众测应用到期。 526 527ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE - wukong模式，不允许启动/停止Ability。 528 529ABILITY_RUNTIME_ERROR_CODE_CONTROLLED - 应用被管控。 530 531ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED - 应用被EDM管控。 532 533ABILITY_RUNTIME_ERROR_CODE_CROSS_APP - 限制API 11以上版本三方应用跳转。 534 535ABILITY_RUNTIME_ERROR_CODE_INTERNAL - 内部错误。 536 537ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY - 非顶层应用。 538 539ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED - 表示应用多实例已达到上限。 540 541ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED - 表示不允许设置APP_INSTANCE_KEY。 542 543**示例代码：** 544```cpp 545#include <AbilityKit/ability_base/want.h> 546#include <AbilityKit/ability_runtime/application_context.h> 547 548void startSelfUIAbilityTest() 549{ 550 AbilityBase_Element element; 551 element.abilityName = const_cast<char*>("EntryAbility"); 552 element.bundleName = const_cast<char*>("com.exampl.myapplication"); 553 element.moduleName = const_cast<char*>("entry"); 554 AbilityBase_Want* want = OH_AbilityBase_CreateWant(element); 555 556 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbility(want); 557 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 558 // 记录错误日志以及其他业务处理 559 return; 560 } 561 // 销毁want，防止内存泄漏 562 OH_AbilityBase_DestroyWant(want); 563} 564``` 565 566### OH_AbilityRuntime_CreateStartOptions 567 568``` 569AbilityRuntime_StartOptions* OH_AbilityRuntime_CreateStartOptions(void) 570``` 571 572**描述** 573 574创建启动当前应用的UIAbility所需要的StartOptions结构体。 575 576**起始版本：** 17 577 578**返回：** 579 580AbilityRuntime_StartOptions - StartOptions数据结构。 581 582**示例代码：** 583```cpp 584#include <AbilityKit/ability_runtime/start_options.h> 585 586void createStartOptionsTest() 587{ 588 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 589 if (options == nullptr) { 590 // 记录错误日志以及其他业务处理 591 return; 592 } 593 594 // 销毁options，防止内存泄漏 595 OH_AbilityRuntime_DestroyStartOptions(&options); 596} 597``` 598 599### OH_AbilityRuntime_DestroyStartOptions 600 601``` 602AbilityRuntime_ErrorCode OH_AbilityRuntime_DestroyStartOptions(AbilityRuntime_StartOptions **startOptions) 603``` 604 605**描述** 606 607销毁StartOptions结构体。 608 609**参数：** 610 611| 名称 | 描述 | 612| ----------- | ------------------------------------------------------------ | 613| startOptions | 需要销毁的StartOptions结构体。 | 614 615**起始版本：** 17 616 617**返回：** 618 619ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 销毁成功。 620 621ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 622 623**示例代码：** 624```cpp 625#include <AbilityKit/ability_runtime/start_options.h> 626 627void destroyStartOptionsTest() 628{ 629 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 630 if (options == nullptr) { 631 // 记录错误日志以及其他业务处理 632 return; 633 } 634 635 // 销毁options，防止内存泄漏 636 OH_AbilityRuntime_DestroyStartOptions(&options); 637} 638``` 639 640### OH_AbilityRuntime_SetStartOptionsWindowMode 641 642``` 643AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowMode(AbilityRuntime_StartOptions *startOptions, 644 AbilityRuntime_WindowMode windowMode); 645``` 646 647**描述** 648 649设置启动Ability时的窗口模式。 650 651**参数：** 652 653| 名称 | 描述 | 654| ----------- | ------------------------------------------------------------ | 655| startOptions | StartOptions结构体。 | 656| windowMode | 需要设置的窗口模式。 | 657 658**起始版本：** 17 659 660**返回：** 661 662ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 663 664ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空或者WindowMode无效。 665 666**示例代码：** 667```cpp 668#include <AbilityKit/ability_runtime/start_options.h> 669 670void demo() 671{ 672 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 673 if (options == nullptr) { 674 // 记录错误日志以及其他业务处理 675 return; 676 } 677 678 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowMode(options, 679 ABILITY_RUNTIME_WINDOW_MODE_FULL_SCREEN); 680 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 681 // 记录错误日志以及其他业务处理 682 } 683 // 销毁options，防止内存泄漏 684 OH_AbilityRuntime_DestroyStartOptions(&options); 685} 686``` 687 688### OH_AbilityRuntime_GetStartOptionsWindowMode 689 690``` 691AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowMode(AbilityRuntime_StartOptions *startOptions, 692 AbilityRuntime_WindowMode &windowMode); 693``` 694 695**描述** 696 697获取启动Ability时的窗口模式。 698 699**参数：** 700 701| 名称 | 描述 | 702| ----------- | ------------------------------------------------------------ | 703| startOptions | StartOptions结构体。 | 704| windowMode | 获取到的窗口模式。 | 705 706**起始版本：** 17 707 708**返回：** 709 710ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 711 712ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 713 714**示例代码：** 715```cpp 716#include <AbilityKit/ability_runtime/start_options.h> 717 718void demo() 719{ 720 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 721 if (options == nullptr) { 722 // 记录错误日志以及其他业务处理 723 return; 724 } 725 726 AbilityRuntime_WindowMode windowMode = ABILITY_RUNTIME_WINDOW_MODE_UNDEFINED; 727 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowMode(options, windowMode); 728 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 729 // 记录错误日志以及其他业务处理 730 } 731 // 销毁options，防止内存泄漏 732 OH_AbilityRuntime_DestroyStartOptions(&options); 733} 734``` 735 736### OH_AbilityRuntime_SetStartOptionsDisplayId 737 738``` 739AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsDisplayId(AbilityRuntime_StartOptions *startOptions, int32_t displayId); 740``` 741 742**描述** 743 744设置启动Ability时窗口所在的屏幕ID。 745 746**参数：** 747 748| 名称 | 描述 | 749| ----------- | ------------------------------------------------------------ | 750| startOptions | StartOptions结构体。 | 751| displayId | 启动Ability时窗口所在的屏幕ID。 | 752 753**起始版本：** 17 754 755**返回：** 756 757ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 758 759ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 760 761**示例代码：** 762```cpp 763#include <AbilityKit/ability_runtime/start_options.h> 764 765void demo() 766{ 767 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 768 if (options == nullptr) { 769 // 记录错误日志以及其他业务处理 770 return; 771 } 772 773 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsDisplayId(options, 1); 774 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 775 // 记录错误日志以及其他业务处理 776 } 777 // 销毁options，防止内存泄漏 778 OH_AbilityRuntime_DestroyStartOptions(&options); 779} 780``` 781 782### OH_AbilityRuntime_GetStartOptionsDisplayId 783 784``` 785AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsDisplayId(AbilityRuntime_StartOptions *startOptions, int32_t &displayId); 786``` 787 788**描述** 789 790获取启动Ability时窗口所在的屏幕ID。 791 792**参数：** 793 794| 名称 | 描述 | 795| ----------- | ------------------------------------------------------------ | 796| startOptions | StartOptions结构体。 | 797| displayId | 获取到的屏幕ID。 | 798 799**起始版本：** 17 800 801**返回：** 802 803ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 804 805ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 806 807**示例代码：** 808```cpp 809#include <AbilityKit/ability_runtime/start_options.h> 810 811void demo() 812{ 813 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 814 if (options == nullptr) { 815 // 记录错误日志以及其他业务处理 816 return; 817 } 818 819 int32_t displayId = 0; 820 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsDisplayId(options, displayId); 821 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 822 // 记录错误日志以及其他业务处理 823 } 824 // 销毁options，防止内存泄漏 825 OH_AbilityRuntime_DestroyStartOptions(&options); 826} 827``` 828 829### OH_AbilityRuntime_SetStartOptionsWithAnimation 830 831``` 832AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWithAnimation(AbilityRuntime_StartOptions *startOptions, bool withAnimation); 833``` 834 835**描述** 836 837设置启动Ability时是否具有动画效果。 838 839**参数：** 840 841| 名称 | 描述 | 842| ----------- | ------------------------------------------------------------ | 843| startOptions | StartOptions结构体。 | 844| withAnimation | 启动Ability时是否具有动画效果。 | 845 846**起始版本：** 17 847 848**返回：** 849 850ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 851 852ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 853 854**示例代码：** 855```cpp 856#include <AbilityKit/ability_runtime/start_options.h> 857 858void demo() 859{ 860 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 861 if (options == nullptr) { 862 // 记录错误日志以及其他业务处理 863 return; 864 } 865 866 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWithAnimation(options, true); 867 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 868 // 记录错误日志以及其他业务处理 869 } 870 // 销毁options，防止内存泄漏 871 OH_AbilityRuntime_DestroyStartOptions(&options); 872} 873``` 874 875### OH_AbilityRuntime_GetStartOptionsWithAnimation 876 877``` 878AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWithAnimation(AbilityRuntime_StartOptions *startOptions, bool &withAnimation); 879``` 880 881**描述** 882 883获取启动Ability时是否具有动画效果。 884 885**参数：** 886 887| 名称 | 描述 | 888| ----------- | ------------------------------------------------------------ | 889| startOptions | StartOptions结构体。 | 890| withAnimation | 启动Ability时是否具有动画效果。 | 891 892**起始版本：** 17 893 894**返回：** 895 896ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 897 898ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 899 900**示例代码：** 901```cpp 902#include <AbilityKit/ability_runtime/start_options.h> 903 904void demo() 905{ 906 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 907 if (options == nullptr) { 908 // 记录错误日志以及其他业务处理 909 return; 910 } 911 912 bool withAnimation = false; 913 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWithAnimation(options, withAnimation); 914 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 915 // 记录错误日志以及其他业务处理 916 } 917 // 销毁options，防止内存泄漏 918 OH_AbilityRuntime_DestroyStartOptions(&options); 919} 920``` 921 922### OH_AbilityRuntime_SetStartOptionsWindowLeft 923 924``` 925AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowLeft(AbilityRuntime_StartOptions *startOptions, int32_t windowLeft); 926``` 927 928**描述** 929 930设置启动Ability时的窗口左侧位置，单位为px。 931 932**参数：** 933 934| 名称 | 描述 | 935| ----------- | ------------------------------------------------------------ | 936| startOptions | StartOptions结构体。 | 937| windowLeft | 需要设置的窗口左侧位置，单位为px。 | 938 939**起始版本：** 17 940 941**返回：** 942 943ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 944 945ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 946 947**示例代码：** 948```cpp 949#include <AbilityKit/ability_runtime/start_options.h> 950 951void demo() 952{ 953 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 954 if (options == nullptr) { 955 // 记录错误日志以及其他业务处理 956 return; 957 } 958 959 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowLeft(options, 200); 960 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 961 // 记录错误日志以及其他业务处理 962 } 963 // 销毁options，防止内存泄漏 964 OH_AbilityRuntime_DestroyStartOptions(&options); 965} 966``` 967 968### OH_AbilityRuntime_GetStartOptionsWindowLeft 969 970``` 971AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowLeft(AbilityRuntime_StartOptions *startOptions, int32_t &windowLeft); 972``` 973 974**描述** 975 976获取启动Ability时的窗口左侧位置，单位为px。 977 978**参数：** 979 980| 名称 | 描述 | 981| ----------- | ------------------------------------------------------------ | 982| startOptions | StartOptions结构体。 | 983| windowLeft | 获取到的窗口左侧位置，单位为px。 | 984 985**起始版本：** 17 986 987**返回：** 988 989ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 990 991ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 992 993**示例代码：** 994```cpp 995#include <AbilityKit/ability_runtime/start_options.h> 996 997void demo() 998{ 999 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1000 if (options == nullptr) { 1001 // 记录错误日志以及其他业务处理 1002 return; 1003 } 1004 1005 int32_t windowLeft = 0; 1006 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowLeft(options, windowLeft); 1007 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1008 // 记录错误日志以及其他业务处理 1009 } 1010 // 销毁options，防止内存泄漏 1011 OH_AbilityRuntime_DestroyStartOptions(&options); 1012} 1013``` 1014 1015### OH_AbilityRuntime_SetStartOptionsWindowTop 1016 1017``` 1018AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowTop(AbilityRuntime_StartOptions *startOptions, int32_t windowTop); 1019``` 1020 1021**描述** 1022 1023设置启动Ability时的窗口顶部位置，单位为px。 1024 1025**参数：** 1026 1027| 名称 | 描述 | 1028| ----------- | ------------------------------------------------------------ | 1029| startOptions | StartOptions结构体。 | 1030| windowTop | 需要设置的窗口顶部位置，单位为px。 | 1031 1032**起始版本：** 17 1033 1034**返回：** 1035 1036ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1037 1038ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1039 1040**示例代码：** 1041```cpp 1042#include <AbilityKit/ability_runtime/start_options.h> 1043 1044void demo() 1045{ 1046 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1047 if (options == nullptr) { 1048 // 记录错误日志以及其他业务处理 1049 return; 1050 } 1051 1052 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowTop(options, 500); 1053 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1054 // 记录错误日志以及其他业务处理 1055 } 1056 // 销毁options，防止内存泄漏 1057 OH_AbilityRuntime_DestroyStartOptions(&options); 1058} 1059``` 1060 1061### OH_AbilityRuntime_GetStartOptionsWindowTop 1062 1063``` 1064AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowTop(AbilityRuntime_StartOptions *startOptions, int32_t &windowTop); 1065``` 1066 1067**描述** 1068 1069获取启动Ability时的窗口顶部位置，单位为px。 1070 1071**参数：** 1072 1073| 名称 | 描述 | 1074| ----------- | ------------------------------------------------------------ | 1075| startOptions | StartOptions结构体。 | 1076| windowTop | 获取到的窗口顶部位置，单位为px。 | 1077 1078**起始版本：** 17 1079 1080**返回：** 1081 1082ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 1083 1084ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1085 1086**示例代码：** 1087```cpp 1088#include <AbilityKit/ability_runtime/start_options.h> 1089 1090void demo() 1091{ 1092 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1093 if (options == nullptr) { 1094 // 记录错误日志以及其他业务处理 1095 return; 1096 } 1097 1098 int32_t windowTop = 0; 1099 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowTop(options, windowTop); 1100 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1101 // 记录错误日志以及其他业务处理 1102 } 1103 // 销毁options，防止内存泄漏 1104 OH_AbilityRuntime_DestroyStartOptions(&options); 1105} 1106``` 1107 1108### OH_AbilityRuntime_SetStartOptionsWindowHeight 1109 1110``` 1111AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowHeight(AbilityRuntime_StartOptions *startOptions, int32_t windowHeight); 1112``` 1113 1114**描述** 1115 1116设置启动Ability时的窗口高度，单位为px。 1117 1118**参数：** 1119 1120| 名称 | 描述 | 1121| ----------- | ------------------------------------------------------------ | 1122| startOptions | StartOptions结构体。 | 1123| windowHeight | 需要设置的窗口高度，单位为px。 | 1124 1125**起始版本：** 17 1126 1127**返回：** 1128 1129ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1130 1131ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1132 1133**示例代码：** 1134```cpp 1135#include <AbilityKit/ability_runtime/start_options.h> 1136 1137void demo() 1138{ 1139 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1140 if (options == nullptr) { 1141 // 记录错误日志以及其他业务处理 1142 return; 1143 } 1144 1145 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowHeight(options, 500); 1146 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1147 // 记录错误日志以及其他业务处理 1148 } 1149 // 销毁options，防止内存泄漏 1150 OH_AbilityRuntime_DestroyStartOptions(&options); 1151} 1152``` 1153 1154### OH_AbilityRuntime_GetStartOptionsWindowHeight 1155 1156``` 1157AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowHeight(AbilityRuntime_StartOptions *startOptions, int32_t &windowHeight); 1158``` 1159 1160**描述** 1161 1162获取启动Ability时的窗口高度，单位为px。 1163 1164**参数：** 1165 1166| 名称 | 描述 | 1167| ----------- | ------------------------------------------------------------ | 1168| startOptions | StartOptions结构体。 | 1169| windowHeight | 获取到的窗口高度，单位为px。 | 1170 1171**起始版本：** 17 1172 1173**返回：** 1174 1175ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 1176 1177ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1178 1179**示例代码：** 1180```cpp 1181#include <AbilityKit/ability_runtime/start_options.h> 1182 1183void demo() 1184{ 1185 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1186 if (options == nullptr) { 1187 // 记录错误日志以及其他业务处理 1188 return; 1189 } 1190 1191 int32_t windowHeight = 0; 1192 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowHeight(options, windowHeight); 1193 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1194 // 记录错误日志以及其他业务处理 1195 } 1196 // 销毁options，防止内存泄漏 1197 OH_AbilityRuntime_DestroyStartOptions(&options); 1198} 1199``` 1200 1201### OH_AbilityRuntime_SetStartOptionsWindowWidth 1202 1203``` 1204AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowWidth(AbilityRuntime_StartOptions *startOptions, int32_t windowWidth); 1205``` 1206 1207**描述** 1208 1209设置启动Ability时的窗口宽度，单位为px。 1210 1211**参数：** 1212 1213| 名称 | 描述 | 1214| ----------- | ------------------------------------------------------------ | 1215| startOptions | StartOptions结构体。 | 1216| windowWidth | 需要设置的窗口宽度，单位为px。 | 1217 1218**起始版本：** 17 1219 1220**返回：** 1221 1222ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1223 1224ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1225 1226**示例代码：** 1227```cpp 1228#include <AbilityKit/ability_runtime/start_options.h> 1229 1230void demo() 1231{ 1232 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1233 if (options == nullptr) { 1234 // 记录错误日志以及其他业务处理 1235 return; 1236 } 1237 1238 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsWindowWidth(options, 500); 1239 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1240 // 记录错误日志以及其他业务处理 1241 } 1242 // 销毁options，防止内存泄漏 1243 OH_AbilityRuntime_DestroyStartOptions(&options); 1244} 1245``` 1246 1247### OH_AbilityRuntime_GetStartOptionsWindowWidth 1248 1249``` 1250AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowWidth(AbilityRuntime_StartOptions *startOptions, int32_t &windowWidth); 1251``` 1252 1253**描述** 1254 1255获取启动Ability时的窗口宽度，单位为px。 1256 1257**参数：** 1258 1259| 名称 | 描述 | 1260| ----------- | ------------------------------------------------------------ | 1261| startOptions | StartOptions结构体。 | 1262| windowWidth | 获取到的窗口宽度，单位为px。 | 1263 1264**起始版本：** 17 1265 1266**返回：** 1267 1268ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 1269 1270ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1271 1272**示例代码：** 1273```cpp 1274#include <AbilityKit/ability_runtime/start_options.h> 1275 1276void demo() 1277{ 1278 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1279 if (options == nullptr) { 1280 // 记录错误日志以及其他业务处理 1281 return; 1282 } 1283 1284 int32_t windowWidth = 0; 1285 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsWindowWidth(options, windowWidth); 1286 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1287 // 记录错误日志以及其他业务处理 1288 } 1289 // 销毁options，防止内存泄漏 1290 OH_AbilityRuntime_DestroyStartOptions(&options); 1291} 1292``` 1293 1294### OH_AbilityRuntime_SetStartOptionsStartWindowIcon 1295 1296``` 1297AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsStartWindowIcon(AbilityRuntime_StartOptions *startOptions, OH_PixelmapNative *startWindowIcon) 1298``` 1299 1300**描述** 1301 1302设置启动Ability时的窗口启动图标。图片数据大小限制为600M。 1303 1304**参数：** 1305 1306| 名称 | 描述 | 1307| ----------- | ------------------------------------------------------------ | 1308| startOptions | StartOptions结构体。 | 1309| startWindowIcon | 需要设置的窗口启动图标。 | 1310 1311**起始版本：** 17 1312 1313**返回：** 1314 1315ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1316 1317ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions或者OH_PixelmapNative信息为空。 1318 1319**示例代码：** 1320```cpp 1321#include <AbilityKit/ability_runtime/start_options.h> 1322 1323void demo() 1324{ 1325 uint8_t data[96]; 1326 size_t dataSize = 96; 1327 for (int i = 0; i < dataSize; i++) { 1328 data[i] = i + 1; 1329 } 1330 1331 //创建参数结构体实例，并设置参数 1332 OH_Pixelmap_InitializationOptions *createOpts = nullptr; 1333 OH_PixelmapInitializationOptions_Create(&createOpts); 1334 OH_PixelmapInitializationOptions_SetWidth(createOpts, 6); 1335 OH_PixelmapInitializationOptions_SetHeight(createOpts, 4); 1336 OH_PixelmapInitializationOptions_SetPixelFormat(createOpts, PIXEL_FORMAT_RGBA_8888); 1337 OH_PixelmapInitializationOptions_SetAlphaType(createOpts, PIXELMAP_ALPHA_TYPE_UNKNOWN); 1338 1339 //创建Pixelmap实例 1340 OH_PixelmapNative *startWindowIcon = nullptr; 1341 Image_ErrorCode errCode = OH_PixelmapNative_CreatePixelmap(data, dataSize, createOpts, &startWindowIcon); 1342 if (errCode != IMAGE_SUCCESS) { 1343 // 记录错误日志以及其他业务处理 1344 1345 // 销毁createOpts，防止内存泄漏 1346 OH_PixelmapInitializationOptions_Release(createOpts); 1347 return; 1348 } 1349 1350 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1351 if (options == nullptr) { 1352 // 记录错误日志以及其他业务处理 1353 1354 // 销毁createOpts，防止内存泄漏 1355 OH_PixelmapInitializationOptions_Release(createOpts); 1356 1357 // 销毁startWindowIcon，防止内存泄漏 1358 OH_PixelmapNative_Release(startWindowIcon); 1359 return; 1360 } 1361 1362 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsStartWindowIcon(options, startWindowIcon); 1363 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1364 // 记录错误日志以及其他业务处理 1365 } 1366 // 销毁createOpts，防止内存泄漏 1367 OH_PixelmapInitializationOptions_Release(createOpts); 1368 1369 // 销毁startWindowIcon，防止内存泄漏 1370 OH_PixelmapNative_Release(startWindowIcon); 1371 1372 // 销毁options，防止内存泄漏 1373 OH_AbilityRuntime_DestroyStartOptions(&options); 1374} 1375``` 1376 1377### OH_AbilityRuntime_SetStartOptionsStartVisibility 1378 1379``` 1380AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsStartVisibility(AbilityRuntime_StartOptions *startOptions, AbilityRuntime_StartVisibility startVisibility); 1381``` 1382 1383**描述** 1384 1385设置启动Ability时窗口和dock栏图标的显示模式。 1386 1387**参数：** 1388 1389| 名称 | 描述 | 1390| ----------- | ------------------------------------------------------------ | 1391| startOptions | StartOptions结构体。 | 1392| startVisibility | 需要设置的显示模式。 | 1393 1394**起始版本：** 17 1395 1396**返回：** 1397 1398ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1399 1400ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空，或startVisibility取值不在枚举类AbilityRuntime_StartVisibility中。 1401 1402**示例代码：** 1403```cpp 1404#include <AbilityKit/ability_runtime/start_options.h> 1405 1406void demo() 1407{ 1408 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1409 if (options == nullptr) { 1410 // 记录错误日志以及其他业务处理 1411 return; 1412 } 1413 1414 AbilityRuntime_StartVisibility visibility = AbilityRuntime_StartVisibility::ABILITY_RUNTIME_SHOW_UPON_START; 1415 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsStartVisibility(options, visibility); 1416 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1417 // 记录错误日志以及其他业务处理 1418 } 1419 // 销毁options，防止内存泄漏 1420 OH_AbilityRuntime_DestroyStartOptions(&options); 1421} 1422``` 1423 1424### OH_AbilityRuntime_GetStartOptionsStartVisibility 1425 1426``` 1427AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsStartVisibility(AbilityRuntime_StartOptions *startOptions, AbilityRuntime_StartVisibility &startVisibility); 1428``` 1429 1430**描述** 1431 1432获取启动Ability时窗口和dock栏图标的显示模式。 1433 1434**参数：** 1435 1436| 名称 | 描述 | 1437| ----------- | ------------------------------------------------------------ | 1438| startOptions | StartOptions结构体。 | 1439| startVisibility | 获取到的显示模式。 | 1440 1441**起始版本：** 17 1442 1443**返回：** 1444 1445ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 1446 1447ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空，或startVisibility未被设置。 1448 1449**示例代码：** 1450```cpp 1451#include <AbilityKit/ability_runtime/start_options.h> 1452 1453void demo() 1454{ 1455 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1456 if (options == nullptr) { 1457 // 记录错误日志以及其他业务处理 1458 return; 1459 } 1460 1461 AbilityRuntime_StartVisibility visibility; 1462 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsStartVisibility(options, visibility); 1463 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1464 // 记录错误日志以及其他业务处理 1465 } 1466 // 销毁options，防止内存泄漏 1467 OH_AbilityRuntime_DestroyStartOptions(&options); 1468} 1469``` 1470 1471### OH_AbilityRuntime_GetStartOptionsStartWindowIcon 1472 1473``` 1474AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsStartWindowIcon(AbilityRuntime_StartOptions *startOptions, 1475 OH_PixelmapNative **startWindowIcon) 1476``` 1477 1478**描述** 1479 1480获取启动Ability时的窗口启动图标。 1481 1482**参数：** 1483 1484| 名称 | 描述 | 1485| ----------- | ------------------------------------------------------------ | 1486| startOptions | StartOptions结构体。 | 1487| startWindowIcon | 获取到的窗口启动图标。 | 1488 1489**起始版本：** 17 1490 1491**返回：** 1492 1493ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 1494 1495ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空，或者OH_PixelmapNative没有置为空指针。 1496 1497**示例代码：** 1498```cpp 1499#include <AbilityKit/ability_runtime/start_options.h> 1500 1501void demo() 1502{ 1503 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1504 if (options == nullptr) { 1505 // 记录错误日志以及其他业务处理 1506 return; 1507 } 1508 1509 OH_PixelmapNative *startWindowIcon = nullptr; 1510 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsStartWindowIcon(options, &startWindowIcon); 1511 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1512 // 记录错误日志以及其他业务处理 1513 } 1514 1515 // 销毁startWindowIcon，防止内存泄漏 1516 OH_PixelmapNative_Release(startWindowIcon); 1517 1518 // 销毁options，防止内存泄漏 1519 OH_AbilityRuntime_DestroyStartOptions(&options); 1520} 1521``` 1522 1523### OH_AbilityRuntime_SetStartOptionsStartWindowBackgroundColor 1524 1525``` 1526AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsStartWindowBackgroundColor(AbilityRuntime_StartOptions *startOptions, const char *startWindowBackgroundColor) 1527``` 1528 1529**描述** 1530 1531设置启动Ability时的窗口背景颜色。启动UIAbility时，启动页所显示的背景颜色。如果未设置该字段，则默认采用[module.json5配置文件](../../quick-start/module-configuration-file.md)中[abilities标签](../../quick-start/module-configuration-file.md#abilities标签)的startWindowBackground字段的配置。 1532 1533**参数：** 1534 1535| 名称 | 描述 | 1536| ----------- | ------------------------------------------------------------ | 1537| startOptions | StartOptions结构体。 | 1538| startWindowBackgroundColor | 需要设置的窗口背景颜色。固定为ARGB格式, 如：`#E5FFFFFF`。| 1539 1540**起始版本：** 17 1541 1542**返回：** 1543 1544ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1545 1546ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions或者StartWindowBackgroundColor为空。 1547 1548**示例代码：** 1549```cpp 1550#include <AbilityKit/ability_runtime/start_options.h> 1551 1552void demo() 1553{ 1554 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1555 if (options == nullptr) { 1556 // 记录错误日志以及其他业务处理 1557 return; 1558 } 1559 1560 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsStartWindowBackgroundColor(options, "#00000000"); 1561 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1562 // 记录错误日志以及其他业务处理 1563 } 1564 1565 // 销毁options，防止内存泄漏 1566 OH_AbilityRuntime_DestroyStartOptions(&options); 1567} 1568``` 1569 1570### OH_AbilityRuntime_GetStartOptionsStartWindowBackgroundColor 1571 1572``` 1573AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsStartWindowBackgroundColor(AbilityRuntime_StartOptions *startOptions, char **startWindowBackgroundColor, size_t &size) 1574``` 1575 1576**描述** 1577 1578获取启动Ability时的窗口背景颜色。 1579 1580**参数：** 1581 1582| 名称 | 描述 | 1583| ----------- | ------------------------------------------------------------ | 1584| startOptions | StartOptions结构体。 | 1585| startWindowBackgroundColor | 获取到的窗口背景颜色。固定为ARGB格式, 如：`#E5FFFFFF`。| 1586| size | 获取到的窗口背景颜色的大小。 | 1587 1588**起始版本：** 17 1589 1590**返回：** 1591 1592ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 1593 1594ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空，或者StartWindowBackgroundColor没有置为空指针。 1595 1596ABILITY_RUNTIME_ERROR_CODE_INTERNAL - 开发者无法恢复的内部错误，比如内部调用malloc错误，或者字符串拷贝函数出错。 1597 1598**示例代码：** 1599```cpp 1600#include <cstdlib> 1601 1602#include <AbilityKit/ability_runtime/start_options.h> 1603 1604void demo() 1605{ 1606 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1607 if (options == nullptr) { 1608 // 记录错误日志以及其他业务处理 1609 return; 1610 } 1611 1612 char *startWindowBackgroundColor = nullptr; 1613 size_t size = 0; 1614 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsStartWindowBackgroundColor(options, 1615 &startWindowBackgroundColor, size); 1616 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1617 // 记录错误日志以及其他业务处理 1618 } 1619 1620 if (startWindowBackgroundColor != nullptr) { 1621 // 销毁startWindowBackgroundColor，防止内存泄漏 1622 free(startWindowBackgroundColor); 1623 startWindowBackgroundColor = nullptr; 1624 } 1625 1626 // 销毁options，防止内存泄漏 1627 OH_AbilityRuntime_DestroyStartOptions(&options); 1628} 1629``` 1630 1631### OH_AbilityRuntime_SetStartOptionsSupportedWindowModes 1632 1633``` 1634AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsSupportedWindowModes(AbilityRuntime_StartOptions *startOptions, 1635 AbilityRuntime_SupportedWindowMode *supportedWindowModes, size_t size) 1636``` 1637 1638**描述** 1639 1640设置启动Ability时组件所支持的窗口模式。 1641 1642**参数：** 1643 1644| 名称 | 描述 | 1645| ----------- | ------------------------------------------------------------ | 1646| startOptions | StartOptions结构体。 | 1647| supportedWindowModes | 需要设置的组件所支持的窗口模式。 | 1648| size | 组件所支持的窗口模式的大小。 | 1649 1650**起始版本：** 17 1651 1652**返回：** 1653 1654ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1655 1656ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions或者SupportedWindowModes为空，或者Size为0。 1657 1658**示例代码：** 1659```cpp 1660#include <AbilityKit/ability_runtime/start_options.h> 1661 1662void demo() 1663{ 1664 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1665 if (options == nullptr) { 1666 // 记录错误日志以及其他业务处理 1667 return; 1668 } 1669 1670 size_t supportedWindowModesSize = 3; 1671 AbilityRuntime_SupportedWindowMode supportedWindowModes[3] = { 1672 ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FULL_SCREEN, 1673 ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_SPLIT, 1674 ABILITY_RUNTIME_SUPPORTED_WINDOW_MODE_FLOATING, 1675 }; 1676 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsSupportedWindowModes(options, 1677 supportedWindowModes, supportedWindowModesSize); 1678 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1679 // 记录错误日志以及其他业务处理 1680 } 1681 1682 // 销毁options，防止内存泄漏 1683 OH_AbilityRuntime_DestroyStartOptions(&options); 1684} 1685``` 1686 1687### OH_AbilityRuntime_GetStartOptionsSupportedWindowModes 1688 1689``` 1690AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsSupportedWindowModes(AbilityRuntime_StartOptions *startOptions, 1691 AbilityRuntime_SupportedWindowMode **supportedWindowModes, size_t &size) 1692``` 1693 1694**描述** 1695 1696获取启动Ability时组件所支持的窗口模式。 1697 1698**参数：** 1699 1700| 名称 | 描述 | 1701| ----------- | ------------------------------------------------------------ | 1702| startOptions | StartOptions结构体。 | 1703| supportedWindowModes | 获取到的组件所支持的窗口模式。 | 1704| size | 获取到的组件所支持的窗口模式的大小。 | 1705 1706**起始版本：** 17 1707 1708**返回：** 1709 1710ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 1711 1712ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空，或者SupportWindowMode没有置为空指针。 1713 1714ABILITY_RUNTIME_ERROR_CODE_INTERNAL - 开发者无法恢复的内部错误，比如内部调用malloc错误。 1715 1716**示例代码：** 1717```cpp 1718#include <cstdlib> 1719 1720#include <AbilityKit/ability_runtime/start_options.h> 1721 1722void demo() 1723{ 1724 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1725 if (options == nullptr) { 1726 // 记录错误日志以及其他业务处理 1727 return; 1728 } 1729 1730 AbilityRuntime_SupportedWindowMode *supportedWindowModes = nullptr; 1731 size_t size = 0; 1732 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsSupportedWindowModes(options, 1733 &supportedWindowModes, size); 1734 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1735 // 记录错误日志以及其他业务处理 1736 } 1737 1738 if (supportedWindowModes != nullptr) { 1739 // 销毁supportedWindowModes，防止内存泄漏 1740 free(supportedWindowModes); 1741 } 1742 1743 // 销毁options，防止内存泄漏 1744 OH_AbilityRuntime_DestroyStartOptions(&options); 1745} 1746``` 1747 1748### OH_AbilityRuntime_SetStartOptionsMinWindowWidth 1749 1750``` 1751AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMinWindowWidth(AbilityRuntime_StartOptions *startOptions, 1752 int32_t minWindowWidth) 1753``` 1754 1755**描述** 1756 1757设置启动Ability时的最小窗口宽度，单位为vp。 1758 1759**参数：** 1760 1761| 名称 | 描述 | 1762| ----------- | ------------------------------------------------------------ | 1763| startOptions | StartOptions结构体。 | 1764| minWindowWidth | 需要设置的最小窗口宽度，单位为vp。 | 1765 1766**起始版本：** 17 1767 1768**返回：** 1769 1770ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1771 1772ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1773 1774**示例代码：** 1775```cpp 1776#include <AbilityKit/ability_runtime/start_options.h> 1777 1778void demo() 1779{ 1780 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1781 if (options == nullptr) { 1782 // 记录错误日志以及其他业务处理 1783 return; 1784 } 1785 1786 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsMinWindowWidth(options, 100); 1787 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1788 // 记录错误日志以及其他业务处理 1789 } 1790 1791 // 销毁options，防止内存泄漏 1792 OH_AbilityRuntime_DestroyStartOptions(&options); 1793} 1794``` 1795 1796### OH_AbilityRuntime_GetStartOptionsMinWindowWidth 1797 1798``` 1799AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMinWindowWidth(AbilityRuntime_StartOptions *startOptions, 1800 int32_t &minWindowWidth) 1801``` 1802 1803**描述** 1804 1805获取启动Ability时的最小窗口宽度，单位为vp。 1806 1807**参数：** 1808 1809| 名称 | 描述 | 1810| ----------- | ------------------------------------------------------------ | 1811| startOptions | StartOptions结构体。 | 1812| minWindowWidth | 获取到的最小窗口宽度，单位为vp。 | 1813 1814**起始版本：** 17 1815 1816**返回：** 1817 1818ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 1819 1820ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1821 1822**示例代码：** 1823```cpp 1824#include <AbilityKit/ability_runtime/start_options.h> 1825 1826void demo() 1827{ 1828 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1829 if (options == nullptr) { 1830 // 记录错误日志以及其他业务处理 1831 return; 1832 } 1833 1834 int32_t minWindowWidth = 0; 1835 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsMinWindowWidth(options, minWindowWidth); 1836 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1837 // 记录错误日志以及其他业务处理 1838 } 1839 1840 // 销毁options，防止内存泄漏 1841 OH_AbilityRuntime_DestroyStartOptions(&options); 1842} 1843``` 1844 1845### OH_AbilityRuntime_SetStartOptionsMaxWindowWidth 1846 1847``` 1848AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMaxWindowWidth(AbilityRuntime_StartOptions *startOptions, 1849 int32_t maxWindowWidth) 1850``` 1851 1852**描述** 1853 1854设置启动Ability时的最大窗口宽度，单位为vp。 1855 1856**参数：** 1857 1858| 名称 | 描述 | 1859| ----------- | ------------------------------------------------------------ | 1860| startOptions | StartOptions结构体。 | 1861| maxWindowWidth | 需要设置的最大窗口宽度，单位为vp。 | 1862 1863**起始版本：** 17 1864 1865**返回：** 1866 1867ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1868 1869ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1870 1871**示例代码：** 1872```cpp 1873#include <AbilityKit/ability_runtime/start_options.h> 1874 1875void demo() 1876{ 1877 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1878 if (options == nullptr) { 1879 // 记录错误日志以及其他业务处理 1880 return; 1881 } 1882 1883 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsMaxWindowWidth(options, 100); 1884 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1885 // 记录错误日志以及其他业务处理 1886 } 1887 1888 // 销毁options，防止内存泄漏 1889 OH_AbilityRuntime_DestroyStartOptions(&options); 1890} 1891``` 1892 1893### OH_AbilityRuntime_GetStartOptionsMaxWindowWidth 1894 1895``` 1896AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMaxWindowWidth(AbilityRuntime_StartOptions *startOptions, 1897 int32_t &maxWindowWidth) 1898``` 1899 1900**描述** 1901 1902获取启动Ability时的最大窗口宽度，单位为vp。 1903 1904**参数：** 1905 1906| 名称 | 描述 | 1907| ----------- | ------------------------------------------------------------ | 1908| startOptions | StartOptions结构体。 | 1909| maxWindowWidth | 获取到的最大窗口宽度，单位为vp。 | 1910 1911**起始版本：** 17 1912 1913**返回：** 1914 1915ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 1916 1917ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1918 1919**示例代码：** 1920```cpp 1921#include <AbilityKit/ability_runtime/start_options.h> 1922 1923void demo() 1924{ 1925 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1926 if (options == nullptr) { 1927 // 记录错误日志以及其他业务处理 1928 return; 1929 } 1930 1931 int32_t maxWindowWidth = 0; 1932 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsMaxWindowWidth(options, maxWindowWidth); 1933 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1934 // 记录错误日志以及其他业务处理 1935 } 1936 1937 // 销毁options，防止内存泄漏 1938 OH_AbilityRuntime_DestroyStartOptions(&options); 1939} 1940``` 1941 1942### OH_AbilityRuntime_SetStartOptionsMinWindowHeight 1943 1944``` 1945AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMinWindowHeight(AbilityRuntime_StartOptions *startOptions, 1946 int32_t minWindowHeight) 1947``` 1948 1949**描述** 1950 1951设置启动Ability时的最小窗口高度，单位为vp。 1952 1953**参数：** 1954 1955| 名称 | 描述 | 1956| ----------- | ------------------------------------------------------------ | 1957| startOptions | StartOptions结构体。 | 1958| minWindowHeight | 需要设置的最小窗口高度，单位为vp。 | 1959 1960**起始版本：** 17 1961 1962**返回：** 1963 1964ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 1965 1966ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 1967 1968**示例代码：** 1969```cpp 1970#include <AbilityKit/ability_runtime/start_options.h> 1971 1972void demo() 1973{ 1974 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 1975 if (options == nullptr) { 1976 // 记录错误日志以及其他业务处理 1977 return; 1978 } 1979 1980 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsMinWindowHeight(options, 100); 1981 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 1982 // 记录错误日志以及其他业务处理 1983 } 1984 1985 // 销毁options，防止内存泄漏 1986 OH_AbilityRuntime_DestroyStartOptions(&options); 1987} 1988``` 1989 1990### OH_AbilityRuntime_GetStartOptionsMinWindowHeight 1991 1992``` 1993AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMinWindowHeight(AbilityRuntime_StartOptions *startOptions, 1994 int32_t &minWindowHeight) 1995``` 1996 1997**描述** 1998 1999获取启动Ability时的最小窗口高度，单位为vp。 2000 2001**参数：** 2002 2003| 名称 | 描述 | 2004| ----------- | ------------------------------------------------------------ | 2005| startOptions | StartOptions结构体。 | 2006| minWindowHeight | 获取到的最小窗口高度，单位为vp。 | 2007 2008**起始版本：** 17 2009 2010**返回：** 2011 2012ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 2013 2014ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 2015 2016**示例代码：** 2017```cpp 2018#include <AbilityKit/ability_runtime/start_options.h> 2019 2020void demo() 2021{ 2022 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 2023 if (options == nullptr) { 2024 // 记录错误日志以及其他业务处理 2025 return; 2026 } 2027 2028 int32_t minWindowHeight = 0; 2029 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsMinWindowHeight(options, minWindowHeight); 2030 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 2031 // 记录错误日志以及其他业务处理 2032 } 2033 2034 // 销毁options，防止内存泄漏 2035 OH_AbilityRuntime_DestroyStartOptions(&options); 2036} 2037``` 2038 2039### OH_AbilityRuntime_SetStartOptionsMaxWindowHeight 2040 2041``` 2042AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMaxWindowHeight(AbilityRuntime_StartOptions *startOptions, 2043 int32_t maxWindowHeight) 2044``` 2045 2046**描述** 2047 2048设置启动Ability时的最大窗口高度，单位为vp。 2049 2050**参数：** 2051 2052| 名称 | 描述 | 2053| ----------- | ------------------------------------------------------------ | 2054| startOptions | StartOptions结构体。 | 2055| maxWindowHeight | 需要设置的最大窗口高度，单位为vp。 | 2056 2057**起始版本：** 17 2058 2059**返回：** 2060 2061ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 设置成功。 2062 2063ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 2064 2065**示例代码：** 2066```cpp 2067#include <AbilityKit/ability_runtime/start_options.h> 2068 2069void demo() 2070{ 2071 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 2072 if (options == nullptr) { 2073 // 记录错误日志以及其他业务处理 2074 return; 2075 } 2076 2077 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_SetStartOptionsMaxWindowHeight(options, 100); 2078 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 2079 // 记录错误日志以及其他业务处理 2080 } 2081 2082 // 销毁options，防止内存泄漏 2083 OH_AbilityRuntime_DestroyStartOptions(&options); 2084} 2085``` 2086 2087### OH_AbilityRuntime_GetStartOptionsMaxWindowHeight 2088 2089``` 2090AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMaxWindowHeight(AbilityRuntime_StartOptions *startOptions, 2091 int32_t &maxWindowHeight) 2092``` 2093 2094**描述** 2095 2096获取启动Ability时的最大窗口高度，单位为vp。 2097 2098**参数：** 2099 2100| 名称 | 描述 | 2101| ----------- | ------------------------------------------------------------ | 2102| startOptions | StartOptions结构体。 | 2103| maxWindowHeight | 获取到的最大窗口高度，单位为vp。 | 2104 2105**起始版本：** 17 2106 2107**返回：** 2108 2109ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 获取成功。 2110 2111ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - StartOptions为空。 2112 2113**示例代码：** 2114```cpp 2115#include <AbilityKit/ability_runtime/start_options.h> 2116 2117void demo() 2118{ 2119 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 2120 if (options == nullptr) { 2121 // 记录错误日志以及其他业务处理 2122 return; 2123 } 2124 2125 int32_t maxWindowHeight = 0; 2126 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_GetStartOptionsMaxWindowHeight(options, maxWindowHeight); 2127 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 2128 // 记录错误日志以及其他业务处理 2129 } 2130 2131 // 销毁options，防止内存泄漏 2132 OH_AbilityRuntime_DestroyStartOptions(&options); 2133} 2134``` 2135 2136### OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions 2137 2138``` 2139AbilityRuntime_ErrorCode OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(AbilityBase_Want *want, AbilityRuntime_StartOptions *options) 2140``` 2141 2142**描述** 2143 2144启动当前应用的UIAbility。 2145 2146> **说明：** 2147> 2148> 当前仅支持2in1设备。 2149 2150**需要权限**：ohos.permission.NDK_START_SELF_UI_ABILITY 2151 2152**起始版本：** 17 2153 2154**参数：** 2155 2156| 名称 | 描述 | 2157| ----------- | ------------------------------------------------------------ | 2158| want | 启动当前应用UIAbility时需要的Want信息。 | 2159| options | 启动当前应用UIAbility时需要的StartOptions信息。<br>**说明：**<br>如果该参数中[startVisibility](#abilityruntime_startvisibility)属性的值不为空，必须确保当前应用已添加到状态栏，否则会返回ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED错误码。 | 2160 2161**返回：** 2162 2163ABILITY_RUNTIME_ERROR_CODE_NO_ERROR - 成功。 2164 2165ABILITY_RUNTIME_ERROR_CODE_PERMISSION_DENIED - 权限校验失败。 2166 2167ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID - Want或者StartOptions为空，或者Want信息里bundleName或abilityName为空。 2168 2169ABILITY_RUNTIME_ERROR_CODE_NOT_SUPPORTED - 设备类型不支持。 2170 2171ABILITY_RUNTIME_ERROR_CODE_NO_SUCH_ABILITY - 指定的Ability名称不存在。 2172 2173ABILITY_RUNTIME_ERROR_CODE_INCORRECT_ABILITY_TYPE - 接口调用Ability类型错误。 2174 2175ABILITY_RUNTIME_ERROR_CODE_CROWDTEST_EXPIRED - 众测应用到期。 2176 2177ABILITY_RUNTIME_ERROR_CODE_WUKONG_MODE - wukong模式，不允许启动/停止Ability。 2178 2179ABILITY_RUNTIME_ERROR_CODE_CONTROLLED - 应用被管控。 2180 2181ABILITY_RUNTIME_ERROR_CODE_EDM_CONTROLLED - 应用被EDM管控。 2182 2183ABILITY_RUNTIME_ERROR_CODE_CROSS_APP - 禁止拉起其他应用。 2184 2185ABILITY_RUNTIME_ERROR_CODE_INTERNAL - 内部错误。 2186 2187ABILITY_RUNTIME_ERROR_CODE_NOT_TOP_ABILITY - 当前应用不是前台进程。 2188 2189ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED - 禁止设置应用启动可见性。 2190 2191ABILITY_RUNTIME_ERROR_CODE_MULTI_APP_NOT_SUPPORTED - 应用不支持分身和多实例。 2192 2193ABILITY_RUNTIME_ERROR_CODE_INVALID_APP_INSTANCE_KEY - 传入的instanceKey无效。 2194 2195ABILITY_RUNTIME_ERROR_CODE_UPPER_LIMIT_REACHED - 多实例已达到上限。 2196 2197ABILITY_RUNTIME_ERROR_MULTI_INSTANCE_NOT_SUPPORTED - 应用不支持多实例。 2198 2199ABILITY_RUNTIME_ERROR_CODE_APP_INSTANCE_KEY_NOT_SUPPORTED - APP_INSTANCE_KEY不能被赋值。 2200 2201**示例代码：** 2202```cpp 2203#include <AbilityKit/ability_base/want.h> 2204#include <AbilityKit/ability_runtime/application_context.h> 2205 2206void demo() 2207{ 2208 AbilityBase_Element element; 2209 element.abilityName = const_cast<char*>("EntryAbility"); 2210 element.bundleName = const_cast<char*>("com.exampl.myapplication"); 2211 element.moduleName = const_cast<char*>("entry"); 2212 AbilityBase_Want* want = OH_AbilityBase_CreateWant(element); 2213 if (want == nullptr) { 2214 // 记录错误日志以及其他业务处理 2215 return; 2216 } 2217 2218 AbilityRuntime_StartOptions* options = OH_AbilityRuntime_CreateStartOptions(); 2219 if (options == nullptr) { 2220 // 记录错误日志以及其他业务处理 2221 2222 // 销毁want，防止内存泄漏 2223 OH_AbilityBase_DestroyWant(want); 2224 return; 2225 } 2226 AbilityRuntime_ErrorCode err = OH_AbilityRuntime_StartSelfUIAbilityWithStartOptions(want, options); 2227 if (err != ABILITY_RUNTIME_ERROR_CODE_NO_ERROR) { 2228 // 记录错误日志以及其他业务处理 2229 } 2230 // 销毁want，防止内存泄漏 2231 OH_AbilityBase_DestroyWant(want); 2232 2233 // 销毁options，防止内存泄漏 2234 OH_AbilityRuntime_DestroyStartOptions(&options); 2235} 2236``` 2237