/**
 * 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;
} savestreamdolphin_t;

/**
 * Opens the consolidated memory card file 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.
 * @return An error if reading the card fails for a reason other than
 *         missing file.
 */
errorret_t saveStreamOpenReadDolphin(savestreamdolphin_t *p, bool_t *found);

/**
 * Opens the consolidated memory card file for writing by zeroing the
 * sector buffer. The buffer is flushed to the card when
 * saveStreamCloseDolphin is called.
 *
 * @param p Stream to initialize.
 * @return An error if initialization fails.
 */
errorret_t saveStreamOpenWriteDolphin(savestreamdolphin_t *p);

/**
 * 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);

/**
 * Gets the current read/write position within the sector buffer.
 *
 * @param p   Active stream.
 * @param out Receives the current position.
 * @return An error - always succeeds, matches saveStreamTellImpl's shape.
 */
errorret_t saveStreamTellDolphin(savestreamdolphin_t *p, size_t *out);