using System.ComponentModel;
using System.Threading.Tasks;
using XP.Hardware.PLC.Configs;
using XP.Hardware.PLC.Helpers;
using XP.Hardware.PLC.Models;

namespace XP.Hardware.Plc.Abstractions
{
    /// <summary>
    /// PLC 服务接口，供跨模块使用 | PLC service interface for cross-module usage
    /// 提供 PLC 连接状态查询、信号管理和属性变更通知 | Provides PLC connection status query, signal management and property change notification
    /// </summary>
    public interface IPlcService : INotifyPropertyChanged
    {
        /// <summary>
        /// PLC 连接状态 | PLC connection status
        /// </summary>
        bool IsConnected { get; }

        /// <summary>
        /// 状态文本，用于 UI 显示 | Status text for UI display
        /// </summary>
        string StatusText { get; }

        /// <summary>
        /// 初始化 PLC 连接 | Initialize PLC connection
        /// </summary>
        /// <param name="config">PLC 配置 | PLC configuration</param>
        /// <returns>连接是否成功 | Whether connection succeeded</returns>
        Task<bool> InitializeAsync(PlcConfig config);

        /// <summary>
        /// 加载信号定义文件 | Load signal definitions from XML file
        /// </summary>
        /// <param name="xmlFilePath">XML 信号定义文件路径 | XML signal definition file path</param>
        void LoadSignalDefinitions(string xmlFilePath);

        /// <summary>
        /// 按名称查找信号定义 | Find signal definition by name
        /// </summary>
        /// <param name="signalName">信号逻辑名称 | Signal logical name</param>
        /// <returns>信号条目 | Signal entry</returns>
        SignalEntry FindSignal(string signalName);

        /// <summary>
        /// 获取当前批量读取缓存快照 | Get current bulk read cache snapshot
        /// </summary>
        /// <returns>缓存快照，缓存为空时返回 null | Cache snapshot, returns null when cache is empty</returns>
        PlcDataBlock GetCacheSnapshot();

        /// <summary>
        /// 释放资源 | Dispose resources
        /// </summary>
        void Dispose();
    }
}