include/app_common.h

   1 /*
   2  * Copyright (c) 2014 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_COMMON_H__
  19 #define __TIZEN_APPFW_APP_COMMON_H__
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /**
  26  * @file app_common.h
  27  */
  28
  29 /**
  30  * @addtogroup CAPI_APP_COMMON_MODULE
  31  * @{
  32  */
  33
  34
  35 /**
  36  * @brief Enumeration for system events
  37  * @since_tizen 2.3
  38  */
  39 typedef enum
  40 {
  41         APP_EVENT_LOW_MEMORY, /**< The low memory event */
  42         APP_EVENT_LOW_BATTERY, /**< The low battery event */
  43         APP_EVENT_LANGUAGE_CHANGED, /**< The system language changed event */
  44         APP_EVENT_DEVICE_ORIENTATION_CHANGED, /**< The device orientation changed event */
  45         APP_EVENT_REGION_FORMAT_CHANGED, /**< The region format changed event */
  46 } app_event_type_e;
  47
  48
  49 /**
  50  * @brief Enumeration for device orientation.
  51  * @since_tizen 2.3
  52  */
  53 typedef enum
  54 {
  55         APP_DEVICE_ORIENTATION_0 = 0, /**< The device is oriented in a natural position */
  56         APP_DEVICE_ORIENTATION_90 = 90, /**< The device's left side is at the top */
  57         APP_DEVICE_ORIENTATION_180 = 180, /**< The device is upside down */
  58         APP_DEVICE_ORIENTATION_270 = 270, /**< The device's right side is at the top */
  59 } app_device_orientation_e;
  60
  61
  62 /**
  63  * @brief Enumeration for low memory status.
  64  * @since_tizen 2.3
  65  */
  66 typedef enum
  67 {
  68         APP_EVENT_LOW_MEMORY_NORMAL = 0x01, /**< Normal status */
  69         APP_EVENT_LOW_MEMORY_SOFT_WARNING = 0x02, /**< Soft warning status */
  70         APP_EVENT_LOW_MEMORY_HARD_WARNING = 0x04, /**< Hard warning status */
  71 } app_event_low_memory_status_e;
  72
  73
  74 /**
  75  * @brief Enumeration for battery status.
  76  * @since_tizen 2.3
  77  */
  78 typedef enum
  79 {
  80         APP_EVENT_LOW_BATTERY_POWER_OFF = 1, /**< The battery status is under 1% */
  81         APP_EVENT_LOW_BATTERY_CRITICAL_LOW, /**< The battery status is under 5% */
  82 } app_event_low_battery_status_e;
  83
  84
  85 /**
  86  * @brief The event handler that returned from add event handler function
  87  *
  88  * @since_tizen 2.3
  89  * @see app_event_type_e
  90  * @see app_add_event_handler
  91  * @see app_remove_event_handler
  92  * @see app_event_info_h
  93  */
  94 typedef struct app_event_handler* app_event_handler_h;
  95
  96
  97 /**
  98  * @brief The system event information
  99  *
 100  * @since_tizen 2.3
 101  * @see app_event_get_low_memory_status
 102  * @see app_event_get_low_battery_status
 103  * @see app_event_get_language
 104  * @see app_event_get_region_format
 105  * @see app_event_get_device_orientation
 106  */
 107 typedef struct app_event_info* app_event_info_h;
 108
 109
 110 /**
 111  * @brief The system event callback function
 112  *
 113  * @since_tizen 2.3
 114  * @param[in] event_info The system event information
 115  * @param[in] user_data The user data passed from the add event handler function
 116  *
 117  * @see app_add_event_handler
 118  * @see app_event_info_h
 119  */
 120 typedef void (*app_event_cb)(app_event_info_h event_info, void *user_data);
 121
 122
 123 /**
 124  * @brief Gets the low memory status from given event info
 125  *
 126  * @since_tizen 2.3
 127  * @param[in] event_info The system event info
 128  * @param[out] status The low memory status
 129  *
 130  * @return 0 on success, otherwise a negative error value
 131  * @retval #APP_ERROR_NONE Successful
 132  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 133  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 134  *
 135  * @see app_event_info_h
 136  * @see app_event_low_memory_status_e
 137  */
 138 int app_event_get_low_memory_status(app_event_info_h event_info, app_event_low_memory_status_e *status);
 139
 140
 141 /**
 142  * @brief Gets the low battery status from given event info
 143  *
 144  * @since_tizen 2.3
 145  * @param[in] event_info The system event info
 146  * @param[out] status The low battery status
 147  *
 148  * @return 0 on success, otherwise a negative error value
 149  * @retval #APP_ERROR_NONE Successful
 150  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 151  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 152  *
 153  * @see app_event_info_h
 154  * @see app_event_low_battery_status_e
 155  */
 156 int app_event_get_low_battery_status(app_event_info_h event_info, app_event_low_battery_status_e *status);
 157
 158
 159 /**
 160  * @brief Gets the language from given event info
 161  *
 162  * @since_tizen 2.3
 163  * @remarks @a lang must be released using free()
 164  * @param[in] event_info The system event info
 165  * @param[out] lang The language changed
 166  *
 167  * @return 0 on success, otherwise a negative error value
 168  * @retval #APP_ERROR_NONE Successful
 169  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 170  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 171  *
 172  * @see app_event_info_h
 173  */
 174 int app_event_get_language(app_event_info_h event_info, char **lang);
 175
 176
 177 /**
 178  * @brief Gets the region format from given event info
 179  *
 180  * @since_tizen 2.3
 181  * @remarks @a region must be released using free()
 182  * @param[in] event_info The system event info
 183  * @param[out] region The region format changed
 184  *
 185  * @return 0 on success, otherwise a negative error value
 186  * @retval #APP_ERROR_NONE Successful
 187  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 188  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 189  *
 190  * @see app_event_info_h
 191  */
 192 int app_event_get_region_format(app_event_info_h event_info, char **region);
 193
 194
 195 /**
 196  * @brief Gets the device orientation from given event info
 197  *
 198  * @since_tizen 2.3
 199  * @param[in] event_info The system event info
 200  * @param[out] orientation The device orientation changed
 201  *
 202  * @return 0 on success, 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 Invalid event context
 206  *
 207  * @see app_event_info_h
 208  * @see app_device_orientation_e
 209  */
 210 int app_event_get_device_orientation(app_event_info_h event_info, app_device_orientation_e *orientation);
 211
 212
 213 /**
 214  * @brief Gets the ID of the application.
 215  *
 216  * @since_tizen 2.3
 217  * @remarks @a id must be released using free().
 218  *
 219  * @param[out] id The ID of the application
 220  *
 221  * @return @c 0 on success,
 222  *         otherwise a negative error value
 223  *
 224  * @retval #APP_ERROR_NONE Successful
 225  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 226  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 227  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 228  */
 229 int app_get_id(char **id);
 230
 231
 232 /**
 233  * @brief Gets the localized name of the application.
 234  *
 235  * @since_tizen 2.3
 236  * @remarks @a name must be released using free().
 237  *
 238  * @param[out] name The name of the application
 239  *
 240  * @return @c 0 on success,
 241  *         otherwise a negative error value
 242  *
 243  * @retval #APP_ERROR_NONE Successful
 244  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 245  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 246  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 247  */
 248 int app_get_name(char **name);
 249
 250
 251 /**
 252  * @brief Gets the version of the application package.
 253  *
 254  * @since_tizen 2.3
 255  * @remarks @a version must be released using free().
 256  *
 257  * @param[out] version The version of the application
 258  *
 259  * @return @c 0 on success,
 260  *         otherwise a negative error value
 261  *
 262  * @retval #APP_ERROR_NONE Successful
 263  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 264  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 265  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 266  */
 267 int app_get_version(char **version);
 268
 269
 270 /**
 271  * @brief       Gets the absolute path to the application's data directory which is used to store private
 272  *          data of the application.
 273  * @details     An application can read and write its own files in the application's data directory.
 274  * @since_tizen 2.3
 275  * @remarks     The returned path should be released.
 276  *
 277  * @return      The absolute path to the application's data directory, @n
 278  *              otherwise a null pointer if the memory is insufficient
 279  */
 280 char *app_get_data_path(void);
 281
 282
 283 /**
 284  * @brief       Gets the absolute path to the application's cache directory which is used to store
 285  *          temporary data of the application.
 286  * @details     An application can read and write its own files in the application's cache directory.
 287  * @since_tizen 2.3
 288  * @remarks     The returned path should be released. @n
 289  *          The files stored in the application's cache directory can be removed by Setting
 290  *          application or platform while the application is running.
 291  *
 292  * @return      The absolute path to the application's cache directory, @n
 293  *          otherwise a null pointer if the memory is insufficient
 294  */
 295 char *app_get_cache_path(void);
 296
 297
 298 /**
 299  * @brief       Gets the absolute path to the application resource directory. The resource files
 300  *          are delivered with the application package.
 301  * @details     An application can only read its own files in the application's resource directory.
 302  * @since_tizen 2.3
 303  * @remarks     The returned path should be released.
 304  *
 305  * @return      The absolute path to the application's resource directory, @n
 306  *          otherwise a null pointer if the memory is insufficient
 307  */
 308 char *app_get_resource_path(void);
 309
 310
 311 /**
 312  * @brief       Gets the absolute path to the application's shared data directory which is used to share
 313  *          data with other applications.
 314  * @details     An application can read and write its own files in the application's shared data
 315  *          directory and others can only read the files.
 316  * @since_tizen 2.3
 317  * @remarks     The returned path should be released.
 318  *
 319  * @return      The absolute path to the application's shared data directory, @n
 320  *          otherwise a null pointer if the memory is insufficient
 321  */
 322 char *app_get_shared_data_path(void);
 323
 324
 325 /**
 326  * @brief       Gets the absolute path to the application's shared resource directory which is used to
 327  *          share resources with other applications.
 328  * @details     An application can read its own files in the application's shared resource directory
 329  *          and others can only read the files.
 330  * @since_tizen 2.3
 331  * @remarks     The returned path should be released.
 332  *
 333  * @return      The absolute path to the application's shared resource directory, @n
 334  *          otherwise a null pointer if the memory is insufficient
 335  */
 336 char *app_get_shared_resource_path(void);
 337
 338
 339 /**
 340  * @brief       Gets the absolute path to the application's shared trusted directory which is used to share data
 341  *          with a family of trusted applications.
 342  * @details     An application can read and write its own files in the application's shared trusted directory
 343  *          and the family applications signed with the same certificate can read and write the files in the
 344  *          shared trusted directory.
 345  * @since_tizen 2.3
 346  * @remarks     The returned path should be released.
 347  *
 348  * @return      The absolute path to the application's shared trusted directory, @n
 349  *          otherwise a null pointer if the memory is insufficient
 350  */
 351 char *app_get_shared_trusted_path(void);
 352
 353
 354 /**
 355  * @brief       Gets the absolute path to the application's external data directory which is used to
 356  *          store data of the application.
 357  * @details     An application can read and write its own files in the application's external data
 358  *          directory.
 359  * @since_tizen 2.3
 360  * @remarks     The returned path should be released. @n
 361  *          The important files stored in the application's external data directory should be
 362  *          encrypted because they can be exported via the external sdcard.
 363  *
 364  * @return      The absolute path to the application's external data directory, @n
 365  *                      otherwise a null pointer if the memory is insufficient
 366  */
 367 char *app_get_external_data_path(void);
 368
 369
 370 /**
 371  * @brief       Gets the absolute path to the application's external cache directory which is used to
 372  *          store temporary data of the application.
 373  * @details     An application can read and write its own files in the application's external cache
 374  *          directory.
 375  * @since_tizen 2.3
 376  * @remarks The returned path should be released. @n
 377  *          The files stored in the application's external cache directory can be removed by
 378  *          Setting application while the application is running. @n
 379  *          The important files stored in the application's external cache directory should be
 380  *          encrypted because they can be exported via the external sdcard.
 381  *
 382  * @return      The absolute path to the application's external cache directory, @n
 383  *          otherwise a null pointer if the memory is insufficient
 384  */
 385 char *app_get_external_cache_path(void);
 386
 387
 388 /**
 389  * @brief       Gets the absolute path to the application's external shared data directory which is
 390  *          used to share data with other applications.
 391  * @details     An application can read and write its own files in the application's external shared
 392  *          data directory and others can only read the files.
 393  * @since_tizen 2.3
 394  * @remarks     The specified @a path should be released.
 395  *
 396  * @return      The absolute path to the application's external shared data directory, @n
 397  *          otherwise a null pointer if the memory is insufficient
 398  */
 399 char *app_get_external_shared_data_path(void);
 400
 401 /**
 402  * @}
 403  */
 404
 405 #ifdef __cplusplus
 406 }
 407 #endif
 408
 409 #endif /* __TIZEN_APPFW_APP_H__ */