epub.h

Go to the documentation of this file.

 
#pragma once
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdalign.h>
#include <stddef.h>
#include <stdint.h>
 
#include "epub_miniz_alloc.h"
#include "ra8_err.h"
#include "xml.h"
 
/* ===========================================================================
 * Compile-time limits
 * ===========================================================================
 */

typedef enum : uint16_t {
  k_epub_max_chapters = 64,  
  k_epub_max_toc      = 64,  
  k_epub_max_path_len = 192, 
  k_epub_meta_len     = 128, 
  k_epub_max_fonts    = 8,   
  k_epub_max_manifest = 96,  
  k_epub_id_len       = 64,  
  k_epub_media_len    = 48,  
  k_epub_zip_archive_bytes =
    256, 
} epub_limits_t;

typedef struct {
  xml_workspace_t reader; 
  xml_span_t references[k_epub_max_chapters];
  xml_span_t legacy_cover_id; 
  uint16_t   reference_count; 
} epub_xml_workspace_t;

typedef enum : uint8_t {
  k_epub_toc_none = 0, 
  k_epub_toc_ncx  = 1, 
  k_epub_toc_nav  = 2, 
} epub_toc_kind_t;

typedef struct {
  char    title[k_epub_meta_len];    
  char    href[k_epub_max_path_len]; 
  uint8_t depth;                     
} epub_toc_entry_t;

typedef enum : uint8_t {
  k_epub_render_alpha8 = 0, 
} epub_render_t;
 
/* ===========================================================================
 * Opaque media interface
 * ===========================================================================
 */

typedef struct {
  const uint8_t* data; 
  size_t         size; 
} epub_mem_media_t;

typedef size_t (*epub_stream_read_fn)(void* ctx, uint64_t offset, void* buf, size_t len);

typedef struct {
  epub_stream_read_fn read; 
  void*               ctx;  
  uint64_t            size; 
} epub_stream_media_t;
 
/* ===========================================================================
 * Manifest item
 * ===========================================================================
 */

typedef struct {
  char id[k_epub_id_len];            
  char href[k_epub_max_path_len];    
  char media_type[k_epub_media_len]; 
} epub_manifest_item_t;
 
/* ===========================================================================
 * Book handle
 * ===========================================================================
 */

typedef struct {
  /* --- Backing storage (caller-owned) ---------------------------------- */
  const uint8_t* zip_bytes; 
  size_t         zip_size;  
 
  /* --- miniz state ----------------------------------------------------- */
  /* Inline storage for `mz_zip_archive`. Sized via static_assert in
   * epub_open.c; the book record owns the archive in-place rather
   * than allocating it on the heap (NASA Rule 3). Cast through
   * `(mz_zip_archive*)&book->zip_archive_storage[0]` inside the
   * implementation. The exact upstream type would force this header
   * to include `miniz.h`; we hold an opaque byte buffer instead.
   *
   * `alignas(max_align_t)` is mandatory: ``mz_zip_archive`` carries
   * pointer-typed and ``uint64_t`` fields that require 8-byte
   * alignment. Without the alignment specifier the cast is
   * undefined behaviour on strict-alignment architectures. */
  alignas(max_align_t) uint8_t
    zip_archive_storage[k_epub_zip_archive_bytes]; 
  uint8_t zip_archive_active;                      
  epub_miniz_arena_t miniz_arena;
  epub_miniz_workspace_t miniz_workspace;
  epub_xml_workspace_t xml_workspace;
 
  /* --- Streamed backing (caller-seekable, no resident blob) (#151) ----- */
  /* For a book opened via `epub_open_streamed()`, miniz's `m_pIO_opaque`
   * points at this inline descriptor (a stable address for the book's
   * lifetime), and `zip_bytes == NULL`. For the resident `epub_open()`
   * path this is left zeroed and unused. */
  epub_stream_media_t stream_media; 
 
  /* --- Chapter table --------------------------------------------------- */
  uint16_t chapter_count; 
  char     chapter_paths[k_epub_max_chapters]
                        [k_epub_max_path_len]; 
 
  /* --- Metadata -------------------------------------------------------- */
  char title[k_epub_meta_len];      
  char author[k_epub_meta_len];     
  char language[k_epub_meta_len];   
  char identifier[k_epub_meta_len]; 
 
  /* --- Cover ----------------------------------------------------------- */
  char cover_path[k_epub_max_path_len]; 
 
  /* --- Embedded fonts (#109) ------------------------------------------- */
  uint16_t embedded_font_count; 
  char     embedded_font_paths[k_epub_max_fonts]
                              [k_epub_max_path_len]; 
 
  /* --- Manifest (document order, #151) -------------------------------- */
  uint16_t manifest_count; 
  epub_manifest_item_t manifest[k_epub_max_manifest];
 
  /* --- OPF base directory --------------------------------------------- */
  char opf_dir[k_epub_max_path_len]; 
 
  /* --- Table of contents ---------------------------------------------- */
  char     toc_path[k_epub_max_path_len]; 
  uint8_t  toc_kind;                      
  uint16_t toc_count;                     
  epub_toc_entry_t toc[k_epub_max_toc];   
 
  /* --- Optional embedded font for glyph rendering --------------------- */
  const uint8_t* font_data; 
  size_t         font_size; 
 
  /* --- Lifecycle ------------------------------------------------------- */
  uint8_t in_use; 
} epub_book_t;
 
/* ===========================================================================
 * Metadata struct
 * ===========================================================================
 */

typedef struct {
  const char* title;      
  const char* author;     
  const char* language;   
  const char* identifier; 
} epub_metadata_t;
 
/* ===========================================================================
 * Public API -- lifecycle
 * ===========================================================================
 */

[[nodiscard]] ra8_err_t epub_open(const void* media, const char* path, epub_book_t* out_book);

[[nodiscard]] ra8_err_t
epub_open_streamed(const epub_stream_media_t* media, const char* path, epub_book_t* out_book);

[[nodiscard]] ra8_err_t epub_close(epub_book_t* book);
 
/* ===========================================================================
 * Public API -- chapter iteration
 * ===========================================================================
 */

[[nodiscard]] ra8_err_t epub_get_chapter_count(const epub_book_t* book, uint16_t* out_count);

[[nodiscard]] ra8_err_t epub_load_chapter(epub_book_t* book,
                                          uint16_t     idx,
                                          uint8_t*     out_xhtml,
                                          size_t       max_len,
                                          size_t*      got_len);
 
/* ===========================================================================
 * Public API -- table of contents
 * ===========================================================================
 */

[[nodiscard]] ra8_err_t epub_get_toc_kind(const epub_book_t* book, uint8_t* out_kind);

[[nodiscard]] ra8_err_t epub_get_toc_count(const epub_book_t* book, uint16_t* out_count);

[[nodiscard]] ra8_err_t
epub_get_toc_entry(const epub_book_t* book, uint16_t idx, epub_toc_entry_t* out_entry);

[[nodiscard]] ra8_err_t
epub_toc_entry_to_chapter(const epub_book_t* book, uint16_t toc_idx, uint16_t* out_chapter_idx);
 
/* ===========================================================================
 * Public API -- metadata + cover + glyph rasterise
 * ===========================================================================
 */

[[nodiscard]] ra8_err_t epub_get_metadata(const epub_book_t* book, epub_metadata_t* out_meta);

[[nodiscard]] ra8_err_t
epub_get_cover_image(epub_book_t* book, uint8_t* out_buf, size_t max_len, size_t* got_len);

[[nodiscard]] ra8_err_t epub_get_resource(epub_book_t* book,
                                          const char*  path,
                                          uint8_t*     out_buf,
                                          size_t       max_len,
                                          size_t*      got_len);

[[nodiscard]] uint16_t epub_manifest_count(const epub_book_t* book);

[[nodiscard]] const epub_manifest_item_t* epub_manifest_item(const epub_book_t* book,
                                                             uint16_t           index);

[[nodiscard]] ra8_err_t epub_get_embedded_font_count(const epub_book_t* book, uint16_t* out_count);

[[nodiscard]] ra8_err_t epub_get_embedded_font(epub_book_t* book,
                                               uint16_t     idx,
                                               uint8_t*     out_buf,
                                               size_t       max_len,
                                               size_t*      got_len);

[[nodiscard]] ra8_err_t
epub_set_font(epub_book_t* book, const uint8_t* font_data, size_t font_size);

[[nodiscard]] ra8_err_t epub_render_glyph(const epub_book_t* book,
                                          int32_t            codepoint,
                                          float              font_size,
                                          uint8_t*           out_bitmap,
                                          size_t             max_pixels,
                                          uint32_t*          out_w,
                                          uint32_t*          out_h);
#ifdef __cplusplus
}
#endif