namespace SHH.CameraSdk;

/// <summary>
/// 视频源状态变更事件参数
/// 核心职责：封装状态迁移的完整上下文信息，支撑三大业务场景
/// <para>1. UI 层：实时反馈设备状态、显示错误提示</para>
/// <para>2. 诊断层：记录异常堆栈、SDK 错误码，辅助问题定位</para>
/// <para>3. 运维层：触发自动重连、告警推送等自动化决策</para>
/// </summary>
public class StatusChangedEventArgs : EventArgs
{
    #region --- 事件核心属性 (Event Core Properties) ---

    /// <summary>
    /// 变更后的目标状态
    /// 业务用途：
    /// 1. UI 层：控制状态图标颜色（如 Playing→绿色、Faulted→红色）
    /// 2. 运维层：状态为 Reconnecting 时触发重连策略调整
    /// </summary>
    public VideoSourceStatus NewStatus { get; }

    /// <summary>
    /// 状态描述文本（可读）
    /// 业务用途：
    /// 1. UI 层：直接显示在状态栏或操作日志面板
    /// 2. 日志层：写入业务日志，便于人工排查
    /// </summary>
    public string Message { get; }

    /// <summary>
    /// 关联的异常对象（可选）
    /// 业务用途：仅当 NewStatus = Faulted 时有效，提供异常堆栈、类型等代码级诊断信息
    /// </summary>
    public Exception? Exception { get; }

    /// <summary>
    /// SDK 底层原始错误码（可选）
    /// 业务用途：
    /// 1. 厂商适配：匹配海康 NET_DVR_GetLastError、大华 SDK 错误码等
    /// 2. 精准诊断：区分“用户锁定(153)”“密码错误(41)”“网络超时”等根因
    /// </summary>
    public int? LastErrorCode { get; }

    /// <summary>
    /// 变更后的新句柄（可选）
    /// 业务用途：渲染器解绑/重绑场景，监听此值更新窗口句柄绑定关系
    /// </summary>
    public IntPtr? NewHandle { get; init; }

    /// <summary>
    /// 状态变更发生的时间戳
    /// 业务用途：日志时序排序、状态迁移耗时统计
    /// </summary>
    public DateTime Timestamp { get; } = DateTime.Now;

    #endregion

    #region --- 构造函数 (Constructor) ---

    /// <summary>
    /// 初始化状态变更事件参数
    /// </summary>
    /// <param name="status">变更后的目标状态</param>
    /// <param name="msg">可读的状态描述文本</param>
    /// <param name="ex">可选：关联的异常对象</param>
    /// <param name="errorCode">可选：SDK 底层错误码</param>
    public StatusChangedEventArgs(
        VideoSourceStatus status,
        string msg,
        Exception? ex = null,
        int? errorCode = null)
    {
        NewStatus = status;
        Message = msg;
        Exception = ex;
        LastErrorCode = errorCode;
    }

    #endregion
}