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) |
#define | EXT_PATH(path) |
#define | ANY_PATH(path) |
#define | APP_DATA_PATH(path) |
#define | APP_ASSETS_PATH(path) |
#define | RECORD_STORAGE "storage" |
Typedefs | |
typedef struct Storage | Storage |
typedef void(* | StorageNameConverter) (FuriString *) |
Enumerations | |
enum | StorageEventType { StorageEventTypeCardMount , StorageEventTypeCardUnmount , StorageEventTypeCardMountError , StorageEventTypeFileClose , StorageEventTypeDirClose } |
Enumeration of events emitted by the storage through the PubSub system. More... | |
Functions | |
File * | storage_file_alloc (Storage *storage) |
Allocate and initialize a file instance. | |
void | storage_file_free (File *file) |
Free the file instance. | |
FuriPubSub * | storage_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) |
Check whether two paths are equivalent. | |
bool | storage_common_is_subdir (Storage *storage, const char *parent, const char *child) |
Check whether a path is a subpath of another path. | |
const char * | storage_error_get_desc (FS_Error error_id) |
Get the textual description of a numeric error identifier. | |
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, StorageNameConverter 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. | |
APIs for working with storages, directories and files.
#define ANY_PATH | ( | path | ) |
#define APP_ASSETS_PATH | ( | path | ) |
#define APP_DATA_PATH | ( | path | ) |
#define EXT_PATH | ( | path | ) |
#define INT_PATH | ( | path | ) |
enum StorageEventType |
Enumeration of events emitted by the storage through the PubSub system.
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.
storage | pointer to a storage API instance. |
old_path | pointer to a zero-terminated string containing the source path. |
new_path | pointer to a zero-terminated string containing the destination path. |
bool storage_common_equivalent_path | ( | Storage * | storage, |
const char * | path1, | ||
const char * | path2 ) |
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:
storage | pointer to a storage API instance. |
path1 | pointer to a zero-terminated string containing the first path. |
path2 | pointer to a zero-terminated string containing the second path. |
bool storage_common_exists | ( | Storage * | storage, |
const char * | path ) |
Check whether a file or a directory exists.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the path in question. |
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.
storage | pointer to a storage API instance. |
fs_path | pointer to a zero-terminated string containing the path to the storage question. |
total_space | pointer to the value to contain the total capacity, in bytes. |
free_space | pointer to the value to contain the available space, in bytes. |
bool storage_common_is_subdir | ( | Storage * | storage, |
const char * | parent, | ||
const char * | child ) |
Check whether a path is a subpath of another path.
This function respects storage-defined equivalence rules (see storage_common_equivalent_path
).
storage | pointer to a storage API instance. |
parent | pointer to a zero-terminated string containing the parent path. |
child | pointer to a zero-terminated string containing the child path. |
child
is a subpath of parent
, or if child
is equivalent to parent
; false otherwise. 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.
storage | pointer to a storage API instance. |
old_path | pointer to a zero-terminated string containing the source path. |
new_path | pointer to a zero-terminated string containing the destination 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.
Source folder will be deleted if the migration was successful.
storage | pointer to a storage API instance. |
source | pointer to a zero-terminated string containing the source path. |
dest | pointer to a zero-terminated string containing the destination path. |
FS_Error storage_common_mkdir | ( | Storage * | storage, |
const char * | path ) |
Create a directory.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the directory path. |
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.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the path of the item to be removed. |
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.
storage | pointer to a storage API instance. |
old_path | pointer to a zero-terminated string containing the source path. |
new_path | pointer to a zero-terminated string containing the destination path. |
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.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the path in question. |
Get information about a file or a directory.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the path of the item in question. |
fileinfo | pointer to the FileInfo structure to contain the info (may be NULL). |
FS_Error storage_common_timestamp | ( | Storage * | storage, |
const char * | path, | ||
uint32_t * | timestamp ) |
Get the last access time in UNIX format.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the path of the item in question. |
timestamp | pointer to a value to contain the timestamp. |
bool storage_dir_close | ( | File * | file | ) |
Close the directory.
file | pointer to a file instance representing the directory in question. |
bool storage_dir_exists | ( | Storage * | storage, |
const char * | path ) |
Check whether a directory exists.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the path of the directory in question. |
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().
file | pointer to a file instance representing the directory in question. |
path | pointer to a zero-terminated string containing the path of the directory in question. |
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.
file | pointer to a file instance representing the directory in question. |
fileinfo | pointer to the FileInfo structure to contain the info (may be NULL). |
name | pointer to the buffer to contain the name (may be NULL). |
name_length | maximum capacity of the name buffer, in bytes. |
bool storage_dir_rewind | ( | File * | file | ) |
Change the access position to first item in the directory.
file | pointer to a file instance representing the directory in question. |
const char * storage_error_get_desc | ( | FS_Error | error_id | ) |
Get the textual description of a numeric error identifier.
error_id | numeric identifier of the error in question. |
Allocate and initialize a file instance.
storage | pointer to a storage API instance. |
bool storage_file_close | ( | File * | file | ) |
Close the file.
file | pointer to the file instance to be closed. |
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.
source | pointer to a source file instance. |
destination | pointer to a destination file instance. |
size | data size to be copied, in bytes. |
bool storage_file_eof | ( | File * | file | ) |
Check whether the current access position is at the end of the file.
file | pointer to a file instance in question. |
bool storage_file_exists | ( | Storage * | storage, |
const char * | path ) |
Check whether a file exists.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the path to the file in question. |
void storage_file_free | ( | File * | file | ) |
Free the file instance.
If the file was open, calling this function will close it automatically.
file | pointer to the file instance to be freed. |
FS_Error storage_file_get_error | ( | File * | file | ) |
Get the numeric error identifier from a file instance.
file | pointer to the file instance in question (must NOT be NULL). |
const char * storage_file_get_error_desc | ( | File * | file | ) |
Get the textual description of a the last error associated with a file instance.
file | pointer to the file instance in question (must NOT be NULL). |
int32_t storage_file_get_internal_error | ( | File * | file | ) |
Get the internal (storage-specific) numeric error identifier from a file instance.
file | pointer to the file instance in question (must NOT be NULL). |
bool storage_file_is_dir | ( | File * | file | ) |
Check whether a file instance represents a directory.
file | pointer to the file instance in question. |
bool storage_file_is_open | ( | File * | file | ) |
Check whether the file is open.
file | pointer to the file instance in question. |
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.
file | pointer to the file instance to be opened. |
path | pointer to a zero-terminated string containing the path to the file to be opened. |
access_mode | access mode from FS_AccessMode. |
open_mode | open mode from FS_OpenMode |
size_t storage_file_read | ( | File * | file, |
void * | buff, | ||
size_t | bytes_to_read ) |
Read bytes from a file into a buffer.
file | pointer to the file instance to read from. |
buff | pointer to the buffer to be filled with read data. |
bytes_to_read | number of bytes to read. Must be less than or equal to the size of the buffer. |
bool storage_file_seek | ( | File * | file, |
uint32_t | offset, | ||
bool | from_start ) |
Change the current access position in a file.
file | pointer to the file instance in question. |
offset | access position offset (meaning depends on from_start parameter). |
from_start | if true, set the access position relative to the file start, otherwise relative to the current position. |
uint64_t storage_file_size | ( | File * | file | ) |
Get the file size.
file | pointer to the file instance in question. |
bool storage_file_sync | ( | File * | file | ) |
Synchronise the file cache with the actual storage.
file | pointer to the file instance in question. |
uint64_t storage_file_tell | ( | File * | file | ) |
Get the current access position.
file | pointer to the file instance in question. |
bool storage_file_truncate | ( | File * | file | ) |
Truncate the file size to the current access position.
file | pointer to the file instance to be truncated. |
size_t storage_file_write | ( | File * | file, |
const void * | buff, | ||
size_t | bytes_to_write ) |
Write bytes from a buffer to a file.
file | pointer to the file instance to write into. |
buff | pointer to the buffer containing the data to be written. |
bytes_to_write | number of bytes to write. Must be less than or equal to the size of the buffer. |
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:
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.
storage | pointer to a storage API instance. |
dirname | pointer to a zero-terminated string containing the directory path. |
filename | pointer to a zero-terminated string containing the file name. |
fileextension | pointer to a zero-terminated string containing the file extension. |
nextfilename | pointer to a dynamic string containing the resulting file name. |
max_len | maximum length of the new name. |
FuriPubSub * storage_get_pubsub | ( | Storage * | storage | ) |
Get the storage pubsub instance.
Storage will send StorageEvent messages.
storage | pointer to a storage API instance. |
FS_Error storage_int_backup | ( | Storage * | storage, |
const char * | dstname ) |
Back up the internal storage contents to a *.tar archive.
storage | pointer to a storage API instance. |
dstname | pointer to a zero-terminated string containing the archive file path. |
FS_Error storage_int_restore | ( | Storage * | storage, |
const char * | dstname, | ||
StorageNameConverter | converter ) |
Restore the internal storage contents from a *.tar archive.
storage | pointer to a storage API instance. |
dstname | pointer to a zero-terminated string containing the archive file path. |
converter | pointer to a filename conversion function (may be NULL). |
FS_Error storage_sd_format | ( | Storage * | storage | ) |
Format the SD Card.
storage | pointer to a storage API instance. |
Get SD card information.
storage | pointer to a storage API instance. |
info | pointer to the info object to contain the requested information. |
FS_Error storage_sd_mount | ( | Storage * | storage | ) |
Mount the SD card.
storage | pointer to a storage API instance. |
FS_Error storage_sd_status | ( | Storage * | storage | ) |
Get SD card status.
storage | pointer to a storage API instance. |
FS_Error storage_sd_unmount | ( | Storage * | storage | ) |
Unmount the SD card.
These return values have special meaning:
storage | pointer to a storage API instance. |
bool storage_simply_mkdir | ( | Storage * | storage, |
const char * | path ) |
Create a directory.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the directory path. |
bool storage_simply_remove | ( | Storage * | storage, |
const char * | path ) |
Remove a file or a directory.
The following conditions must be met:
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the item path. |
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.
storage | pointer to a storage API instance. |
path | pointer to a zero-terminated string containing the item path. |