#ifndef __MF4_LOADER_HPP__
#define __MF4_LOADER_HPP__

#include <string>

#include "DataTable.hpp"

namespace jdi
{

	/**
	 * @brief 读取并解析一个 ASAM MDF v4（`.mf4` / `.mdf`）测量文件。
	 *
	 * 只解析**绘制需要的那部分**：头块版本、数据组（DG）→ 通道组（CG）→ 通道（CN）/换算（CC），
	 * 以及每个通道组的原始记录；字符串/字节数组通道、MIME 通道一律跳过。
	 *
	 * **时间轴**：MDF 的每个通道组（CG）自带一个时间基准。本加载器把每个 CG 输出为一个
	 * 时间轴块（`TableBlock`）：块的时间列取自该组的**主通道**
	 *（`cn_sync_type` = 1 时间 / 2 角度 / 3 距离，退回名为 `time`/`t`/`timestamp` 的通道，
	 * 再退回第一个数值通道），其余数值通道作为该块的信号列。
	 * 内容完全相同的时间轴在数据模型层会被合并（见 `BuildSignalGroup`）。
	 * `cg_flags` 的「远程主通道」位会跳过第一步，避免把普通信号误当时间轴。
	 *
	 * **数据块**：`##DT` / `##DV` / `##DZ`（zlib + 转置压缩之外的纯 deflate）/
	 * `##DL`（数据列表）/ `##HL`（头部列表），支持记录跨段拼接。
	 *
	 * **VLSD（`cn_type == 1`）**：记录里是 64 位偏移，样本在 `##SD`（`UINT32` 长度 + 数据）。
	 * 本项目取样本的第一个元素作为该采样点的取值。
	 *
	 * **采样索引（`##SI`）**：仅当索引表至少两条且全部落在记录范围内时生效
	 *（否则忽略——实测部分工具会给每个通道挂一个只含常量 513 的 `##SI`）。
	 *
	 * 支持的通道编码：无符号/有符号整数（1–64 位，任意位偏移）与 IEEE-754 浮点（32/64 位）。
	 * 支持的换算（`cc_type`）：
	 * * `0` 无换算（恒等）；
	 * * `1` 线性 `phys = c0 + c1·raw`；
	 * * `2` 有理式 `(c0 + c1·raw) / (c2 + c3·raw)`；
	 * * `3` 代数式 `(c0·raw² + c1·raw + c2) / (c3·raw² + c4·raw + c5)`；
	 * * `4` 值→值查表（**线性插值**，即标定的特性曲线）；
	 * * `5` 值→值查表（**不插值**，取阶梯值）；
	 * * `6` 值区间→值（`(min, max, phys)` 三元组）；
	 * * `7` 值 → 文本（`cc_val[i]` ↔ `cc_ref[i]`，输出到 `DataTable::columnEnumText`）；
	 * * `8` 值区间 → 文本（`cc_val` 交错 `(下限, 上限)` ↔ `cc_ref[i]`）。
	 *
	 * ⚠️ 所有数值换算的参数个数不匹配、表为空、分母为 0 时**原样返回原始值**（绝不猜）。
	 * ⚠️ `cc_type ≥ 9`（MDF 后续版本新增的类型）**按无换算处理**，不是「静默按错公式算」。
	 * ⚠️ `7` / `8` 只影响**显示**：界面仅在光标取值标注里追加 ` = <文本>`，不改采样数值，
	 *    常规状态（未启用光标）观感完全不变。
	 *
	 * @param [IN] filePath MDF 文件完整路径。
	 * @param [OUT] source 解析结果（每个通道组一个时间轴块）。
	 * @param [OUT] error 失败原因描述（成功时清空）。
	 * @param [IN] progress 进度回调（按已处理数据组比例；同时上报已读/总字节），可为空。
	 * @return 解析成功返回 true。
	 */
	bool LoadMf4Source(const std::wstring& filePath, LoadedSource& source, std::wstring& error,
	                   const LoadProgress& progress = LoadProgress());

} // namespace jdi

#endif // __MF4_LOADER_HPP__