fm_rules.h File Reference

What the file manager may do to a name: the places the bench keeps, the files the logger writes, and the write gate of the bench's state. More...

#include <stdbool.h>
#include <stddef.h>
#include "fm_io.h"
#include "fm_name.h"
#include "log_take.h"

Go to the source code of this file.

Data Structures
struct	fm_bench_t
	The bench as the rules see it, filled by the caller each time it asks. Every pointer may be NULL. More...

Enumerations
enum	fm_op_t {   FM_OP_OPEN = 0 , FM_OP_INFO , FM_OP_EDIT , FM_OP_COPY ,   FM_OP_MOVE , FM_OP_RENAME , FM_OP_DELETE , FM_OP_NEW ,   FM_OP_SAVE , FM_OP_COUNT }
	What a person asks of a name. More...
enum	fm_place_t { FM_PLACE_FREE = 0 , FM_PLACE_FIXED , FM_PLACE_LOCKED , FM_PLACE_FAULT }
	Where a name stands (the file's comment).
enum	fm_kind_t {   FM_KIND_FOLDER = 0 , FM_KIND_RUN , FM_KIND_REPORT , FM_KIND_KST ,   FM_KIND_PROFILE , FM_KIND_FAULT , FM_KIND_CSV , FM_KIND_JSON ,   FM_KIND_TEXT , FM_KIND_OTHER , FM_KIND_COUNT }
	What an entry is, for its icon and kind word. More...

Functions
bool	fm_op_writes (fm_op_t op)
	Whether op writes to the card.
bool	fm_logging (const log_marks_t *marks)
	Whether a log file is open: any of the logger's three marks.
fm_err_t	fm_gate (fm_op_t op, const fm_bench_t *bench)
	The write gate: whether the bench's state lets op run.
fm_place_t	fm_place_of (const fm_bench_t *bench, const char *dir, const char *name, bool is_dir)
	Where name in folder dir stands.
bool	fm_busy (const fm_bench_t *bench, const char *dir, const char *name)
	Whether the logger writes name in folder dir now (log_marks_busy()).
fm_err_t	fm_allowed (const fm_bench_t *bench, fm_op_t op, const char *dir, const char *name, bool is_dir)
	Whether op may run on name in folder dir: the gate, the file's place and whether the logger writes it, in that order.
fm_err_t	fm_target_check (const fm_bench_t *bench, const char *dir, const char *name, bool typed)
	Whether a COPY, a SAVE, a RENAME or a NEW may make name in folder dir.
fm_err_t	fm_path_err (fm_path_t r)
	The answer of a path call (fm_name.h) as the core's.
fm_kind_t	fm_kind_of (const char *dir, const char *name, bool is_dir)
	The kind of name in folder dir.
bool	fm_read_at_start (const char *dir, const char *name)
	Whether a file saved as name in dir is read only at the next start of the panel: an ESC profile.
bool	fm_same_path (const char *a, const char *b)
	Whether two paths name one place, case folded.
bool	fm_path_within (const char *outer, const char *inner)
	Whether path inner is outer or a place below it, case folded.

Detailed Description

What the file manager may do to a name: the places the bench keeps, the files the logger writes, and the write gate of the bench's state.

Reads are allowed in every bench state: browsing, entering a folder, viewing a file, INFO. Writes (COPY, MOVE, RENAME, DELETE, NEW, SAVE) are allowed only while the bench is SAFE and no log file is open (fm_gate()).

The places (fm_place_of()):

FIXED the bench's folders of card_tree.h (BENCH, BENCH/LOGS, BENCH/ESC, BENCH/ESC/CONF, BENCH/KST, BENCH/KST/CONF, BENCH/HITEC, BENCH/HITEC/CONF, USER, USER/LOGS), the two log folders SETUP > SD CARD names and every folder above them: no RENAME, MOVE or DELETE. What they hold is the person's. LOCKED the servo programmers' records, BENCH/KST/CONF/KST.TXT and KST.NEW, BENCH/HITEC/CONF/HITEC.TXT and HITEC.NEW: INFO only. A hand edit can send a wrong image to a servo. FAULT the fault log, BENCH/RCBENCH.LOG, .OLD and .TMP: OPEN and INFO; COPY and DELETE while the link to the IOmcu is up, since the fault log is written while it is down; no EDIT, RENAME or MOVE, since its writer renames the three among themselves. FREE everything else.

A file the logger has open (log_marks_busy()) takes INFO only, whatever its place. A name that is LOCKED or FAULT is not made by COPY, MOVE, RENAME or NEW either (fm_target_check()).

Folders and names compare with case folded, as FAT (File Allocation Table) compares long names: a to z with A to Z, and ä ö ü with Ä Ö Ü; ß has no upper case there and matches only itself.

Pure C, no ESP-IDF (Espressif Internet-of-Things Development Framework).

SPDX-License-Identifier: MIT

Enumeration Type Documentation

fm_kind_t

enum fm_kind_t

What an entry is, for its icon and kind word.

Enumerator
FM_KIND_FOLDER	a folder
FM_KIND_RUN	a run's log: ATEST042.CSV, SERVO007.CSV
FM_KIND_REPORT	a test's report: ATEST042.TXT, LIMIT003.TXT
FM_KIND_KST	a ".TXT" in BENCH/KST/CONF: a servo file
FM_KIND_PROFILE	a ".json" in BENCH/ESC/CONF: an ESC profile
FM_KIND_FAULT	the fault log and its two other names
FM_KIND_CSV	any other ".csv"
FM_KIND_JSON	any other ".json"
FM_KIND_TEXT	any other ".txt"
FM_KIND_OTHER	anything else

fm_op_t

enum fm_op_t

What a person asks of a name.

Enumerator
FM_OP_OPEN	enter a folder, view a file (read)
FM_OP_INFO	the INFO box (read)
FM_OP_EDIT	switch the viewer to the editor (read)
FM_OP_COPY	copy to the other pane's folder (write)
FM_OP_MOVE	move to the other pane's folder (write)
FM_OP_RENAME	give it another name (write)
FM_OP_DELETE	delete it (write)
FM_OP_NEW	make a folder or a file in it (write)
FM_OP_SAVE	write the editor's text to it (write)

Function Documentation

fm_allowed()

fm_err_t fm_allowed	(	const fm_bench_t *	bench,
		fm_op_t	op,
		const char *	dir,
		const char *	name,
		bool	is_dir )

Whether op may run on name in folder dir: the gate, the file's place and whether the logger writes it, in that order.

Parameters

bench	the bench; may be NULL
op	the operation
dir	the folder, a path from the root
name	the entry's name
is_dir	the entry is a folder

Returns

FM_OK; FM_ERR_ARMED or FM_ERR_LOGGING for a write the gate stops; FM_ERR_BUSY for a file the logger writes, and for the fault log's COPY and DELETE while the link is down; FM_ERR_FIXED, FM_ERR_LOCKED for the places; FM_ERR_ARG for COPY, EDIT or SAVE of a folder and NEW in a file

fm_busy()

bool fm_busy	(	const fm_bench_t *	bench,
		const char *	dir,
		const char *	name )

Whether the logger writes name in folder dir now (log_marks_busy()).

Parameters

bench	the open files; NULL is none
dir	the folder
name	the file's name

Returns

true for a busy file

fm_gate()

fm_err_t fm_gate	(	fm_op_t	op,
		const fm_bench_t *	bench )

The write gate: whether the bench's state lets op run.

Reads pass in every state. A write is refused while the bench is ARMED, and while a log file is open; ARMED is the answer when both hold.

Parameters

op	the operation
bench	the bench; NULL is SAFE with nothing open

Returns

FM_OK, FM_ERR_ARMED or FM_ERR_LOGGING

fm_kind_of()

fm_kind_t fm_kind_of	(	const char *	dir,
		const char *	name,
		bool	is_dir )

The kind of name in folder dir.

Parameters

dir	the folder, a path from the root
name	the entry's name
is_dir	the entry is a folder

Returns

its kind

fm_logging()

bool fm_logging

(

const log_marks_t *

marks

)

Whether a log file is open: any of the logger's three marks.

Parameters

marks

the open files; NULL is none

Returns

true while a run, a test's CSV or a report is open

fm_op_writes()

bool fm_op_writes

(

fm_op_t

op

)

Whether op writes to the card.

Parameters

op	the operation

Returns

true for COPY, MOVE, RENAME, DELETE, NEW and SAVE

fm_path_err()

fm_err_t fm_path_err

(

fm_path_t

r

)

The answer of a path call (fm_name.h) as the core's.

Parameters

r	what fm_path_join() or fm_path_check() said

Returns

FM_OK; FM_ERR_ARG for FM_PATH_ARG; FM_ERR_NAME for a path that is bad, too long or too deep

fm_path_within()

bool fm_path_within	(	const char *	outer,
		const char *	inner )

Whether path inner is outer or a place below it, case folded.

Parameters

outer	a folder's path
inner	a path

Returns

true when inner is in outer or is outer

fm_place_of()

fm_place_t fm_place_of	(	const fm_bench_t *	bench,
		const char *	dir,
		const char *	name,
		bool	is_dir )

Where name in folder dir stands.

Parameters

bench	the log folders in force; may be NULL
dir	the folder, a path from the root
name	the entry's name
is_dir	the entry is a folder

Returns

its place

fm_read_at_start()

bool fm_read_at_start	(	const char *	dir,
		const char *	name )

Whether a file saved as name in dir is read only at the next start of the panel: an ESC profile.

Parameters

dir	the folder
name	the file's name

Returns

true for a ".json" in BENCH/ESC/CONF

fm_same_path()

bool fm_same_path	(	const char *	a,
		const char *	b )

Whether two paths name one place, case folded.

Parameters

a	a path
b	a path

Returns

true for one place

fm_target_check()

fm_err_t fm_target_check	(	const fm_bench_t *	bench,
		const char *	dir,
		const char *	name,
		bool	typed )

Whether a COPY, a SAVE, a RENAME or a NEW may make name in folder dir.

A name a person types (typed: RENAME, NEW) follows fm_name_check(). A name a copy or a save carries over from the card is any name of 1 to FM_NAME_MAX bytes without "/" that is not "." or "..": it may hold any character a computer wrote, and only its ".NEW" has to stay listed (fm_name_new()). Either way neither the name nor its ".NEW" is a LOCKED or FAULT name (a file named KST in BENCH/KST/CONF would write the programmer's KST.NEW), and the paths of both fit fm_path_join().

Parameters

bench	the log folders in force; may be NULL
dir	the target folder
name	the name to make
typed	the name is typed by a person

Returns

FM_OK, FM_ERR_LOCKED, FM_ERR_FIXED, FM_ERR_NAME or FM_ERR_ARG