save Namespace Reference

Saved records: load, store, and the raw read/write underneath. More...

Functions
constexpr uint32_t	magic (const char(&s)[5])
	Four characters as a magic number ("CHCR" -> 0x52434843).
bool	available ()
	Whether saving works in this image.
const void *	read (uint32_t magic, uint8_t version, uint16_t size, uint8_t *flag=nullptr)
	Find the newest valid record.
void *	buffer ()
	The page buffer to fill before write(): writing in place.
bool	write (uint32_t magic, uint8_t version, uint16_t size, uint8_t flag=0)
	Write what is in buffer() as a new record, to the older page.
template<class T >
bool	load (uint32_t magic, uint8_t version, T &data, uint8_t *flag=nullptr)
	Load a struct from the newest valid record.
template<class T >
bool	store (uint32_t magic, uint8_t version, const T &data, uint8_t flag=0)
	Save a struct as a new record.

Variables
static const uint16_t	MAX_DATA = 256 - 12
	The most data a record holds: a 256-byte page less the header and CRC.

Detailed Description

Saved records: load, store, and the raw read/write underneath.

Function Documentation

magic()

constexpr uint32_t save::magic ( const char(&)  s[5] )

constexpr

Four characters as a magic number ("CHCR" -> 0x52434843).

Parameters

s	Exactly four characters, e.g. save::magic("CHXX"). Each game needs its own: the pages are shared by everything ever uploaded.

Returns

The magic number (computed at compile time).

available()

bool save::available

(

)

Whether saving works in this image.

Returns

false if the image is too big (it reaches into the save pages), or a write did not verify.

read()

const void * save::read	(	uint32_t	magic,
		uint8_t	version,
		uint16_t	size,
		uint8_t *	flag = nullptr
	)

Find the newest valid record.

Parameters

magic	The game's magic number.
version	The record's version: records of another version are ignored.
size	The data's size in bytes: records of another size are ignored.
flag	Optional: gets the header's flag byte.

Returns

A pointer to its data, in flash (read-only), or nullptr if there is no record with this magic, version and size.

buffer()

void * save::buffer

(

)

The page buffer to fill before write(): writing in place.

Returns

MAX_DATA bytes, zeroed, in the chunk scratch (so only between gfx_wait() and the next flush).

write()

bool save::write	(	uint32_t	magic,
		uint8_t	version,
		uint16_t	size,
		uint8_t	flag = 0
	)

Write what is in buffer() as a new record, to the older page.

Parameters

magic	The game's magic number.
version	The record's version.
size	How many bytes of buffer() to keep (at most MAX_DATA).
flag	A byte for the header (read back by read()'s flag).

Returns

true if the page was written and verified; false if saving is not available or the write failed (then available() turns false).

load()

template<class T >

bool save::load	(	uint32_t	magic,
		uint8_t	version,
		T &	data,
		uint8_t *	flag = nullptr
	)

Load a struct from the newest valid record.

Parameters

magic	The game's magic number.
version	The record's version.
data	Gets a copy of the record; left as it was if there is none.
flag	Optional: gets the header's flag byte.

Returns

true if a record was found.

store()

template<class T >

bool save::store	(	uint32_t	magic,
		uint8_t	version,
		const T &	data,
		uint8_t	flag = 0
	)

Save a struct as a new record.

Call between gfx_wait() and the next flush.

Parameters

magic	The game's magic number.
version	The record's version.
data	What to save (at most MAX_DATA bytes; checked at compile time).
flag	A byte for the header.

Returns

true if it was written and verified.

Variable Documentation

MAX_DATA

const uint16_t save::MAX_DATA = 256 - 12

static

The most data a record holds: a 256-byte page less the header and CRC.