"""The .HMI container: a small file system with a checksummed, duplicated file table. Layout (all offsets absolute, little-endian): 0x000000 file table: count(u32), count * 28-byte entries, then table checksum (u32) 0x080000 exact backup copy of the file table (+ checksum) 0x380000 u32 0xFFFFFFFF marker 0x6FFFF8 b"ver21234" 0x700000 entry data, packed back to back Entry (28 bytes): name[16] (NUL padded), start(u32), size(u32), deleted(u8), 3 more bytes (not interpreted by us; kept as-is, written as 0 for new entries). A deleted entry also has the first byte of its name set to 0 -- the Editor matches entries by name, so the flag alone is not enough. """ from __future__ import annotations import struct from dataclasses import dataclass, field from . import checksum TABLE_OFFSET = 0x000000 BACKUP_TABLE_OFFSET = 0x080000 MARKER_OFFSET = 0x380000 VERSION_OFFSET = 0x6FFFF8 VERSION_MAGIC = b"ver21234" DATA_OFFSET = 0x700000 ENTRY_SIZE = 28 MAX_TABLE_BYTES = BACKUP_TABLE_OFFSET - TABLE_OFFSET - 4 class HMIError(Exception): pass @dataclass class Entry: name: str start: int size: int deleted: bool = False extra: bytes = b"\0\0\0" # the 3 trailing entry bytes raw_name: bytes = b"" # name exactly as stored (deleted entries are mangled) def pack(self) -> bytes: nm = self.raw_name if self.raw_name else self.name.encode("latin-1") nm = nm[:16].ljust(16, b"\0") if self.deleted: nm = b"\0" + nm[1:] return nm + struct.pack(" "HMIFile": with open(path, "rb") as f: return cls.from_bytes(f.read()) @classmethod def from_bytes(cls, data: bytes) -> "HMIFile": raw = bytearray(data) entries = cls._read_table(raw, TABLE_OFFSET) if entries is None: entries = cls._read_table(raw, BACKUP_TABLE_OFFSET) if entries is None: raise HMIError("both file tables are corrupt (checksum mismatch)") return cls(raw, entries) @staticmethod def _read_table(raw: bytes, base: int): if len(raw) < base + 4: return None count, = struct.unpack_from(" MAX_TABLE_BYTES // ENTRY_SIZE or end + 4 > len(raw): return None stored, = struct.unpack_from(" list[Entry]: return [e for e in self.entries if not e.deleted] def find(self, name: str) -> Entry | None: for e in self.entries: if not e.deleted and e.name == name: return e return None def read(self, name: str) -> bytes: e = self.find(name) if e is None: raise KeyError(name) return bytes(self.raw[e.start:e.start + e.size]) def names(self) -> list[str]: return [e.name for e in self.live()] def table_ok(self) -> tuple[bool, bool]: return (self._read_table(self.raw, TABLE_OFFSET) is not None, self._read_table(self.raw, BACKUP_TABLE_OFFSET) is not None) # ------------------------------------------------------------------ writing def write(self, name: str, data: bytes) -> None: """Replace (or add) an entry the way the Editor does: append the data at the end of the file, mark the old entry deleted, add a new entry. Call fix_checksums()/save() after.""" old = self.find(name) start = len(self.raw) self.raw += data if old is not None: old.deleted = True self.entries.append(Entry(name, start, len(data))) def delete(self, name: str) -> None: e = self.find(name) if e is None: raise KeyError(name) e.deleted = True def _table_bytes(self) -> bytes: return struct.pack(" None: tbl = self._table_bytes() if len(tbl) > MAX_TABLE_BYTES: raise HMIError("file table too large") blob = tbl + struct.pack(" bytes: self._store_tables() return bytes(self.raw) def save(self, path) -> None: with open(path, "wb") as f: f.write(self.to_bytes()) def compacted(self) -> "HMIFile": """A fresh file containing only the live entries, packed from DATA_OFFSET.""" return build([(e.name, self.read(e.name)) for e in self.live()]) def build(items: list[tuple[str, bytes]]) -> HMIFile: """Create a new .HMI container from (name, data) pairs, in the given order.""" raw = bytearray(DATA_OFFSET) struct.pack_into("