Header-only C++ RAII layer over Diplomat. All methods are inline. Include headers, link libhonzo_c.a.

Usage

#include <cpp/HonzoFileReader.hpp>

HonzoFileReader_open_result r = HonzoFileReader::open("/sdcard/books/book.hzo", 1);
if (!r.is_ok()) return;

auto reader = std::move(r).ok();
uint32_t n = reader->chunk_count();

for (uint32_t i = 0; i < n; i++) {
    uint32_t tag = reader->get_chunk_type(i);
    // ... process chunks ...
}

Exported types

• HonzoFileReader - file-backed streaming reader (owns an open FD)
• HonzoHandle - in-memory parser handle
• HonzoBuilderHandle - builder/writer for creating Honzo files
• TocEntryOwned - owned C++ struct with per-chunk TOC metadata
• HonzoErrorCode - error code enum
• Free functions (guess_image_mime, guess_font_format, validate_css, validate_mathml, latex_to_mathml, render_math, normalize_search_term)

---

HonzoFileReader (streaming)

Open a Honzo file from the filesystem and read chunks on demand. Each get_chunk call performs one seek, one read, and one LZ4 decompression. The returned span is valid only until the next get_chunk call on the same reader.

HonzoFileReader lifecycle

Include: #include <cpp/HonzoFileReader.hpp>

HonzoFileReader accessors

---

HonzoHandle (in-memory parser)

Parse a Honzo file from a byte buffer in memory. Returns nullptr (via std::unique_ptr) on error.

HonzoHandle lifecycle

Include: #include <cpp/HonzoHandle.hpp>

HonzoHandle accessors

Methods ending in _write(W&) overloads are also available for writing directly to a custom writeable (e.g. a fixed buffer).

---

HonzoBuilderHandle (builder)

Construct Honzo files programmatically. Add chunks, set metadata, configure DRM, then finalize() and read the result.

HonzoBuilderHandle lifecycle

Include: #include <cpp/HonzoBuilderHandle.hpp>

HonzoBuilderHandle setters

Parameters follow the same semantics as the Rust builder.

---

TocEntryOwned struct

Include: #include <cpp/TocEntryOwned.hpp>

struct TocEntryOwned {
    uint32_t chunk_id;
    uint64_t offset;
    uint32_t size_compressed;
    uint32_t size_raw;
    uint8_t  compression;
    uint8_t  ctype_kind;
    uint8_t  ctype_value;
    uint8_t  cover_type;
    uint8_t  flags;
    uint32_t crc32;
};

Owned (non-opaque) C++ struct, safe to copy.

---

HonzoErrorCode

Include: #include <cpp/HonzoErrorCode.hpp>

---

Free functions

Include: #include <cpp/free_functions.hpp>

Each function also has a _write(W&) overload for custom writeable targets.

Image format detection example

#include <cpp/HonzoFileReader.hpp>
#include <cpp/free_functions.hpp>

auto r = HonzoFileReader::open("/sdcard/books/book.hzo", 1);
if (!r.is_ok()) return;
auto reader = std::move(r).ok();

auto chunk = reader->get_chunk(0);
if (chunk.has_value()) {
    auto mime = guess_image_mime(chunk.value());
    if (mime.is_ok()) {
        // mime.ok() == "image/png", "image/jpeg", etc.
    }
}

Recognizes: PNG, JPEG, GIF, BMP, TIFF (LE/BE), WebP, ICO, PNM (PBM/PGM/PPM/PAM).

---

Building

Host

cargo build -p honzo-c --release
# Produces: target/release/libhonzo_c.a
# Headers:  Build/crates/honzo-c/include/cpp/

Link your C++ program against the static library:

c++ -o reader reader.cpp -L./target/release -lhonzo_c -lpthread -ldl -lm

ESP32

Requires the xtensa-esp32-espidf target (install via espup).

# Build staticlib without image processing
cargo +esp build --release -p honzo-c \
  --target xtensa-esp32-espidf \
  -Zbuild-std=std,panic_abort \
  --no-default-features

# Link firmware (PlatformIO extra_script.py):
#   env.Prepend(LIBPATH=["lib/honzo_c/xtensa-esp32s3-espidf/release"])
#   env.Prepend(LIBS=["honzo_c"])

Add to platformio.ini:

build_flags =
    -Ithird_party/honzo/Build/crates/honzo-c/include
lib_deps =
    # ... add the .a via extra_script.py

Feature flags

The image feature (default: on) enables cover thumbnail generation and is only needed when building files. The streaming reader path (HonzoFileReader) never uses it.

# Embedded build (no image crate, smaller compile)
cargo build -p honzo-c --release --no-default-features

Related