package lib;


import com.sun.jna.*;
import com.sun.jna.ptr.*;


/**
 * 运动控制库通信组件 - 基础数据类型和工具类
 * 提供与C/C++运动控制库交互的基础数据类型转换和句柄管理
 */
public class mtn_lib20_com {
    
    /**
     * 设备/轴句柄类型（对应C语言的HANDLE）
     * 继承Pointer实现JNA原生指针交互
     */
    public static class HAND extends Pointer {
        /**
         * 创建空句柄（NULL指针）
         */
        public HAND() {
            super(Pointer.nativeValue(Pointer.NULL));
        }

        /**
         * 从原生指针创建句柄
         * @param p 原生指针对象
         */
        public HAND(Pointer p) {
            super(Pointer.nativeValue(p));
        }
    }

    /**
     * 句柄指针引用类型（对应C语言的HANDLE*）
     * 用于接收运动控制库返回的句柄指针
     */
    public static class PHAND extends PointerByReference {
        /**
         * 创建空指针引用
         */
        public PHAND() {
            super();
        }

        /**
         * 从原生指针创建引用
         * @param p 原生指针对象
         */
        public PHAND(Pointer p) {
            super(p);
        }

        /**
         * 从HAND句柄创建引用
         * @param value 已存在的句柄对象
         */
        public PHAND(HAND value) {
            super(value);
        }

        /**
         * 获取引用的句柄对象
         * @return 解引用后的HAND对象
         */
        public HAND getHandle() {
            return new HAND(getValue());
        }
    }

    // 无符号类型掩码常量
    /** 8位无符号掩码（0xFF） */
    public static final int UNSIGNED_CHAR = 0xFF;
    /** 16位无符号掩码（0xFFFF） */
    public static final int UNSIGNED_SHORT = 0xFFFF;
    /** 32位无符号掩码（0xFFFFFFFF） */
    public static final long UNSIGNED_INT = 0xFFFFFFFFL;

    /**
     * 转换为无符号byte（处理Java的有符号byte问题）
     * @param value 输入值（int类型）
     * @return 截取低8位的无符号byte
     * @throws IllegalArgumentException 输入值超过8位范围
     */
    public static byte toUnsignedByte(int value) {
        if ((value & ~UNSIGNED_CHAR) != 0) {
            throw new IllegalArgumentException("Value exceeds 8-bit range: " + value);
        }
        return (byte)(value & UNSIGNED_CHAR);
    }
    
    /**
     * 转换为无符号short（处理Java的有符号short问题）
     * @param value 输入值（int类型）
     * @return 截取低16位的无符号short
     * @throws IllegalArgumentException 输入值超过16位范围
     */
    public static short toUnsignedShort(int value) {
        if ((value & ~UNSIGNED_SHORT) != 0) {
            throw new IllegalArgumentException("Value exceeds 16-bit range: " + value);
        }
        return (short)(value & UNSIGNED_SHORT);
    }
    
    /**
     * 转换为无符号int（处理Java的有符号int问题）
     * @param value 输入值（long类型）
     * @return 截取低32位的无符号int
     * @throws IllegalArgumentException 输入值超过32位范围
     */
    public static int toUnsignedInt(long value) {
        if ((value & ~UNSIGNED_INT) != 0) {
            throw new IllegalArgumentException("Value exceeds 32-bit range: " + value);
        }
        return (int)(value & UNSIGNED_INT);
    }

    /**
     * 运动控制库专用异常
     */
    public static class NMCException extends RuntimeException {
        /**
         * 创建带错误信息的异常
         * @param message 错误描述
         */
        public NMCException(String message) {
            super(message);
        }

        /**
         * 创建带错误码的异常
         * @param code 错误码（通常来自运动控制库）
         */
        public NMCException(int code) {
            super("Motion control error: 0x" + Integer.toHexString(code));
        }
    }
}