Tizen Native API  6.5

The STORAGE API provides functions to get storage information.

Required Header

#include <storage.h>

Overview

The STORAGE API provides functions to get storage information.

The type of storage information includes:

  • Root directory
  • Storage type (Internal or External)
  • Storage status
  • Total and available space size

The type of directory information includes:

  • Images
  • Sounds
  • Videos
  • Camera
  • Downloads
  • Music
  • Documents
  • Others
  • System ringtones

Overview

This API is related with the following features:

  • http://tizen.org/feature/storage.external

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from feature element description.

Functions

int storage_foreach_device_supported (storage_device_supported_cb callback, void *user_data)
 Retrieves all the storage in a device.
int storage_get_root_directory (int storage_id, char **path)
 Gets the absolute path to the root directory of the given storage.
int storage_get_directory (int storage_id, storage_directory_e type, char **path)
 Gets the absolute path to the each directory of the given storage.
int storage_get_type (int storage_id, storage_type_e *type)
 Gets the type of the given storage.
int storage_get_state (int storage_id, storage_state_e *state)
 Gets the current state of the given storage.
int storage_set_state_changed_cb (int storage_id, storage_state_changed_cb callback, void *user_data)
 Registers a callback function to be invoked when the state of the storage changes.
int storage_unset_state_changed_cb (int storage_id, storage_state_changed_cb callback)
 Unregisters the callback function.
int storage_set_changed_cb (storage_type_e type, storage_changed_cb callback, void *user_data)
 Registers a callback function to be invoked when the state of the specified storage device type changes.
int storage_unset_changed_cb (storage_type_e type, storage_changed_cb callback)
 Unregisters the callback function for storage type state changes.
int storage_get_total_space (int storage_id, unsigned long long *bytes)
 Gets the total space of the given storage in bytes.
int storage_get_available_space (int storage_id, unsigned long long *bytes)
 Gets the available space size of the given storage in bytes.
int storage_get_type_dev (int storage_id, storage_type_e *type, storage_dev_e *dev)
 Gets the type and the kind of external device for the given storage id.
int storage_get_internal_memory_size (struct statvfs *buf)
 Gets the internal memory size.
int storage_get_external_memory_size (struct statvfs *buf)
 Gets the external memory size.

Typedefs

typedef bool(* storage_device_supported_cb )(int storage_id, storage_type_e type, storage_state_e state, const char *path, void *user_data)
 Called to get information once for each supported storage.
typedef void(* storage_state_changed_cb )(int storage_id, storage_state_e state, void *user_data)
 Called when the state of storage changes.
typedef void(* storage_changed_cb )(int storage_id, storage_dev_e dev, storage_state_e state, const char *fstype, const char *fsuuid, const char *mountpath, bool primary, int flags, void *user_data)
 Called when the state of a storage type changes.

Typedef Documentation

typedef void(* storage_changed_cb)(int storage_id, storage_dev_e dev, storage_state_e state, const char *fstype, const char *fsuuid, const char *mountpath, bool primary, int flags, void *user_data)

Called when the state of a storage type changes.

Since :
3.0
Parameters:
[in]storage_idThe unique storage ID
[in]devThe type of the external storage device
[in]stateThe state of the storage
[in]fstypeThe type of the file system
[in]fsuuidThe uuid of the file system
[in]mountpathThe mount path of the file system
[in]primaryThe primary partition
[in]flagsThe flags for the storage status
[in]user_dataThe user data
Precondition:
storage_set_changed_cb() will invoke this callback function.
See also:
storage_set_changed_cb()
storage_unset_changed_cb()
typedef bool(* storage_device_supported_cb)(int storage_id, storage_type_e type, storage_state_e state, const char *path, void *user_data)

Called to get information once for each supported storage.

Since :
2.3
Parameters:
[in]storage_idThe unique storage ID
[in]typeThe type of the storage
[in]stateThe current state of the storage
[in]pathThe absolute path to the root directory of the storage
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop,
otherwise false to break out of the loop
Precondition:
storage_foreach_device_supported() will invoke this callback function.
See also:
storage_foreach_device_supported()
typedef void(* storage_state_changed_cb)(int storage_id, storage_state_e state, void *user_data)

Called when the state of storage changes.

Since :
2.3
Parameters:
[in]storage_idThe unique storage ID
[in]stateThe current state of the storage
[in]user_dataThe user data passed from the foreach function
Precondition:
storage_set_state_changed_cb() will invoke this callback function.
See also:
storage_set_state_changed_cb()
storage_unset_state_changed_cb()

Enumeration Type Documentation

Enumeration for storage device types.

Since :
3.0
Enumerator:
STORAGE_DEV_EXT_SDCARD 

SD card device (external storage)

STORAGE_DEV_EXT_USB_MASS_STORAGE 

USB storage device (external storage)

STORAGE_DEV_EXTENDED_INTERNAL 

Extended internal storage device (External storage used as internal storage) (Since 4.0)

Enumeration for the storage directory types.

Since :
2.3
Enumerator:
STORAGE_DIRECTORY_IMAGES 

Image directory

STORAGE_DIRECTORY_SOUNDS 

Sounds directory

STORAGE_DIRECTORY_VIDEOS 

Videos directory

STORAGE_DIRECTORY_CAMERA 

Camera directory

STORAGE_DIRECTORY_DOWNLOADS 

Downloads directory

STORAGE_DIRECTORY_MUSIC 

Music directory

STORAGE_DIRECTORY_DOCUMENTS 

Documents directory

STORAGE_DIRECTORY_OTHERS 

Others directory

STORAGE_DIRECTORY_SYSTEM_RINGTONES 

System ringtones directory. Only available for internal storage.

Enumeration for Storage of error codes.

Since :
2.3
Enumerator:
STORAGE_ERROR_NONE 

Successful

STORAGE_ERROR_INVALID_PARAMETER 

Invalid parameter

STORAGE_ERROR_OUT_OF_MEMORY 

Out of memory

STORAGE_ERROR_NOT_SUPPORTED 

Storage not supported

STORAGE_ERROR_OPERATION_FAILED 

Operation failed

Enumeration for storage devices state.

Since :
2.3
Enumerator:
STORAGE_STATE_UNMOUNTABLE 

Storage is present but cannot be mounted. Typically it happens if the file system of the storage is corrupted

STORAGE_STATE_REMOVED 

Storage is not present

STORAGE_STATE_MOUNTED 

Storage is present and mounted with read/write access

STORAGE_STATE_MOUNTED_READ_ONLY 

Storage is present and mounted with read only access

Enumeration for the storage types.

Since :
2.3
Enumerator:
STORAGE_TYPE_INTERNAL 

Internal device storage (built-in storage in a device, non-removable)

STORAGE_TYPE_EXTERNAL 

External storage

STORAGE_TYPE_EXTENDED_INTERNAL 

Extended internal storage (External storage used as internal storage) (Since 4.0)


Function Documentation

int storage_foreach_device_supported ( storage_device_supported_cb  callback,
void *  user_data 
)

Retrieves all the storage in a device.

This function invokes the callback function once for each storage in a device.
If storage_device_supported_cb() returns false, then the iteration will be finished.

Since :
2.3
Parameters:
[in]callbackThe iteration callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
Postcondition:
This function invokes storage_device_supported_cb() repeatedly for each supported device.
See also:
storage_device_supported_cb()
int storage_get_available_space ( int  storage_id,
unsigned long long *  bytes 
)

Gets the available space size of the given storage in bytes.

Since :
2.3
Parameters:
[in]storage_idThe storage device
[out]bytesThe available space size of the storage (bytes)
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_OUT_OF_MEMORYOut of memory
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
See also:
storage_get_state()
storage_get_total_space()
int storage_get_directory ( int  storage_id,
storage_directory_e  type,
char **  path 
)

Gets the absolute path to the each directory of the given storage.

Since :
2.3
Remarks:
Files saved on the internal/external storage are readable or writable by all applications.
When an application is uninstalled, the files written by that application are not removed from the internal/external storage.
The directory path may not exist, so you must make sure that it exists before using it.
If you want to access files or directories in internal storage, you must declare http://tizen.org/privilege/mediastorage.
If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.
Refer to Privacy-related Permissions.
You must release path using free().
Parameters:
[in]storage_idThe storage device
[in]typeThe directory type
[out]pathThe absolute path to the directory type
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_OUT_OF_MEMORYOut of memory
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
See also:
storage_get_state()
int storage_get_external_memory_size ( struct statvfs *  buf)

Gets the external memory size.

Since :
2.3
Parameters:
[out]bufA pointer to a statvfs structure
Returns:
0 on success, otherwise a negative error value on failure
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_OPERATION_FAILEDOperation failed
Example:
    ...
  struct statvfs s;
    if (storage_get_external_memory_size(&s) < 0)
        dlog_print(DLOG_DEBUG, LOG_TAG, "Fail to get external memory size");
    else
        dlog_print(DLOG_DEBUG, LOG_TAG, "Total mem : %lf, Avail mem : %lf",
                (double)s.f_frsize*s.f_blocks, (double)s.f_bsize*s.f_bavail);
    ...
int storage_get_internal_memory_size ( struct statvfs *  buf)

Gets the internal memory size.

Since :
2.3
Parameters:
[out]bufA pointer to a statvfs structure
Returns:
0 on success, otherwise a negative error value on failure
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_OPERATION_FAILEDOperation failed
Example:
    ...
  struct statvfs s;
    if (storage_get_internal_memory_size(&s) < 0)
    dlog_print(DLOG_DEBUG, LOG_TAG, "Fail to get internal memory size");
    else
        dlog_print(DLOG_DEBUG, LOG_TAG, "Total mem : %lf, Avail mem : %lf",
                (double)s.f_frsize*s.f_blocks, (double)s.f_bsize*s.f_bavail);
    ...
int storage_get_root_directory ( int  storage_id,
char **  path 
)

Gets the absolute path to the root directory of the given storage.

Since :
2.3
Remarks:
Files saved on the internal/external storage are readable or writable by all applications.
When an application is uninstalled, the files written by that application are not removed from the internal/external storage.
If you want to access files or directories in internal storage, you must declare http://tizen.org/privilege/mediastorage.
If you want to access files or directories in external storage, you must declare http://tizen.org/privilege/externalstorage.
Refer to Privacy-related Permissions.
You must release path using free().
Parameters:
[in]storage_idThe storage device
[out]pathThe absolute path to the storage directory
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_OUT_OF_MEMORYOut of memory
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
See also:
storage_get_state()
int storage_get_state ( int  storage_id,
storage_state_e state 
)

Gets the current state of the given storage.

Since :
2.3
Parameters:
[in]storage_idThe storage device
[out]stateThe current state of the storage
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_OUT_OF_MEMORYOut of memory
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
See also:
storage_get_root_directory()
storage_get_total_space()
storage_get_available_space()
int storage_get_total_space ( int  storage_id,
unsigned long long *  bytes 
)

Gets the total space of the given storage in bytes.

Since :
2.3
Parameters:
[in]storage_idThe storage device
[out]bytesThe total space size of the storage (bytes)
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_OUT_OF_MEMORYOut of memory
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
See also:
storage_get_state()
storage_get_available_space()
int storage_get_type ( int  storage_id,
storage_type_e type 
)

Gets the type of the given storage.

Since :
2.3
Parameters:
[in]storage_idThe storage device
[out]typeThe type of the storage
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_OUT_OF_MEMORYOut of memory
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
int storage_get_type_dev ( int  storage_id,
storage_type_e type,
storage_dev_e dev 
)

Gets the type and the kind of external device for the given storage id.

Since :
5.0
Remarks:
This function works only for external storages. If type is STORAGE_TYPE_INTERNAL, this function returns STORAGE_ERROR_INVALID_PARAMETER and dev is unchanged.
Parameters:
[in]storage_idThe storage id
[out]typeThe storage type (internal or external). If type is STORAGE_TYPE_INTERNAL, this function returns STORAGE_ERROR_INVALID_PARAMETER and dev is unchanged.
[out]devThe storage device for external storage.
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_OUT_OF_MEMORYOut of memory
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
int storage_set_changed_cb ( storage_type_e  type,
storage_changed_cb  callback,
void *  user_data 
)

Registers a callback function to be invoked when the state of the specified storage device type changes.

Since :
3.0
Parameters:
[in]typeThe type of the storage device
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
Postcondition:
storage_changed_cb() will be invoked if the state of the registered storage type changes.
See also:
storage_changed_cb()
storage_unset_changed_cb()
int storage_set_state_changed_cb ( int  storage_id,
storage_state_changed_cb  callback,
void *  user_data 
)

Registers a callback function to be invoked when the state of the storage changes.

Since :
2.3
Parameters:
[in]storage_idThe storage device
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
Postcondition:
storage_state_changed_cb() will be invoked if the state of the registered storage changes.
See also:
storage_state_changed_cb()
storage_unset_state_changed_cb()

Unregisters the callback function for storage type state changes.

Since :
3.0
Parameters:
[in]typeThe type of the the storage device
[in]callbackThe callback function to unregister
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
See also:
storage_changed_cb()
storage_set_changed_cb()
int storage_unset_state_changed_cb ( int  storage_id,
storage_state_changed_cb  callback 
)

Unregisters the callback function.

Since :
2.3
Parameters:
[in]storage_idThe storage device to monitor
[in]callbackThe callback function to register
Returns:
0 on success, otherwise a negative error value
Return values:
STORAGE_ERROR_NONESuccessful
STORAGE_ERROR_INVALID_PARAMETERInvalid parameter
STORAGE_ERROR_NOT_SUPPORTEDStorage not supported
STORAGE_ERROR_OPERATION_FAILEDOperation failed
See also:
storage_state_changed_cb()
storage_set_state_changed_cb()