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