using SHH.CameraSdk;

/// <summary>
/// 海康 SDK 扩展方法类
/// 功能：提供海康 API 调用结果校验的快捷扩展，简化错误处理逻辑
/// </summary>
public static class HikExtensions
{
    #region --- 结果校验扩展 (Result Validation Extensions) ---

    /// <summary>
    /// 校验海康 API 调用结果是否成功
    /// 功能：若结果为 false（调用失败），自动捕获海康错误码并抛出统一异常
    /// </summary>
    /// <param name="result">海康 API 调用返回的布尔结果（true=成功，false=失败）</param>
    /// <param name="actionName">操作名称（用于异常信息描述，如“设备登录”“启动预览”）</param>
    /// <param name="brand">设备品牌（默认海康威视，无需手动指定）</param>
    /// <exception cref="CameraException">API 调用失败时抛出，包含标准错误码与原始错误描述</exception>
    public static void EnsureSuccess(this bool result, string actionName, DeviceBrand brand = DeviceBrand.HikVision)
    {
        // 调用成功则直接返回，无需后续处理
        if (result) return;

        // 1. 获取海康 SDK 最后一次操作的原始错误码
        uint lastError = HikNativeMethods.NET_DVR_GetLastError();

        // 2. 将海康原始错误码映射为系统统一标准错误码
        CameraErrorCode standardCode = HikErrorMapper.Map(lastError);

        // 3. 抛出统一异常，携带操作名称、标准错误码、原始错误描述等上下文
        throw new CameraException(standardCode, $"{actionName} 失败", brand, (int)lastError)
            .WithContext("Action", actionName)          // 附加操作名称上下文
            .WithContext("HikDesc", HikErrorMapper.GetRawDescription(lastError)); // 附加海康原始错误描述
    }

    #endregion
}