namespace SHH.CameraSdk;

/// <summary>
/// [核心契约] 工业级视频源接口 (V3.3.1 终极定稿)
/// 核心职责：定义所有视频源设备的标准化生命周期、状态观测与数据分发能力
/// 关键修复：
/// <para>1. [Fix Bug δ] 新增 UpdateConfig 接口，支持运行时配置热更新</para>
/// <para>2. 强化资源管理契约：继承 IDisposable/IAsyncDisposable，规范非托管资源释放</para>
/// 适用场景：海康/大华/宇视等不同品牌相机的驱动适配、统一管理
/// </summary>
public interface IVideoSource : IDisposable, IAsyncDisposable
{
    #region --- 1. 只读属性 (设备标识与状态观测) ---

    /// <summary> 设备唯一业务标识（全局唯一，如数据库自增ID） </summary>
    long Id { get; }

    /// <summary> 设备详细逻辑状态（如 Idle/Connecting/Playing/Faulted） </summary>
    VideoSourceStatus Status { get; }

    /// <summary> 用户意图标识：是否需要保持设备运行状态 </summary>
    bool IsRunning { get; set; }

    /// <summary> 设备物理在线状态（基于心跳/探测的实时感知结果） </summary>
    bool IsOnline { get; }

    /// <summary> 设备能力元数据（只读，如分辨率、码流类型、支持的功能集） </summary>
    DeviceMetadata Metadata { get; }

    #endregion

    #region --- 2. 事件契约 (数据分发与状态通知) ---

    /// <summary>
    /// 视频帧接收事件（热路径，高频触发）
    /// </summary>
    /// <remarks>
    /// 1. 载荷类型：通常为 <see cref="OpenCvSharp.Mat"/> 或 <see cref="SmartFrame"/> 对象
    /// 2. 内存管理：订阅者必须负责载荷对象的 Dispose 操作，否则会导致内存泄漏
    /// 3. 性能约束：事件处理逻辑需控制在 10ms 内，避免阻塞取流线程
    /// </remarks>
    event Action<object>? FrameReceived;

    /// <summary>
    /// 设备状态变更通知事件（结构化状态同步）
    /// </summary>
    /// <remarks> 携带状态变更前后的详细信息，用于监控告警、日志记录 </remarks>
    event EventHandler<StatusChangedEventArgs> StatusChanged;

    #endregion

    #region --- 3. 核心方法 (生命周期与配置管理) ---

    /// <summary>
    /// 异步启动设备（完整流程：连接设备 → 登录鉴权 → 启动码流接收）
    /// </summary>
    /// <exception cref="InvalidOperationException">设备状态非法时抛出</exception>
    /// <exception cref="SdkCommunicationException">SDK 通信失败时抛出</exception>
    Task StartAsync();

    /// <summary>
    /// 异步停止设备（完整流程：停止码流 → 登出设备 → 释放连接资源）
    /// </summary>
    Task StopAsync();

    /// <summary>
    /// [Fix Bug δ] 运行时更新设备配置
    /// </summary>
    /// <param name="newConfig">新的设备配置（如 IP、端口、用户名密码）</param>
    /// <remarks>
    /// 1. 生效机制：新配置不会立即生效，将在下次启动或自动重连时应用
    /// 2. 原子性保证：配置更新为原子操作，不会出现部分生效的情况
    /// 3. 适用场景：设备 IP 变更、密码修改等运维场景
    /// </remarks>
    void UpdateConfig(VideoSourceConfig newConfig);

    /// <summary>
    /// 应用动态流配置补丁（无需重启，实时生效）
    /// </summary>
    /// <param name="options">动态流参数（如主码流/子码流切换、分辨率调整）</param>
    /// <remarks> 适用于运行时按需调整码流参数，降低带宽占用 </remarks>
    void ApplyOptions(DynamicStreamOptions options);

    /// <summary>
    /// 强制刷新设备元数据，并返回元数据变更差异
    /// </summary>
    /// <returns>元数据变更差异对象（如分辨率变化、功能集变化）</returns>
    Task<MetadataDiff> RefreshMetadataAsync();

    #endregion
}