include/storage-expand.h

   1 /*
   2  * storage
   3  * Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the License);
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18
  19 #ifndef __STORAGE_EXPAND_H__
  20 #define __STORAGE_EXPAND_H__
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26
  27  /**
  28  * @addtogroup CAPI_SYSTEM_STORAGE_MODULE
  29  * @{
  30  */
  31
  32 #include <tizen.h>
  33
  34 /**
  35  * @brief Enumeration of error codes for Storage.
  36  * @since_tizen 2.3
  37  */
  38 typedef enum
  39 {
  40     STORAGE_ERROR_NONE              = TIZEN_ERROR_NONE,                /**< Successful */
  41     STORAGE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  42     STORAGE_ERROR_OUT_OF_MEMORY     = TIZEN_ERROR_OUT_OF_MEMORY,       /**< Out of memory */
  43     STORAGE_ERROR_NOT_SUPPORTED     = TIZEN_ERROR_NO_SUCH_DEVICE,      /**< Storage not supported */
  44     STORAGE_ERROR_OPERATION_FAILED  = TIZEN_ERROR_SYSTEM_CLASS | 0x12, /**< Operation failed */
  45 } storage_error_e;
  46
  47
  48 /**
  49  * @brief Enumeration of the storage types.
  50  * @since_tizen 2.3
  51  */
  52 typedef enum
  53 {
  54     STORAGE_TYPE_INTERNAL, /**< Internal device storage (built-in storage in a device, non-removable) */
  55     STORAGE_TYPE_EXTERNAL, /**< External storage */
  56 } storage_type_e;
  57
  58
  59 /**
  60  * @brief Enumeration of the state of storage devices.
  61  * @since_tizen 2.3
  62  */
  63 typedef enum
  64 {
  65     STORAGE_STATE_UNMOUNTABLE = -2, /**< Storage is present but cannot be mounted. Typically it happens if the file system of the storage is corrupted */
  66     STORAGE_STATE_REMOVED = -1, /**< Storage is not present */
  67     STORAGE_STATE_MOUNTED = 0, /**< Storage is present and mounted with read/write access */
  68     STORAGE_STATE_MOUNTED_READ_ONLY = 1, /**< Storage is present and mounted with read only access */
  69 } storage_state_e;
  70
  71 /**
  72  * @brief Called to get information once for each supported storage.
  73  *
  74  * @since_tizen 2.3
  75  *
  76  * @param[in] storage_id The unique storage ID
  77  * @param[in] type The type of the storage
  78  * @param[in] state The current state of the storage
  79  * @param[in] path The absolute path to the root directory of the storage
  80  * @param[in] user_data The user data passed from the foreach function
  81  *
  82  * @return @c true to continue with the next iteration of the loop, \n
  83  *         otherwise @c false to break out of the loop
  84  *
  85  * @pre storage_foreach_device_supported() will invoke this callback function.
  86  * @see storage_foreach_device_supported()
  87  */
  88 typedef bool (*storage_device_supported_cb)(int storage_id, storage_type_e type,
  89                 storage_state_e state, const char *path, void *user_data);
  90
  91 /**
  92  * @brief Retrieves all storage in a device.
  93  * @details This function invokes the callback function once for each storage in a device. \n
  94  *          If storage_device_supported_cb() returns @c false, then the iteration will be finished.
  95  *
  96  * @since_tizen 2.3
  97  *
  98  * @param[in] callback The iteration callback function
  99  * @param[in] user_data The user data to be passed to the callback function
 100  *
 101  * @return @c 0 on success,
 102  *         otherwise a negative error value
 103  *
 104  * @retval #STORAGE_ERROR_NONE               Successful
 105  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 106  *
 107  * @post This function invokes storage_device_supported_cb() repeatedly for each supported device.
 108  * @see storage_device_supported_cb()
 109  */
 110 int storage_foreach_device_supported(storage_device_supported_cb callback, void *user_data);
 111
 112 /**
 113  * @brief Gets the absolute path to the root directory of the given storage.
 114  * @details 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  * @since_tizen 2.3
 118  *
 119  * @remarks If you want to access files or directories in internal storage, you must declare http://tizen.org/privilege/mediastorage.\n
 120  * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n
 121  * You must release @a path using free().
 122  *
 123  * @param[in] storage_id The storage device
 124  * @param[out] path The absolute path to the storage directory
 125  *
 126  * @return @c 0 on success,
 127  *         otherwise a negative error value
 128  *
 129  * @retval #STORAGE_ERROR_NONE               Successful
 130  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 131  * @retval #STORAGE_ERROR_OUT_OF_MEMORY      Out of memory
 132  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 133  *
 134  * @see storage_get_state()
 135  */
 136 int storage_get_root_directory(int storage_id, char **path);
 137
 138 /**
 139  * @brief Enumeration of the storage directory types
 140  * @since_tizen 2.3
 141  */
 142 typedef enum
 143 {
 144         STORAGE_DIRECTORY_IMAGES,           /**< Image directory */
 145         STORAGE_DIRECTORY_SOUNDS,           /**< Sounds directory */
 146         STORAGE_DIRECTORY_VIDEOS,           /**< Videos directory */
 147         STORAGE_DIRECTORY_CAMERA,           /**< Camera directory */
 148         STORAGE_DIRECTORY_DOWNLOADS,        /**< Downloads directory */
 149         STORAGE_DIRECTORY_MUSIC,            /**< Music directory */
 150         STORAGE_DIRECTORY_DOCUMENTS,        /**< Documents directory */
 151         STORAGE_DIRECTORY_OTHERS,           /**< Others directory */
 152         STORAGE_DIRECTORY_SYSTEM_RINGTONES, /**< System ringtones directory. Only available for internal storage. */
 153         STORAGE_DIRECTORY_MAX
 154 } storage_directory_e;
 155
 156 /**
 157  * @brief Gets the absolute path to the each directory of the given storage.
 158  * @details Files saved on the internal/external storage are readable or writeable by all applications.
 159  *          When an application is uninstalled, the files written by that application are not removed from the internal/external storage.
 160  *
 161  * @since_tizen 2.3
 162  *
 163  * @remarks The directory path may not exist, so you must make sure that it exists before using it.\n
 164  * If you want to access files or directories in internal storage except #STORAGE_DIRECTORY_SYSTEM_RINGTONES, you must declare http://tizen.org/privilege/mediastorage.\n
 165  * If you want to access files or directories in #STORAGE_DIRECTORY_SYSTEM_RINGTONES, you must declare %http://tizen.org/privilege/systemsettings.\n
 166  * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n
 167  * You must release @a path using free().
 168  *
 169  * @param[in] storage_id The storage device
 170  * @param[in] type The directory type
 171  * @param[out] path The absolute path to the directory type
 172  *
 173  * @return @c 0 on success,
 174  *         otherwise a negative error value
 175  *
 176  * @retval #STORAGE_ERROR_NONE               Successful
 177  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 178  * @retval #STORAGE_ERROR_OUT_OF_MEMORY      Out of memory
 179  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 180  *
 181  * @see storage_get_state()
 182  */
 183 int storage_get_directory(int storage_id, storage_directory_e type, char **path);
 184
 185 /**
 186  * @brief Gets the type of the given storage.
 187  *
 188  * @since_tizen 2.3
 189  *
 190  * @param[in] storage_id The storage device
 191  * @param[out] type The type of the storage
 192  *
 193  * @return @c 0 on success,
 194  *         otherwise a negative error value
 195  *
 196  * @retval #STORAGE_ERROR_NONE               Successful
 197  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 198  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 199  */
 200 int storage_get_type(int storage_id, storage_type_e *type);
 201
 202 /**
 203  * @brief Gets the current state of the given storage.
 204  *
 205  * @since_tizen 2.3
 206  *
 207  * @param[in] storage_id The storage device
 208  * @param[out] state The current state of the storage
 209  *
 210  * @return @c 0 on success,
 211  *         otherwise a negative error value
 212  *
 213  * @retval #STORAGE_ERROR_NONE               Successful
 214  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 215  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 216  *
 217  * @see storage_get_root_directory()
 218  * @see storage_get_total_space()
 219  * @see storage_get_available_space()
 220  */
 221 int storage_get_state(int storage_id, storage_state_e *state);
 222
 223 /**
 224  * @brief Called when the state of storage changes
 225  *
 226  * @since_tizen 2.3
 227  *
 228  * @param[in] storage_id The unique storage ID
 229  * @param[in] state The current state of the storage
 230  * @param[in] user_data The user data passed from the foreach function
 231  *
 232  * @pre storage_set_state_changed_cb() will invoke this callback function.
 233  * @see storage_set_state_changed_cb()
 234  * @see storage_unset_state_changed_cb()
 235  */
 236 typedef void (*storage_state_changed_cb)(int storage_id, storage_state_e state, void *user_data);
 237
 238 /**
 239  * @brief Registers a callback function to be invoked when the state of the storage changes.
 240  *
 241  * @since_tizen 2.3
 242  *
 243  * @param[in] storage_id The storage device
 244  * @param[in] callback The callback function to register
 245  * @param[in] user_data The user data to be passed to the callback function
 246  *
 247  * @return @c 0 on success,
 248  *         otherwise a negative error value
 249  *
 250  * @retval #STORAGE_ERROR_NONE               Successful
 251  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 252  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 253  * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
 254  *
 255  * @post storage_state_changed_cb() will be invoked if the state of the registered storage changes.
 256  * @see storage_state_changed_cb()
 257  * @see storage_unset_state_changed_cb()
 258  */
 259 int storage_set_state_changed_cb(int storage_id, storage_state_changed_cb callback, void *user_data);
 260
 261 /**
 262  * @brief Unregisters the callback function.
 263  *
 264  * @since_tizen 2.3
 265  *
 266  * @param[in] storage_id The storage device to monitor
 267  * @param[in] callback The callback function to register
 268  *
 269  * @return @c 0 on success,
 270  *         otherwise a negative error value
 271  *
 272  * @retval #STORAGE_ERROR_NONE               Successful
 273  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 274  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 275  * @retval #STORAGE_ERROR_OPERATION_FAILED   Operation failed
 276  *
 277  * @see storage_state_changed_cb()
 278  * @see storage_set_state_changed_cb()
 279  */
 280 int storage_unset_state_changed_cb(int storage_id, storage_state_changed_cb callback);
 281
 282 /**
 283  * @brief Gets the total space of the given storage in bytes.
 284  *
 285  * @since_tizen 2.3
 286  *
 287  * @param[in] storage_id The storage device
 288  * @param[out] bytes The total space size of the storage (bytes)
 289  *
 290  * @return @c 0 on success,
 291  *         otherwise a negative error value
 292  *
 293  * @retval #STORAGE_ERROR_NONE               Successful
 294  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 295  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 296  * @retval #STORAGE_ERROR_OPERATION_FAILED   Operation failed
 297  *
 298  * @see storage_get_state()
 299  * @see storage_get_available_space()
 300  */
 301 int storage_get_total_space(int storage_id, unsigned long long *bytes);
 302
 303 /**
 304  * @brief Gets the available space size of the given storage in bytes.
 305  *
 306  * @since_tizen 2.3
 307  *
 308  * @param[in] storage_id The storage device
 309  * @param[out] bytes The available space size of the storage (bytes)
 310  *
 311  * @return @c 0 on success,
 312  *         otherwise a negative error value
 313  *
 314  * @retval #STORAGE_ERROR_NONE               Successful
 315  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 316  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 317  * @retval #STORAGE_ERROR_OPERATION_FAILED   Operation failed
 318  *
 319  * @see storage_get_state()
 320  * @see storage_get_total_space()
 321  */
 322 int storage_get_available_space(int storage_id, unsigned long long *bytes);
 323
 324 /**
 325  * @}
 326  */
 327
 328 #ifdef __cplusplus
 329 }
 330 #endif
 331 #endif