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