using System.Threading.Tasks;

namespace XP.Hardware.Plc.Abstractions
{
    /// <summary>
    /// PLC 信号数据交互服务接口 | PLC signal data interaction service interface
    /// 提供基于信号逻辑名称的读写操作 | Provides read/write operations based on signal logical names
    /// </summary>
    public interface ISignalDataService
    {
        /// <summary>
        /// 根据信号名称读取解析值（非泛型）| Read parsed value by signal name (non-generic)
        /// 批量读取 DB 中的信号使用缓存解析，其他 DB 的信号使用单点读取
        /// Signals in bulk read DB use cache parsing, others use single-point read
        /// </summary>
        /// <param name="signalName">信号逻辑名称 | Signal logical name</param>
        /// <returns>解析后的信号值 | Parsed signal value</returns>
        /// <exception cref="XP.Hardware.PLC.Exceptions.PlcException">
        /// 信号未找到、数据缓存未就绪或单点读取失败时抛出 | Thrown when signal not found, cache not ready, or single-point read failed
        /// </exception>
        object GetValueByName(string signalName);

        /// <summary>
        /// 根据信号名称读取解析值（泛型）| Read parsed value by signal name (generic)
        /// 批量读取 DB 中的信号使用缓存解析，其他 DB 的信号使用单点读取
        /// Signals in bulk read DB use cache parsing, others use single-point read
        /// </summary>
        /// <typeparam name="T">期望的返回类型 | Expected return type</typeparam>
        /// <param name="signalName">信号逻辑名称 | Signal logical name</param>
        /// <returns>解析后的信号值 | Parsed signal value</returns>
        /// <exception cref="XP.Hardware.PLC.Exceptions.PlcException">
        /// 信号未找到、数据缓存未就绪、单点读取失败或类型转换失败时抛出
        /// Thrown when signal not found, cache not ready, single-point read failed, or type conversion failed
        /// </exception>
        T GetValueByName<T>(string signalName);

        /// <summary>
        /// 将写入任务提交到写入队列 | Enqueue write task to write queue
        /// </summary>
        /// <param name="signalName">信号逻辑名称 | Signal logical name</param>
        /// <param name="value">要写入的值 | Value to write</param>
        /// <returns>入队成功返回 true，队列已满或已停止返回 false | Returns true if enqueued, false if queue full or stopped</returns>
        /// <exception cref="XP.Hardware.PLC.Exceptions.PlcException">
        /// 信号未找到或类型不兼容时抛出 | Thrown when signal not found or type incompatible
        /// </exception>
        bool EnqueueWrite(string signalName, object value);

        /// <summary>
        /// 直接写入并回读校验 | Direct write with read-back verification
        /// 绕过写入队列，使用独立通道高优先级写入 | Bypasses write queue, uses independent channel for high-priority write
        /// </summary>
        /// <param name="signalName">信号逻辑名称 | Signal logical name</param>
        /// <param name="value">要写入的值 | Value to write</param>
        /// <returns>回读校验通过返回 true，否则返回 false | Returns true if verification passed, false otherwise</returns>
        /// <exception cref="XP.Hardware.PLC.Exceptions.PlcException">
        /// 信号未找到或类型不兼容时抛出 | Thrown when signal not found or type incompatible
        /// </exception>
        Task<bool> WriteDirectWithVerify(string signalName, object value);
    }
}