Display_D_HP/TeamAAS-VM/Interfaces/ICameraService.cs

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

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// 提供相机生命周期管理的接口，包括创建、获取及注销相机实例。
    /// 实现者应保证线程安全，并在 <see cref="Dispose"/> 中释放所有已注册相机的资源。
    /// </summary>
    public interface ICameraService : IDisposable
    {
        /// <summary>
        /// 异步创建并注册一个相机实例。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <param name="cameraInfo">用于创建相机的配置信息，不能为空。</param>
        /// <returns>返回一个任务，任务结果为 true 表示创建并注册成功，false 表示已存在或创建失败。</returns>
        Task<bool> CreateCameraAsync(Guid id, CameraInfo cameraInfo);

        /// <summary>
        /// 同步创建并注册一个相机实例。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <param name="cameraInfo">用于创建相机的配置信息，不能为空。</param>
        /// <returns>如果创建并注册成功则返回 true；如果已存在或创建失败则返回 false。</returns>
        bool CreateCamera(Guid id, CameraInfo cameraInfo);

        /// <summary>
        /// 根据标识符获取已注册的相机实例（同步）。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <returns>返回对应的 <see cref="ICamera"/> 实例；若未找到，返回 null（实现者应在文档中明确 null 语义）。</returns>
        ICamera GetCamera(Guid id);

        /// <summary>
        /// 根据标识符获取已注册的相机实例（异步）。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <returns>返回一个任务，其结果为对应的 <see cref="ICamera"/> 实例；若未找到，结果为 null。</returns>
        Task<ICamera> GetCameraAsync(Guid id);

        /// <summary>
        /// 获取当前所有已注册相机的只读集合（同步快照）。
        /// </summary>
        /// <returns>返回一个只读集合，包含当前已注册的所有 <see cref="ICamera"/> 实例。</returns>
        IReadOnlyCollection<ICamera> GetAllCameras();

        /// <summary>
        /// 获取当前所有已注册相机的只读集合（异步快照）。
        /// </summary>
        /// <returns>返回一个任务，其结果为当前已注册的所有 <see cref="ICamera"/> 实例的只读集合。</returns>
        Task<IReadOnlyCollection<ICamera>> GetAllCamerasAsync();

        /// <summary>
        /// 尝试根据标识符获取相机（同步）。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <param name="camera">当返回值为 true 时，输出对应的 <see cref="ICamera"/> 实例；否则为 null。</param>
        /// <returns>如果找到则返回 true，否则返回 false。</returns>
        bool TryGetCamera(Guid id, out ICamera camera);

        /// <summary>
        /// 尝试根据标识符获取相机（异步）。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <returns>
        /// 返回一个任务，任务结果为一个元组：
        /// - found: 是否找到相机；
        /// - camera: 如果 found 为 true，则为对应的 <see cref="ICamera"/> 实例；否则为 null。
        /// </returns>
        Task<(bool found, ICamera camera)> TryGetCameraAsync(Guid id);

        /// <summary>
        /// 检查是否包含指定标识符的注册相机（同步）。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <returns>如果已注册则返回 true；否则返回 false。</returns>
        bool ContainsCamera(Guid id);

        /// <summary>
        /// 检查是否包含指定标识符的注册相机（异步）。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <returns>返回一个任务，其结果为是否已注册该相机。</returns>
        Task<bool> ContainsCameraAsync(Guid id);

        /// <summary>
        /// 从注册表中移除并注销指定标识符的相机（同步）。
        /// 实现者应在移除时妥善释放相机占用的资源或根据语义选择仅反注册。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <returns>如果成功移除则返回 true；如果未找到则返回 false。</returns>
        bool RemoveCamera(Guid id);

        /// <summary>
        /// 从注册表中移除并注销指定标识符的相机（异步）。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <returns>返回一个任务，任务结果为是否成功移除。</returns>
        Task<bool> RemoveCameraAsync(Guid id);

        /// <summary>
        /// 异步反注册指定标识符的相机（不一定释放底层资源，具体语义由实现者决定并在实现文档中说明）。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        /// <returns>异步任务，完成时表示已反注册或确认不存在。</returns>
        Task UnRegisterCameraAsync(Guid id);

        /// <summary>
        /// 同步反注册指定标识符的相机（不一定释放底层资源，具体语义由实现者决定并在实现文档中说明）。
        /// </summary>
        /// <param name="id">相机唯一标识符（Guid）。</param>
        void UnRegisterCamera(Guid id);

        /// <summary>
        /// 根据物理或逻辑编号获取相机（同步）。
        /// </summary>
        /// <param name="number">相机编号（通常为设备顺序号或配置中的数字索引）。</param>
        /// <returns>返回对应的 <see cref="ICamera"/> 实例；若未找到，返回 null。</returns>
        ICamera GetCameraByNumber(int number);

        /// <summary>
        /// 根据物理或逻辑编号获取相机（异步）。
        /// </summary>
        /// <param name="number">相机编号（通常为设备顺序号或配置中的数字索引）。</param>
        /// <returns>返回一个任务，其结果为对应的 <see cref="ICamera"/> 实例；若未找到，结果为 null。</returns>
        Task<ICamera> GetCameraByNumberAsync(int number);

        /// <summary>
        /// 异步按编号反注册相机。
        /// </summary>
        /// <param name="number">相机编号。</param>
        /// <returns>异步任务，完成时表示已按编号反注册或确认不存在。</returns>
        Task UnRegisterCameraByNumberAsync(int number);

        /// <summary>
        /// 同步按编号反注册相机。
        /// </summary>
        /// <param name="number">相机编号。</param>
        void UnRegisterCameraByNumber(int number);

        /// <summary>
        /// 移除所有相机
        /// </summary>
        void RemoveAllCameras();

        /// <summary>
        /// 初始化所有相机
        /// </summary>
        /// <param name="cameras"></param>
        /// <returns></returns>
        (bool IsSucceed, string Message) InitializeAllCameras(CameraInfo[] cameras);

        /// <summary>
        /// 初始化所有相机（异步）
        /// </summary>
        /// <param name="cameras"></param>
        /// <returns></returns>
        Task<(bool IsSucceed, string Message)> InitializeAllCamerasAsync(CameraInfo[] cameras);

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