GrabBag/Module/ModbusTCPClient/Inc/IYModbusTCPClient.h

#ifndef IY_MODBUS_TCP_CLIENT_H
#define IY_MODBUS_TCP_CLIENT_H

#include <string>
#include <vector>
#include <functional>
#include <cstdint>

/**
 * @brief Modbus TCP 客户端虚拟接口类
 *
 * 提供 Modbus TCP 客户端的抽象接口，隔离底层 libmodbus 依赖。
 * 外部使用者只需包含此头文件，通过 CreateInstance 工厂方法创建实例。
 */
class IYModbusTCPClient {
public:
    // 连接状态枚举
    enum ConnectionState {
        DISCONNECTED = 0,   ///< 已断开连接
        CONNECTING,         ///< 正在连接
        CONNECTED,          ///< 已连接
        ERROR_STATE         ///< 错误状态
    };

    // 操作结果枚举
    enum Result {
        SUCCESS = 0,                ///< 操作成功
        ERROR_CONNECTION = -1,      ///< 连接错误
        ERROR_INVALID_PARAM = -2,   ///< 参数错误
        ERROR_TIMEOUT = -3,         ///< 超时错误
        ERROR_DEVICE = -4,          ///< 设备错误
        ERROR_PROTOCOL = -5,        ///< 协议错误
        ERROR_UNKNOWN = -6          ///< 未知错误
    };

    // 连接状态变化回调函数类型
    using ConnectionStateCallback = std::function<void(ConnectionState oldState, ConnectionState newState, const std::string& message)>;

public:
    virtual ~IYModbusTCPClient() = default;

    /**
     * @brief 工厂方法：创建 ModbusTCPClient 实例
     * @param ppClient 输出的客户端实例指针
     * @param serverIP 服务器 IP 地址
     * @param serverPort 服务器端口（默认 502）
     * @return 是否创建成功
     */
    static bool CreateInstance(IYModbusTCPClient** ppClient, const std::string& serverIP, int serverPort = 502);

    // === 连接管理 ===

    virtual bool SetConnectionParams(const std::string& serverIP, int serverPort) = 0;
    virtual bool SetSlaveId(int slaveId) = 0;
    virtual bool SetTimeout(int timeoutMs) = 0;
    virtual void SetConnectionStateCallback(ConnectionStateCallback callback) = 0;

    virtual Result Connect() = 0;
    virtual void Disconnect() = 0;

    virtual ConnectionState GetConnectionState() const = 0;
    virtual bool IsConnected() const = 0;

    // === 读操作 ===

    virtual Result ReadCoils(int startAddress, int quantity, std::vector<bool>& values) = 0;
    virtual Result ReadDiscreteInputs(int startAddress, int quantity, std::vector<bool>& values) = 0;
    virtual Result ReadHoldingRegisters(int startAddress, int quantity, std::vector<uint16_t>& values) = 0;
    virtual Result ReadInputRegisters(int startAddress, int quantity, std::vector<uint16_t>& values) = 0;

    // === 写操作 ===

    virtual Result WriteSingleCoil(int address, bool value) = 0;
    virtual Result WriteSingleRegister(int address, uint16_t value) = 0;
    virtual Result WriteMultipleCoils(int startAddress, const std::vector<bool>& values) = 0;
    virtual Result WriteMultipleRegisters(int startAddress, const std::vector<uint16_t>& values) = 0;

    // === 组合操作 ===

    virtual Result ReadWriteMultipleRegisters(int readStartAddress, int readQuantity,
                                              int writeStartAddress, const std::vector<uint16_t>& writeValues,
                                              std::vector<uint16_t>& readValues) = 0;

    // === 数据类型转换辅助函数 ===

    static uint32_t RegistersToUInt32(uint16_t high, uint16_t low);
    static void UInt32ToRegisters(uint32_t value, uint16_t& high, uint16_t& low);
    static float RegistersToFloat(uint16_t high, uint16_t low);
    static void FloatToRegisters(float value, uint16_t& high, uint16_t& low);

    // === 错误处理 ===

    virtual std::string GetLastError() const = 0;

    static std::string ResultToString(Result result);
    static std::string ConnectionStateToString(ConnectionState state);
};

#endif // IY_MODBUS_TCP_CLIENT_H