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 #include <tzplatform_config.h>
  23
  24 /* GNU gettext macro is already defined at appcore-common.h */
  25 #ifdef _
  26 #undef _
  27 #endif
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #define TIZEN_PATH_MAX 1024
  34
  35 #define PATH_FMT_APP_ROOT tzplatform_getenv(TZ_USER_APP)
  36 #define PATH_FMT_RES_DIR "/res"
  37 #define PATH_FMT_LOCALE_DIR "/locale"
  38 #define PATH_FMT_DATA_DIR "/data"
  39
  40 #define PATH_FMT_RO_APP_ROOT tzplatform_getenv(TZ_SYS_RO_APP)
  41 #define PATH_FMT_RO_RES_DIR "/res"
  42 #define PATH_FMT_RO_LOCALE_DIR "/local"
  43
  44 typedef void (*app_finalizer_cb) (void *data);
  45 typedef void *appcore_context_h;
  46
  47 int app_error(app_error_e error, const char *function, const char *description);
  48
  49 int app_get_package_app_name(const char *package, char **name);
  50
  51 int app_finalizer_add(app_finalizer_cb callback, void *data);
  52
  53 int app_finalizer_remove(app_finalizer_cb callback);
  54
  55 void app_finalizer_execute(void);
  56
  57 int app_get_package(char **package);
  58
  59 /**
  60  * @internal
  61  * @brief Called when the system memory is running low.
  62  *
  63  * @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
  64  *          If enough memory is not reclaimed during low memory conditions, the system will terminate some of the applications to reclaim the memory.
  65  *
  66  * @since_tizen 2.3
  67  * @param[in] user_data The user data passed from the callback registration function
  68  * @see app_main()
  69  * @see #app_event_callback_s
  70  */
  71 typedef void (*app_low_memory_cb) (void *user_data);
  72
  73 /**
  74  * @internal
  75  * @brief Called when the battery power is running low.
  76  * @details When the battery level falls below 5%, it is called.
  77  *
  78  * @since_tizen 2.3
  79  * @param[in] user_data The user data passed from the callback registration function
  80  * @see app_main()
  81  * @see #app_event_callback_s
  82  */
  83 typedef void (*app_low_battery_cb) (void *user_data);
  84
  85 /**
  86  * @internal
  87  * @brief Called when the orientation of the device changes.
  88  *
  89  * @since_tizen 2.3
  90  * @param[in] orientation The orientation of the device
  91  * @param[in] user_data The user data passed from the callback registration function
  92  * @see app_main()
  93  * @see #app_event_callback_s
  94  */
  95 typedef void (*app_device_orientation_cb) (app_device_orientation_e orientation, void *user_data);
  96
  97 /**
  98  * @internal
  99  * @brief Called when language setting changes.
 100  *
 101  * @since_tizen 2.3
 102  * @param[in] user_data The user data passed from the callback registration function
 103  * @see app_main()
 104  * @see #app_event_callback_s
 105  */
 106 typedef void (*app_language_changed_cb) (void *user_data);
 107
 108 /**
 109  * @internal
 110  * @brief Called when region format setting changes.
 111  *
 112  * @since_tizen 2.3
 113  * @param[in] user_data The user data passed from the callback registration function
 114  * @see app_main()
 115  * @see #app_event_callback_s
 116  */
 117 typedef void (*app_region_format_changed_cb) (void *user_data);
 118
 119 /**
 120  * @internal
 121  * @brief The structure type containing the set of callback functions for handling application events.
 122  * @details It is one of the input parameters of the app_main() function.
 123  *
 124  * @since_tizen 2.3
 125  * @see app_main()
 126  * @see app_create_cb()
 127  * @see app_pause_cb()
 128  * @see app_resume_cb()
 129  * @see app_terminate_cb()
 130  * @see app_control_cb()
 131  * @see app_low_memory_cb()
 132  * @see app_low_battery_cb()
 133  * @see app_device_orientation_cb()
 134  * @see app_language_changed_cb()
 135  * @see app_region_format_changed_cb()
 136  */
 137 typedef struct {
 138         app_create_cb create; /**< This callback function is called at the start of the application. */
 139         app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
 140         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. */
 141         app_resume_cb resume; /**< This callback function is called each time the application becomes visible to the user. */
 142         app_control_cb app_control; /**< This callback function is called when another application sends the launch request to the application. */
 143         app_low_memory_cb low_memory; /**< The registered callback function is called when the system runs low on memory. */
 144         app_low_battery_cb low_battery; /**< The registered callback function is called when the battery is low. */
 145         app_device_orientation_cb device_orientation; /**< The registered callback function is called when the orientation of the device changes */
 146         app_language_changed_cb language_changed; /**< The registered callback function is called when language setting changes. */
 147         app_region_format_changed_cb region_format_changed; /**< The registered callback function is called when region format setting changes. */
 148 } app_event_callback_s;
 149
 150 /**
 151  * @internal
 152  * @brief Runs the application's main loop until app_exit() is called.
 153  *
 154  * @details This function is the main entry point of the Tizen application.
 155  *          The app_create_cb() callback function is called to initialize the application before the main loop of application starts up.
 156  *          After the app_create_cb() callback function returns true, the main loop starts up and the app_control_cb() callback function is subsequently called.
 157  *          If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called.
 158  *
 159  * @since_tizen 2.3
 160  * @param[in] argc The argument count
 161  * @param[in] argv The argument vector
 162  * @param[in] callback The set of callback functions to handle application events
 163  * @param[in] user_data The user data to be passed to the callback functions
 164  *
 165  * @return 0 on success, otherwise a negative error value
 166  * @retval #APP_ERROR_NONE Successful
 167  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 168  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 169  * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts
 170  *
 171  * @see app_create_cb()
 172  * @see app_terminate_cb()
 173  * @see app_pause_cb()
 174  * @see app_resume_cb()
 175  * @see app_control_cb()
 176  * @see app_low_memory_cb()
 177  * @see app_low_battery_cb()
 178  * @see app_device_orientation_cb()
 179  * @see app_language_changed_cb()
 180  * @see app_region_format_changed_cb()
 181  * @see app_exit()
 182  * @see #app_event_callback_s
 183  */
 184 int app_main(int argc, char **argv, app_event_callback_s *callback, void *user_data);
 185
 186 /**
 187  * @internal
 188  * @brief Runs the application's main loop until app_efl_exit() is called.
 189  *
 190  * @details This function is the main entry point of the Tizen application.
 191  *          The app_create_cb() callback function is called to initialize the application before the main loop of the application starts up.
 192  *          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.
 193  *          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.
 194  *
 195  * @since_tizen 2.3
 196  * @param[in] argc The argument count
 197  * @param[in] argv The argument vector
 198  * @param[in] callback The set of callback functions to handle application events
 199  * @param[in] user_data The user data to be passed to the callback functions
 200  *
 201  * @return @c 0 on success,
 202  *         otherwise a negative error value
 203  * @retval #APP_ERROR_NONE Successful
 204  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 205  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 206  * @retval #APP_ERROR_ALREADY_RUNNING The main loop has already started
 207  *
 208  * @see app_create_cb()
 209  * @see app_terminate_cb()
 210  * @see app_pause_cb()
 211  * @see app_resume_cb()
 212  * @see app_control_cb()
 213  * @see app_low_memory_cb()
 214  * @see app_low_battery_cb()
 215  * @see app_device_orientation_cb()
 216  * @see app_language_changed_cb()
 217  * @see app_region_format_changed_cb()
 218  * @see app_efl_exit()
 219  * @see #app_event_callback_s
 220  */
 221 int app_efl_main(int *argc, char ***argv, app_event_callback_s *callback, void *user_data);
 222
 223 /**
 224  * @internal
 225  * @brief Exits the main loop of application.
 226  *
 227  * @details The main loop of application stops and app_terminate_cb() is invoked.
 228  * @since_tizen 2.3
 229  * @see app_main()
 230  * @see app_terminate_cb()
 231  */
 232 void app_exit(void);
 233
 234 /**
 235  * @internal
 236  * @brief Exits the main loop of the application.
 237  *
 238  * @details The main loop of the application stops and app_terminate_cb() is invoked.
 239  * @since_tizen 2.3
 240  * @see app_efl_main()
 241  * @see app_terminate_cb()
 242  */
 243 void app_efl_exit(void);
 244
 245 /**
 246  * @brief Initialize the application main loop.
 247  *
 248  * @details After calling this API, the application main loop doesn't run.
 249  * @since_tizen 3.0
 250  * @param[in] argc The argument count
 251  * @param[in] argv The argument vector
 252  * @param[in] callback The set of callback functions to handle application lifecycle events
 253  * @param[in] user_data The user data to be passed to the callback functions
 254  * @param[out] handle The appcore_context handle to be newly created on success
 255  *
 256  * @return 0 on success, otherwise a negative error value
 257  * @retval #APP_ERROR_NONE Successful
 258  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 259  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 260  * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts
 261  * @sett ui_app_fini()
 262  */
 263 int ui_app_init(int argc, char **argv, ui_app_lifecycle_callback_s *callback, void *user_data, appcore_context_h *handle);
 264
 265 /**
 266  * @brief Finalize the application main loop.
 267  *
 268  * @since_tizen 3.0
 269  * @param[in] handle The handle of appcore context
 270  *
 271  * @see ui_app_init()
 272  */
 273 void ui_app_fini(appcore_context_h handle);
 274
 275 #ifdef __cplusplus
 276 }
 277 #endif
 278
 279 #endif /* __TIZEN_APPFW_APP_INTERNAL_H__ */
 280