// Commander X16 Emulator — SD card FAT index
// Copyright (c) 2024 X16Emu ADD contributors
// All rights reserved. License: 2-clause BSD
//
// Read-only FAT16/FAT32 index over an SD card image.  Borrows the caller's
// already-open file handle and never opens or closes it.

#ifndef SDCARD_FAT_H
#define SDCARD_FAT_H

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

#ifdef __cplusplus
extern "C" {
#endif

// Forward declaration so C++ panels can include this header without pulling in
// files.h (which includes SDL.h).
struct x16file;

// ── Region tags ─────────────────────────────────────────────────────────────
typedef enum {
	SDCARD_FAT_REGION_UNKNOWN = 0,
	SDCARD_FAT_REGION_MBR,
	SDCARD_FAT_REGION_RESERVED,
	SDCARD_FAT_REGION_FAT,
	SDCARD_FAT_REGION_ROOTDIR,
	SDCARD_FAT_REGION_FILE,
	SDCARD_FAT_REGION_DIR,
	SDCARD_FAT_REGION_FREE,
} sdcard_fat_region_t;

// ── File/directory entry ─────────────────────────────────────────────────────
typedef struct {
	const char *path;          // e.g. "/GAMES/FOO.PRG", owned by the index
	uint32_t    size;          // file size in bytes (0 for directories)
	uint32_t    first_cluster;
	bool        is_dir;
	uint64_t    bytes_read;    // session counter, updated by sdcard_fat_note_access
	uint64_t    bytes_written;
} sdcard_fat_file_t;

// ── Lifecycle ────────────────────────────────────────────────────────────────

// Build or rebuild the index using the already-open image handle `img`.
// The handle is borrowed: sdcard_fat never closes it, and save/restores the
// stream position around every internal read so the caller's file position is
// unchanged on return.
// Returns false if the image cannot be parsed (not a FAT image, I/O error, etc.).
// On false the previous index (if any) is freed.  Safe to call repeatedly.
bool sdcard_fat_build(struct x16file *img);

// Release all index memory.  Safe to call when not built.
void sdcard_fat_free(void);

// ── Global flag ──────────────────────────────────────────────────────────────

// When false, sdcard_attach() will not build the index.  Owned by the debugger
// UI; defaults to true so a build without the UI behaves as before.
extern bool sdcard_fat_autoindex;

// ── State queries ────────────────────────────────────────────────────────────

bool        sdcard_fat_ready(void);
bool        sdcard_fat_is_stale(void);
void        sdcard_fat_mark_stale(void);
bool        sdcard_fat_truncated(void);
const char *sdcard_fat_type_name(void);   // "FAT16" / "FAT32" / ""
uint32_t    sdcard_fat_bytes_per_cluster(void);

// ── Lookup ───────────────────────────────────────────────────────────────────

sdcard_fat_region_t sdcard_fat_lookup(uint32_t lba,
                                      const sdcard_fat_file_t **out_file,
                                      uint64_t                 *out_offset);

void sdcard_fat_note_access(uint32_t lba, bool is_write, uint32_t bytes);

// ── Enumeration ─────────────────────────────────────────────────────────────

int                      sdcard_fat_file_count(void);
const sdcard_fat_file_t *sdcard_fat_file_at(int i);

#ifdef __cplusplus
}
#endif

#endif // SDCARD_FAT_H