include/app_internal.h

   1 /*
   2  * Copyright (c) 2011 - 2016 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_INTERNAL_H__
  19 #define __TIZEN_APPFW_APP_INTERNAL_H__
  20
  21 #include <app.h>
  22
  23 /* GNU gettext macro is already defined at appcore-common.h */
  24 #ifdef _
  25 #undef _
  26 #endif
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 typedef void *appcore_context_h;
  33
  34 /**
  35  * @internal
  36  * @brief Called when the system memory is running low.
  37  *
  38  * @details When a low memory event is dispatched, the application should immediately save state and release resources to save as much memory as possible. \n
  39  *          If enough memory is not reclaimed during low memory conditions, the system will terminate some of the applications to reclaim the memory.
  40  *
  41  * @since_tizen 2.3
  42  * @param[in] user_data The user data passed from the callback registration function
  43  * @see app_main()
  44  * @see #app_event_callback_s
  45  */
  46 typedef void (*app_low_memory_cb) (void *user_data);
  47
  48 /**
  49  * @internal
  50  * @brief Called when the battery power is running low.
  51  * @details When the battery level falls below 5%, it is called.
  52  *
  53  * @since_tizen 2.3
  54  * @param[in] user_data The user data passed from the callback registration function
  55  * @see app_main()
  56  * @see #app_event_callback_s
  57  */
  58 typedef void (*app_low_battery_cb) (void *user_data);
  59
  60 /**
  61  * @internal
  62  * @brief Called when the orientation of the device changes.
  63  *
  64  * @since_tizen 2.3
  65  * @param[in] orientation The orientation of the device
  66  * @param[in] user_data The user data passed from the callback registration function
  67  * @see app_main()
  68  * @see #app_event_callback_s
  69  */
  70 typedef void (*app_device_orientation_cb) (app_device_orientation_e orientation, void *user_data);
  71
  72 /**
  73  * @internal
  74  * @brief Called when language setting changes.
  75  *
  76  * @since_tizen 2.3
  77  * @param[in] user_data The user data passed from the callback registration function
  78  * @see app_main()
  79  * @see #app_event_callback_s
  80  */
  81 typedef void (*app_language_changed_cb) (void *user_data);
  82
  83 /**
  84  * @internal
  85  * @brief Called when region format setting changes.
  86  *
  87  * @since_tizen 2.3
  88  * @param[in] user_data The user data passed from the callback registration function
  89  * @see app_main()
  90  * @see #app_event_callback_s
  91  */
  92 typedef void (*app_region_format_changed_cb) (void *user_data);
  93
  94 /**
  95  * @internal
  96  * @brief The structure type containing the set of callback functions for handling application events.
  97  * @details It is one of the input parameters of the app_main() function.
  98  *
  99  * @since_tizen 2.3
 100  * @see app_main()
 101  * @see app_create_cb()
 102  * @see app_pause_cb()
 103  * @see app_resume_cb()
 104  * @see app_terminate_cb()
 105  * @see app_control_cb()
 106  * @see app_low_memory_cb()
 107  * @see app_low_battery_cb()
 108  * @see app_device_orientation_cb()
 109  * @see app_language_changed_cb()
 110  * @see app_region_format_changed_cb()
 111  */
 112 typedef struct {
 113         app_create_cb create; /**< This callback function is called at the start of the application. */
 114         app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
 115         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. */
 116         app_resume_cb resume; /**< This callback function is called each time the application becomes visible to the user. */
 117         app_control_cb app_control; /**< This callback function is called when another application sends the launch request to the application. */
 118         app_low_memory_cb low_memory; /**< The registered callback function is called when the system runs low on memory. */
 119         app_low_battery_cb low_battery; /**< The registered callback function is called when the battery is low. */
 120         app_device_orientation_cb device_orientation; /**< The registered callback function is called when the orientation of the device changes */
 121         app_language_changed_cb language_changed; /**< The registered callback function is called when language setting changes. */
 122         app_region_format_changed_cb region_format_changed; /**< The registered callback function is called when region format setting changes. */
 123 } app_event_callback_s;
 124
 125 /**
 126  * @internal
 127  * @brief Runs the application's main loop until app_exit() is called.
 128  *
 129  * @details This function is the main entry point of the Tizen application.
 130  *          The app_create_cb() callback function is called to initialize the application before the main loop of application starts up.
 131  *          After the app_create_cb() callback function returns true, the main loop starts up and the app_control_cb() callback function is subsequently called.
 132  *          If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called.
 133  *
 134  * @since_tizen 2.3
 135  * @param[in] argc The argument count
 136  * @param[in] argv The argument vector
 137  * @param[in] callback The set of callback functions to handle application events
 138  * @param[in] user_data The user data to be passed to the callback functions
 139  *
 140  * @return 0 on success, otherwise a negative error value
 141  * @retval #APP_ERROR_NONE Successful
 142  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 143  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 144  * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts
 145  *
 146  * @see app_create_cb()
 147  * @see app_terminate_cb()
 148  * @see app_pause_cb()
 149  * @see app_resume_cb()
 150  * @see app_control_cb()
 151  * @see app_low_memory_cb()
 152  * @see app_low_battery_cb()
 153  * @see app_device_orientation_cb()
 154  * @see app_language_changed_cb()
 155  * @see app_region_format_changed_cb()
 156  * @see app_exit()
 157  * @see #app_event_callback_s
 158  */
 159 int app_main(int argc, char **argv, app_event_callback_s *callback, void *user_data);
 160
 161 /**
 162  * @internal
 163  * @brief Runs the application's main loop until app_efl_exit() is called.
 164  *
 165  * @details This function is the main entry point of the Tizen application.
 166  *          The app_create_cb() callback function is called to initialize the application before the main loop of the application starts up.
 167  *          After the app_create_cb() callback function returns @c true, the main loop starts up and the app_control_cb() callback function is subsequently called.
 168  *          If the app_create_cb() callback function returns @c false, the main loop doesn't start up and the app_terminate_cb() callback function is called.
 169  *
 170  * @since_tizen 2.3
 171  * @param[in] argc The argument count
 172  * @param[in] argv The argument vector
 173  * @param[in] callback The set of callback functions to handle application events
 174  * @param[in] user_data The user data to be passed to the callback functions
 175  *
 176  * @return @c 0 on success,
 177  *         otherwise a negative error value
 178  * @retval #APP_ERROR_NONE Successful
 179  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 180  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 181  * @retval #APP_ERROR_ALREADY_RUNNING The main loop has already started
 182  *
 183  * @see app_create_cb()
 184  * @see app_terminate_cb()
 185  * @see app_pause_cb()
 186  * @see app_resume_cb()
 187  * @see app_control_cb()
 188  * @see app_low_memory_cb()
 189  * @see app_low_battery_cb()
 190  * @see app_device_orientation_cb()
 191  * @see app_language_changed_cb()
 192  * @see app_region_format_changed_cb()
 193  * @see app_efl_exit()
 194  * @see #app_event_callback_s
 195  */
 196 int app_efl_main(int *argc, char ***argv, app_event_callback_s *callback, void *user_data);
 197
 198 /**
 199  * @internal
 200  * @brief Exits the main loop of application.
 201  *
 202  * @details The main loop of application stops and app_terminate_cb() is invoked.
 203  * @since_tizen 2.3
 204  * @see app_main()
 205  * @see app_terminate_cb()
 206  */
 207 void app_exit(void);
 208
 209 /**
 210  * @internal
 211  * @brief Exits the main loop of the application.
 212  *
 213  * @details The main loop of the application stops and app_terminate_cb() is invoked.
 214  * @since_tizen 2.3
 215  * @see app_efl_main()
 216  * @see app_terminate_cb()
 217  */
 218 void app_efl_exit(void);
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif /* __TIZEN_APPFW_APP_INTERNAL_H__ */
 225