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_alarm.h>
  24 #include <app_preference.h>
  25 #include <app_storage.h>
  26 #include <app_i18n.h>
  27 #include <app_ui_notification.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 Enumerations of the device orientation.
  55  */
  56 typedef enum
  57 {
  58         APP_DEVICE_ORIENTATION_0 = 0, /**< The device is oriented in natural position */
  59         APP_DEVICE_ORIENTATION_90 = 90, /**< The device's left side is at the top */
  60         APP_DEVICE_ORIENTATION_180 = 180, /**< The device is upside down */
  61         APP_DEVICE_ORIENTATION_270 = 270, /**<The device's right side is to the top */
  62 } app_device_orientation_e;
  63
  64
  65 /**
  66  * @brief Called at the start of the application.
  67  *
  68  * @details The callback function is called before the main loop of application starts.
  69  * In this callback you can initialize application resources like window creation, data structure, etc.
  70  * After this callback function returns @c true, the main loop starts up and app_service_cb() is subsequently called.
  71  * If this callback function returns @c false, the main loop doesn't start and app_terminate_cb() is subsequently called.
  72  *
  73  * @param[in]   user_data       The user data passed from the callback registration function
  74  * @return @c true on success, otherwise @c false
  75  * @pre app_efl_main() will invoke this callback function.
  76  * @see app_efl_main()
  77  * @see #app_event_callback_s
  78  */
  79 typedef bool (*app_create_cb) (void *user_data);
  80
  81
  82 /**
  83  * @brief   Called when the application is completely obscured by another application and becomes invisible.
  84  *
  85  * @details The application is not terminated and still running in paused 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_pause_cb) (void *user_data);
  92
  93
  94 /**
  95  * @brief   Called when the application becomes visible.
  96  *
  97  * @remarks This callback function is not called when the application moved from created state to running state.
  98  *
  99  * @param[in]   user_data       The user data passed from the callback registration function
 100  * @see app_efl_main()
 101  * @see #app_event_callback_s
 102  */
 103 typedef void (*app_resume_cb) (void *user_data);
 104
 105
 106 /**
 107  * @brief   Called once after the main loop of application exits.
 108  * @details You should release the application's resources in this function.
 109  *
 110  * @param[in]   user_data       The user data passed from the callback registration function
 111  * @see app_efl_main()
 112  * @see #app_event_callback_s
 113  */
 114 typedef void (*app_terminate_cb) (void *user_data);
 115
 116
 117 /**
 118  * @brief Called when other application send the launch request to the application.
 119  *
 120  * @details When the application is launched, this callback function is called after the main loop of application starts up.
 121  * The passed service handle describes the launch request and contains the information about why the application is launched.
 122  * If the launch request is sent to the application on running or pause state,
 123  * this callback function can be called again to notify that the application is asked to be launched.
 124  *
 125  * The application could be explicitly launched by the user from the application launcher or be launched to perform the specific operation by other application.
 126  * The application is responsible for handling the each launch request and responding appropriately.
 127  * Using the Service API, the application can get the information what has to perform.
 128  * If the application is launched from the application launcher or explicitly launched by other application,
 129  * the passed service handle may include only the default operation (#SERVICE_OPERATION_DEFAULT) without any data
 130  * For more information, see The @ref CAPI_SERVICE_MODULE API description.
 131  *
 132  * @param[in]   service The handle to the service
 133  * @param[in]   user_data       The user data passed from the callback registration function
 134  * @see app_efl_main()
 135  * @see #app_event_callback_s
 136  * @see @ref CAPI_SERVICE_MODULE API
 137  */
 138 typedef void (*app_service_cb) (service_h service, void *user_data);
 139
 140
 141 /**
 142  * @brief   Called when the system memory is running low.
 143  *
 144  * @details
 145  * When low memory event is dispatched, the application should immediately save state and release resources to save as much memory as possible. \n
 146  * If enough memory is not reclaimed during low memory conditions, the system will terminate some of the applications to reclaim the memory.
 147  *
 148  * @param[in]   user_data       The user data passed from the callback registration function
 149  * @see app_efl_main()
 150  * @see #app_event_callback_s
 151  */
 152 typedef void (*app_low_memory_cb) (void *user_data);
 153
 154
 155 /**
 156  * @brief   Called when the battery power is running low.
 157  * @details When the battery level falls below 5%, it is called.
 158  *
 159  * @param[in]   user_data       The user data passed from the callback registration function
 160  * @see app_efl_main()
 161  * @see #app_event_callback_s
 162  */
 163 typedef void (*app_low_battery_cb) (void *user_data);
 164
 165
 166 /**
 167  * @brief   Called when the orientation of device changes.
 168  *
 169  * @param[in]   orientation     The orientation of device
 170  * @param[in]   user_data       The user data passed from the callback registration function
 171  * @see app_efl_main()
 172  * @see #app_event_callback_s
 173  */
 174 typedef void (*app_device_orientation_cb) (app_device_orientation_e orientation, void *user_data);
 175
 176
 177 /**
 178  * @brief   Called when language setting changes.
 179  *
 180  * @param   [in] user_data The user data passed from the callback registration function
 181  * @see app_efl_main()
 182  * @see #app_event_callback_s
 183  */
 184 typedef void (*app_language_changed_cb) (void *user_data);
 185
 186
 187 /**
 188  * @brief   Called when region format setting changes.
 189  *
 190  * @param   [in] user_data The user data passed from the callback registration function
 191  * @see app_efl_main()
 192  * @see #app_event_callback_s
 193  */
 194 typedef void (*app_region_format_changed_cb) (void *user_data);
 195
 196
 197 /**
 198  * @brief The structure type to contain the set of callback functions for handling application events.
 199  * @details It is one of the input parameters of the app_efl_main() function.
 200  *
 201  * @see app_efl_main()
 202  * @see app_create_cb()
 203  * @see app_pause_cb()
 204  * @see app_resume_cb()
 205  * @see app_terminate_cb()
 206  * @see app_service_cb()
 207  * @see app_low_memory_cb()
 208  * @see app_low_battery_cb()
 209  * @see app_device_orientation_cb()
 210  * @see app_language_changed_cb()
 211  * @see app_region_format_changed_cb()
 212  */
 213 typedef struct
 214 {
 215         app_create_cb create; /**< This callback function is called at the start of the application. */
 216         app_terminate_cb terminate; /**< This callback function is called once after the main loop of application exits. */
 217         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. */
 218         app_resume_cb resume; /**< This callback function is called each time the application becomes visible to the user. */
 219         app_service_cb service; /**< This callback function is called when other application send the launch request to the application. */
 220         app_low_memory_cb low_memory; /**< The registered callback function is called when the system runs low on memory. */
 221         app_low_battery_cb low_battery; /**< The registered callback function is called when battery is low. */
 222         app_device_orientation_cb device_orientation; /**< The registered callback function is called when the orientation of device changes */
 223         app_language_changed_cb language_changed; /**< The registered callback function is called when language setting changes. */
 224         app_region_format_changed_cb region_format_changed; /**< The registered callback function is called when region format setting is changes. */
 225 } app_event_callback_s;
 226
 227
 228 /**
 229  * @brief Runs the main loop of application until app_efl_exit() is called
 230  *
 231  * @details This function is the main entry point of the Tizen application.
 232  * The app_create_cb() callback function is called to initialize the application before the main loop of application starts up.
 233  * After the app_create_cb() callback function returns true, the main loop starts up and the app_service_cb() callback function is subsequently called.
 234  * If the app_create_cb() callback function returns false, the main loop doesn't start up and app_terminate_cb() callback function is called
 235  *
 236  * @param [in] argc The argument count
 237  * @param [in] argv The argument vector
 238  * @param [in] callback The set of callback functions to handle application events
 239  * @param [in] user_data The user data to be passed to the callback functions
 240  *
 241  * @return 0 on success, otherwise a negative error value.
 242  * @retval #APP_ERROR_NONE Successful
 243  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 244  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system.
 245  * @retval #APP_ERROR_ALREADY_RUNNING The main loop already starts
 246  *
 247  * @see app_create_cb()
 248  * @see app_terminate_cb()
 249  * @see app_pause_cb()
 250  * @see app_resume_cb()
 251  * @see app_service_cb()
 252  * @see app_low_memory_cb()
 253  * @see app_low_battery_cb()
 254  * @see app_device_orientation_cb()
 255  * @see app_language_changed_cb()
 256  * @see app_region_format_changed_cb()
 257  * @see app_efl_exit()
 258  * @see #app_event_callback_s
 259  */
 260 int app_efl_main(int *argc, char ***argv, app_event_callback_s *callback, void *user_data);
 261
 262
 263 /**
 264  * @brief Exits the main loop of application.
 265  *
 266  * @details The main loop of application stops and app_terminate_cb() is invoked
 267  * @see app_efl_main()
 268  * @see app_terminate_cb()
 269  */
 270 void app_efl_exit(void);
 271
 272
 273 /**
 274  * @brief Gets the name of the application package.
 275  *
 276  * @remarks @a package must be released with free() by you.
 277  *
 278  * @param [out] package The name of the application package
 279  *
 280  * @return 0 on success, otherwise a negative error value.
 281  *
 282  * @retval #APP_ERROR_NONE Successful
 283  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 284  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system.
 285  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 286  */
 287 int app_get_package(char **package);
 288
 289
 290 /**
 291  * @brief Gets the ID of the application.
 292  *
 293  * @remarks @a ID must be released with free() by you.
 294  *
 295  * @param [out] id The ID of the application
 296  *
 297  * @return 0 on success, otherwise a negative error value.
 298  *
 299  * @retval #APP_ERROR_NONE Successful
 300  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 301  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system.
 302  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 303  */
 304 int app_get_id(char **id);
 305
 306
 307 /**
 308  * @brief Gets the localized name of the application.
 309  *
 310  * @remarks @a name must be released with free() by you.
 311  *
 312  * @param [out] name The name of the application
 313  *
 314  * @return 0 on success, otherwise a negative error value.
 315  *
 316  * @retval #APP_ERROR_NONE Successful
 317  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 318  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system.
 319  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 320  */
 321 int app_get_name(char **name);
 322
 323
 324 /**
 325  * @brief Gets the version of the application package.
 326  *
 327  * @remarks @a version must be released with free() by you.
 328  *
 329  * @param [out] version The version of the application
 330  *
 331  * @return 0 on success, otherwise a negative error value.
 332  *
 333  * @retval #APP_ERROR_NONE Successful
 334  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 335  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system.
 336  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 337  */
 338 int app_get_version(char **version);
 339
 340
 341 /**
 342  * @brief Gets the absolute path to the resource included in application package
 343  *
 344  * @details The application cannot write and modify any resource files.
 345  *
 346  * @remarks This function stores the absolute path into the @a buffer at most one less than @a size bytes
 347  * and a null character is appended  in @a buffer after the path stored.
 348  *
 349  * @param [in] resource The resource's path relative to the resource directory of the application package (e.g. edje/app.edj or images/background.png)
 350  * @param [in] buffer The pre-allocated buffer where the absolute path to the resource is stored.
 351  * @param [in] size The size of @a buffer in bytes
 352  * @return  @a buffer on success, otherwise NULL.
 353  */
 354 char* app_get_resource(const char *resource, char *buffer, int size);
 355
 356
 357 /**
 358  * @brief Gets the absolute path to the application's data directory.
 359  *
 360  * @details An application can read and write its own data files in the application's data directory.
 361  *
 362  * @remarks This function stores the absolute path into the @a buffer at most one less than @a size bytes
 363  * and a null character is appended  in @a buffer after the path stored.
 364  *
 365  * @param [in] buffer The pre-allocated buffer where the absolute path to the application data directory
 366  * @param [in] size The size of @a buffer in bytes
 367  * @return  @a buffer on success, otherwise NULL.
 368  */
 369 char* app_get_data_directory(char *buffer, int size);
 370
 371
 372 /**
 373  * @brief Gets the current device orientation.
 374  *
 375  * @return The current device orientation
 376  */
 377 app_device_orientation_e app_get_device_orientation(void);
 378
 379
 380 /**
 381  * @brief Sets whether reclaiming system cache is enabled in the pause state.
 382  *
 383  * @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.
 384  *
 385  * @remarks The reclaiming system cache is enabled by default
 386  *
 387  * @param [in] enable whether reclaiming system cache is enabled
 388  */
 389 void app_set_reclaiming_system_cache_on_pause(bool enable);
 390
 391
 392 /**
 393  * @}
 394  */
 395
 396 #ifdef __cplusplus
 397 }
 398 #endif
 399
 400 #endif /* __TIZEN_APPFW_APP_H__ */