Display_D_HP/TeamAAS-VM/Interfaces/IPlcService.cs

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using TeamAAS_VP.Models;

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// 提供 PLC 生命周期管理的接口，包括创建、获取、初始化及注销 PLC 实例。
    /// </summary>
    public interface IPlcService : IDisposable
    {
        /// <summary>
        /// 异步创建并注册一个新的 PLC 实例。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <param name="plcInfo">PLC 的配置信息。</param>
        /// <returns>创建是否成功。</returns>
        Task<bool> CreatePlcAsync(Guid id, PlcInfo plcInfo);

        /// <summary>
        /// 同步创建并注册一个新的 PLC 实例。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <param name="plcInfo">PLC 的配置信息。</param>
        /// <returns>创建是否成功。</returns>
        bool CreatePlc(Guid id, PlcInfo plcInfo);

        /// <summary>
        /// 初始化所有PLC实例（同步）。
        /// </summary>
        /// <param name="plcs"></param>
        /// <returns></returns>
        (bool IsSucceed, string Message) InitializePlc(PlcInfo[] plcs);

        /// <summary>
        /// 初始化所有PLC实例（异步）。
        /// </summary>
        /// <param name="plcs"></param>
        /// <returns></returns>
        Task<(bool IsSucceed, string Message)> InitializePlcAsync(PlcInfo[] plcs);

        /// <summary>
        /// 获取指定 ID 的 PLC 实例（同步），如果不存在可返回 null 或抛出异常，视实现而定。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <returns>对应的 <see cref="IPlc"/> 实例。</returns>
        IPlc GetPlc(Guid id);

        /// <summary>
        /// 异步获取指定 ID 的 PLC 实例。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <returns>对应的 <see cref="IPlc"/> 实例的任务。</returns>
        Task<IPlc> GetPlcAsync(Guid id);

        /// <summary>
        /// 获取当前所有已注册的 PLC（只读集合，同步）。
        /// </summary>
        /// <returns>只读的 PLC 实例集合。</returns>
        IReadOnlyCollection<IPlc> GetAllPlcs();

        /// <summary>
        /// 异步获取当前所有已注册的 PLC（只读集合）。
        /// </summary>
        /// <returns>只读的 PLC 实例集合的任务。</returns>
        Task<IReadOnlyCollection<IPlc>> GetAllPlcsAsync();

        /// <summary>
        /// 尝试根据 ID 获取 PLC（同步），若存在则返回 true 并通过 out 参数返回实例。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <param name="plc">输出的 PLC 实例（若找到）。</param>
        /// <returns>是否找到。</returns>
        bool TryGetPlc(Guid id, out IPlc plc);

        /// <summary>
        /// 尝试根据 ID 异步获取 PLC，返回是否找到及实例的元组。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <returns>包含是否找到与实例的元组。</returns>
        Task<(bool found, IPlc plc)> TryGetPlcAsync(Guid id);

        /// <summary>
        /// 判断是否包含指定 ID 的 PLC（同步）。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <returns>是否包含。</returns>
        bool ContainsPlc(Guid id);

        /// <summary>
        /// 判断是否包含指定 ID 的 PLC（异步）。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <returns>是否包含的任务。</returns>
        Task<bool> ContainsPlcAsync(Guid id);

        /// <summary>
        /// 移除指定 ID 的 PLC（同步），并释放其资源。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <returns>移除是否成功。</returns>
        bool RemovePlc(Guid id);

        /// <summary>
        /// 异步移除指定 ID 的 PLC，并释放其资源。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <returns>移除是否成功的任务。</returns>
        Task<bool> RemovePlcAsync(Guid id);

        /// <summary>
        /// 移除所有已注册的 PLC（同步），并释放相关资源。
        /// </summary>
        /// <returns>是否全部成功移除；若部分失败则返回 false。</returns>
        bool RemoveAllPlcs();

        /// <summary>
        /// 异步移除所有已注册的 PLC，并释放相关资源。
        /// </summary>
        /// <returns>是否全部成功移除的任务；若部分失败则返回 false。</returns>
        Task<bool> RemoveAllPlcsAsync();

        /// <summary>
        /// 异步注销指定的 PLC（例如注销事件、断开连接等），不一定会立即从集合中移除，具体行为由实现决定。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        /// <returns>任务。</returns>
        Task UnRegisterPlcAsync(Guid id);

        /// <summary>
        /// 同步注销指定的 PLC（例如注销事件、断开连接等），不一定会立即从集合中移除，具体行为由实现决定。
        /// </summary>
        /// <param name="id">PLC 唯一标识。</param>
        void UnRegisterPlc(Guid id);

        /// <summary>
        /// 根据 PLC 编号获取 PLC 实例（同步）。
        /// </summary>
        /// <param name="number">PLC 编号。</param>
        /// <returns>对应的 <see cref="IPlc"/> 实例。</returns>
        IPlc GetPlcByNumber(int number);

        /// <summary>
        /// 根据 PLC 编号异步获取 PLC 实例。
        /// </summary>
        /// <param name="number">PLC 编号。</param>
        /// <returns>对应的 <see cref="IPlc"/> 实例的任务。</returns>
        Task<IPlc> GetPlcByNumberAsync(int number);

        /// <summary>
        /// 根据 PLC 编号异步注销 PLC（例如注销事件、断开连接等）。
        /// </summary>
        /// <param name="number">PLC 编号。</param>
        /// <returns>任务。</returns>
        Task UnRegisterPlcByNumberAsync(int number);

        /// <summary>
        /// 根据 PLC 编号同步注销 PLC（例如注销事件、断开连接等）。
        /// </summary>
        /// <param name="number">PLC 编号。</param>
        void UnRegisterPlcByNumber(int number);

        /// <summary>
        /// 更新PLC编号
        /// </summary>
        /// <param name="id"></param>
        /// <param name="newNumber"></param>
        void UpdatePlcNumber(Guid id, int newNumber);
    }
}