// hlpformat.h -- DVX Help binary file format structures
//
// Shared between the host-side help compiler and the DVX help viewer app.

#ifndef HLPFORMAT_H
#define HLPFORMAT_H

#include <stdint.h>
#include <stdbool.h>


// ---------------------------------------------------------------------------
// File magic and version
// ---------------------------------------------------------------------------

#define HLP_MAGIC   0x484C5044  // "HLPD" little-endian
#define HLP_VERSION 1


// ---------------------------------------------------------------------------
// Record types (HlpRecordHdrT.type)
// ---------------------------------------------------------------------------

#define HLP_REC_TEXT      0x01
#define HLP_REC_HEADING1  0x02
#define HLP_REC_HEADING2  0x03
#define HLP_REC_HEADING3  0x04
#define HLP_REC_IMAGE     0x05
#define HLP_REC_LINK      0x06
#define HLP_REC_LIST_ITEM 0x07
#define HLP_REC_TABLE     0x08
#define HLP_REC_HRULE     0x09
#define HLP_REC_NOTE      0x0A
#define HLP_REC_CODE      0x0B
#define HLP_REC_END       0xFF


// ---------------------------------------------------------------------------
// Note flags (HlpRecordHdrT.flags when type == HLP_REC_NOTE)
// ---------------------------------------------------------------------------

#define HLP_NOTE_INFO    0x00
#define HLP_NOTE_TIP     0x01
#define HLP_NOTE_WARNING 0x02


// ---------------------------------------------------------------------------
// TOC entry flags
// ---------------------------------------------------------------------------

#define HLP_TOC_EXPANDED 0x01


// ---------------------------------------------------------------------------
// File header (64 bytes, stored at EOF)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t magic;             // HLP_MAGIC
    uint32_t version;           // HLP_VERSION
    uint32_t topicCount;
    uint32_t topicDirOffset;    // absolute file offset
    uint32_t tocOffset;
    uint32_t tocCount;
    uint32_t indexOffset;
    uint32_t indexCount;
    uint32_t searchOffset;
    uint32_t searchSize;
    uint32_t stringTableOffset;
    uint32_t stringTableSize;
    uint32_t imagePoolOffset;
    uint32_t imagePoolSize;
    uint32_t defaultTopicStr;   // string table offset of default topic ID
} HlpHeaderT;


// ---------------------------------------------------------------------------
// Topic directory entry (20 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t topicIdStr;    // string table offset
    uint32_t titleStr;      // string table offset
    uint32_t contentOffset; // absolute file offset
    uint32_t contentSize;
    uint32_t reserved;
} HlpTopicDirT;


// ---------------------------------------------------------------------------
// Content record header (4 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint8_t  type;
    uint8_t  flags;
    uint16_t length;  // payload length (excluding this header)
} HlpRecordHdrT;


// ---------------------------------------------------------------------------
// Image reference (8 bytes, payload of HLP_REC_IMAGE)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t imageOffset;  // offset within image pool
    uint32_t imageSize;    // BMP data size
} HlpImageRefT;


// ---------------------------------------------------------------------------
// TOC entry (8 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t titleStr;   // string table offset
    uint16_t topicIdx;   // index into topic directory (0xFFFF = no topic)
    uint8_t  depth;      // nesting depth (0 = root)
    uint8_t  flags;      // HLP_TOC_EXPANDED
} HlpTocEntryT;


// ---------------------------------------------------------------------------
// Keyword index entry (8 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t keywordStr;  // string table offset
    uint16_t topicIdx;    // index into topic directory
    uint16_t reserved;
} HlpIndexEntryT;


// ---------------------------------------------------------------------------
// Search index -- trigram entry (8 bytes)
// ---------------------------------------------------------------------------

typedef struct {
    uint8_t  trigram[3];
    uint8_t  postingCount;
    uint32_t postingOffset;  // byte offset within search section to uint16_t[] posting list
} HlpTrigramEntryT;


// ---------------------------------------------------------------------------
// Search section header
// ---------------------------------------------------------------------------

typedef struct {
    uint32_t trigramCount;
    // followed by HlpTrigramEntryT[trigramCount]
    // followed by uint16_t posting lists
} HlpSearchHeaderT;


#endif // HLPFORMAT_H