include/app_storage.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 #ifndef __TIZEN_APPFW_STORAGE_H__
  18 #define __TIZEN_APPFW_STORAGE_H__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27  /**
  28  * @addtogroup CAPI_STORAGE_MODULE
  29  * @{
  30  */
  31
  32
  33 /**
  34  * @brief Enumerations of error code for Storage.
  35  */
  36 typedef enum
  37 {
  38         STORAGE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  39         STORAGE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  40         STORAGE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  41         STORAGE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NO_SUCH_DEVICE /**< Not supported storage */
  42 } storage_error_e;
  43
  44
  45 /**
  46  * @brief Enumerations of the storage type.
  47  */
  48 typedef enum
  49 {
  50         STORAGE_TYPE_INTERNAL, /**< Internal device storage (built-in storage in a device, non-removable) */
  51         STORAGE_TYPE_EXTERNAL, /**< External storage */
  52 } storage_type_e;
  53
  54
  55 /**
  56  * @brief Enumerations of the state of storage device.
  57  */
  58 typedef enum
  59 {
  60         STORAGE_STATE_UNMOUNTABLE = -2, /**< Storage is present but cannot be mounted. Typically it happens if the file system of the storage is corrupted. */
  61         STORAGE_STATE_REMOVED = -1, /**< Storage is not present. */
  62         STORAGE_STATE_MOUNTED = 0, /**< Storage is present and mounted with read/write access. */
  63         STORAGE_STATE_MOUNTED_READ_ONLY = 1, /**< Storage is present and mounted with read only access. */
  64 } storage_state_e;
  65
  66
  67 /**
  68 * @brief   Called to get information once for each supported storage.
  69 *
  70 * @param [in] storage The unique storage ID
  71 * @param [in] type The type of the storage
  72 * @param [in] state The current state of the storage
  73 * @param [in] path The absolute path to the root directory of the @a storage
  74 * @param [in] user_data The user data passed from the foreach function
  75 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  76 * @pre  storage_foreach_device_supported() will invoke this callback function.
  77 * @see  storage_foreach_device_supported()
  78 */
  79 typedef bool (*storage_device_supported_cb)(int storage, storage_type_e type, storage_state_e state, const char *path, void *user_data);
  80
  81
  82 /**
  83 * @brief   Called when the state of storage changes
  84 *
  85 * @param [in] storage The unique storage ID
  86 * @param [in] state The current state of the storage
  87 * @param [in] user_data The user data passed from the foreach function
  88 * @pre  storage_set_state_changed_cb() will invoke this callback function.
  89 * @see  storage_set_state_changed_cb()
  90 * @see  storage_unset_state_changed_cb()
  91 */
  92 typedef void (*storage_state_changed_cb)(int storage, storage_state_e state, void *user_data);
  93
  94
  95 /**
  96  * @brief Retrieves all storage in device.
  97  * @details This function invokes the callback function once for each @a storage in device. \n
  98  * If storage_device_supported_cb() returns @c false, then iteration will be finished.
  99  *
 100  * @param [in] callback The iteration callback function
 101  * @param [in] user_data The user data to be passed to the callback function
 102  * @return 0 on success, otherwise a negative error value.
 103  * @retval #STORAGE_ERROR_NONE Successful
 104  * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
 105  * @post        This function invokes storage_device_supported_cb() repeatedly for each supported device.
 106  * @see storage_device_supported_cb()
 107  */
 108 int storage_foreach_device_supported(storage_device_supported_cb callback, void *user_data);
 109
 110
 111 /**
 112  * @brief   Gets the absolute path to the root directory of the given @a storage.
 113  * @details
 114  * Files saved on the internal/external storage are readable or writeable by all applications.
 115  * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.
 116  *
 117  * @remarks @a path must be released with free() by you.
 118  *
 119  * @param[in] storage The storage device
 120  * @param[out] path The absolute path to the storage directory
 121  * @return  0 on success, otherwise a negative error value.
 122  * @retval #STORAGE_ERROR_NONE Successful
 123  * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
 124  * @retval #STORAGE_ERROR_OUT_OF_MEMORY Out of memory
 125  * @retval #STORAGE_ERROR_NOT_SUPPORTED  Not supported storage
 126  * @see storage_get_state()
 127  */
 128 int storage_get_root_directory(int storage, char **path);
 129
 130
 131 /**
 132  * @brief   Gets the type of the given @a storage.
 133  *
 134  * @param[in] storage The storage device
 135  * @param[out] type The type of the storage
 136  * @return  0 on success, otherwise a negative error value.
 137  * @retval #STORAGE_ERROR_NONE Successful
 138  * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
 139  * @retval #STORAGE_ERROR_NOT_SUPPORTED  Not supported storage
 140  */
 141 int storage_get_type(int storage, storage_type_e *type);
 142
 143
 144 /**
 145  * @brief   Gets the current state of the given @a storage.
 146  *
 147  * @param[in] storage The storage device
 148  * @param[out] state The current state of the storage,
 149  * @return  0 on success, otherwise a negative error value.
 150  * @retval #STORAGE_ERROR_NONE Successful
 151  * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
 152  * @retval #STORAGE_ERROR_NOT_SUPPORTED  Not supported storage
 153  * @see storage_get_root_directory()
 154  * @see storage_get_total_space()
 155  * @see storage_get_available_space()
 156  */
 157 int storage_get_state(int storage, storage_state_e *state);
 158
 159
 160 /**
 161  * @brief   Registers a callback function to be invoked when the state of the storage changes.
 162  *
 163  * @param[in] storage The storage device
 164  * @param[in] callback The callback function to register
 165  * @param[in] user_data The user data to be passed to the callback function
 166  * @return  0 on success, otherwise a negative error value.
 167  * @retval #STORAGE_ERROR_NONE Successful
 168  * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
 169  * @retval #STORAGE_ERROR_NOT_SUPPORTED  Not supported storage
 170  * @post storage_state_changed_cb() will be invoked if the state of registered storage changes.
 171  * @see storage_state_changed_cb()
 172  * @see storage_unset_state_changed_cb()
 173  */
 174 int storage_set_state_changed_cb(int storage, storage_state_changed_cb callback, void *user_data);
 175
 176
 177 /**
 178  * @brief Unregisters the callback function.
 179  *
 180  * @param [in] storage The storage device to monitor
 181  * @return 0 on success, otherwise a negative error value.
 182  * @retval #STORAGE_ERROR_NONE Successful
 183  * @retval #STORAGE_ERROR_NOT_SUPPORTED  Not supported storage
 184  * @see storage_state_changed_cb()
 185  * @see storage_set_state_changed_cb()
 186  */
 187 int storage_unset_state_changed_cb(int storage);
 188
 189 /**
 190  * @brief   Gets the total space of the given @a storage in bytes.
 191  *
 192  * @param[in]   storage The storage device
 193  * @param[out]  bytes   The total space size of the storage (bytes)
 194  * @return  0 on success, otherwise a negative error value
 195  * @retval #STORAGE_ERROR_NONE Successful
 196  * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
 197  * @retval #STORAGE_ERROR_NOT_SUPPORTED Not supported storage
 198  * @see storage_get_state()
 199  * @see storage_get_available_space()
 200  */
 201 int storage_get_total_space(int storage, unsigned long long *bytes);
 202
 203 /**
 204  * @brief   Gets the available space size of the given @a storage in bytes.
 205  *
 206  * @param[in] storage The storage device
 207  * @param[out] bytes The available space size of the storage (bytes)
 208  * @return  0 on success, otherwise a negative error value.
 209  * @retval #STORAGE_ERROR_NONE Successful
 210  * @retval #STORAGE_ERROR_INVALID_PARAMETER Invalid parameter
 211  * @retval #STORAGE_ERROR_NOT_SUPPORTED Not supported storage
 212
 213  * @see storage_get_state()
 214  * @see storage_get_total_space()
 215  */
 216 int storage_get_available_space(int storage, unsigned long long *bytes);
 217
 218 /**
 219  * @}
 220  */
 221
 222 #ifdef __cplusplus
 223 }
 224 #endif
 225
 226 #endif /* __TIZEN_APPFW_STORAGE_H__ */