using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using X1.DynamicClientCore.Models;

namespace X1.DynamicClientCore.Features
{
    /// <summary>
    /// 仪器协议客户端接口
    /// 提供仪器设备的网络控制功能，包括网络启动、停止等协议相关操作
    /// </summary>
    /// <remarks>
    /// 作为仪器客户端的协议接口，定义了仪器设备网络控制相关的功能
    /// 主要用于网络连接的管理和控制操作
    /// </remarks>
    public interface IInstrumentProtocolClient
    {
        /// <summary>
        /// 启动网络连接
        /// </summary>
        /// <param name="request">蜂窝网络启动请求</param>
        /// <param name="options">请求选项，包含超时、请求头等配置</param>
        /// <param name="cancellationToken">取消令牌，用于取消异步操作</param>
        /// <returns>异步任务，表示网络启动操作的完成状态</returns>
        /// <exception cref="ArgumentNullException">当request为null时抛出</exception>
        /// <exception cref="ArgumentException">当request中的设备编号为空时抛出</exception>
        Task<bool> StartNetworkAsync(
            StartCellularNetworkRequest request,
            RequestOptions? options = null, 
            CancellationToken cancellationToken = default);

        /// <summary>
        /// 停止网络连接
        /// </summary>
        /// <param name="instrumentNumber">仪器编号，用于标识特定的仪器设备</param>
        /// <param name="request">蜂窝网络停止请求</param>
        /// <param name="options">请求选项，包含超时、请求头等配置</param>
        /// <param name="cancellationToken">取消令牌，用于取消异步操作</param>
        /// <returns>异步任务，表示网络停止操作的完成状态</returns>
        /// <exception cref="ArgumentNullException">当instrumentNumber为null或空时抛出</exception>
        /// <exception cref="ArgumentException">当instrumentNumber格式无效时抛出</exception>
        Task<bool> StopNetworkAsync(
            string instrumentNumber,
            StopCellularNetworkRequest request,
            RequestOptions? options = null, 
            CancellationToken cancellationToken = default);
    }
}