Storage service

Enumerate the SD card's playable tracks and serve them by index. More...

Collaboration diagram for Storage service:

Macros
#define	STORAGE_MAX_TRACKS   512
	Largest number of tracks held in the in-memory index. Overflow fails loud.
#define	STORAGE_PATH_MAX   320
	Size of one stored path buffer: "/sdcard/" + FATFS LFN (255) + nul, rounded up.

Functions
esp_err_t	storage_init (void)
	Mount the SD card and scan its root for playable tracks.
esp_err_t	storage_rescan (void)
	Re-scan the (already mounted) card root, rebuilding the track index.
esp_err_t	storage_unmount (void)
	Unmount the card and invalidate the index, after a card removal.
bool	storage_ready (void)
	Whether the card is mounted and a scan has completed.
size_t	storage_count (void)
	Number of tracks in the index (0 before any successful scan).
esp_err_t	storage_get_usage (uint64_t *total_bytes, uint64_t *used_bytes)
	Total and used size of the mounted FAT volume, in bytes.
const char *	storage_track_path (size_t index)
	Full POSIX path of a track, ready for decoder_open().
const char *	storage_track_name (size_t index)
	Display name of a track (file name, no directory prefix).
esp_err_t	storage_scan_dir (const char *root)
	Scan an arbitrary directory for playable tracks, rebuilding the index.
esp_err_t	storage_deinit (void)
	Unmount the card and free the index.

Detailed Description

Enumerate the SD card's playable tracks and serve them by index.

Macro Definition Documentation

STORAGE_MAX_TRACKS

#define STORAGE_MAX_TRACKS   512

Largest number of tracks held in the in-memory index. Overflow fails loud.

STORAGE_PATH_MAX

#define STORAGE_PATH_MAX   320

Size of one stored path buffer: "/sdcard/" + FATFS LFN (255) + nul, rounded up.

Function Documentation

storage_count()

size_t storage_count

(

void

)

Number of tracks in the index (0 before any successful scan).

storage_deinit()

esp_err_t storage_deinit

(

void

)

Unmount the card and free the index.

Returns

ESP_OK, or the sdcard_unmount error.

storage_get_usage()

esp_err_t storage_get_usage	(	uint64_t *	total_bytes,
		uint64_t *	used_bytes )

Total and used size of the mounted FAT volume, in bytes.

Thin wrapper over esp_vfs_fat_info(): a full scan of the FAT, so call it from a non-time-critical context (the stats page), not the audio path.

Parameters

[out]	total_bytes	Volume capacity in bytes (ignored if NULL).
[out]	used_bytes	Bytes in use = total - free (ignored if NULL).

Returns

ESP_OK; ESP_ERR_INVALID_STATE if the card is not mounted; otherwise the underlying FATFS error.

storage_init()

esp_err_t storage_init

(

void

)

Mount the SD card and scan its root for playable tracks.

Checks card presence, mounts the FAT volume via sdcard_mount, then scans SDCARD_MOUNT_POINT. Idempotent: a second call while already ready is a no-op.

Returns

ESP_OK; ESP_ERR_NOT_FOUND if no card is inserted; the sdcard_mount error if mounting fails; ESP_FAIL if the root cannot be read; ESP_ERR_NO_MEM if the card holds more than STORAGE_MAX_TRACKS tracks (never truncated silently).

storage_ready()

bool storage_ready

(

void

)

Whether the card is mounted and a scan has completed.

Returns

true if the index is usable (it may still hold zero tracks on an empty card).

storage_rescan()

esp_err_t storage_rescan

(

void

)

Re-scan the (already mounted) card root, rebuilding the track index.

Use after a card is (re)inserted and remounted. Requires the volume to be mounted.

Returns

ESP_OK; ESP_ERR_INVALID_STATE if not mounted; otherwise as storage_init.

storage_scan_dir()

esp_err_t storage_scan_dir

(

const char *

root

)

Scan an arbitrary directory for playable tracks, rebuilding the index.

The pure enumeration core: recursive opendir/readdir walk + extension filter + sort, parameterised by directory. storage_init and storage_rescan wrap it onto SDCARD_MOUNT_POINT; the host tests call it on a temporary folder, so the logic is exercised without hardware.

Parameters

root	Directory to scan (no trailing slash), e.g. "/sdcard".

Returns

ESP_OK (possibly 0 tracks); ESP_FAIL if root cannot be opened; ESP_ERR_NO_MEM on allocation failure or more than STORAGE_MAX_TRACKS tracks.

storage_track_name()

const char * storage_track_name

(

size_t

index

)

Display name of a track (file name, no directory prefix).

Parameters

index

0-based track index.

Returns

The name, or NULL if index is out of range.

storage_track_path()

const char * storage_track_path

(

size_t

index

)

Full POSIX path of a track, ready for decoder_open().

Parameters

index

0-based track index.

Returns

The path, or NULL if index is out of range.

storage_unmount()

esp_err_t storage_unmount

(

void

)

Unmount the card and invalidate the index, after a card removal.

Unlike storage_deinit it keeps the PSRAM index buffer allocated, ready for the storage_init() that follows a re-insertion. No-op if not mounted.

Returns

ESP_OK, or the sdcard_unmount error.