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