XTCP

一个便捷的TCP消息包拼装和解析框架

关于我

特征

简单通过@Protocol和@ProtocolField的配置，即可让实体对象拥有自动转化为TCP传输的byte数据和自动byte数据解析。
支持byte、short、int、long、byte[]、short[]、int[]、long[]、String等常用基础类型，支持类型的拓展。
支持无符号数和有符号数两种。
支持BCD编码格式【时间、int、float、double等】。
支持大端和小端两种存储方式，支持设置全局默认存储方式和局部存储方式。
支持short、int、long读取长度的自定义。
支持对实体字段进行排序，避免解析错乱。
支持自定义协议项和协议解析器。
支持对不定长数组解析【需要注意的是，在一条协议中有且只能有一个不定长的数组，否则将无法解析成功】。
支持自动协议映射，自动根据读取的opcode识别出对应的协议并进行解析，并根据对应注册的协议信息判断协议是否有响应。

1、演示（请star支持）

Demo下载

2、如何使用

目前支持主流开发工具AndroidStudio的使用，直接配置build.gradle，增加依赖即可.

2.1 添加Gradle依赖

1.先在项目根目录的 build.gradle 的 repositories 添加:

allprojects {
     repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}

2.然后在dependencies添加:

dependencies {
  ...
  implementation 'com.github.xuexiangjys.XTCP:xtcp_runtime:1.0.7'
  annotationProcessor 'com.github.xuexiangjys.XTCP:xtcp_compiler:1.0.7'
}

3.进行moduleName注册

defaultConfig {
    ...

    javaCompileOptions {
        annotationProcessorOptions {
            arguments = [ moduleName : project.getName() ]
        }
    }
}

【注意】：如果不注册的话，默认ModuleName为app。

2.2 初始化协议中心

在Application中注册协议中心和协议字段中心。

XTCP.getInstance()
        .addIProtocolCenter(AppProtocolCenter.getInstance()) //添加协议中心
        .addIProtocolFieldCenter(AppProtocolFieldCenter.getInstance(), XTCPProtocolFieldCenter.getInstance()) //添加协议字段中心
        .setDefaultStorageMode(StorageMode.BigEndian) //设置默认存储方式（默认是大端）
        .debug(true); //打开调试日志

2.3 构建通信协议实体

通过继承XProtocolItem或者实现IProtocolItem接口，通过@Protocol和@ProtocolField注解进行配置。

@Protocol: 用于注解协议项，包括name、opcode、resCode、mode、desc等属性。
@ProtocolField: 用于注解协议项字段，包括index、isField、length、mode、charset等属性。

@Protocol(name = "参数设置请求", opCode = 0x12, resCode = 0x33, desc = "注意重启下位机后生效！")
public class SettingRequest extends XProtocolItem {
    @ProtocolField(index = 0)
    private byte func1;
    @ProtocolField(index = 1)
    private short func2;
    @ProtocolField(index = 2)
    private int func3;
    @ProtocolField(index = 3)
    private long func4;
    @ProtocolField(index = 4)
    private ByteArray list1;
    @ProtocolField(index = 5)
    private ShortArray list2;
    @ProtocolField(index = 6)
    private IntArray list3;
    @ProtocolField(index = 7)
    private LongArray list4;
    @ProtocolField(index = 8)
    private StringField string1;
    @ProtocolField(index = 9)
    private LargeString string2;
    @ProtocolField(index = 10)
    private TestProtocolItem testItem;
    @ProtocolField(index = 11)
    private LoginInfo loginInfo;
    @ProtocolField(index = 12)
    private BCD<Date> time = new BCD<>(Date.class, "yy-MM-dd HH:mm:ss");
    @ProtocolField(index = 13)
    private BCD<Integer> number = new BCD<>(Integer.class, "XXX");
    @ProtocolField(index = 14)
    private BCD<Float> total = new BCD<>(Float.class, "XXXXX.XX");
    @ProtocolField(index = 15)
    private BCD<Double> money = new BCD<>(Double.class, "XXXXX.XX");
    @ProtocolField(index = 16)
    private FixedString ID = new FixedString(10);
    @ProtocolField(index = 17)
    private LoginInfoArray loginInfos;
    @ProtocolField(index = 18, unsigned = false)
    private short signedShort;
    @ProtocolField(index = 19, unsigned = false)
    private int signedInt;
    @ProtocolField(index = 20, unsigned = false)
    private long signedLong;
}

2.4 自定义协议项和协议项数组

自定义协议项

要想自定义协议项很简单，同样的，只需要继承XProtocolItem或者实现IProtocolItem接口，使用@ProtocolField注解进行配置即可。

【注意】不需要使用@Protocol进行注解。

public class LoginInfo extends XProtocolItem {
    @ProtocolField(index = 0)
    private StringField loginName;

    @ProtocolField(index = 1)
    private StringField password;
}

自定义协议项数组

自定义协议项数组类需要继承AbstractArrayItem，详细的实现案例点击查看

2.5 协议项的byte化和反byte化

凡是继承XProtocolItem或者实现IProtocolItem接口，都将有如下两个方法:

/**
 * 将协议实体转化为byte数组
 *
 * @param storageMode 存储形式
 * @return
 */
byte[] proto2byte(StorageMode storageMode);

/**
 * 将byte数组数据转化为协议实体
 *
 * @param bytes       byte数组数据
 * @param index       起始字节
 * @param tailLength  消息尾的长度[和index一起决定了数据解析的范围]
 * @param storageMode 存储形式
 * @return 是否解析成功
 */
boolean byte2proto(byte[] bytes, int index, int tailLength, StorageMode storageMode);

使用案例如下:

SettingRequest request = new SettingRequest()
        .setFunc1((byte) 0x45)
        .setFunc2((short) 12)
        .setFunc3(2345)
        .setFunc4((long) 1213131233)
        .setList1((byte) 0x23, (byte) 0x45, (byte) 0x56)
        .setList2((short) 11, (short) 22, (short) 33)
        .setList3(111, 222, 333)
        .setList4((long) 1221312, (long) 23123123)
        //长度超过255的话，就溢出了
        .setString1("我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！")
        .setString2("我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！" +
                "我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！" +
                "我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！" +
                "我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！" +
                "我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！" +
                "我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！" +
                "我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！我的名字叫薛翔！")
        .setLoginInfo(new LoginInfo("xuexiang", "123456"))
        .setTime(new Date())
        .setNumber(123)
        .setTotal(12345.67F)
        .setMoney(23456.78)
        .setID("1234567890")
        .setLoginInfos(new LoginInfo("xuexiang1", "222"),
                new LoginInfo("xuexiang23", "3333"),
                new LoginInfo("xuexiang456", "44444"))
        .setTestItem(new TestProtocolItem()
                .setFunc1((byte) 0x56)
                .setFunc2((short) 314)
                .setFunc3(6111)
                .setFunc4((long) 35536234)
                .setList1(314, 334, 34235, 67584, 45234, 6757)
                .setLoginInfo(new LoginInfo("xuexiangjys", "111111")))
        .setSignedShort((short) -678)
        .setSignedInt(-214)
        .setSignedLong(-14523L);
byte[] bytes = request.proto2byte(StorageMode.Default);
Log.e("xuexiang", ConvertUtils.bytesToHexString(bytes));

SettingRequest request1 = new SettingRequest();
request1.byte2proto(bytes, 0, 0, StorageMode.Default);

Log.e("xuexiang", request1.toString());

2.6 消息体包装与解析

实现IMessage接口，可自定义属于自己的协议消息载体。框架中默认提供了XMessage和XOrderlyMessage两种消息体模版。

XMessage: 无序消息体模版，无消息ID，无法检测是否丢包或者包重复。详细实现点击查看
XOrderlyMessage: 有序消息体模版, 可检测是否丢包或者包重复。详细实现点击查看

消息转byte的使用方法

1.新建你需要使用的消息体模版。
2.设置你传输的协议项。
3.使用msg2Byte方法将消息转化为byte数组数据。

byte转消息的使用方法

1.新建你需要转化的消息体模版。
2.使用byte2Msg方法，传入byte数组数据进行转化。

MessageTest messageTest = new MessageTest()
        .setFunc1((byte) 0x45)
        .setFunc2((short) 12)
        .setFunc3(2345)
        .setFunc4((long) 1213131233)
        .setList2((short) 11, (short) 22, (short) 33)
        .setLoginInfo(new LoginInfo("xuexiang", "123456"));

XMessage message = new XMessage()
        .setIProtocolItem(messageTest);
byte[] bytes = message.msg2Byte();
Log.e("xuexiang", ConvertUtils.bytesToHexString(bytes));

XMessage message1 = new XMessage();
boolean result = message1.byte2Msg(bytes);

Log.e("xuexiang", "result:" + result +", ProtocolItem:" + message1.getProtocolItem());

2.7 自定义协议解析器

如果你对协议的解析有特殊的需求，可实现IProtocolParser接口，并通过XTCP.getInstance().setIProtocolParser来替换默认的协议解析器。

【注意】谨慎替换，如果替换方法有误的话，会导致整个框架无法正常使用，建议不要替换。

3、基础内容介绍

协议项注解@Protocol

属性名	类型	默认值	备注
name	String	""	协议的名称
opCode	byte	/(必填）	协议命令码，协议命令的唯一号
resCode	byte	-1	协议响应码（结果对应的命令码）
mode	StorageMode	StorageMode.Default	数据存储方式（大端 or 小端）
desc	String	""	描述信息

协议字段注解@ProtocolField

属性名	类型	默认值	备注
index	int	/(必填）	字段的顺序索引
isField	boolean	true	是否为协议解析字段
length	int	-1	协议字段的长度, 不设置的话，默认自动识别
unsigned	boolean	true	是否是无符号数
mode	StorageMode	StorageMode.Default	数据存储方式（大端 or 小端）
charset	String	"UTF-8"	字符集（只对String有效）

基础数组数据类型

类名	对应的数组类型	数组最大长度
ByteArray	byte[]	255
LargeByteArray	byte[]	65535
IntArray	int[]	255
ShortArray	short[]	255
LongArray	long[]	255
StringField	String	255
LargeString	String	65535

【注意】:框架支持不定长数组，如果你的数组长度不定（没有确定长度的字段），那么你有且只能有这么一个数组可以不使用以上的数组包装类。

4、混淆配置

# xtcp
-keep @com.xuexiang.xtcp.annotation.* class * {*;}
-keep class * {
    @com.xuexiang.xtcp.annotation.* <fields>;
}
-keepclassmembers class * {
    @com.xuexiang.xtcp.annotation.* <methods>;
}

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

xuexiangjys / XTCP

Programming Languages

Labels

Projects that are alternatives of or similar to XTCP