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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  37  */
  38 typedef enum {
  39         STORAGE_ERROR_NONE              = TIZEN_ERROR_NONE,                /**< Successful */
  40         STORAGE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  41         STORAGE_ERROR_OUT_OF_MEMORY     = TIZEN_ERROR_OUT_OF_MEMORY,       /**< Out of memory */
  42         STORAGE_ERROR_NOT_SUPPORTED     = TIZEN_ERROR_NO_SUCH_DEVICE,      /**< Storage not supported */
  43         STORAGE_ERROR_OPERATION_FAILED  = TIZEN_ERROR_SYSTEM_CLASS | 0x12, /**< Operation failed */
  44 } storage_error_e;
  45
  46
  47 /**
  48  * @brief Enumeration of the storage types.
  49  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  50  */
  51 typedef enum {
  52         STORAGE_TYPE_INTERNAL, /**< Internal device storage (built-in storage in a device, non-removable) */
  53         STORAGE_TYPE_EXTERNAL, /**< External storage */
  54 } storage_type_e;
  55
  56
  57 /**
  58  * @brief Enumeration of the state of storage devices.
  59  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  60  */
  61 typedef enum {
  62         STORAGE_STATE_UNMOUNTABLE = -2, /**< Storage is present but cannot be mounted. Typically it happens if the file system of the storage is corrupted */
  63         STORAGE_STATE_REMOVED = -1, /**< Storage is not present */
  64         STORAGE_STATE_MOUNTED = 0, /**< Storage is present and mounted with read/write access */
  65         STORAGE_STATE_MOUNTED_READ_ONLY = 1, /**< Storage is present and mounted with read only access */
  66 } storage_state_e;
  67
  68 /**
  69  * @brief Called to get information once for each supported storage.
  70  *
  71  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  72  *
  73  * @param[in] storage_id The unique storage ID
  74  * @param[in] type The type of the storage
  75  * @param[in] state The current state of the storage
  76  * @param[in] path The absolute path to the root directory of the storage
  77  * @param[in] user_data The user data passed from the foreach function
  78  *
  79  * @return @c true to continue with the next iteration of the loop, \n
  80  *         otherwise @c false to break out of the loop
  81  *
  82  * @pre storage_foreach_device_supported() will invoke this callback function.
  83  * @see storage_foreach_device_supported()
  84  */
  85 typedef bool (*storage_device_supported_cb)(int storage_id, storage_type_e type,
  86                 storage_state_e state, const char *path, void *user_data);
  87
  88 /**
  89  * @brief Retrieves all storage in a device.
  90  * @details This function invokes the callback function once for each storage in a device. \n
  91  *          If storage_device_supported_cb() returns @c false, then the iteration will be finished.
  92  *
  93  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  94  *
  95  * @param[in] callback The iteration callback function
  96  * @param[in] user_data The user data to be passed to the callback function
  97  *
  98  * @return @c 0 on success,
  99  *         otherwise a negative error value
 100  *
 101  * @retval #STORAGE_ERROR_NONE               Successful
 102  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 103  *
 104  * @post This function invokes storage_device_supported_cb() repeatedly for each supported device.
 105  * @see storage_device_supported_cb()
 106  */
 107 int storage_foreach_device_supported(storage_device_supported_cb callback, void *user_data);
 108
 109 /**
 110  * @brief Gets the absolute path to the root directory of the given storage.
 111  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 112  *
 113  * @remarks Files saved on the internal/external storage are readable or writable by all applications.\n
 114  * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n
 115  * If you want to access files or directories in internal storage, you must declare http://tizen.org/privilege/mediastorage.\n
 116  * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n
 117  * You must release @a path using free().
 118  *
 119  * @param[in] storage_id The storage device
 120  * @param[out] path The absolute path to the storage directory
 121  *
 122  * @return @c 0 on success,
 123  *         otherwise a negative error value
 124  *
 125  * @retval #STORAGE_ERROR_NONE               Successful
 126  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 127  * @retval #STORAGE_ERROR_OUT_OF_MEMORY      Out of memory
 128  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 129  *
 130  * @see storage_get_state()
 131  */
 132 int storage_get_root_directory(int storage_id, char **path);
 133
 134 /**
 135  * @brief Enumeration of the storage directory types
 136  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 137  */
 138 typedef enum {
 139         STORAGE_DIRECTORY_IMAGES,           /**< Image directory */
 140         STORAGE_DIRECTORY_SOUNDS,           /**< Sounds directory */
 141         STORAGE_DIRECTORY_VIDEOS,           /**< Videos directory */
 142         STORAGE_DIRECTORY_CAMERA,           /**< Camera directory */
 143         STORAGE_DIRECTORY_DOWNLOADS,        /**< Downloads directory */
 144         STORAGE_DIRECTORY_MUSIC,            /**< Music directory */
 145         STORAGE_DIRECTORY_DOCUMENTS,        /**< Documents directory */
 146         STORAGE_DIRECTORY_OTHERS,           /**< Others directory */
 147         STORAGE_DIRECTORY_SYSTEM_RINGTONES, /**< System ringtones directory. Only available for internal storage. */
 148         STORAGE_DIRECTORY_MAX
 149 } storage_directory_e;
 150
 151 /**
 152  * @brief Gets the absolute path to the each directory of the given storage.
 153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 154  *
 155  * @remarks Files saved on the internal/external storage are readable or writable by all applications.\n
 156  * When an application is uninstalled, the files written by that application are not removed from the internal/external storage.\n
 157  * The directory path may not exist, so you must make sure that it exists before using it.\n
 158  * 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
 159  * If you want to access files or directories in #STORAGE_DIRECTORY_SYSTEM_RINGTONES, you must declare %http://tizen.org/privilege/systemsettings.\n
 160  * If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.\n
 161  * You must release @a path using free().
 162  *
 163  * @param[in] storage_id The storage device
 164  * @param[in] type The directory type
 165  * @param[out] path The absolute path to the directory type
 166  *
 167  * @return @c 0 on success,
 168  *         otherwise a negative error value
 169  *
 170  * @retval #STORAGE_ERROR_NONE               Successful
 171  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 172  * @retval #STORAGE_ERROR_OUT_OF_MEMORY      Out of memory
 173  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 174  *
 175  * @see storage_get_state()
 176  */
 177 int storage_get_directory(int storage_id, storage_directory_e type, char **path);
 178
 179 /**
 180  * @brief Gets the type of the given storage.
 181  *
 182  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 183  *
 184  * @param[in] storage_id The storage device
 185  * @param[out] type The type of the storage
 186  *
 187  * @return @c 0 on success,
 188  *         otherwise a negative error value
 189  *
 190  * @retval #STORAGE_ERROR_NONE               Successful
 191  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 192  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 193  */
 194 int storage_get_type(int storage_id, storage_type_e *type);
 195
 196 /**
 197  * @brief Gets the current state of the given storage.
 198  *
 199  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 200  *
 201  * @param[in] storage_id The storage device
 202  * @param[out] state The current state of the storage
 203  *
 204  * @return @c 0 on success,
 205  *         otherwise a negative error value
 206  *
 207  * @retval #STORAGE_ERROR_NONE               Successful
 208  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 209  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 210  *
 211  * @see storage_get_root_directory()
 212  * @see storage_get_total_space()
 213  * @see storage_get_available_space()
 214  */
 215 int storage_get_state(int storage_id, storage_state_e *state);
 216
 217 /**
 218  * @brief Called when the state of storage changes
 219  *
 220  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 221  *
 222  * @param[in] storage_id The unique storage ID
 223  * @param[in] state The current state of the storage
 224  * @param[in] user_data The user data passed from the foreach function
 225  *
 226  * @pre storage_set_state_changed_cb() will invoke this callback function.
 227  * @see storage_set_state_changed_cb()
 228  * @see storage_unset_state_changed_cb()
 229  */
 230 typedef void (*storage_state_changed_cb)(int storage_id, storage_state_e state, void *user_data);
 231
 232 /**
 233  * @brief Registers a callback function to be invoked when the state of the storage changes.
 234  *
 235  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 236  *
 237  * @param[in] storage_id The storage device
 238  * @param[in] callback The callback function to register
 239  * @param[in] user_data The user data to be passed to the callback function
 240  *
 241  * @return @c 0 on success,
 242  *         otherwise a negative error value
 243  *
 244  * @retval #STORAGE_ERROR_NONE               Successful
 245  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 246  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 247  * @retval #STORAGE_ERROR_OPERATION_FAILED Operation failed
 248  *
 249  * @post storage_state_changed_cb() will be invoked if the state of the registered storage changes.
 250  * @see storage_state_changed_cb()
 251  * @see storage_unset_state_changed_cb()
 252  */
 253 int storage_set_state_changed_cb(int storage_id, storage_state_changed_cb callback, void *user_data);
 254
 255 /**
 256  * @brief Unregisters the callback function.
 257  *
 258  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 259  *
 260  * @param[in] storage_id The storage device to monitor
 261  * @param[in] callback The callback function to register
 262  *
 263  * @return @c 0 on success,
 264  *         otherwise a negative error value
 265  *
 266  * @retval #STORAGE_ERROR_NONE               Successful
 267  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 268  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 269  * @retval #STORAGE_ERROR_OPERATION_FAILED   Operation failed
 270  *
 271  * @see storage_state_changed_cb()
 272  * @see storage_set_state_changed_cb()
 273  */
 274 int storage_unset_state_changed_cb(int storage_id, storage_state_changed_cb callback);
 275
 276 /**
 277  * @brief Enumeration of storage device types
 278  * @since_tizen 3.0
 279  */
 280 typedef enum {
 281         STORAGE_DEV_EXT_SDCARD = 1001,     /**< sdcard device (external storage) */
 282         STORAGE_DEV_EXT_USB_MASS_STORAGE,  /**< USB storage device (external storage) */
 283 } storage_dev_e;
 284
 285 /**
 286  * @brief Called when the state of a storage type changes.
 287  *
 288  * @since_tizen 3.0
 289  *
 290  * @param[in] storage_id The unique storage ID
 291  * @param[in] type The type of the storage device
 292  * @param[in] state The state of the storage
 293  * @param[in] fstype The type of the file system
 294  * @param[in] fsuuid The uuid of the file system
 295  * @param[in] mountpath The mount path of the file system
 296  * @param[in] primary The primary partition
 297  * @param[in] flags The flags for the storage status
 298  * @param[in] user_data The user data
 299  *
 300  * @pre storage_set_changed_cb() will invoke this callback function.
 301  * @see storage_set_changed_cb()
 302  * @see storage_unset_changed_cb()
 303  */
 304 typedef void (*storage_changed_cb)(int storage_id,
 305                 storage_dev_e dev, storage_state_e state,
 306                 const char *fstype, const char *fsuuid, const char *mountpath,
 307                 bool primary, int flags, void *user_data);
 308
 309 /**
 310  * @brief Registers a callback function to be invoked when the state of the specified storage device type changes.
 311  *
 312  * @since_tizen 3.0
 313  *
 314  * @param[in] type The type of the storage device
 315  * @param[in] callback The callback function to register
 316  * @param[in] user_data The user data to be passed to the callback function
 317  *
 318  * @return @c 0 on success,
 319  *         otherwise a negative error value
 320  *
 321  * @retval #STORAGE_ERROR_NONE               Successful
 322  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 323  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 324  * @retval #STORAGE_ERROR_OPERATION_FAILED   Operation failed
 325  *
 326  * @post storage_changed_cb() will be invoked if the state of the registered storage type changes.
 327  * @see storage_changed_cb()
 328  * @see storage_unset_changed_cb()
 329  */
 330 int storage_set_changed_cb(storage_type_e type, storage_changed_cb callback, void *user_data);
 331
 332 /**
 333  * @brief Unregisters the callback function for storage type state changes.
 334  *
 335  * @since_tizen 3.0
 336  *
 337  * @param[in] type The type of the the storage device
 338  * @param[in] callback The callback function to unregister
 339  *
 340  * @return @c 0 on success,
 341  *         otherwise a negative error value
 342  *
 343  * @retval #STORAGE_ERROR_NONE               Successful
 344  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 345  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 346  * @retval #STORAGE_ERROR_OPERATION_FAILED   Operation failed
 347  *
 348  * @see storage_changed_cb()
 349  * @see storage_set_changed_cb()
 350  */
 351 int storage_unset_changed_cb(storage_type_e type, storage_changed_cb callback);
 352
 353 /**
 354  * @brief Gets the total space of the given storage in bytes.
 355  *
 356  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 357  *
 358  * @param[in] storage_id The storage device
 359  * @param[out] bytes The total space size of the storage (bytes)
 360  *
 361  * @return @c 0 on success,
 362  *         otherwise a negative error value
 363  *
 364  * @retval #STORAGE_ERROR_NONE               Successful
 365  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 366  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 367  * @retval #STORAGE_ERROR_OPERATION_FAILED   Operation failed
 368  *
 369  * @see storage_get_state()
 370  * @see storage_get_available_space()
 371  */
 372 int storage_get_total_space(int storage_id, unsigned long long *bytes);
 373
 374 /**
 375  * @brief Gets the available space size of the given storage in bytes.
 376  *
 377  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 378  *
 379  * @param[in] storage_id The storage device
 380  * @param[out] bytes The available space size of the storage (bytes)
 381  *
 382  * @return @c 0 on success,
 383  *         otherwise a negative error value
 384  *
 385  * @retval #STORAGE_ERROR_NONE               Successful
 386  * @retval #STORAGE_ERROR_INVALID_PARAMETER  Invalid parameter
 387  * @retval #STORAGE_ERROR_NOT_SUPPORTED      Storage not supported
 388  * @retval #STORAGE_ERROR_OPERATION_FAILED   Operation failed
 389  *
 390  * @see storage_get_state()
 391  * @see storage_get_total_space()
 392  */
 393 int storage_get_available_space(int storage_id, unsigned long long *bytes);
 394
 395 /**
 396  * @}
 397  */
 398
 399 #ifdef __cplusplus
 400 }
 401 #endif
 402 #endif