Storage: Getting Information about Storages

This tutorial demonstrates how you can obtain detailed information from the internal and external storage.

Warm-up

Become familiar with the Storage API basics by learning about:

Using Statvfs Wrapper
Retrieve internal and external memory sizes.
Retrieving Storage Information
Retrieve information about supported storages and the storage content.
Monitoring Storage State Changes
Monitor changes in the storage state.
Retrieving Storage Space Information
Retrieve information about the storage space.

Using Statvfs Wrapper

Use the statvfs wrapper to get memory sizes:

To use the Storage API (in mobile and wearable applications) features, include the <storage.h> header file in your application:
```
#include <storage.h>
```
Get memory sizes:
- Get internal memory size with the storage_get_internal_memory_size() function.
  The function returns the internal memory size. Use it instead of the statvfs function when you need the internal memory size.
  
  At least a low memory pop-up is launched in case the memory is low, and to do that, a minimum memory is reserved. To allow memory for the pop-up, the function returns a memory size except for a minimum memory size. The minimum memory size depends on the device storage size.
  
  Statvfs structure has a different structure size from the __USE_FILE_OFFSET64 option. If your module defines this option, libstorage changes storage_get_internal_memory_size() to storage_get_internal_memory_size64() automatically.
```
int error;
struct statvfs s;
error = storage_get_internal_memory_size(&s);
```
- Get external memory size with the storage_get_external_memory_size() function.
  The function returns the external memory size. Use it instead of the statvfs function when you need the external memory size.
  
  At least a low memory pop-up is launched in case the memory is low, and to do that, a minimum memory is reserved. To allow memory for the pop-up, the function returns a memory size except for a minimum memory size. The minimum memory size depends on the device storage size.
  
  Statvfs structure has a different structure size from the __USE_FILE_OFFSET64 option. If your module defines this option, libstorage changes storage_get_external_memory_size() to storage_get_external_memory_size64() automatically.
```
int error;
struct statvfs s;
error = storage_get_external_memory_size(&s);
```

Retrieving Storage Information

To retrieve storage information:

To use the Storage API (in mobile and wearable applications) features, include the <storage.h> header file in your application:
```
#include <storage.h>
```
Retrieve storage information:
- Check for supported storages.
  Call the storage_device_supported_cb callback function to get information once for each supported storage. If this function returns false, the iteration is finished.
```
static int internal_storage_id;
static bool storage_cb(int storage_id, storage_type_e type, storage_state_e state, const char *path, void *user_data)
{
   if (type == STORAGE_TYPE_INTERNAL) 
   {
      internal_storage_id = storage_id;

      return false;
   }

   return true;
}
```
- Retrieve all storages in a device.
  Call the storage_foreach_device_supported() function to invoke the storage_device_supported_cb() callback function repeatedly, once for each storage in a device.
```
int error;
error = storage_foreach_device_supported(storage_cb, NULL);
```
- Get the root directory.
  Call the storage_get_root_directory() function to get the absolute path to the root directory of a given storage. Files saved on the internal and external storage are readable or writeable by all applications. When an application is uninstalled, the files written by that application are not removed from the internal or external storage.
```
int error;
char *path;
error = storage_get_root_directory(internal_storage_id, &path);

free(path);
```
- Get the media directory.
  Call the storage_get_directory() function to get the absolute path to each directory of the given storage. Files saved on the internal or external storage are readable or writeable by all applications. When an application is uninstalled, the files written by that application are not removed from the internal or external storage.
  
  The second parameter defines the directory type based on the storage_directory_e enum:
  - STORAGE_DIRECTORY_IMAGES
  - STORAGE_DIRECTORY_SOUNDS
  - STORAGE_DIRECTORY_VIDEOS
  - STORAGE_DIRECTORY_CAMERA
  - STORAGE_DIRECTORY_DOWNLOADS
  - STORAGE_DIRECTORY_MUSIC
  - STORAGE_DIRECTORY_DOCUMENTS
  - STORAGE_DIRECTORY_OTHERS
  - STORAGE_DIRECTORY_SYSTEM_RINGTONES
```
int error;
char *path;
error = storage_get_directory(internal_storage_id, STORAGE_DIRECTORY_IMAGES, &path);

free(path);
```
- Get the storage type.
  Call the storage_get_type() function to get the type of the given storage.
  
  The storage_type_e enumerator (in mobile and wearable applications)defines the available storage types.
```
int error;
storage_type_e type;
error = storage_get_type(internal_storage_id, &type);
```
- Get the storage mount state.
  Call the storage_get_state() function to get the current state of the given storage.
  
  The storage_state_e enumerator (in mobile and wearable applications)defines the available storage states.
```
int error;
storage_state_e state;
error = storage_get_state(internal_storage_id, &state);
```

Monitoring Storage State Changes

To monitor storage state changes:

To use the Storage API (in mobile and wearable applications) features, include the <storage.h> header file in your application:
```
#include <storage.h>
```

Define the storage changed callback, which is called when a storage state changes.

static void storage_changed_cb(int storage_id, storage_state_e state, void *user_data)
{
   if (storage_id != internal_storage_id)
      return;
   dlog_print(DLOG_DEBUG, LOG_TAG, "state changed to %d", state);
}

int error;
error = storage_set_state_changed_cb(internal_storage_id, storage_changed_cb, NULL);

When the callback is no longer needed, unregister it.

int error;
error = storage_unset_state_changed_cb(internal_storage_id, storage_changed_cb);

Retrieving Storage Space Information

To retrieve storage space information:

To use the Storage API (in mobile and wearable applications) features, include the <storage.h> header file in your application:
```
#include <storage.h>
```
Retrieve storage space:
- Get the total space of the storage using the storage_get_total_space() function.
  The function returns the total space of the given storage in bytes. It invokes the storage_get_internal_memory_size() or storage_get_external_memory_size() internally.
```
int error;
unsigned long long bytes;
error = storage_get_total_space(internal_storage_id, &bytes);
```
- Get the available space of the storage using the storage_get_available_space() function.
  This function returns the available space of the given storage in bytes. This function invokes the storage_get_internal_memory_size() or storage_get_external_memory_size() internally.
```
int error;
unsigned long long bytes;
error = storage_get_available_space(internal_storage_id, &bytes);
```