Display_D_HP/TeamAAS-VM/Core/Lights/ICommunicationProtocol.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using TeamAAS_VP.Enums;

namespace TeamAAS_VP.Core.Lights
{
    /// <summary>
    /// 定义灯光控制或通信设备的通用通信协议契约。
    /// 实现此接口的类负责建立连接、发送/接收数据以及在连接状态改变时通知订阅者。
    /// 实现类应负责释放底层资源，因此继承自 <see cref="IDisposable"/>。
    /// </summary>
    public interface ICommunicationProtocol : IDisposable
    {
        /// <summary>
        /// 获取当前连接状态。
        /// 返回 true 表示已建立连接并可进行数据收发；false 表示未连接或已断开。
        /// </summary>
        bool IsConnected { get; }

        /// <summary>
        /// 获取或设置通信报文的结束标记（终止符）。
        /// 该标记用于分割或终结文本协议消息。
        /// </summary>
        Terminator Terminator { get; }

        /// <summary>
        /// 获取用于文本消息编码/解码的字符编码（例如 UTF8、ASCII）。
        /// 当使用字符串重载的发送/接收方法时，此编码将被应用。
        /// </summary>
        Encoding Encoding { get; }

        /// <summary>
        /// 当连接状态发生变化时触发。
        /// sender 为事件源，bool 参数表示新的连接状态（true=已连接，false=已断开）。
        /// </summary>
        event Action<object, bool> ConnectionChanged;

        /// <summary>
        /// 当接收到完整的数据（按协议分包或终止符）时触发。
        /// sender 为事件源，string 为已接收并按 <see cref="Encoding"/> 解码的文本内容。
        /// </summary>
        event Action<object, string> DataReceived;

        /// <summary>
        /// 当成功发送数据时触发。
        /// sender 为事件源，string 为已发送并按 <see cref="Encoding"/> 编码的文本内容（若使用字节发送则可为空或经转换的展示文本）。
        /// </summary>
        event Action<object, string> DataSent;

        /// <summary>
        /// 异步建立与设备的连接。
        /// 实现应在连接成功后触发 <see cref="ConnectionChanged"/>（true）。
        /// </summary>
        /// <returns>任务结果为 true 表示连接成功，false 表示连接失败或未建立。</returns>
        Task<bool> ConnectAsync();

        /// <summary>
        /// 异步断开与设备的连接并释放相关资源（但不等同于 Dispose）。
        /// 实现应在断开后触发 <see cref="ConnectionChanged"/>（false）。
        /// </summary>
        /// <returns>表示断开操作完成的任务。</returns>
        Task DisconnectAsync();

        /// <summary>
        /// 异步发送字节数组并等待返回的字节数组响应。
        /// </summary>
        /// <param name="data">要发送的原始字节数据。</param>
        /// <param name="timeout">超时时间（毫秒），在超时未收到完整响应时应抛出或返回空/部分数据，默认 5000ms。</param>
        /// <returns>返回接收到的字节数组响应。</returns>
        Task<byte[]> SendAndReceiveAsync(byte[] data, int timeout = 5000);

        /// <summary>
        /// 异步发送字节数组，不等待响应。
        /// </summary>
        /// <param name="data">要发送的原始字节数据。</param>
        /// <returns>表示发送操作完成的任务。</returns>
        Task SendAsync(byte[] data);

        /// <summary>
        /// 异步发送文本并等待文本响应。
        /// 使用 <see cref="Encoding"/> 对字符串进行编码/解码，超时时间单位为毫秒。
        /// </summary>
        /// <param name="data">要发送的文本数据。</param>
        /// <param name="timeout">超时时间（毫秒），默认 5000ms。</param>
        /// <returns>返回接收到的文本响应。</returns>
        Task<string> SendAndReceiveAsync(string data, int timeout = 5000);

        /// <summary>
        /// 同步发送文本并等待文本响应。
        /// 注意：在 UI 线程中调用此方法可能导致界面阻塞，建议使用异步重载。
        /// </summary>
        /// <param name="data">要发送的文本数据。</param>
        /// <param name="timeout">超时时间（毫秒），默认 5000ms。</param>
        /// <returns>接收到的文本响应。</returns>
        string SendAndReceive(string data, int timeout = 5000);

        /// <summary>
        /// 同步发送字节数组并等待返回的字节数组响应。
        /// 注意：在 UI 线程中调用此方法可能导致界面阻塞，建议使用异步重载。
        /// </summary>
        /// <param name="data">要发送的字节数组。</param>
        /// <param name="timeout">超时时间（毫秒），默认 5000ms。</param>
        /// <returns>接收到的字节数组响应。</returns>
        byte[] SendAndReceive(byte[] data, int timeout = 5000);

        /// <summary>
        /// 同步发送字节数组，不等待响应。
        /// 注意：在 UI 线程中调用此方法可能导致界面阻塞，建议使用异步重载。
        /// </summary>
        /// <param name="data">要发送的字节数组。</param>
        void Send(byte[] data);

        /// <summary>
        /// 异步发送文本数据。
        /// 使用 <see cref="Encoding"/> 对字符串进行编码后发送。
        /// </summary>
        /// <param name="data">要发送的文本数据。</param>
        /// <returns>表示发送操作完成的任务。</returns>
        Task SendAsync(string data);

        /// <summary>
        /// 同步发送文本数据。
        /// 注意：在 UI 线程中调用此方法可能导致界面阻塞，建议使用异步重载。
        /// </summary>
        /// <param name="data">要发送的文本数据。</param>
        void Send(string data);
    }
}