1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup AbilityRuntime 18 * @{ 19 * 20 * @brief Describe the functions provided by the start options. 21 * 22 * @syscap SystemCapability.Ability.AbilityRuntime.Core 23 * @since 17 24 */ 25 26 /** 27 * @file start_options.h 28 * 29 * @brief Defines the start options APIs. 30 * 31 * @library libability_runtime.so 32 * @kit AbilityKit 33 * @syscap SystemCapability.Ability.AbilityRuntime.Core 34 * @since 17 35 */ 36 37 #ifndef ABILITY_RUNTIME_START_OPTIONS_H 38 #define ABILITY_RUNTIME_START_OPTIONS_H 39 40 #include <stdint.h> 41 #include <stddef.h> 42 #include "ability_runtime_common.h" 43 #include "context_constant.h" 44 #include "multimedia/image_framework/image/pixelmap_native.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 struct AbilityRuntime_StartOptions; 51 typedef struct AbilityRuntime_StartOptions AbilityRuntime_StartOptions; 52 53 /** 54 * @brief Create start options. 55 * 56 * @return Returns the newly created AbilityRuntime_StartOptions object. 57 * 58 * @since 17 59 */ 60 AbilityRuntime_StartOptions* OH_AbilityRuntime_CreateStartOptions(void); 61 62 /** 63 * @brief Destroy input start options. 64 * 65 * @param startOptions The options to be deleted. 66 * @return The error code. 67 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 68 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 69 * @since 17 70 */ 71 AbilityRuntime_ErrorCode OH_AbilityRuntime_DestroyStartOptions(AbilityRuntime_StartOptions **startOptions); 72 73 /** 74 * @brief Set window mode for start options. 75 * 76 * @param startOptions The options to set window mode for. 77 * @param windowMode The window mode. 78 * @return The error code. 79 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 80 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions or windowMode is invalid. 81 * @since 17 82 */ 83 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowMode(AbilityRuntime_StartOptions *startOptions, 84 AbilityRuntime_WindowMode windowMode); 85 86 /** 87 * @brief Get window mode from start options. 88 * 89 * @param startOptions The options to get window mode from. 90 * @param windowMode The obtained window mode. 91 * @return The error code. 92 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 93 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 94 * @since 17 95 */ 96 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowMode(AbilityRuntime_StartOptions *startOptions, 97 AbilityRuntime_WindowMode &windowMode); 98 99 /** 100 * @brief Set display id for start options. 101 * 102 * @param startOptions The options to set display id for. 103 * @param displayId The display id. 104 * @return The error code. 105 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 106 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 107 * @since 17 108 */ 109 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsDisplayId(AbilityRuntime_StartOptions *startOptions, 110 int32_t displayId); 111 112 /** 113 * @brief Get display id from start options. 114 * 115 * @param startOptions The options to get display id from. 116 * @param displayId The obtained display id. 117 * @return The error code. 118 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 119 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 120 * @since 17 121 */ 122 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsDisplayId(AbilityRuntime_StartOptions *startOptions, 123 int32_t &displayId); 124 125 /** 126 * @brief Set with animation flag for start options. 127 * 128 * @param startOptions The options to set with animation for. 129 * @param withAnimation The with animation. 130 * @return The error code. 131 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 132 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 133 * @since 17 134 */ 135 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWithAnimation(AbilityRuntime_StartOptions *startOptions, 136 bool withAnimation); 137 138 /** 139 * @brief Get with animation from start options. 140 * 141 * @param startOptions The options to get with animation from. 142 * @param withAnimation The obtained with animation. 143 * @return The error code. 144 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 145 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 146 * @since 17 147 */ 148 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWithAnimation(AbilityRuntime_StartOptions *startOptions, 149 bool &withAnimation); 150 151 /** 152 * @brief Set window left for start options. 153 * 154 * @param startOptions The options to set window left for. 155 * @param windowLeft The window left. 156 * @return The error code. 157 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 158 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 159 * @since 17 160 */ 161 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowLeft(AbilityRuntime_StartOptions *startOptions, 162 int32_t windowLeft); 163 164 /** 165 * @brief Get window left from start options. 166 * 167 * @param startOptions The options to get window left from. 168 * @param windowLeft The obtained window left. 169 * @return The error code. 170 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 171 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 172 * @since 17 173 */ 174 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowLeft(AbilityRuntime_StartOptions *startOptions, 175 int32_t &windowLeft); 176 177 /** 178 * @brief Set window top for start options. 179 * 180 * @param startOptions The options to set window top for. 181 * @param windowTop The window top. 182 * @return The error code. 183 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 184 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 185 * @since 17 186 */ 187 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowTop(AbilityRuntime_StartOptions *startOptions, 188 int32_t windowTop); 189 190 /** 191 * @brief Get window top from start options. 192 * 193 * @param startOptions The options to get window top from. 194 * @param windowTop The obtained window top. 195 * @return The error code. 196 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 197 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 198 * @since 17 199 */ 200 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowTop(AbilityRuntime_StartOptions *startOptions, 201 int32_t &windowTop); 202 203 /** 204 * @brief Set window height for start options. 205 * 206 * @param startOptions The options to set window height for. 207 * @param windowHeight The window height. 208 * @return The error code. 209 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 210 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 211 * @since 17 212 */ 213 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowHeight(AbilityRuntime_StartOptions *startOptions, 214 int32_t windowHeight); 215 216 /** 217 * @brief Get window height from start options. 218 * 219 * @param startOptions The options to get window height from. 220 * @param windowHeight The obtained window height. 221 * @return The error code. 222 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 223 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 224 * @since 17 225 */ 226 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowHeight(AbilityRuntime_StartOptions *startOptions, 227 int32_t &windowHeight); 228 229 /** 230 * @brief Set window width for start options. 231 * 232 * @param startOptions The options to set window width for. 233 * @param windowWidth The window width. 234 * @return The error code. 235 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 236 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 237 * @since 17 238 */ 239 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsWindowWidth(AbilityRuntime_StartOptions *startOptions, 240 int32_t windowWidth); 241 242 /** 243 * @brief Get window width from start options. 244 * 245 * @param startOptions The options to get window width from. 246 * @param windowWidth The obtained window width. 247 * @return The error code. 248 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 249 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 250 * @since 17 251 */ 252 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsWindowWidth(AbilityRuntime_StartOptions *startOptions, 253 int32_t &windowWidth); 254 255 /** 256 * @brief Set start visibility for start options. 257 * 258 * @param startOptions The options to set start visibility for. 259 * @param startVisibility The start visibility. 260 * @return The error code. 261 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 262 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 263 * @since 17 264 */ 265 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsStartVisibility(AbilityRuntime_StartOptions *startOptions, 266 AbilityRuntime_StartVisibility startVisibility); 267 268 /** 269 * @brief Get start visibility from start options. 270 * 271 * @param startOptions The options to get start visibility from. 272 * @param startVisibility The obtained start visibility. 273 * @return The error code. 274 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 275 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 276 * @since 17 277 */ 278 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsStartVisibility(AbilityRuntime_StartOptions *startOptions, 279 AbilityRuntime_StartVisibility &startVisibility); 280 281 /** 282 * @brief Set start window icon for start options. 283 * 284 * @param startOptions The options to set start window icon for. 285 * @param startWindowIcon The start window icon. 286 * @return The error code. 287 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 288 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid 289 * or startWindowIcon is nullptr. 290 * @since 17 291 */ 292 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsStartWindowIcon(AbilityRuntime_StartOptions *startOptions, 293 OH_PixelmapNative *startWindowIcon); 294 295 /** 296 * @brief Get start window icon from start options. 297 * 298 * @param startOptions The options to get start window icon from. 299 * @param startWindowIcon The obtained start window icon. 300 * @return The error code. 301 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 302 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid 303 * or startWindowIcon is NOT nullptr. 304 * @since 17 305 */ 306 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsStartWindowIcon(AbilityRuntime_StartOptions *startOptions, 307 OH_PixelmapNative **startWindowIcon); 308 309 /** 310 * @brief Set start window background color for start options. 311 * 312 * @param startOptions The options to set start window background color for. 313 * @param startWindowBackgroundColor The start window background color. 314 * @return The error code. 315 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 316 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid 317 * or startWindowBackgroundColor is nullptr. 318 * @since 17 319 */ 320 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsStartWindowBackgroundColor( 321 AbilityRuntime_StartOptions *startOptions, const char *startWindowBackgroundColor); 322 323 /** 324 * @brief Get start window background color from start options. 325 * 326 * @param startOptions The options to get start window background color from. 327 * @param startWindowBackgroundColor The obtained start window background color. 328 * @param size The size of start window background color. 329 * @return The error code. 330 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 331 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid 332 * or startWindowBackgroundColor is NOT nullptr. 333 * {@link ABILITY_RUNTIME_ERROR_CODE_INTERNAL} if error occurred in malloc. 334 * @since 17 335 */ 336 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsStartWindowBackgroundColor( 337 AbilityRuntime_StartOptions *startOptions, char **startWindowBackgroundColor, size_t &size); 338 339 /** 340 * @brief Set start window modes for start options. 341 * 342 * @param startOptions The options to set start window modes for. 343 * @param supportedWindowModes The start window modes. 344 * @param size The size of start window modes. 345 * @return The error code. 346 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 347 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions or supportWindowMode 348 * or size is invalid. 349 * @since 17 350 */ 351 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsSupportedWindowModes( 352 AbilityRuntime_StartOptions *startOptions, AbilityRuntime_SupportedWindowMode *supportedWindowModes, 353 size_t size); 354 355 /** 356 * @brief Get start window modes from start options. 357 * 358 * @param startOptions The options to get start window modes from. 359 * @param supportedWindowModes The obtained start window modes. 360 * @param size The size of the returned start window modes. 361 * @return The error code. 362 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 363 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invallid 364 * or supportWindowMode is NOT nullptr 365 * {@link ABILITY_RUNTIME_ERROR_CODE_INTERNAL} if error occurred in malloc. 366 * @since 17 367 */ 368 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsSupportedWindowModes( 369 AbilityRuntime_StartOptions *startOptions, AbilityRuntime_SupportedWindowMode **supportedWindowModes, 370 size_t &size); 371 372 /** 373 * @brief Set min window width for start options. 374 * 375 * @param startOptions The options to set min window width for. 376 * @param minWindowWidth The min window width. 377 * @return The error code. 378 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 379 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 380 * @since 17 381 */ 382 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMinWindowWidth( 383 AbilityRuntime_StartOptions *startOptions, int32_t minWindowWidth); 384 385 /** 386 * @brief Get min window width from start options. 387 * 388 * @param startOptions The options to get min window width from. 389 * @param minWindowWidth The obtained min window width. 390 * @return The error code. 391 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 392 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 393 * @since 17 394 */ 395 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMinWindowWidth( 396 AbilityRuntime_StartOptions *startOptions, int32_t &minWindowWidth); 397 398 /** 399 * @brief Set max window width for start options. 400 * 401 * @param startOptions The options to set max window width for. 402 * @param maxWindowWidth The max window width. 403 * @return The error code. 404 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 405 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 406 * @since 17 407 */ 408 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMaxWindowWidth( 409 AbilityRuntime_StartOptions *startOptions, int32_t maxWindowWidth); 410 411 /** 412 * @brief Get max window width from start options. 413 * 414 * @param startOptions The options to get max window width from. 415 * @param maxWindowWidth The obtained max window width. 416 * @return The error code. 417 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 418 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 419 * @since 17 420 */ 421 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMaxWindowWidth( 422 AbilityRuntime_StartOptions *startOptions, int32_t &maxWindowWidth); 423 424 /** 425 * @brief Set min window height for start options. 426 * 427 * @param startOptions The options to set min window height for. 428 * @param minWindowHeight The min window height. 429 * @return The error code. 430 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 431 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 432 * @since 17 433 */ 434 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMinWindowHeight( 435 AbilityRuntime_StartOptions *startOptions, int32_t minWindowHeight); 436 437 /** 438 * @brief Get min window height from start options. 439 * 440 * @param startOptions The options to get min window height from. 441 * @param minWindowHeight The obtained min window height. 442 * @return The error code. 443 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 444 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 445 * @since 17 446 */ 447 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMinWindowHeight( 448 AbilityRuntime_StartOptions *startOptions, int32_t &minWindowHeight); 449 450 /** 451 * @brief Set max window height for start options. 452 * 453 * @param startOptions The options to set max window height for. 454 * @param maxWindowHeight The max window height. 455 * @return The error code. 456 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 457 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 458 * @since 17 459 */ 460 AbilityRuntime_ErrorCode OH_AbilityRuntime_SetStartOptionsMaxWindowHeight( 461 AbilityRuntime_StartOptions *startOptions, int32_t maxWindowHeight); 462 463 /** 464 * @brief Get max window height from start options. 465 * 466 * @param startOptions The options to get max window height from. 467 * @param maxWindowHeight The obtained max window height. 468 * @return The error code. 469 * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} if the operation is successful. 470 * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID} if the startOptions is invalid. 471 * @since 17 472 */ 473 AbilityRuntime_ErrorCode OH_AbilityRuntime_GetStartOptionsMaxWindowHeight( 474 AbilityRuntime_StartOptions *startOptions, int32_t &maxWindowHeight); 475 476 #ifdef __cplusplus 477 } // extern "C" 478 #endif 479 480 /** @} */ 481 #endif // ABILITY_RUNTIME_START_OPTIONS_H