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