/**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

#pragma once
#include "error/error.h"
#include "save/savedolphin.h"
#include <gccore.h>
#include <stddef.h>

typedef struct {
  /** libogc memory card file handle. */
  card_file cardFile;
  /** In-memory sector buffer; all reads and writes operate on this. */
  uint8_t buffer[SAVE_DOLPHIN_SECTOR_SIZE] __attribute__((aligned(32)));
  /** Current read/write position within buffer. */
  size_t position;
  /** True when opened for writing; flushes buffer to card on close. */
  bool_t writing;
  /** Slot index stored at open time so Close can derive the filename. */
  uint8_t slot;
} savestreamdolphin_t;

/**
 * Opens a memory card slot for reading by loading its sector into buffer.
 *
 * @param p     Stream to initialize.
 * @param found Set to true if the file exists, false if it does not.
 * @param slot  Save slot index.
 * @return An error if reading the card fails for a reason other than
 *         missing file.
 */
errorret_t saveStreamOpenReadDolphin(
  savestreamdolphin_t *p, bool_t *found, const uint8_t slot
);

/**
 * Opens a memory card slot for writing by zeroing the sector buffer.
 * The buffer is flushed to the card when savestreamCloseDolphin is called.
 *
 * @param p    Stream to initialize.
 * @param slot Save slot index.
 * @return An error if initialization fails.
 */
errorret_t saveStreamOpenWriteDolphin(
  savestreamdolphin_t *p, const uint8_t slot
);

/**
 * Flushes the sector buffer to the memory card (write mode only) and
 * releases the card file handle.
 *
 * @param p Stream to close.
 */
void saveStreamCloseDolphin(savestreamdolphin_t *p);

/**
 * Copies len bytes from the sector buffer at the current position into buf.
 *
 * @param p   Active stream.
 * @param buf Destination buffer.
 * @param len Number of bytes to read.
 * @return An error if the read would exceed the sector size.
 */
errorret_t saveStreamReadBytesDolphin(
  savestreamdolphin_t *p, void *buf, const size_t len
);

/**
 * Copies len bytes from buf into the sector buffer at the current position.
 *
 * @param p   Active stream.
 * @param buf Source buffer.
 * @param len Number of bytes to write.
 * @return An error if the write would exceed the sector size.
 */
errorret_t saveStreamWriteBytesDolphin(
  savestreamdolphin_t *p, const void *buf, const size_t len
);

/**
 * Sets the current read/write position within the sector buffer.
 *
 * @param p   Active stream.
 * @param pos Target byte offset from the start of the sector.
 * @return An error if pos is out of range.
 */
errorret_t saveStreamSeekDolphin(savestreamdolphin_t *p, const size_t pos);