91 lines
3.8 KiB
C#
91 lines
3.8 KiB
C#
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
|
||
} |