/*
 * OTA 二进制流接收模块
 * 通用 OTA 实现，支持 BLE 和 UART 两种传输方式
 * 内部载荷：0x01/0x02/0x03（由 ota_frame_protocol 解帧后调用）
 * 对外传输：见 protocol/ota_frame_protocol.h（OT 包头 + CRC8 + 包尾 0x16）
 */

#ifndef OTA_BINARY_STREAM_H
#define OTA_BINARY_STREAM_H

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

#ifdef __cplusplus
extern "C" {
#endif

/* OTA 状态回调类型 */
typedef void (*ota_binary_stream_status_callback_t)(const char *json);

/* OTA 传输类型 */
typedef enum {
    OTA_TRANSPORT_BLE = 0,    /* BLE GATT OTA */
    OTA_TRANSPORT_UART,       /* UART 串口 OTA */
} ota_transport_type_t;

/**
 * @brief 初始化 OTA 二进制流接收器
 * @param transport 传输类型（BLE 或 UART）
 * @param status_callback 状态回调函数，用于发送 OTA 状态 JSON
 * @param target_version 目标版本号（可选，用于OTA管理器）
 * @return ESP_OK 成功，其他错误码
 */
esp_err_t ota_binary_stream_init(ota_transport_type_t transport,
                                  ota_binary_stream_status_callback_t status_callback,
                                  const char *target_version);

/**
 * @brief 反初始化 OTA 二进制流接收器
 * 如果 OTA 进行中，会自动中止
 */
void ota_binary_stream_deinit(void);

/**
 * @brief 处理接收到的 OTA 数据包
 * 由传输层（BLE/UART）调用
 * @param data 数据指针
 * @param len 数据长度
 * @return 0 成功处理，负数错误码（传输层可映射为相应错误）
 */
int ota_binary_stream_process_packet(const uint8_t *data, uint16_t len);

/**
 * @brief 检查 OTA 是否进行中
 * @return true OTA进行中，false 空闲
 */
bool ota_binary_stream_is_active(void);

/**
 * @brief 中止当前 OTA 会话
 * 清理资源，擦除不完整的固件写入
 */
void ota_binary_stream_abort(void);

/** 当前会话已写入字节数（未 begin 时为 0） */
uint32_t ota_binary_stream_get_written_bytes(void);

/**
 * @brief 获取 OTA 状态 JSON 字符串
 * 用于主动查询OTA状态
 * @param buf 输出缓冲区
 * @param len 缓冲区长度
 * @return ESP_OK 成功
 */
esp_err_t ota_binary_stream_get_status_json(char *buf, size_t len);

/* OTA 操作码定义（与数据包格式一致） */
#define OTA_OP_BEGIN  0x01    /* 开始OTA会话 */
#define OTA_OP_DATA   0x02    /* 传输固件数据 */
#define OTA_OP_END    0x03    /* 结束OTA会话 */

#ifdef __cplusplus
}
#endif

#endif /* OTA_BINARY_STREAM_H */
