wa_walk.h File Reference

Every file and folder on the card, one at a time. More...

#include <stdbool.h>
#include <stdint.h>
#include "wa_text.h"

Go to the source code of this file.

Data Structures
struct	wa_dirent_t
struct	wa_fs_t
struct	wa_level_t
struct	wa_walk_t
	A walk under way. More...

Macros
#define	WA_WALK_DEPTH   16u

Enumerations
enum	wa_walk_ev_t {   WA_WALK_DIR = 0 , WA_WALK_FILE , WA_WALK_END , WA_WALK_NO_CARD ,   WA_WALK_ERROR }
	What wa_walk_next() hands out. More...

Functions
void	wa_walk_begin (wa_walk_t *w, const wa_fs_t *fs)
	A walk of fs from its root; nothing is opened yet.
wa_walk_ev_t	wa_walk_next (wa_walk_t *w)
	The next event.
void	wa_walk_end (wa_walk_t *w)
	Close every handle that is open; for a walk given up part way.

Detailed Description

Every file and folder on the card, one at a time.

The walk goes folder by folder from the root: a folder, then its files, then each of its folders the same way. It holds no list of what it has seen, so a card of any size is walked in the same memory, and two walks of an unchanged card give the same entries in the same order – which the ZIP (wa_zip.h) relies on, walking three times.

A folder is read twice, its files and then its folders, and each entry once a pass: going down into a folder keeps the parent's handle open, and coming back reads on from it. At most one handle a level is open, the root's included: WA_WALK_DEPTH + 1.

A walk asked to stop (wa_fs_t.stopped) ends at the next entry with WA_WALK_ERROR, every handle closed.

What it leaves out, and counts in wa_walk_t.left_out: a name that is not UTF-8 or longer than WA_NAME_UNITS, a path over WA_PATH_MAX bytes, and a folder deeper than WA_WALK_DEPTH.

The file system is passed in, so the walk runs on the host against memory. Pure C, no ESP-IDF (Espressif Internet-of-Things Development Framework).

SPDX-License-Identifier: MIT

Macro Definition Documentation

WA_WALK_DEPTH

#define WA_WALK_DEPTH   16u

Folders below the root a walk goes into.

Enumeration Type Documentation

wa_walk_ev_t

enum wa_walk_ev_t

What wa_walk_next() hands out.

Enumerator
WA_WALK_DIR	a folder: path, its files follow
WA_WALK_FILE	a file: path, size, mtime
WA_WALK_END	the whole card is walked
WA_WALK_NO_CARD	the root cannot be opened
WA_WALK_ERROR	a folder could not be read part way

Function Documentation

wa_walk_begin()

void wa_walk_begin	(	wa_walk_t *	w,
		const wa_fs_t *	fs )

A walk of fs from its root; nothing is opened yet.

Parameters

w	the walk
fs	the card

wa_walk_end()

void wa_walk_end

(

wa_walk_t *

w

)

Close every handle that is open; for a walk given up part way.

Parameters

w

the walk

wa_walk_next()

wa_walk_ev_t wa_walk_next

(

wa_walk_t *

w

)

The next event.

WA_WALK_DIR and WA_WALK_FILE carry path, and a file ent.size and ent.mtime; the root's WA_WALK_DIR has the path "".

Parameters

w

the walk

Returns

the event; after WA_WALK_END, NO_CARD or ERROR every call returns the same