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_id	The unique storage ID
[in]	dev	The type of the external storage device
[in]	state	The state of the storage
[in]	fstype	The type of the file system
[in]	fsuuid	The uuid of the file system
[in]	mountpath	The mount path of the file system
[in]	primary	The primary partition
[in]	flags	The flags for the storage status
[in]	user_data	The 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_id	The unique storage ID
[in]	type	The type of the storage
[in]	state	The current state of the storage
[in]	path	The absolute path to the root directory of the storage
[in]	user_data	The 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_id	The unique storage ID
[in]	state	The current state of the storage
[in]	user_data	The 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

enum storage_dev_e

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)

enum storage_directory_e

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.

enum storage_error_e

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

enum storage_state_e

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

enum storage_type_e

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]	callback	The iteration callback function
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

STORAGE_ERROR_NONE	Successful
STORAGE_ERROR_INVALID_PARAMETER	Invalid 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_id	The storage device
[out]	bytes	The available space size of the storage (bytes)

Returns:: 0 on success, otherwise a negative error value

Return values:

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

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_id	The storage device
[in]	type	The directory type
[out]	path	The absolute path to the directory type

Returns:: 0 on success, otherwise a negative error value

Return values:

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

See also:: storage_get_state()

int storage_get_external_memory_size ( struct statvfs * buf )

Gets the external memory size.

Since :: 2.3

Parameters:

[out] buf A pointer to a statvfs structure

Returns:: 0 on success, otherwise a negative error value on failure

Return values:

STORAGE_ERROR_NONE	Successful
STORAGE_ERROR_INVALID_PARAMETER	Invalid parameter
STORAGE_ERROR_OPERATION_FAILED	Operation 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] buf A pointer to a statvfs structure

Returns:: 0 on success, otherwise a negative error value on failure

Return values:

STORAGE_ERROR_NONE	Successful
STORAGE_ERROR_INVALID_PARAMETER	Invalid parameter
STORAGE_ERROR_OPERATION_FAILED	Operation 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_id	The storage device
[out]	path	The absolute path to the storage directory

Returns:: 0 on success, otherwise a negative error value

Return values:

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

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_id	The storage device
[out]	state	The current state of the storage

Returns:: 0 on success, otherwise a negative error value

Return values:

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

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_id	The storage device
[out]	bytes	The total space size of the storage (bytes)

Returns:: 0 on success, otherwise a negative error value

Return values:

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

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_id	The storage device
[out]	type	The type of the storage

Returns:: 0 on success, otherwise a negative error value

Return values:

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

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_id	The storage id
[out]	type	The storage type (internal or external). If type is STORAGE_TYPE_INTERNAL, this function returns STORAGE_ERROR_INVALID_PARAMETER and dev is unchanged.
[out]	dev	The storage device for external storage.

Returns:: 0 on success, otherwise a negative error value

Return values:

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

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]	type	The type of the storage device
[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

STORAGE_ERROR_NONE	Successful
STORAGE_ERROR_INVALID_PARAMETER	Invalid parameter
STORAGE_ERROR_NOT_SUPPORTED	Storage not supported
STORAGE_ERROR_OPERATION_FAILED	Operation 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_id	The storage device
[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

STORAGE_ERROR_NONE	Successful
STORAGE_ERROR_INVALID_PARAMETER	Invalid parameter
STORAGE_ERROR_NOT_SUPPORTED	Storage not supported
STORAGE_ERROR_OPERATION_FAILED	Operation 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()

int storage_unset_changed_cb	(	storage_type_e	type,
		storage_changed_cb	callback
	)

Unregisters the callback function for storage type state changes.

Since :: 3.0

Parameters:

[in]	type	The type of the the storage device
[in]	callback	The callback function to unregister

Returns:: 0 on success, otherwise a negative error value

Return values:

STORAGE_ERROR_NONE	Successful
STORAGE_ERROR_INVALID_PARAMETER	Invalid parameter
STORAGE_ERROR_NOT_SUPPORTED	Storage not supported
STORAGE_ERROR_OPERATION_FAILED	Operation 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_id	The storage device to monitor
[in]	callback	The callback function to register

Returns:: 0 on success, otherwise a negative error value

Return values:

STORAGE_ERROR_NONE	Successful
STORAGE_ERROR_INVALID_PARAMETER	Invalid parameter
STORAGE_ERROR_NOT_SUPPORTED	Storage not supported
STORAGE_ERROR_OPERATION_FAILED	Operation failed

See also:: storage_state_changed_cb(); storage_set_state_changed_cb()

Required Header

Overview

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation