Skip to content

API.md

Latest commit

 

History

History
250 lines (163 loc) · 10.1 KB

API.md

File metadata and controls

250 lines (163 loc) · 10.1 KB
Raw

EDB API Reference

Types

EDB_Status

Value Meaning
EDB_OK Success
EDB_ERROR General failure (invalid/corrupt header, I/O verification failed, invalid params)
EDB_OUT_OF_RANGE recno is less than 1 or refers to a never-used slot
EDB_TABLE_FULL Table cannot hold another record
EDB_DELETED recno refers to a deleted (tombstoned) slot
EDB_CORRUPT A record or header CRC failed verification
EDB_NEEDS_MIGRATION A legacy v1/v2 file — migrate offline with tools/edb_migrate.py

EDB_Rec

Alias for byte*. Cast structs with the EDB_REC macro:

MyRecord rec;
db.appendRec(EDB_REC rec);

Constructors

EDB(EDB_Write_Handler *write_byte, EDB_Read_Handler *read_byte);
EDB(EDB_Write_Buffer *write_buffer, EDB_Read_Buffer *read_buffer);

EDB_Status create(unsigned long head_ptr, unsigned long table_size, unsigned int rec_size)

Creates a new v3 database at head_ptr.

  • Sets n_recs = 0.
  • Writes and read-verifies the header.
  • Returns EDB_ERROR for invalid parameters or failed verification.

EDB_Status open(unsigned long head_ptr)

Opens an existing database.

  • Detects legacy v1/v2 headers.
  • Validates flag, sizes, and n_recs <= limit().
  • Returns EDB_ERROR for corrupt or unrecognized headers.

EDB_Status appendRec(const EDB_Rec rec) / appendRec(const EDB_Rec rec, unsigned long* out_recno)

Appends a record into a free slot (reused or newly grown), O(1). The optional out_recno receives the slot index for immediate readRec / updateRec / deleteRec — not a durable logical id. On normal tables, returns EDB_TABLE_FULL when full. On ring tables, when full the oldest slot is overwritten in place and EDB_OK is returned (ring mode never returns EDB_TABLE_FULL).

EDB_Status readRec(unsigned long recno, EDB_Rec rec)

Reads record recno into caller-provided memory (rec_size bytes) and verifies its CRC. Returns EDB_OUT_OF_RANGE (never-used id), EDB_DELETED (tombstoned), or EDB_CORRUPT (CRC mismatch).

EDB_Status updateRec(unsigned long recno, const EDB_Rec rec)

Overwrites an existing live record, O(1) (no header write). Returns EDB_OUT_OF_RANGE/EDB_DELETED.

EDB_Status insertRec(unsigned long recno, const EDB_Rec rec)

v3 behavior: allocates a free slot like appendRec; the recno argument is ignored and positional order is not preserved. Prefer appendRec. (Kept for source compatibility.)

EDB_Status deleteRec(unsigned long recno)

Tombstones the record's slot, O(1). The slot may be reused by a later appendRec with different data. Returns EDB_ERROR on ring tables (append-only; use clear() to wipe). Returns EDB_OUT_OF_RANGE/EDB_DELETED for invalid ids on normal tables.

unsigned long firstRec() / unsigned long nextRec(unsigned long recno)

Iterate live records in slot index order, skipping tombstones; return 0 when exhausted. Use these instead of looping 1..count() (slots can be sparse after deletes). On ring tables, prefer fifoFirstRec() / fifoNextRec() for chronological order.

for (unsigned long r = db.firstRec(); r != 0; r = db.nextRec(r)) {
    db.readRec(r, EDB_REC rec);
}

bool isLive(unsigned long recno)

Returns true if recno is an allocated, non-tombstoned slot.

EDB_Status compact()

Reconciles count() and rebuilds the free list from tombstones (reclaims slots leaked by a crash). Does not move live records. Returns EDB_ERROR on ring tables (use clear() instead).

EDB_Status enableRingMode()

Enables fixed-capacity ring FIFO mode: append-only, overwrites the oldest record when full. deleteRec and compact() return EDB_ERROR. Reset the log with clear() (examples often wrap this in a local deleteAll() helper).

bool ringModeEnabled() const

Returns whether ring FIFO mode is active.

unsigned long fifoFirstRec() / unsigned long fifoNextRec(unsigned long recno)

Iterate live records in FIFO order (oldest first). Before the ring has wrapped, order matches firstRec() / nextRec(). After wrap, starts at the oldest slot (the next slot to be overwritten).

EDB_Status enableStableIds()

Enables monotonic record_id in payload bytes [0..3] on each appendRec (requires rec_size >= 4). Your struct should reserve those bytes (e.g. struct { uint32_t id; ... }). Existing live records with non-zero ids in that field are respected when enabling.

bool stableIdsEnabled() const

Returns whether stable record ids are active for this table.

EDB_Status recordId(unsigned long recno, uint32_t* out_id) const

Returns the stable record_id for a live slot when stable ids are enabled.

EDB_Status findRecById(uint32_t record_id, unsigned long* out_recno) const

Linear scan for a live record by stable id; sets out_recno to the current slot address.

unsigned int recSize() const

Returns the stored record size (bytes) of the open table.

EDB_Status beginBatch() / EDB_Status endBatch() / bool batchActive() const

Defers the header publish so each appendRec costs only the slot write (~11 writes instead of 59):

db.beginBatch();
for (...) db.appendRec(EDB_REC rec);
db.endBatch();

A crash mid-batch never corrupts the table: beginBatch() sets a dirty bit, and the next open() rebuilds count(), the slot high-water mark, and the free list from the slot region, then clears it — no records are lost. deleteRec, clear, and compact return EDB_ERROR while a batch is open, and ring tables cannot be batched. See BENCHMARK.md.

EDB_Status clear()

Re-reads the header and recreates the table with the same table_size and rec_size, resetting count() to 0 and clearing ring head / next_record_id when those modes are enabled. Writes a fresh v3 header.

This is a destructive logical wipe: it does not securely erase old record bytes from EEPROM/flash/SD — stale data may remain until overwritten. It is not a substitute for migrating a legacy file to v3 when you need to preserve records (use MIGRATION.md instead).

unsigned long count()

Returns the number of stored records.

unsigned long limit()

Returns the maximum number of records that fit in the table. Returns 0 if rec_size == 0.

unsigned long headPtr() const

Returns the byte offset in storage where this table's header begins (the value passed to open() or create()).

unsigned long tableSize() const

Returns the allocated table size in bytes for the currently open table.

static unsigned long nextTableOffset(unsigned long head_ptr, unsigned long table_size)

Returns the byte offset where the next table can start without overlapping:

#define TABLE_A_SIZE 512
#define TABLE_B_SIZE 256
const unsigned long TABLE_A_HEAD = 0;
const unsigned long TABLE_B_HEAD = EDB::nextTableOffset(TABLE_A_HEAD, TABLE_A_SIZE);

EDB_Status openOrCreate(unsigned long head_ptr, unsigned long table_size, unsigned int rec_size)

Calls open(head_ptr) and, if that returns EDB_ERROR, calls create() with the same parameters. Useful when initializing several tables at boot.

Multiple tables

head_ptr is a byte address in EEPROM, SD, or other storage — not a table index. Do not use create(1, ...), create(2, ...) unless those addresses are intentionally spaced.

Recommended: one EDB object per table

Each instance keeps its own header in memory after open() or create():

EDB dbEvents(&writer, &reader);
EDB dbConfig(&writer, &reader);

dbEvents.openOrCreate(EVENTS_HEAD, EVENTS_TABLE_SIZE, sizeof(EventRecord));
dbConfig.openOrCreate(CONFIG_HEAD, CONFIG_TABLE_SIZE, sizeof(ConfigRecord));

dbEvents.appendRec(...);   // count() applies to events only
dbConfig.appendRec(...);   // count() applies to config only

Alternative: one EDB object, switch with open()

EDB db(&writer, &reader);
db.open(EVENTS_HEAD);
db.appendRec(...);
db.open(CONFIG_HEAD);
db.appendRec(...);

You must call open() before operating on each table. count() always reflects the currently open table only.

Legacy single global EDB edb

1.0.x headers declared extern EDB edb. Sketches that define EDB edb(&writer, &reader); continue to work. For multiple tables, use separate EDB instances (or call open() before each table). Opt out of the legacy declaration in 2.0.0 with #define EDB_NO_GLOBAL before #include <EDB.h>.

Record numbering rules

  • recno is a 1-based slot address for I/O and iteration — not a durable logical record id. Put uint32_t id (or enableStableIds()) in your struct for anything you must find again later.
  • Valid recno for read/update/delete: allocated slots 1 through n_slots that are live (see isLive()). After deletes, do not assume 1..count() covers all live rows — use firstRec / nextRec.
  • recno == 0 always returns EDB_OUT_OF_RANGE.

Build flags

Optional compile-time flags (define before #include or via -D in build properties). See ENCRYPTION.md.

Flag Default Purpose
EDB_VERIFY_ON_READ 1 Verify each record's CRC on read; 0 = write-only integrity (min read CPU)
EDB_HEADER_REDUNDANT 1 Store the header twice for atomic updates; 0 = single header (discouraged)
EDB_WRITE_IF_DIFFERENT 1 On byte handlers, skip writes whose stored value is already correct (cuts appendRec from 59 to 18 writes). Set 0 for RAM/FRAM backends where reads cost as much as writes. See BENCHMARK.md
EDB_ENABLE_CRYPTO off Include EDB_Crypto.h (ChaCha20-Poly1305 record encryption)
EDB_CRYPTO_DEVICE_AUTONOMOUS off On-device wrapped-key extension helpers
EDB_NO_GLOBAL off Omit legacy extern EDB edb
EDB_TEST off Test hooks (native tests only)

Bridge sketch flags (examples/EDB_SerialBridge/config.h): EDB_BRIDGE_ENABLE_TRANSPORT_CRYPTO, EDB_BRIDGE_MAX_LINE, EDB_BRIDGE_ENABLE_BASE64.

Gateway REST mapping

The EDB Gateway exposes the same semantics over HTTP. Encrypted tables use stored_rec_size = plaintext_rec_size + 16 at create() time.