//! 统一邮箱协议 trait (对齐 C# IMailboxProtocol)

use super::{MailboxStatistics, MailboxStatus};

/// 所有邮箱协议的统一接口 (对齐 C# `IMailboxProtocol`).
///
/// 对应七个协议实现:
/// `CoEInstance` / `FoEInstance` / `SoEInstance` /
/// `AoEInstance` / `EoEInstance` / `VoEInstance` / `SafetyManager`.
pub trait MailboxProtocol {
    /// 协议类型 (`ECT_MBXT_*`):
    ///
    /// | 协议 | 值    |
    /// |------|-------|
    /// | AoE  | 0x01  |
    /// | EoE  | 0x02  |
    /// | CoE  | 0x03  |
    /// | FoE  | 0x04  |
    /// | SoE  | 0x05  |
    /// | FSoE | 0x08  |
    /// | VoE  | 0x0F  |
    fn protocol_type(&self) -> u8;

    /// 协议名称 ("CoE" / "FoE" / "SoE" / "AoE" / "EoE" / "VoE" / "FSoE")
    fn protocol_name(&self) -> &'static str;

    /// 从站是否支持本协议 (读 SII mbx_proto 或邮箱能力)
    fn is_supported(&self) -> bool;

    /// 最后一次邮箱事务的状态 (跨该协议实例的所有调用).
    /// 初始为 [`MailboxStatus::Pending`], 调用后更新.
    ///
    /// 默认返回 `Pending`, 各协议如跟踪本地状态可 override.
    fn last_status(&self) -> MailboxStatus { MailboxStatus::Pending }

    /// 最后一次邮箱事务的协议层错误码
    /// (CoE 为 SDO Abort Code, FoE 为 FoE Error Code, SoE 为 SoE Error Code 等).
    /// 0 表示无错误或不适用.
    ///
    /// 默认返回 0, 各协议如跟踪错误码可 override.
    fn last_error_code(&self) -> u32 { 0 }

    /// 邮箱统计快照 (当前会话).
    ///
    /// 通过调用 DLL `EcxMbxGetStatsByMaster` 获取.
    fn statistics(&self) -> MailboxStatistics;

    /// 重置邮箱统计计数器 (调用 DLL `EcxMbxResetStatsByMaster`).
    fn reset_statistics(&self);
}
