Flipper Zero Firmware
Loading...
Searching...
No Matches
storage.h File Reference

APIs for working with storages, directories and files. More...

#include <stdint.h>
#include "filesystem_api_defines.h"
#include "storage_sd_api.h"

Go to the source code of this file.

Data Structures

struct  StorageEvent
 Storage event (passed to the PubSub callback). More...
 

Macros

#define STORAGE_INT_PATH_PREFIX   "/int"
 
#define STORAGE_EXT_PATH_PREFIX   "/ext"
 
#define STORAGE_ANY_PATH_PREFIX   "/any"
 
#define STORAGE_APP_DATA_PATH_PREFIX   "/data"
 
#define STORAGE_APP_ASSETS_PATH_PREFIX   "/assets"
 
#define INT_PATH(path)   STORAGE_INT_PATH_PREFIX "/" path
 
#define EXT_PATH(path)   STORAGE_EXT_PATH_PREFIX "/" path
 
#define ANY_PATH(path)   STORAGE_ANY_PATH_PREFIX "/" path
 
#define APP_DATA_PATH(path)   STORAGE_APP_DATA_PATH_PREFIX "/" path
 
#define APP_ASSETS_PATH(path)   STORAGE_APP_ASSETS_PATH_PREFIX "/" path
 
#define RECORD_STORAGE   "storage"
 

Typedefs

typedef struct Storage Storage
 
typedef void(* Storage_name_converter) (FuriString *)
 

Enumerations

enum  StorageEventType {
  StorageEventTypeCardMount , StorageEventTypeCardUnmount , StorageEventTypeCardMountError , StorageEventTypeFileClose ,
  StorageEventTypeDirClose
}
 Enumeration of events emitted by the storage through the PubSub system. More...
 

Functions

Filestorage_file_alloc (Storage *storage)
 Allocate and initialize a file instance.
 
void storage_file_free (File *file)
 Free the file instance.
 
FuriPubSubstorage_get_pubsub (Storage *storage)
 Get the storage pubsub instance.
 
bool storage_file_open (File *file, const char *path, FS_AccessMode access_mode, FS_OpenMode open_mode)
 Open an existing file or create a new one.
 
bool storage_file_close (File *file)
 Close the file.
 
bool storage_file_is_open (File *file)
 Check whether the file is open.
 
bool storage_file_is_dir (File *file)
 Check whether a file instance represents a directory.
 
size_t storage_file_read (File *file, void *buff, size_t bytes_to_read)
 Read bytes from a file into a buffer.
 
size_t storage_file_write (File *file, const void *buff, size_t bytes_to_write)
 Write bytes from a buffer to a file.
 
bool storage_file_seek (File *file, uint32_t offset, bool from_start)
 Change the current access position in a file.
 
uint64_t storage_file_tell (File *file)
 Get the current access position.
 
bool storage_file_truncate (File *file)
 Truncate the file size to the current access position.
 
uint64_t storage_file_size (File *file)
 Get the file size.
 
bool storage_file_sync (File *file)
 Synchronise the file cache with the actual storage.
 
bool storage_file_eof (File *file)
 Check whether the current access position is at the end of the file.
 
bool storage_file_exists (Storage *storage, const char *path)
 Check whether a file exists.
 
bool storage_file_copy_to_file (File *source, File *destination, size_t size)
 Copy data from a source file to the destination file.
 
bool storage_dir_open (File *file, const char *path)
 Open a directory.
 
bool storage_dir_close (File *file)
 Close the directory.
 
bool storage_dir_read (File *file, FileInfo *fileinfo, char *name, uint16_t name_length)
 Get the next item in the directory.
 
bool storage_dir_rewind (File *file)
 Change the access position to first item in the directory.
 
bool storage_dir_exists (Storage *storage, const char *path)
 Check whether a directory exists.
 
FS_Error storage_common_timestamp (Storage *storage, const char *path, uint32_t *timestamp)
 Get the last access time in UNIX format.
 
FS_Error storage_common_stat (Storage *storage, const char *path, FileInfo *fileinfo)
 Get information about a file or a directory.
 
FS_Error storage_common_remove (Storage *storage, const char *path)
 Remove a file or a directory.
 
FS_Error storage_common_rename (Storage *storage, const char *old_path, const char *new_path)
 Rename a file or a directory.
 
FS_Error storage_common_copy (Storage *storage, const char *old_path, const char *new_path)
 Copy the file to a new location.
 
FS_Error storage_common_merge (Storage *storage, const char *old_path, const char *new_path)
 Copy the contents of one directory into another and rename all conflicting files.
 
FS_Error storage_common_mkdir (Storage *storage, const char *path)
 Create a directory.
 
FS_Error storage_common_fs_info (Storage *storage, const char *fs_path, uint64_t *total_space, uint64_t *free_space)
 Get the general information about the storage.
 
void storage_common_resolve_path_and_ensure_app_directory (Storage *storage, FuriString *path)
 Parse aliases in a path and replace them with the real path.
 
FS_Error storage_common_migrate (Storage *storage, const char *source, const char *dest)
 Move the contents of source folder to destination one and rename all conflicting files.
 
bool storage_common_exists (Storage *storage, const char *path)
 Check whether a file or a directory exists.
 
bool storage_common_equivalent_path (Storage *storage, const char *path1, const char *path2, bool truncate)
 Check whether two paths are equivalent.
 
const char * storage_error_get_desc (FS_Error error_id)
 Get the textual description of a numeric error identifer.
 
FS_Error storage_file_get_error (File *file)
 Get the numeric error identifier from a file instance.
 
int32_t storage_file_get_internal_error (File *file)
 Get the internal (storage-specific) numeric error identifier from a file instance.
 
const char * storage_file_get_error_desc (File *file)
 Get the textual description of a the last error associated with a file instance.
 
FS_Error storage_sd_format (Storage *storage)
 Format the SD Card.
 
FS_Error storage_sd_unmount (Storage *storage)
 Unmount the SD card.
 
FS_Error storage_sd_mount (Storage *storage)
 Mount the SD card.
 
FS_Error storage_sd_info (Storage *storage, SDInfo *info)
 Get SD card information.
 
FS_Error storage_sd_status (Storage *storage)
 Get SD card status.
 
FS_Error storage_int_backup (Storage *storage, const char *dstname)
 Back up the internal storage contents to a *.tar archive.
 
FS_Error storage_int_restore (Storage *storage, const char *dstname, Storage_name_converter converter)
 Restore the internal storage contents from a *.tar archive.
 
bool storage_simply_remove (Storage *storage, const char *path)
 Remove a file or a directory.
 
bool storage_simply_remove_recursive (Storage *storage, const char *path)
 Recursively remove a file or a directory.
 
bool storage_simply_mkdir (Storage *storage, const char *path)
 Create a directory.
 
void storage_get_next_filename (Storage *storage, const char *dirname, const char *filename, const char *fileextension, FuriString *nextfilename, uint8_t max_len)
 Get the next free filename in a directory.
 

Detailed Description

APIs for working with storages, directories and files.

Enumeration Type Documentation

◆ StorageEventType

Enumeration of events emitted by the storage through the PubSub system.

Enumerator
StorageEventTypeCardMount 

SD card was mounted.

StorageEventTypeCardUnmount 

SD card was unmounted.

StorageEventTypeCardMountError 

An error occurred during mounting of an SD card.

StorageEventTypeFileClose 

A file was closed.

StorageEventTypeDirClose 

A directory was closed.

Function Documentation

◆ storage_common_copy()

FS_Error storage_common_copy ( Storage * storage,
const char * old_path,
const char * new_path )

Copy the file to a new location.

The file must NOT be open at the time of calling this function.

Parameters
storagepointer to a storage API instance.
old_pathpointer to a zero-terminated string containing the source path.
new_pathpointer to a zero-terminated string containing the destination path.
Returns
FSE_OK if the file has been successfully copied, any other error code on failure.

◆ storage_common_equivalent_path()

bool storage_common_equivalent_path ( Storage * storage,
const char * path1,
const char * path2,
bool truncate )

Check whether two paths are equivalent.

This function will resolve aliases and apply filesystem-specific rules to determine whether the two given paths are equivalent.

Examples:

  • /int/text and /ext/test -> false (Different storages),
  • /int/Test and /int/test -> false (Case-sensitive storage),
  • /ext/Test and /ext/test -> true (Case-insensitive storage).

If the truncate parameter is set to true, the second path will be truncated to be no longer than the first one. It is useful to determine whether path2 is a subdirectory of path1.

Parameters
storagepointer to a storage API instance.
path1pointer to a zero-terminated string containing the first path.
path2pointer to a zero-terminated string containing the second path.
truncatewhether to truncate path2 to be no longer than path1.
Returns
true if paths are equivalent, false otherwise.

◆ storage_common_exists()

bool storage_common_exists ( Storage * storage,
const char * path )

Check whether a file or a directory exists.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the path in question.
Returns
true if a file or a directory exists, false otherwise.

◆ storage_common_fs_info()

FS_Error storage_common_fs_info ( Storage * storage,
const char * fs_path,
uint64_t * total_space,
uint64_t * free_space )

Get the general information about the storage.

Parameters
storagepointer to a storage API instance.
fs_pathpointer to a zero-terminated string containing the path to the storage question.
total_spacepointer to the value to contain the total capacity, in bytes.
free_spacepointer to the value to contain the available space, in bytes.
Returns
FSE_OK if the information has been successfully received, any other error code on failure.

◆ storage_common_merge()

FS_Error storage_common_merge ( Storage * storage,
const char * old_path,
const char * new_path )

Copy the contents of one directory into another and rename all conflicting files.

Parameters
storagepointer to a storage API instance.
old_pathpointer to a zero-terminated string containing the source path.
new_pathpointer to a zero-terminated string containing the destination path.
Returns
FSE_OK if the directories have been successfully merged, any other error code on failure.

◆ storage_common_migrate()

FS_Error storage_common_migrate ( Storage * storage,
const char * source,
const char * dest )

Move the contents of source folder to destination one and rename all conflicting files.

Source folder will be deleted if the migration was successful.

Parameters
storagepointer to a storage API instance.
sourcepointer to a zero-terminated string containing the source path.
destpointer to a zero-terminated string containing the destination path.
Returns
FSE_OK if the migration was successfull completed, any other error code on failure.

◆ storage_common_mkdir()

FS_Error storage_common_mkdir ( Storage * storage,
const char * path )

Create a directory.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the directory path.
Returns
FSE_OK if the directory has been successfully created, any other error code on failure.

◆ storage_common_remove()

FS_Error storage_common_remove ( Storage * storage,
const char * path )

Remove a file or a directory.

The directory must be empty. The file or the directory must NOT be open.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the path of the item to be removed.
Returns
FSE_OK if the file or directory has been successfully removed, any other error code on failure.

◆ storage_common_rename()

FS_Error storage_common_rename ( Storage * storage,
const char * old_path,
const char * new_path )

Rename a file or a directory.

The file or the directory must NOT be open. Will overwrite the destination file if it already exists.

Renaming a regular file to itself does nothing and always succeeds. Renaming a directory to itself or to a subdirectory of itself always fails.

Parameters
storagepointer to a storage API instance.
old_pathpointer to a zero-terminated string containing the source path.
new_pathpointer to a zero-terminated string containing the destination path.
Returns
FSE_OK if the file or directory has been successfully renamed, any other error code on failure.

◆ storage_common_resolve_path_and_ensure_app_directory()

void storage_common_resolve_path_and_ensure_app_directory ( Storage * storage,
FuriString * path )

Parse aliases in a path and replace them with the real path.

Necessary special directories will be created automatically if they did not exist.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the path in question.

◆ storage_common_stat()

FS_Error storage_common_stat ( Storage * storage,
const char * path,
FileInfo * fileinfo )

Get information about a file or a directory.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the path of the item in question.
fileinfopointer to the FileInfo structure to contain the info (may be NULL).
Returns
FSE_OK if the info has been successfully received, any other error code on failure.

◆ storage_common_timestamp()

FS_Error storage_common_timestamp ( Storage * storage,
const char * path,
uint32_t * timestamp )

Get the last access time in UNIX format.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the path of the item in question.
timestamppointer to a value to contain the timestamp.
Returns
FSE_OK if the timestamp has been successfully received, any other error code on failure.

◆ storage_dir_close()

bool storage_dir_close ( File * file)

Close the directory.

Parameters
filepointer to a file instance representing the directory in question.
Returns
true if the directory was successfully closed, false otherwise.

◆ storage_dir_exists()

bool storage_dir_exists ( Storage * storage,
const char * path )

Check whether a directory exists.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the path of the directory in question.
Returns
true if the directory exists, false otherwise.

◆ storage_dir_open()

bool storage_dir_open ( File * file,
const char * path )

Open a directory.

Opening a directory is necessary to be able to read its contents with storage_dir_read().

Warning
The calling code MUST call storage_dir_close() even if the open operation had failed.
Parameters
filepointer to a file instance representing the directory in question.
pathpointer to a zero-terminated string containing the path of the directory in question.
Returns
true if the directory was successfully opened, false otherwise.

◆ storage_dir_read()

bool storage_dir_read ( File * file,
FileInfo * fileinfo,
char * name,
uint16_t name_length )

Get the next item in the directory.

If the next object does not exist, this function returns false as well and sets the file error id to FSE_NOT_EXIST.

Parameters
filepointer to a file instance representing the directory in question.
fileinfopointer to the FileInfo structure to contain the info (may be NULL).
namepointer to the buffer to contain the name (may be NULL).
name_lengthmaximum capacity of the name buffer, in bytes.
Returns
true if the next item was successfully read, false otherwise.

◆ storage_dir_rewind()

bool storage_dir_rewind ( File * file)

Change the access position to first item in the directory.

Parameters
filepointer to a file instance representing the directory in question.
Returns
true if the access position was successfully changed, false otherwise.

◆ storage_error_get_desc()

const char * storage_error_get_desc ( FS_Error error_id)

Get the textual description of a numeric error identifer.

Parameters
error_idnumeric identifier of the error in question.
Returns
pointer to a statically allocated zero-terminated string containing the respective error text.

◆ storage_file_alloc()

File * storage_file_alloc ( Storage * storage)

Allocate and initialize a file instance.

Parameters
storagepointer to a storage API instance.
Returns
pointer to the created instance.

◆ storage_file_close()

bool storage_file_close ( File * file)

Close the file.

Parameters
filepointer to the file instance to be closed.
Returns
true if the file was successfully closed, false otherwise.

◆ storage_file_copy_to_file()

bool storage_file_copy_to_file ( File * source,
File * destination,
size_t size )

Copy data from a source file to the destination file.

Both files must be opened prior to calling this function.

The requested amount of bytes will be copied from the current access position in the source file to the current access position in the destination file.

Parameters
sourcepointer to a source file instance.
destinationpointer to a destination file instance.
sizedata size to be copied, in bytes.
Returns
true if the data was successfully copied, false otherwise.

◆ storage_file_eof()

bool storage_file_eof ( File * file)

Check whether the current access position is at the end of the file.

Parameters
filepointer to a file instance in question.
Returns
bool true if the current access position is at the end of the file, false otherwise.

◆ storage_file_exists()

bool storage_file_exists ( Storage * storage,
const char * path )

Check whether a file exists.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the path to the file in question.
Returns
true if the file exists, false otherwise.

◆ storage_file_free()

void storage_file_free ( File * file)

Free the file instance.

If the file was open, calling this function will close it automatically.

Parameters
filepointer to the file instance to be freed.

◆ storage_file_get_error()

FS_Error storage_file_get_error ( File * file)

Get the numeric error identifier from a file instance.

Warning
It is not possible to get the error identifier after the file has been closed.
Parameters
filepointer to the file instance in question (must NOT be NULL).
Returns
numeric identifier of the last error associated with the file instance.

◆ storage_file_get_error_desc()

const char * storage_file_get_error_desc ( File * file)

Get the textual description of a the last error associated with a file instance.

Warning
It is not possible to get the error text after the file has been closed.
Parameters
filepointer to the file instance in question (must NOT be NULL).
Returns
pointer to a statically allocated zero-terminated string containing the respective error text.

◆ storage_file_get_internal_error()

int32_t storage_file_get_internal_error ( File * file)

Get the internal (storage-specific) numeric error identifier from a file instance.

Warning
It is not possible to get the internal error identifier after the file has been closed.
Parameters
filepointer to the file instance in question (must NOT be NULL).
Returns
numeric identifier of the last internal error associated with the file instance.

◆ storage_file_is_dir()

bool storage_file_is_dir ( File * file)

Check whether a file instance represents a directory.

Parameters
filepointer to the file instance in question.
Returns
true if the file instance represents a directory, false otherwise.

◆ storage_file_is_open()

bool storage_file_is_open ( File * file)

Check whether the file is open.

Parameters
filepointer to the file instance in question.
Returns
true if the file is open, false otherwise.

◆ storage_file_open()

bool storage_file_open ( File * file,
const char * path,
FS_AccessMode access_mode,
FS_OpenMode open_mode )

Open an existing file or create a new one.

Warning
The calling code MUST call storage_file_close() even if the open operation had failed.
Parameters
filepointer to the file instance to be opened.
pathpointer to a zero-terminated string containing the path to the file to be opened.
access_modeaccess mode from FS_AccessMode.
open_modeopen mode from FS_OpenMode
Returns
true if the file was successfully opened, false otherwise.

◆ storage_file_read()

size_t storage_file_read ( File * file,
void * buff,
size_t bytes_to_read )

Read bytes from a file into a buffer.

Parameters
filepointer to the file instance to read from.
buffpointer to the buffer to be filled with read data.
bytes_to_readnumber of bytes to read. Must be less than or equal to the size of the buffer.
Returns
actual number of bytes read (may be fewer than requested).

◆ storage_file_seek()

bool storage_file_seek ( File * file,
uint32_t offset,
bool from_start )

Change the current access position in a file.

Parameters
filepointer to the file instance in question.
offsetaccess position offset (meaning depends on from_start parameter).
from_startif true, set the access position relative to the file start, otherwise relative to the current position.
Returns
success flag

◆ storage_file_size()

uint64_t storage_file_size ( File * file)

Get the file size.

Parameters
filepointer to the file instance in question.
Returns
size of the file, in bytes.

◆ storage_file_sync()

bool storage_file_sync ( File * file)

Synchronise the file cache with the actual storage.

Parameters
filepointer to the file instance in question.
Returns
true if the file was successfully synchronised, false otherwise.

◆ storage_file_tell()

uint64_t storage_file_tell ( File * file)

Get the current access position.

Parameters
filepointer to the file instance in question.
Returns
current access position.

◆ storage_file_truncate()

bool storage_file_truncate ( File * file)

Truncate the file size to the current access position.

Parameters
filepointer to the file instance to be truncated.
Returns
true if the file was successfully truncated, false otherwise.

◆ storage_file_write()

size_t storage_file_write ( File * file,
const void * buff,
size_t bytes_to_write )

Write bytes from a buffer to a file.

Parameters
filepointer to the file instance to write into.
buffpointer to the buffer containing the data to be written.
bytes_to_writenumber of bytes to write. Must be less than or equal to the size of the buffer.
Returns
actual number of bytes written (may be fewer than requested).

◆ storage_get_next_filename()

void storage_get_next_filename ( Storage * storage,
const char * dirname,
const char * filename,
const char * fileextension,
FuriString * nextfilename,
uint8_t max_len )

Get the next free filename in a directory.

Usage example:

FuriString* file_name = furi_string_alloc();
Storage* storage = furi_record_open(RECORD_STORAGE);
"/ext/test",
"cookies",
".yum",
20);
furi_record_close(RECORD_STORAGE);
use_file_name(file_name);
furi_string_free(file_name);
void storage_get_next_filename(Storage *storage, const char *dirname, const char *filename, const char *fileextension, FuriString *nextfilename, uint8_t max_len)
Get the next free filename in a directory.
Definition storage_external_api.c:1037
Definition string.c:4
Definition storage_i.h:23

Possible file_name values after calling storage_get_next_filename(): "cookies", "cookies1", "cookies2", ... etc depending on whether any of these files have already existed in the directory.

Note
If the resulting next file name length is greater than set by the max_len parameter, the original filename will be returned instead.
Parameters
storagepointer to a storage API instance.
dirnamepointer to a zero-terminated string containing the directory path.
filenamepointer to a zero-terminated string containing the file name.
fileextensionpointer to a zero-terminated string containing the file extension.
nextfilenamepointer to a dynamic string containing the resulting file name.
max_lenmaximum length of the new name.

◆ storage_get_pubsub()

FuriPubSub * storage_get_pubsub ( Storage * storage)

Get the storage pubsub instance.

Storage will send StorageEvent messages.

Parameters
storagepointer to a storage API instance.
Returns
pointer to the pubsub instance.

◆ storage_int_backup()

FS_Error storage_int_backup ( Storage * storage,
const char * dstname )

Back up the internal storage contents to a *.tar archive.

Parameters
storagepointer to a storage API instance.
dstnamepointer to a zero-terminated string containing the archive file path.
Returns
FSE_OK if the storage was successfully backed up, any other error code on failure.

◆ storage_int_restore()

FS_Error storage_int_restore ( Storage * storage,
const char * dstname,
Storage_name_converter converter )

Restore the internal storage contents from a *.tar archive.

Parameters
storagepointer to a storage API instance.
dstnamepointer to a zero-terminated string containing the archive file path.
converterpointer to a filename conversion function (may be NULL).
Returns
FSE_OK if the storage was successfully restored, any other error code on failure.

◆ storage_sd_format()

FS_Error storage_sd_format ( Storage * storage)

Format the SD Card.

Parameters
storagepointer to a storage API instance.
Returns
FSE_OK if the card was successfully formatted, any other error code on failure.

◆ storage_sd_info()

FS_Error storage_sd_info ( Storage * storage,
SDInfo * info )

Get SD card information.

Parameters
storagepointer to a storage API instance.
infopointer to the info object to contain the requested information.
Returns
FSE_OK if the info was successfully received, any other error code on failure.

◆ storage_sd_mount()

FS_Error storage_sd_mount ( Storage * storage)

Mount the SD card.

Parameters
storagepointer to a storage API instance.
Returns
FSE_OK if the card was successfully mounted, any other error code on failure.

◆ storage_sd_status()

FS_Error storage_sd_status ( Storage * storage)

Get SD card status.

Parameters
storagepointer to a storage API instance.
Returns
storage status in the form of a numeric error identifier.

◆ storage_sd_unmount()

FS_Error storage_sd_unmount ( Storage * storage)

Unmount the SD card.

These return values have special meaning:

  • FSE_NOT_READY if the SD card is not mounted.
  • FSE_DENIED if there are open files on the SD card.
Parameters
storagepointer to a storage API instance.
Returns
FSE_OK if the card was successfully formatted, any other error code on failure.

◆ storage_simply_mkdir()

bool storage_simply_mkdir ( Storage * storage,
const char * path )

Create a directory.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the directory path.
Returns
true on success or if directory does already exist, false otherwise.

◆ storage_simply_remove()

bool storage_simply_remove ( Storage * storage,
const char * path )

Remove a file or a directory.

The following conditions must be met:

  • the directory must be empty.
  • the file or the directory must NOT be open.
Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the item path.
Returns
true on success or if the item does not exist, false otherwise.

◆ storage_simply_remove_recursive()

bool storage_simply_remove_recursive ( Storage * storage,
const char * path )

Recursively remove a file or a directory.

Unlike storage_simply_remove(), the directory does not need to be empty.

Parameters
storagepointer to a storage API instance.
pathpointer to a zero-terminated string containing the item path.
Returns
true on success or if the item does not exist, false otherwise.