The STORAGE API provides functions to get storage information.

Required Header

#include <storage.h>

Overview

The STORAGE API provides functions to get storage information.
It also offers functionality that enables users to register a callback so they can be informed whenever there is a change in the storage state.

The type of storage information includes:

Root directory
Storage type (Internal or External)
Storage state
Total and available space size
Storage device type (SDCARD or USB storage or extended internal)

The type of directory information includes:

Images
Sounds
Videos
Camera
Downloads
Music
Documents
Others
System ringtones

Related Features

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 using a callback function.
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 (such as internal or external) of the given storage.
int	storage_get_state (int storage_id, storage_state_e *state)
	Gets the current mounted state of storage corresponding to the specified id.
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 specific storage changes.
int	storage_unset_state_changed_cb (int storage_id, storage_state_changed_cb callback)
	Unregisters the callback function to stop calling the callback.
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 using id.
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 size of the internal storage located in the TZ_SYS_USER path.
int	storage_get_external_memory_size (struct statvfs *buf)
	Gets the size of the primary external storage if external storage is supported.
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 every time when the state of specific 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 each time when the state of a specific 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 each time when the state of a specific storage type changes.

Called every time the state of specific storage type changes.

Since :: 3.0

Remarks:: Defined by the storage_set_changed_cb() and storage_unset_changed_cb() caller.

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()

      my_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) {
      }

      storage_set_changed_cb(STORAGE_TYPE_EXTERNAL, my_storage_changed_cb, NULL);

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.

Called up to the maximum number of supported storages to get information.

Since :: 2.3

Remarks:: Defined by the storage_foreach_device_supported() caller.

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()

      my_storage_device_supported_cb(int storage_id, storage_type_e type,
              storage_state_e state, const char *path, void *user_data) {
              return true;
      }

      storage_foreach_device_supported(my_storage_device_supported_cb, NULL);

typedef void(* storage_state_changed_cb)(int storage_id, storage_state_e state, void *user_data)

Called every time when the state of specific storage changes.

Called every time the state of a specific storage changes, and when it is called, it retrieves the id and state of the storage.

Since :: 2.3

Remarks:: Defined by the storage_set_state_changed_cb() and storage_unset_state_changed_cb() caller.

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()

      my_storage_state_changed_cb(int storage_id, storage_state_e state, void *user_data) {
      }

      storage_set_state_changed_cb(0, my_storage_state_changed_cb, NULL);

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 using a callback 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

Remarks:: A callback function should be defined by this function caller.

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:: 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.

Gets the available space of a storage in bytes using storage_id.

Since :: 2.3

Remarks:: Determines whether it is an internal or external storage using the input storage_id.

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_id = 0;
      unsigned long long bytes;

      storage_get_available_space(storage_id, &bytes);

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.

Gets absolute path among several directories defined in the storage_directory_e.

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_id = 0;
      char path[100];

      storage_get_directory(storage_id, STORAGE_DIRECTORY_IMAGES, &path)

int storage_get_external_memory_size ( struct statvfs * buf )

Gets the size of the primary external storage if external storage is supported.

Retrieves of the external storage information
and returns the information stored in the struct statvfs structure.

Since :: 2.3

Remarks:: Returns STORAGE_ERROR_NOT_SUPPORTED if device does not support external storage feature.

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
STORAGE_ERROR_NOT_SUPPORTED	Storage not supported

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 size of the internal storage located in the TZ_SYS_USER path.

Retrieves of the internal storage information using statvfs() syscall
and returns the information stored in the struct statvfs structure.

Since :: 2.3

Remarks:: Does not require internal storage path as input.
It always uses the path stored in the TZ_SYS_USER environment variable.

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.

Determines root directory of internal or external storage using storage_id.

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_id = 0;
      char path[100];

      storage_get_root_directory(storage_id, &path)

int storage_get_state	(	int	storage_id,
		storage_state_e *	state
	)

Gets the current mounted state of storage corresponding to the specified id.

Gets the storage mounted state among defined in the storage_state_e using storage_id.

Since :: 2.3

Remarks:: Determines whether it is an internal or external storage using the input storage_id.

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_id = 0;
      storage_state_e state;

      storage_get_state(storage_id, &state);

int storage_get_total_space	(	int	storage_id,
		unsigned long long *	bytes
	)

Gets the total space of the given storage in bytes using id.

Finds target storage using storage_id and gets the total space of a storage in bytes.

Since :: 2.3

Remarks:: Determines whether it is an internal or external storage using the input storage_id.

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_id = 0;
      unsigned long long bytes;

      storage_get_total_space(storage_id, &bytes);

int storage_get_type	(	int	storage_id,
		storage_type_e *	type
	)

Gets the type (such as internal or external) of the given storage.

Gets the storage type among defined in the storage_type_e using storage_id.

Since :: 2.3

Remarks:: Determines whether it is an internal or external storage using the input storage_id.

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_id = 0; storage_type_e type; storage_get_type(storage_id, &type);

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.

Gets the external storage type defined in storage_type_e and kind defined in storage_dev_e using storage_id.

Since :: 5.0

Remarks:: Works solely on external storages, not internal 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_id = 0; storage_type_e type; storage_dev_e dev; storage_get_type_dev(storage_id, &type, &dev);

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.

Invokes the callback function each time for specific storage type whose state changes.

Since :: 3.0

Remarks:: A callback function should be defined by this function caller.

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 specific storage changes.

Invokes the callback function each time for a specific storage whose state changes.

Since :: 2.3

Remarks:: A callback function should be defined by this function caller.

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.

Prevents the callback function from being called any further.

Since :: 3.0

Remarks:: A callback function should be defined by this function caller.

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 to stop calling the callback.

Prevents the callback function from being called any further.

Since :: 2.3

Remarks:: A callback function should be defined by this function caller.

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

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation