using System;

namespace IvfTl.Hardware
{
    /// <summary>使用者身份，用于优先级与日志归因。</summary>
    public enum HardwareUser { ControlCapture, OperateDebug, AutoFocus }

    /// <summary>
    /// 按舱借用闸门。同一舱同一时刻只有一个使用者持有 IHardwareLease。
    /// 优先级/抢占策略：
    ///   · OperateDebug / AutoFocus 是【前台显式操作】，优先级高于 ControlCapture【后台节拍采集】；
    ///   · 申请前台借用时，HAL 通知 control 暂停该舱采集(PauseCapture)，归还后恢复(ResumeCapture)；
    ///   · 同为前台的 Debug 与 AutoFocus 互斥排队（不可同时操作同一舱电机/相机）。
    /// 接口签名权威：13 文档 §3.4。
    /// </summary>
    public interface IHouseGate
    {
        int HouseSn { get; }

        /// <summary>申请独占借用该舱（串口+相机）。阻塞直到拿到或超时。拿不到返回 null。
        /// 拿到 lease 期间，HAL 已暂停其它使用者对本舱的访问。Dispose(lease) 即归还。</summary>
        IHardwareLease Acquire(HardwareUser user, int timeoutMs = 30000);

        /// <summary>尝试借用，不阻塞。拿不到立即返回 false。</summary>
        bool TryAcquire(HardwareUser user, out IHardwareLease lease);

        /// <summary>暂停 control 对本舱的后台采集（前台借用时由 HAL 调用；也可供宿主显式调）。</summary>
        void PauseCapture();
        void ResumeCapture();

        /// <summary>本舱采集是否处于暂停态（采集线程每节拍据此让路）。</summary>
        bool IsCapturePaused { get; }

        /// <summary>宿主注册采集暂停/恢复回调（control 采集线程订阅，前台借用时被通知挂起本舱）。</summary>
        event Action OnPauseCapture;
        event Action OnResumeCapture;
    }

    /// <summary>借用凭证。Dispose 即归还闸门并触发 ResumeCapture。务必 using 包裹。</summary>
    public interface IHardwareLease : IDisposable
    {
        HardwareUser Owner { get; }
        ISerialChannel Serial { get; }   // 借用期内安全独占
        ICamera Camera { get; }
    }

    /// <summary>
    /// 全进程统一相机原生调用锁。替代现状 control/operate/af 各自的 static locker（三把不互斥的锁）。
    /// 所有 ICamera 实现的 native 调用都必须经此锁串行化（mvcapi.dll 非线程安全，跨相机也走同一把锁）。
    /// 接口签名权威：13 文档 §3.4。
    /// </summary>
    public interface ICameraGate
    {
        /// <summary>在全局相机锁内执行 native 操作。</summary>
        T Invoke<T>(Func<T> nativeCall);
        void Invoke(Action nativeCall);
    }
}