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         APP_EVENT_LOW_MEMORY, /**< The low memory event */
  43         APP_EVENT_LOW_BATTERY, /**< The low battery event */
  44         APP_EVENT_LANGUAGE_CHANGED, /**< The system language changed event */
  45         APP_EVENT_DEVICE_ORIENTATION_CHANGED, /**< The device orientation changed event */
  46         APP_EVENT_REGION_FORMAT_CHANGED, /**< The region format changed event */
  47         APP_EVENT_SUSPENDED_STATE_CHANGED, /**< The suspended state changed event of the application (since 2.4)
  48                                              @see app_event_get_suspended_state */
  49 } app_event_type_e;
  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         APP_DEVICE_ORIENTATION_0 = 0, /**< The device is oriented in a natural position */
  57         APP_DEVICE_ORIENTATION_90 = 90, /**< The device's left side is at the top */
  58         APP_DEVICE_ORIENTATION_180 = 180, /**< The device is upside down */
  59         APP_DEVICE_ORIENTATION_270 = 270, /**< The device's right side is at the top */
  60 } app_device_orientation_e;
  61
  62 /**
  63  * @brief Enumeration for low memory status.
  64  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  65  */
  66 typedef enum {
  67         APP_EVENT_LOW_MEMORY_NORMAL = 0x01, /**< Normal status */
  68         APP_EVENT_LOW_MEMORY_SOFT_WARNING = 0x02, /**< Soft warning status */
  69         APP_EVENT_LOW_MEMORY_HARD_WARNING = 0x04, /**< Hard warning status */
  70 } app_event_low_memory_status_e;
  71
  72 /**
  73  * @brief Enumeration for battery status.
  74  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  75  */
  76 typedef enum {
  77         APP_EVENT_LOW_BATTERY_POWER_OFF = 1, /**< The battery status is under 1% */
  78         APP_EVENT_LOW_BATTERY_CRITICAL_LOW, /**< The battery status is under 5% */
  79 } app_event_low_battery_status_e;
  80
  81 /**
  82  * @brief Enumeration for suspended state
  83  * @since_tizen 2.4
  84  */
  85 typedef enum {
  86         APP_SUSPENDED_STATE_WILL_ENTER = 0, /**< Application will enter the suspended state */
  87         APP_SUSPENDED_STATE_DID_EXIT, /**< Application did exit from the suspended state */
  88 } app_suspended_state_e;
  89
  90 /**
  91  * @brief The event handler that returned from add event handler function
  92  *
  93  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  94  * @see app_event_type_e
  95  * @see app_add_event_handler
  96  * @see app_remove_event_handler
  97  * @see app_event_info_h
  98  */
  99 typedef struct app_event_handler* app_event_handler_h;
 100
 101
 102 /**
 103  * @brief The system event information
 104  *
 105  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 106  * @see app_event_get_low_memory_status
 107  * @see app_event_get_low_battery_status
 108  * @see app_event_get_language
 109  * @see app_event_get_region_format
 110  * @see app_event_get_device_orientation
 111  * @see app_event_get_suspended_state
 112  */
 113 typedef struct app_event_info* app_event_info_h;
 114
 115
 116 /**
 117  * @brief The system event callback function
 118  *
 119  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 120  * @param[in] event_info The system event information
 121  * @param[in] user_data The user data passed from the add event handler function
 122  *
 123  * @see app_add_event_handler
 124  * @see app_event_info_h
 125  *
 126  * @remarks If the given @a event_info has #APP_SUSPENDED_STATE_WILL_ENTER value,
 127  * the application should not call any asynchronous operations in this callback.
 128  * After the callback returns, process of the application will be changed to suspended
 129  * state immediately. Thus, asynchronous operations may work incorrectly. (since 2.4)
 130  *
 131  */
 132 typedef void (*app_event_cb)(app_event_info_h event_info, void *user_data);
 133
 134
 135 /**
 136  * @brief Gets the low memory status from given event info
 137  *
 138  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 139  * @param[in] event_info The system event info
 140  * @param[out] status The low memory status
 141  *
 142  * @return 0 on success, otherwise a negative error value
 143  * @retval #APP_ERROR_NONE Successful
 144  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 145  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 146  *
 147  * @see app_event_info_h
 148  * @see app_event_low_memory_status_e
 149  */
 150 int app_event_get_low_memory_status(app_event_info_h event_info, app_event_low_memory_status_e *status);
 151
 152
 153 /**
 154  * @brief Gets the low battery status from given event info
 155  *
 156  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 157  * @param[in] event_info The system event info
 158  * @param[out] status The low battery status
 159  *
 160  * @return 0 on success, otherwise a negative error value
 161  * @retval #APP_ERROR_NONE Successful
 162  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 163  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 164  *
 165  * @see app_event_info_h
 166  * @see app_event_low_battery_status_e
 167  */
 168 int app_event_get_low_battery_status(app_event_info_h event_info, app_event_low_battery_status_e *status);
 169
 170
 171 /**
 172  * @brief Gets the language from given event info
 173  *
 174  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 175  * @remarks @a lang must be released using free()
 176  * @param[in] event_info The system event info
 177  * @param[out] lang The language changed
 178  *
 179  * @return 0 on success, otherwise a negative error value
 180  * @retval #APP_ERROR_NONE Successful
 181  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 182  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 183  *
 184  * @see app_event_info_h
 185  */
 186 int app_event_get_language(app_event_info_h event_info, char **lang);
 187
 188
 189 /**
 190  * @brief Gets the region format from given event info
 191  *
 192  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 193  * @remarks @a region must be released using free()
 194  * @param[in] event_info The system event info
 195  * @param[out] region The region format changed
 196  *
 197  * @return 0 on success, otherwise a negative error value
 198  * @retval #APP_ERROR_NONE Successful
 199  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 200  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 201  *
 202  * @see app_event_info_h
 203  */
 204 int app_event_get_region_format(app_event_info_h event_info, char **region);
 205
 206
 207 /**
 208  * @brief Gets the device orientation from given event info
 209  *
 210  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 211  * @param[in] event_info The system event info
 212  * @param[out] orientation The device orientation changed
 213  *
 214  * @return 0 on success, otherwise a negative error value
 215  * @retval #APP_ERROR_NONE Successful
 216  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 217  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 218  *
 219  * @see app_event_info_h
 220  * @see app_device_orientation_e
 221  */
 222 int app_event_get_device_orientation(app_event_info_h event_info, app_device_orientation_e *orientation);
 223
 224
 225 /**
 226  * @brief Gets the suspended state of the application from given event info.
 227  *
 228  * @since_tizen 2.4
 229  * @param[in] event_info The handle for getting the suspended state
 230  * @param[out] state The suspended state of the application
 231  *
 232  * @return 0 on success, otherwise a negative error value
 233  * @retval #APP_ERROR_NONE Successful
 234  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 235  * @retval #APP_ERROR_INVALID_CONTEXT Invalid event context
 236  *
 237  * @remarks The application should not use any asynchronous operations in #APP_SUSPENDED_STATE_WILL_ENTER event.
 238  * Because applications will be changed to suspended state just after #APP_SUSPENDED_STATE_WILL_ENTER,
 239  * asynchronous calls are not guaranteed to work properly.
 240  */
 241 int app_event_get_suspended_state(app_event_info_h event_info, app_suspended_state_e *state);
 242
 243
 244 /**
 245  * @brief Gets the ID of the application.
 246  *
 247  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 248  * @remarks @a id must be released using free().
 249  *
 250  * @param[out] id The ID of the application
 251  *
 252  * @return @c 0 on success,
 253  *         otherwise a negative error value
 254  *
 255  * @retval #APP_ERROR_NONE Successful
 256  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 257  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 258  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 259  */
 260 int app_get_id(char **id);
 261
 262
 263 /**
 264  * @brief Gets the localized name of the application.
 265  *
 266  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 267  * @remarks @a name must be released using free().
 268  *
 269  * @param[out] name The name of the application
 270  *
 271  * @return @c 0 on success,
 272  *         otherwise a negative error value
 273  *
 274  * @retval #APP_ERROR_NONE Successful
 275  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 276  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 277  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 278  */
 279 int app_get_name(char **name);
 280
 281
 282 /**
 283  * @brief Gets the version of the application package.
 284  *
 285  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 286  * @remarks @a version must be released using free().
 287  *
 288  * @param[out] version The version of the application
 289  *
 290  * @return @c 0 on success,
 291  *         otherwise a negative error value
 292  *
 293  * @retval #APP_ERROR_NONE Successful
 294  * @retval #APP_ERROR_INVALID_PARAMETER Invalid parameter
 295  * @retval #APP_ERROR_INVALID_CONTEXT The application is illegally launched, not launched by the launch system
 296  * @retval #APP_ERROR_OUT_OF_MEMORY Out of memory
 297  */
 298 int app_get_version(char **version);
 299
 300
 301 /**
 302  * @brief       Gets the absolute path to the application's data directory which is used to store private
 303  *          data of the application.
 304  * @details     An application can read and write its own files in the application's data directory.
 305  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 306  * @remarks     The returned path should be released.
 307  *
 308  * @return      The absolute path to the application's data directory, @n
 309  *              otherwise a null pointer if the memory is insufficient
 310  */
 311 char *app_get_data_path(void);
 312
 313
 314 /**
 315  * @brief       Gets the absolute path to the application's cache directory which is used to store
 316  *          temporary data of the application.
 317  * @details     An application can read and write its own files in the application's cache directory.
 318  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 319  * @remarks     The returned path should be released. @n
 320  *          The files stored in the application's cache directory can be removed by Setting
 321  *          application or platform while the application is running.
 322  *
 323  * @return      The absolute path to the application's cache directory, @n
 324  *          otherwise a null pointer if the memory is insufficient
 325  */
 326 char *app_get_cache_path(void);
 327
 328
 329 /**
 330  * @brief       Gets the absolute path to the application resource directory. The resource files
 331  *          are delivered with the application package.
 332  * @details     An application can only read its own files in the application's resource directory.
 333  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 334  * @remarks     The returned path should be released.
 335  *
 336  * @return      The absolute path to the application's resource directory, @n
 337  *          otherwise a null pointer if the memory is insufficient
 338  */
 339 char *app_get_resource_path(void);
 340
 341
 342 /**
 343  * @deprecated Deprecated since 3.0.
 344  * @brief       Gets the absolute path to the application's shared data directory which is used to share
 345  *          data with other applications.
 346  * @details     An application can read and write its own files in the application's shared data
 347  *          directory and others can only read the files.
 348  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 349  * @remarks     The returned path should be released. @n
 350  *              shared/data directory is not supported since Tizen 3.0.
 351  *              You MUST NOT use this API when you develop new application.
 352  *              Actually, we strongly recommend to stop using shared/data path for all your previous applications.
 353  *              Files in shared/data directory can be read by all other applications.
 354  *              You cannot control what applications can read the files in shared/data directory.
 355  *              If you want to share files with other applications, consider passing path via @ref CAPI_APP_CONTROL_MODULE API.
 356  *              The @ref CAPI_APP_CONTROL_MODULE API supports giving permission to other applications by passing path via app_control. @n
 357  *              shared/data directory is only available for applications with api-version lower than 3.0 from Tizen 3.0 platform.
 358  *              The applications with api-version from 3.0 cannot access other applications' shared/data directory.
 359  *              For example, a Tizen 2.4 application can access another Tizen 2.4 application's shared/data directory as it did in Tizen 2.4 platform.
 360  *              However, a Tizen 3.0 application cannot access another application's shared/data directory even the another application is Tizen 2.4 application.
 361  *              Note that Tizen 3.0 platform only supports shared/data directory among applications with api-version lower than 3.0 for minimum backward compatibility. @n
 362  *              The specific error code can be obtained using the get_last_result(). Error codes are described in Exception section.
 363  *
 364  * @return      The absolute path to the application's shared data directory, @n
 365  *          otherwise a null pointer if the memory is insufficient. It will return NULL for 3.0 application, and set to APP_ERROR_NOT_SUPPORTED.
 366  * @exception   APP_ERROR_NONE Success
 367  * @exception   APP_ERROR_OUT_OF_MEMORY Out of memory
 368  * @exception   APP_ERROR_NOT_SUPPORTED Not supported
 369  */
 370 char *app_get_shared_data_path(void);
 371
 372
 373 /**
 374  * @brief       Gets the absolute path to the application's shared resource directory which is used to
 375  *          share resources with other applications.
 376  * @details     An application can read its own files in the application's shared resource directory
 377  *          and others can only read the files.
 378  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 379  * @remarks     The returned path should be released.
 380  *
 381  * @return      The absolute path to the application's shared resource directory, @n
 382  *          otherwise a null pointer if the memory is insufficient
 383  */
 384 char *app_get_shared_resource_path(void);
 385
 386
 387 /**
 388  * @brief       Gets the absolute path to the application's shared trusted directory which is used to share data
 389  *          with a family of trusted applications.
 390  * @details     An application can read and write its own files in the application's shared trusted directory
 391  *          and the family applications signed with the same certificate can read and write the files in the
 392  *          shared trusted directory.
 393  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 394  * @remarks     The returned path should be released.
 395  *
 396  * @return      The absolute path to the application's shared trusted directory, @n
 397  *          otherwise a null pointer if the memory is insufficient
 398  */
 399 char *app_get_shared_trusted_path(void);
 400
 401
 402 /**
 403  * @brief       Gets the absolute path to the application's external data directory which is used to
 404  *          store data of the application.
 405  * @details     An application can read and write its own files in the application's external data
 406  *          directory.
 407  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 408  * @remarks     The returned path should be released. @n
 409  *          The important files stored in the application's external data directory should be
 410  *          encrypted because they can be exported via the external sdcard.
 411  * @remarks     To access the path returned by this function requires the privilege
 412  *              that is "http://tizen.org/privilege/externalstorage.appdata".
 413  *
 414  * @return      The absolute path to the application's external data directory, @n
 415  *                      otherwise a null pointer if the memory is insufficient
 416  */
 417 char *app_get_external_data_path(void);
 418
 419
 420 /**
 421  * @brief       Gets the absolute path to the application's external cache directory which is used to
 422  *          store temporary data of the application.
 423  * @details     An application can read and write its own files in the application's external cache
 424  *          directory.
 425  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 426  * @remarks The returned path should be released. @n
 427  *          The files stored in the application's external cache directory can be removed by
 428  *          Setting application while the application is running. @n
 429  *          The important files stored in the application's external cache directory should be
 430  *          encrypted because they can be exported via the external sdcard.
 431  * @remarks     To access the path returned by this function requires the privilege
 432  *              that is "http://tizen.org/privilege/externalstorage.appdata".
 433  *
 434  * @return      The absolute path to the application's external cache directory, @n
 435  *          otherwise a null pointer if the memory is insufficient
 436  */
 437 char *app_get_external_cache_path(void);
 438
 439
 440 /**
 441  * @deprecated Deprecated since 2.4.
 442  * @brief       Gets the absolute path to the application's external shared data directory which is
 443  *          used to share data with other applications.
 444  * @details     An application can read and write its own files in the application's external shared
 445  *          data directory and others can only read the files.
 446  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 447  * @remarks     The specified @a path should be released.
 448  * @remarks     To access the path returned by this function requires the privilege
 449  *              that is "http://tizen.org/privilege/externalstorage.appdata".
 450  * @remarks     The function may not work as intended in certain devices due to some implementation issues.
 451  *
 452  * @return      The absolute path to the application's external shared data directory, @n
 453  *          otherwise a null pointer if the memory is insufficient
 454  */
 455 char *app_get_external_shared_data_path(void);
 456
 457 /**
 458  * @brief       Gets the absolute path to the application's TEP(Tizen Expansion Package) directory.
 459  *              The resource files are delivered with the expansion package.
 460  * @details     An application can only read its own files in the application's TEP(Tizen Expansion Package) directory.
 461  * @since_tizen 2.4
 462  * @remarks     The returned path should be released.
 463  *
 464  * @return      The absolute path to the application's TEP(Tizen Expansion Package) directory, @n
 465  *              otherwise a null pointer if the memory is insufficient
 466  **/
 467 char *app_get_tep_resource_path(void);
 468
 469 /**
 470  * @}
 471  */
 472
 473 #ifdef __cplusplus
 474 }
 475 #endif
 476
 477 #endif /* __TIZEN_APPFW_APP_H__ */