include/app.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_APPFW_APP_H__
  19 #define __TIZEN_APPFW_APP_H__
  20
  21 #include <tizen.h>
  22 #include <app_service.h>
  23 #include <app_control.h>
  24 #include <app_alarm.h>
  25 #include <app_common.h>
  26 #include <app_preference.h>
  27 #include <app_i18n.h>
  28 #include <app_types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @addtogroup CAPI_APPLICATION_MODULE
  36  * @{
  37  */
  38
  39
  40 /**
  41  * @brief Called when the application starts.
  42  *
  43  * @details The callback function is called before the main loop of the application starts.
  44  *          In this callback, you can initialize application resources like window creation, data structure, and so on.
  45  *          After this callback function returns @c true, the main loop starts up and app_control_cb() is subsequently called.
  46  *          If this callback function returns @c false, the main loop doesn't start and app_terminate_cb() is subsequently called.
  47  *
  48  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  49  * @param[in] user_data The user data passed from the callback registration function
  50  * @return @c true on success,
  51  *         otherwise @c false
  52  * @pre ui_app_main() will invoke this callback function.
  53  * @see ui_app_main()
  54  * @see #ui_app_lifecycle_callback_s
  55  */
  56 typedef bool (*app_create_cb) (void *user_data);
  57
  58
  59 /**
  60  * @brief Called when the application is completely obscured by another application and becomes invisible.
  61  *
  62  * @details The application is not terminated and still running in the paused state.
  63  *
  64  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  65  * @param[in] user_data The user data passed from the callback registration function
  66  * @see ui_app_main()
  67  * @see #ui_app_lifecycle_callback_s
  68  */
  69 typedef void (*app_pause_cb) (void *user_data);
  70
  71
  72 /**
  73  * @brief Called when the application becomes visible.
  74  *
  75  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  76  *
  77  * @param[in] user_data The user data passed from the callback registration function
  78  * @see ui_app_main()
  79  * @see #ui_app_lifecycle_callback_s
  80  */
  81 typedef void (*app_resume_cb) (void *user_data);
  82
  83
  84 /**
  85  * @brief Called when the application's main loop exits.
  86  * @details You should release the application's resources in this function.
  87  *
  88  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  89  * @param[in] user_data The user data passed from the callback registration function
  90  * @see ui_app_main()
  91  * @see #ui_app_lifecycle_callback_s
  92  */
  93 typedef void (*app_terminate_cb) (void *user_data);
  94
  95
  96 /**
  97  * @brief Called when another application sends a launch request to the application.
  98  *
  99  * @details When the application is launched, this callback function is called after the main loop of the application starts up.
 100  *          The passed app_control handle describes the launch request and contains the information about why the application is launched.
 101  *          If the launch request is sent to the application in the running or pause state,
 102  *          this callback function can be called again to notify that the application has been asked to launch.
 103  *
 104  *          The application could be explicitly launched by the user from the application launcher or be launched to perform the specific operation by another application.
 105  *          The application is responsible for handling each launch request and responding appropriately.
 106  *          Using the App Control API, the application can get information about what is to be performed.
 107  *          If the application is launched from the application launcher or explicitly launched by another application,
 108  *          the passed app_control handle may include only the default operation (#APP_CONTROL_OPERATION_DEFAULT) without any data.
 109  *          For more information, see The @ref CAPI_APP_CONTROL_MODULE API description.
 110  *
 111  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 112  * @param[in] app_control The handle to the app_control
 113  * @param[in] user_data The user data passed from the callback registration function
 114  * @see ui_app_main()
 115  * @see #ui_app_lifecycle_callback_s
 116  * @see @ref CAPI_APP_CONTROL_MODULE API
 117  */
 118 typedef void (*app_control_cb) (app_control_h app_control, void *user_data);
 119
 120
 121 /**
 122  * @brief Called when other application send the launch request to the application.
 123  *
 124  * @details When the application is launched, this callback function is called after the main loop of application starts up.
 125  * The passed service handle describes the launch request and contains the information about why the application is launched.
 126  * If the launch request is sent to the application on running or pause state,
 127  * this callback function can be called again to notify that the application is asked to be launched.
 128  *
 129  * The application could be explicitly launched by the user from the application launcher or be launched to perform the specific operation by other application.
 130  * The application is responsible for handling the each launch request and responding appropriately.
 131  * Using the Service API, the application can get the information what has to perform.
 132  * If the application is launched from the application launcher or explicitly launched by other application,
 133  * the passed service handle may include only the default operation (#SERVICE_OPERATION_DEFAULT) without any data
 134  * For more information, see The @ref CAPI_SERVICE_MODULE API description.
 135  *
 136  * @param[in]   service The handle to the service
 137  * @param[in]   user_data       The user data passed from the callback registration function
 138  * @see app_efl_main()
 139  * @see #app_event_callback_s
 140  * @see @ref CAPI_SERVICE_MODULE API
 141  */
 142 typedef void (*app_service_cb) (service_h service, void *user_data);
 143
 144
 145 /**
 146  * @brief   Called when the system memory is running low.
 147  *
 148  * @details
 149  * When low memory event is dispatched, the application should immediately save state and release resources to save as much memory as possible. \n
 150  * If enough memory is not reclaimed during low memory conditions, the system will terminate some of the applications to reclaim the memory.
 151  *
 152  * @param[in]   user_data       The user data passed from the callback registration function
 153  * @see app_efl_main()
 154  * @see #app_event_callback_s
 155  */
 156 typedef void (*app_low_memory_cb) (void *user_data);
 157
 158
 159 /**
 160  * @brief   Called when the battery power is running low.
 161  * @details When the battery level falls below 5%, it is called.
 162  *
 163  * @param[in]   user_data       The user data passed from the callback registration function
 164  * @see app_efl_main()
 165  * @see #app_event_callback_s
 166  */
 167 typedef void (*app_low_battery_cb) (void *user_data);
 168
 169
 170 /**
 171  * @brief   Called when the orientation of device changes.
 172  *
 173  * @param[in]   orientation     The orientation of device
 174  * @param[in]   user_data       The user data passed from the callback registration function
 175  * @see app_efl_main()
 176  * @see #app_event_callback_s
 177  */
 178 typedef void (*app_device_orientation_cb) (app_device_orientation_e orientation, void *user_data);
 179
 180
 181 /**
 182  * @brief   Called when language setting changes.
 183  *
 184  * @param   [in] user_data The user data passed from the callback registration function
 185  * @see app_efl_main()
 186  * @see #app_event_callback_s
 187  */
 188 typedef void (*app_language_changed_cb) (void *user_data);
 189
 190
 191 /**
 192  * @brief   Called when region format setting changes.
 193  *
 194  * @param   [in] user_data The user data passed from the callback registration function
 195  * @see app_efl_main()
 196  * @see #app_event_callback_s
 197  */
 198 typedef void (*app_region_format_changed_cb) (void *user_data);
 199
 200
 201 /**
 202  * @brief The structure type to contain the set of callback functions for handling application events.
 203  * @details It is one of the input parameters of the app_efl_main() function.
 204  *
 205  * @see app_efl_main()
 206  * @see app_create_cb()
 207  * @see app_pause_cb()
 208  * @see app_resume_cb()
 209  * @see app_terminate_cb()
 210  * @see app_service_cb()
 211  * @see app_low_memory_cb()
 212  * @see app_low_battery_cb()
 213  * @see app_device_orientation_cb()
 214  * @see app_language_changed_cb()
 215  * @see app_region_format_changed_cb()
 216  */
 217 typedef struct
 218 {
 219         app_create_cb create; /**< This callback function is called at the start of the application. */
 220         app_terminate_cb terminate; /**< This callback function is called once after the main loop of application exits. */
 221         app_pause_cb pause; /**< This callback function is called each time the application is completely obscured by another application and becomes invisible to the user. */
 222         app_resume_cb resume; /**< This callback function is called each time the application becomes visible to the user. */
 223         app_service_cb service; /**< This callback function is called when other application send the launch request to the application. */
 224         app_low_memory_cb low_memory; /**< The registered callback function is called when the system runs low on memory. */
 225         app_low_battery_cb low_battery; /**< The registered callback function is called when battery is low. */
 226         app_device_orientation_cb device_orientation; /**< The registered callback function is called when the orientation of device changes */
 227         app_language_changed_cb language_changed; /**< The registered callback function is called when language setting changes. */
 228         app_region_format_changed_cb region_format_changed; /**< The registered callback function is called when region format setting is changes. */
 229 } app_event_callback_s;
 230
 231 /**
 232  * @brief The structure type containing the set of callback functions for handling application lifecycle events.
 233  * @details It is one of the input parameters of the ui_app_main() function.
 234  *
 235  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 236  * @see ui_app_main()
 237  * @see app_create_cb()
 238  * @see app_pause_cb()
 239  * @see app_resume_cb()
 240  * @see app_terminate_cb()
 241  * @see app_control_cb()
 242  */
 243 typedef struct
 244 {
 245         app_create_cb create; /**< This callback function is called at the start of the application. */
 246         app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
 247         app_pause_cb pause; /**< This callback function is called each time the application is completely obscured by another application and becomes invisible to the user. */
 248         app_resume_cb resume; /**< This callback function is called each time the application becomes visible to the user. */
 249         app_control_cb app_control; /**< This callback function is called when another application sends the launch request to the application. */
 250 } ui_app_lifecycle_callback_s;
 251
 252
 253 /**
 254  * @brief Runs the main loop of application until app_efl_exit() is called
 255  *
 256  * @details This function is the main entry point of the Tizen application.
 257  * The app_create_cb() callback function is called to initialize the application before the main loop of application starts up.
 258  * After the app_create_cb() callback function returns true, the main loop starts up and the app_service_cb() callback function is subsequently called.
 259  * If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called
 260  *
 261  * @param [in] argc The argument count
 262  * @param [in] argv The argument vector
 263  * @param [in] callback The set of callback functions to handle application events
 264  * @param [in] user_data The user data to be passed to the callback functions
 265  *
 266  * @return 0 on success, otherwise a negative error value.
 267  * @retval #APP_ERROR_NONE Successful
 268  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 269  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system.
 270  * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts
 271  *
 272  * @see app_create_cb()
 273  * @see app_terminate_cb()
 274  * @see app_pause_cb()
 275  * @see app_resume_cb()
 276  * @see app_service_cb()
 277  * @see app_low_memory_cb()
 278  * @see app_low_battery_cb()
 279  * @see app_device_orientation_cb()
 280  * @see app_language_changed_cb()
 281  * @see app_region_format_changed_cb()
 282  * @see app_efl_exit()
 283  * @see #app_event_callback_s
 284  */
 285 int app_efl_main(int *argc, char ***argv, app_event_callback_s *callback, void *user_data);
 286
 287
 288 /**
 289  * @brief Exits the main loop of application.
 290  *
 291  * @details The main loop of application stops and app_terminate_cb() is invoked
 292  * @see app_efl_main()
 293  * @see app_terminate_cb()
 294  */
 295 void app_efl_exit(void);
 296
 297
 298 /**
 299  * @brief Gets the current device orientation.
 300  *
 301  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 302  * @return The current device orientation
 303  */
 304 app_device_orientation_e app_get_device_orientation(void);
 305
 306
 307 /**
 308  * @brief Sets whether reclaiming system cache is enabled in the pause state.
 309  *
 310  * @details If the reclaiming system cache is enabled, the system caches are released as possible when the application's state changes to the pause state.
 311  *
 312  * @remarks The reclaiming system cache is enabled by default
 313  *
 314  * @param [in] enable whether reclaiming system cache is enabled
 315  */
 316 void app_set_reclaiming_system_cache_on_pause(bool enable);
 317
 318 /**
 319  * @brief Runs the application's main loop until ui_app_exit() is called.
 320  *
 321  * @details This function is the main entry point of the Tizen application.
 322  *          The app_create_cb() callback function is called to initialize the application before the main loop of application starts up.
 323  *          After the app_create_cb() callback function returns true, the main loop starts up and the app_control_cb() callback function is subsequently called.
 324  *          If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called.
 325  *          This main loop supports event handling for the Ecore Main Loop.
 326  *
 327  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 328  * @param[in] argc The argument count
 329  * @param[in] argv The argument vector
 330  * @param[in] callback The set of callback functions to handle application lifecycle events
 331  * @param[in] user_data The user data to be passed to the callback functions
 332  *
 333  * @return 0 on success, otherwise a negative error value
 334  * @retval #APP_ERROR_NONE Successful
 335  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 336  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 337  * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts
 338  *
 339  * @see app_create_cb()
 340  * @see app_terminate_cb()
 341  * @see app_pause_cb()
 342  * @see app_resume_cb()
 343  * @see app_control_cb()
 344  * @see ui_app_exit()
 345  * @see #ui_app_lifecycle_callback_s
 346  */
 347 int ui_app_main(int argc, char **argv, ui_app_lifecycle_callback_s *callback, void *user_data);
 348
 349
 350 /**
 351  * @brief Exits the main loop of application.
 352  *
 353  * @details The main loop of application stops and app_terminate_cb() is invoked.
 354  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 355  *
 356  * @see ui_app_main()
 357  * @see app_terminate_cb()
 358  */
 359 void ui_app_exit(void);
 360
 361
 362 /**
 363  * @brief Adds the system event handler
 364  *
 365  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 366  * @param[out] event_handler The event handler
 367  * @param[in] event_type The system event type
 368  * @param[in] callback The callback function
 369  * @param[in] user_data The user data to be passed to the callback functions
 370  *
 371  * @return 0 on success, otherwise a negative error value
 372  * @retval #APP_ERROR_NONE Successful
 373  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 374  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 375  *
 376  * @see app_event_type_e
 377  * @see app_event_cb
 378  * @see ui_app_remove_event_handler
 379  */
 380 int ui_app_add_event_handler(app_event_handler_h *event_handler, app_event_type_e event_type, app_event_cb callback, void *user_data);
 381
 382
 383 /**
 384  * @brief Removes registered event handler
 385  *
 386  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 387  * @param[in] event_handler The event handler
 388  *
 389  * @return 0 on success, otherwise a negative error value
 390  * @retval #APP_ERROR_NONE Successful
 391  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 392  *
 393  * @see ui_app_add_event_handler
 394  */
 395 int ui_app_remove_event_handler(app_event_handler_h event_handler);
 396
 397
 398 /**
 399  * @}
 400  */
 401
 402 #ifdef __cplusplus
 403 }
 404 #endif
 405 #endif /* __TIZEN_APPFW_APP_H__ */