/**
 * @file hal_file.h
 * @brief 文件 I/O HAL 接口
 */

#ifndef HAL_FILE_H
#define HAL_FILE_H

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

#ifdef __cplusplus
extern "C" {
#endif

/** 文件句柄 */
typedef void *hal_file_t;

/* 打开模式 */
#define HAL_FILE_MODE_READ       "r"   /* 只读 */
#define HAL_FILE_MODE_WRITE      "w"   /* 写入（截断）*/
#define HAL_FILE_MODE_APPEND     "a"   /* 追加 */
#define HAL_FILE_MODE_READ_WRITE "r+"  /* 读写 */

/**
 * @brief 打开文件
 * @param path 文件路径
 * @param mode 打开模式（HAL_FILE_MODE_xxx）
 * @return 句柄，失败返回 NULL
 */
hal_file_t hal_file_open(const char *path, const char *mode);

/**
 * @brief 读取数据
 * @return 实际读取字节数，负值失败
 */
int hal_file_read(hal_file_t file, void *buf, size_t len);

/**
 * @brief 写入数据
 * @return 实际写入字节数，负值失败
 */
int hal_file_write(hal_file_t file, const void *buf, size_t len);

/** @brief 关闭文件 */
int hal_file_close(hal_file_t file);

/** @brief 获取文件大小（字节）*/
int hal_file_size(hal_file_t file);

/** @brief 检查文件是否存在 */
bool hal_file_exists(const char *path);

#ifdef __cplusplus
}
#endif

#endif /* HAL_FILE_H */
