// dvxResource.h  -- DVX resource format and runtime API
//
// Resources are appended to DXE3 files (.app, .wgt, .lib) after the
// normal DXE content. dlopen never reads past the DXE header-specified
// sections, so the appended data is invisible to the loader.
//
// File layout:
//   [DXE3 content]           -- untouched, loaded by dlopen
//   [resource data entries]  -- sequential, variable length
//   [resource directory]     -- fixed-size entries, one per resource
//   [footer]                 -- magic + directory offset + count
//
// Reading starts from the end: seek to EOF - sizeof(footer), verify
// the magic, then seek to the directory and read entries.

#ifndef DVX_RESOURCE_H
#define DVX_RESOURCE_H

#include <stdint.h>

// Fallback for the native dvxres tool, which includes this header
// without dvxTypes.h.  The canonical definition is in dvxTypes.h.
#ifndef DVX_MAX_PATH
#define DVX_MAX_PATH 260
#endif

// Resource type IDs
#define DVX_RES_ICON     1   // image data (BMP icon: 16x16, 32x32, etc.)
#define DVX_RES_TEXT     2   // null-terminated string (author, copyright, etc.)
#define DVX_RES_BINARY   3   // arbitrary binary data (app-specific)

// Footer magic: "DVXR" as a 32-bit little-endian value
#define DVX_RES_MAGIC    0x52585644UL

// Maximum resource name length (including null terminator)
#define DVX_RES_NAME_MAX 32

// Directory entry (48 bytes each)
typedef struct {
    char     name[DVX_RES_NAME_MAX];  // resource name (e.g. "icon16", "author")
    uint32_t type;                    // DVX_RES_ICON, DVX_RES_TEXT, DVX_RES_BINARY
    uint32_t offset;                  // absolute file offset of data
    uint32_t size;                    // data size in bytes
    uint32_t reserved;                // padding for future use
} DvxResDirEntryT;

// Footer (16 bytes, at the very end of the file)
typedef struct {
    uint32_t magic;       // DVX_RES_MAGIC
    uint32_t dirOffset;   // absolute file offset of directory
    uint32_t entryCount;  // number of resources
    uint32_t reserved;
} DvxResFooterT;

// Runtime resource handle (opaque to callers)
typedef struct {
    char              path[DVX_MAX_PATH];
    DvxResDirEntryT  *entries;
    uint32_t          entryCount;
} DvxResHandleT;

// Open a resource handle by reading the footer and directory.
// Returns NULL if the file has no resource block.
DvxResHandleT *dvxResOpen(const char *path);

// Find a resource by name and read its data into a malloc'd buffer.
// Sets *outSize to the data size. Returns NULL if not found.
// Caller must free the returned buffer.
void *dvxResRead(DvxResHandleT *h, const char *name, uint32_t *outSize);

// Find a resource by name and return its directory entry.
// Returns NULL if not found. The returned pointer is valid until
// dvxResClose is called.
const DvxResDirEntryT *dvxResFind(DvxResHandleT *h, const char *name);

// Close the handle and free all associated memory.
void dvxResClose(DvxResHandleT *h);

#endif // DVX_RESOURCE_H