#ifndef NOVA64_IO_INTERFACE_H
#define NOVA64_IO_INTERFACE_H

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

/* ========================================================================== */
/* I/O Callback Typedefs                                                      */
/* ========================================================================== */

/**
 * @brief Callback to output audio samples.
 * @param samples Pointer to PCM audio sample buffer.
 * @param count Number of samples in the buffer.
 */
typedef void (*nova64_audio_output_cb_t)(const int16_t *samples,
                                         uint32_t count);

/**
 * @brief Callback to read data from the SD card.
 * @param slot_idx Zero-based cartridge slot index.
 * @param file_path Null-terminated path to the file to read.
 * @param destination_buffer Pointer to memory where file data should be copied.
 * @param destination_length Maximum number of bytes available in the
 * destination buffer.
 * @return Number of bytes read on success, negative value on read error.
 */
typedef int32_t (*nova64_sd_read_file_cb_t)(uint32_t slot_idx,
                                            const char *file_path,
                                            uint8_t *destination_buffer,
                                            uint32_t destination_length);

/**
 * @brief Callback to retrieve the size of a file on the SD card.
 * @param slot_idx Zero-based cartridge slot index.
 * @param file_path Null-terminated path to the file.
 * @return File size in bytes on success, negative value on error.
 */
typedef int32_t (*nova64_sd_get_file_size_cb_t)(uint32_t slot_idx,
                                                const char *file_path);

/**
 * @brief Callback triggered when a cartridge state change occurs (e.g.
 * inserted/removed).
 * @param slot_idx Zero-based cartridge slot index.
 * @param is_inserted True if a cartridge is detected, false if ejected.
 */
typedef void (*nova64_cartridge_status_cb_t)(uint32_t slot_idx,
                                             bool is_inserted);

/**
 * @brief Callback for core log output.
 * @param message Null-terminated UTF-8 log string.
 */
typedef void (*nova64_log_cb_t)(const char *message);

/* ========================================================================== */
/* I/O Interface Configuration Struct                                         */
/* ========================================================================== */

/**
 * @brief Struct containing all I/O hardware abstraction callbacks.
 *        Pass NULL for any unneeded callback.
 */
typedef struct {
  nova64_audio_output_cb_t audio_output;
  nova64_sd_read_file_cb_t sd_read_file;
  nova64_sd_get_file_size_cb_t sd_get_file_size;
  nova64_cartridge_status_cb_t cartridge_status;
  nova64_log_cb_t log_message;
} nova64_io_interface_t;

#endif // NOVA64_IO_INTERFACE_H