Merge pull request #219 from aceld/translate_english

translate english

Author: aceld

zdecoder/htlvcrcdecoder.go

@@ -104,7 +104,7 @@ func (hcd *HtlvCrcDecoder) decode(data []byte) *HtlvCrcDecoder {
 
 	// CRC
 	if !CheckCRC(data[:datasize-2], htlvData.Crc) {
-		zlog.Ins().DebugF("crc校验失败 %s %s\n", hex.EncodeToString(data), hex.EncodeToString(htlvData.Crc))
+		zlog.Ins().DebugF("crc check error %s %s\n", hex.EncodeToString(data), hex.EncodeToString(htlvData.Crc))
 		return nil
 	}
 
@@ -118,25 +118,28 @@ func (hcd *HtlvCrcDecoder) Intercept(chain ziface.IChain) ziface.IcResp {
 	//1. Get the IMessage of zinx
 	iMessage := chain.GetIMessage()
 	if iMessage == nil {
-		//进入责任链下一层
+		// Go to the next layer in the chain of responsibility
 		return chain.ProceedWithIMessage(iMessage, nil)
 	}
 
 	//2. Get Data
 	data := iMessage.GetData()
 	//zlog.Ins().DebugF("HTLVCRC-RawData size:%d data:%s\n", len(data), hex.EncodeToString(data))
 
-	//3. 读取的数据不超过包头，直接进入下一层
+	//3. If the amount of data read is less than the length of the header, proceed to the next layer directly.
+	// (读取的数据不超过包头，直接进入下一层)
 	if len(data) < HEADER_SIZE {
 		return chain.ProceedWithIMessage(iMessage, nil)
 	}
 
 	//4. HTLV+CRC Decode
 	htlvData := hcd.decode(data)
 
-	//5. 将解码后的数据重新设置到IMessage中, Zinx的Router需要MsgID来寻址
+	//5. Set the decoded data back to the IMessage, the Zinx Router needs MsgID for addressing
+	// (将解码后的数据重新设置到IMessage中, Zinx的Router需要MsgID来寻址)
 	iMessage.SetMsgID(uint32(htlvData.Funcode))
 
-	//6. 将解码后的数据进入下一层
+	//6. Pass the decoded data to the next layer.
+	// (将解码后的数据进入下一层)
 	return chain.ProceedWithIMessage(iMessage, *htlvData)
 }

zdecoder/ltvdecoder_little.go

@@ -1,3 +1,29 @@
+// LTV, which stands for Length-Tag(Type)-Value, is a simple and practical data transmission scheme.
+// In the definition of LTV, there are three fields: Tag field, Length field, and Value field.
+// The value of the Length field is actually the length of the Value field.
+//
+// Before decoding (20 bytes) After decoding (20 bytes)
+//+------------+------------+-----------------+      +------------+------------+-----------------+
+//| Length     |        Tag | Value           |----->| Length     | Tag        | Value           |
+//| 0x0000000C | 0x00000001 | "HELLO, WORLD"  |      | 0x0000000C | 0x00000001 | "HELLO, WORLD"  |
+//+------------+------------+-----------------+      +------------+------------+-----------------+
+// Length: uint32 type, 4 bytes, indicating the length of Value is 12 (hex: 0x0000000C).
+// Tag: uint32 type, 4 bytes, serves as MsgId, temporarily set to 1.
+// Value: 12 characters in total, 12 bytes in length.
+//
+// Explanation:
+// lengthFieldOffset = 0 (The index of Length byte is 0) Length field offset.
+// lengthFieldLength = 4 (Length takes up 4 bytes) Length field length.
+// lengthAdjustment = 4 (Length only represents the length of Value. The program will only read Length bytes and end.
+//                       If there is a crc of 2 bytes after Value, then it is 2 here. If Length represents the total
+//                       length of Tag+Length+Value, then it is -8 here.)
+// initialBytesToStrip = 0 (0 means returning the complete protocol content Tag+Length+Value. If you only want to
+//                          return the Value content and remove the 4 bytes of Tag and 4 bytes of Length, it is 8 here.)
+//                          The number of bytes removed from the decoded frame for the first time.
+// maxFrameLength = 2^32 + 4 + 4 (Since Length is of uint type, 2^32 represents the maximum length of Value.
+//                                In addition, Tag and Length each take up 4 bytes.)
+
+// [简体中文]
 // LTV，即Length-Tag(Type)-Value，是一种简单实用的数据传输方案。
 //在LTV的定义中，可以知道它包括三个域，分别为：标签域（Tag），长度域（Length），内容域（Value）。这里的长度域的值实际上就是内容域的长度。
 //
@@ -13,8 +39,11 @@
 //   说明：
 //   lengthFieldOffset   = 0            (Length的字节位索引下标是0) 长度字段的偏差
 //   lengthFieldLength   = 4            (Length是4个byte) 长度字段占的字节数
-//   lengthAdjustment    = 4            (Length只表示Value长度，程序只会读取Length个字节就结束，后面没有来，故为0，若Value后面还有crc占2字节的话，那么此处就是2。若Length标记的是Tag+Length+Value总长度，那么此处是-8)
-//   initialBytesToStrip = 0            (这个0表示返回完整的协议内容Tag+Length+Value，如果只想返回Value内容，去掉Tag的4字节和Length的4字节，此处就是8) 从解码帧中第一次去除的字节数
+//   lengthAdjustment    = 4            (Length只表示Value长度，程序只会读取Length个字节就结束，后面没有来，故为0，
+//                                        若Value后面还有crc占2字节的话，那么此处就是2。若Length标记的是Tag+Length+Value总长度，
+//                                        那么此处是-8)
+//   initialBytesToStrip = 0            (这个0表示返回完整的协议内容Tag+Length+Value，如果只想返回Value内容，去掉Tag的4字节和Length
+//                                        的4字节，此处就是8) 从解码帧中第一次去除的字节数
 //   maxFrameLength      = 2^32 + 4 + 4 (Length为uint类型，故2^32次方表示Value最大长度，此外Tag和Length各占4字节)
 
 package zdecoder
@@ -29,9 +58,9 @@ import (
 const LTV_HEADER_SIZE = 8 //表示TLV空包长度
 
 type LTV_Little_Decoder struct {
-	Length uint32 //消息长度
-	Tag    uint32 //消息类型
-	Value  []byte //消息内容
+	Length uint32 //L
+	Tag    uint32 //T
+	Value  []byte //V
 }
 
 func NewLTV_Little_Decoder() ziface.IDecoder {
@@ -66,45 +95,47 @@ func (ltv *LTV_Little_Decoder) GetLengthField() *ziface.LengthField {
 func (ltv *LTV_Little_Decoder) decode(data []byte) *LTV_Little_Decoder {
 	ltvData := LTV_Little_Decoder{}
 
-	//获取L
+	//Get L
 	ltvData.Length = binary.LittleEndian.Uint32(data[0:4])
-	//获取T
+	//Get T
 	ltvData.Tag = binary.LittleEndian.Uint32(data[4:8])
-	//确定V的长度
+	//Determine the length of V. (确定V的长度)
 	ltvData.Value = make([]byte, ltvData.Length)
 
-	//5. 获取V
+	//5. Get V
 	binary.Read(bytes.NewBuffer(data[8:8+ltvData.Length]), binary.LittleEndian, ltvData.Value)
 
 	return &ltvData
 }
 
 func (ltv *LTV_Little_Decoder) Intercept(chain ziface.IChain) ziface.IcResp {
-	//1.获取zinx的IMessage
+	//1. Get the IMessage of zinx
 	iMessage := chain.GetIMessage()
 	if iMessage == nil {
-		//进入责任链下一层
+		// Go to the next layer in the chain of responsibility
 		return chain.ProceedWithIMessage(iMessage, nil)
 	}
 
-	//2. 获取数据
+	//2. Get Data
 	data := iMessage.GetData()
 	//zlog.Ins().DebugF("LTV-RawData size:%d data:%s\n", len(data), hex.EncodeToString(data))
 
-	//3. 读取的数据不超过包头，直接进入下一层
+	//3. If the amount of data read is less than the length of the header, proceed to the next layer directly.
+	// (读取的数据不超过包头，直接进入下一层)
 	if len(data) < LTV_HEADER_SIZE {
-		//进入责任链下一层
 		return chain.ProceedWithIMessage(iMessage, nil)
 	}
 
-	//4. ltv解码
+	//4. LTV Decode
 	ltvData := ltv.decode(data)
 
-	//5. 将解码后的数据重新设置到IMessage中, Zinx的Router需要MsgID来寻址
+	//5. Set the decoded data back to the IMessage, the Zinx Router needs MsgID for addressing
+	// (将解码后的数据重新设置到IMessage中, Zinx的Router需要MsgID来寻址)
 	iMessage.SetDataLen(ltvData.Length)
 	iMessage.SetMsgID(ltvData.Tag)
 	iMessage.SetData(ltvData.Value)
 
-	//6. 将解码后的数据进入下一层
+	//6. Pass the decoded data to the next layer.
+	// (将解码后的数据进入下一层)
 	return chain.ProceedWithIMessage(iMessage, *ltvData)
 }

zdecoder/tlvdecoder.go

@@ -1,3 +1,30 @@
+// TLV, which stands for Tag(Type)-Length-Value, is a simple and practical data transmission scheme.
+// In the definition of TLV, it can be seen that it consists of three fields: the tag field (Tag), the length
+// field (Length), and the value field (Value).
+// The value of the length field is actually the length of the content field.
+//
+// Before decoding (20 bytes) After decoding (20 bytes)
+// +------------+------------+-----------------+       +------------+------------+-----------------+
+// | Tag        | Length     | Value           |-----> | Tag        | Length     | Value           |
+// | 0x00000001 | 0x0000000C | "HELLO, WORLD"  |       | 0x00000001 | 0x0000000C | "HELLO, WORLD"  |
+// +------------+------------+-----------------+       +------------+------------+-----------------+
+// Tag: uint32 type, occupies 4 bytes, Tag is set as MsgId, temporarily set to 1
+// Length: uint32 type, occupies 4 bytes, Length marks the length of Value, which is 12(hex:0x0000000C)
+// Value: 12 characters in total, occupies 12 bytes
+//
+// Explanation:
+// lengthFieldOffset = 4 (The byte index of Length is 4) Length field offset
+// lengthFieldLength = 4 (Length is 4 bytes) Length field length in bytes
+// lengthAdjustment = 0 (Length only represents the length of Value. The program will read only Length bytes and end.
+// 	                     If there is a crc of 2 bytes after Value, then this is 2. If Length marks the total length of
+//	                     Tag+Length+Value, then this is -8)
+// initialBytesToStrip = 0 (This 0 means that the complete protocol content Tag+Length+Value is returned. If you only
+//                          want to return the Value content, remove the 4 bytes of Tag and 4 bytes of Length, and
+//                          this is 8) Number of bytes to strip from the decoded frame
+// maxFrameLength = 2^32 + 4 + 4 (Since Length is of uint type, 2^32 represents the maximum length of Value. In addition,
+//                                Tag and Length each occupy 4 bytes.)
+
+// [简体中文]
 // TLV，即Tag(Type)—Length—Value，是一种简单实用的数据传输方案。
 //在TLV的定义中，可以知道它包括三个域，分别为：标签域（Tag），长度域（Length），内容域（Value）。这里的长度域的值实际上就是内容域的长度。
 //
@@ -13,8 +40,11 @@
 //   说明：
 //   lengthFieldOffset   = 4            (Length的字节位索引下标是4) 长度字段的偏差
 //   lengthFieldLength   = 4            (Length是4个byte) 长度字段占的字节数
-//   lengthAdjustment    = 0            (Length只表示Value长度，程序只会读取Length个字节就结束，后面没有来，故为0，若Value后面还有crc占2字节的话，那么此处就是2。若Length标记的是Tag+Length+Value总长度，那么此处是-8)
-//   initialBytesToStrip = 0            (这个0表示返回完整的协议内容Tag+Length+Value，如果只想返回Value内容，去掉Tag的4字节和Length的4字节，此处就是8) 从解码帧中第一次去除的字节数
+//   lengthAdjustment    = 0            (Length只表示Value长度，程序只会读取Length个字节就结束，后面没有来，故为0，
+//                                       若Value后面还有crc占2字节的话，那么此处就是2。若Length标记的是Tag+Length+Value总长度，
+//                                       那么此处是-8)
+//   initialBytesToStrip = 0            (这个0表示返回完整的协议内容Tag+Length+Value，如果只想返回Value内容，去掉Tag的4字节和Length
+//                                       的4字节，此处就是8) 从解码帧中第一次去除的字节数
 //   maxFrameLength      = 2^32 + 4 + 4 (Length为uint类型，故2^32次方表示Value最大长度，此外Tag和Length各占4字节)
 
 package zdecoder
@@ -29,9 +59,9 @@ import (
 const TLV_HEADER_SIZE = 8 //表示TLV空包长度
 
 type TLVDecoder struct {
-	Tag    uint32 //消息类型
-	Length uint32 //消息长度
-	Value  []byte //消息内容
+	Tag    uint32 //T
+	Length uint32 //L
+	Value  []byte //V
 }
 
 func NewTLVDecoder() ziface.IDecoder {
@@ -65,14 +95,14 @@ func (tlv *TLVDecoder) GetLengthField() *ziface.LengthField {
 
 func (tlv *TLVDecoder) decode(data []byte) *TLVDecoder {
 	tlvData := TLVDecoder{}
-	//获取T
+	//Get T
 	tlvData.Tag = binary.BigEndian.Uint32(data[0:4])
-	//获取L
+	//Get L
 	tlvData.Length = binary.BigEndian.Uint32(data[4:8])
-	//确定V的长度
+	//Determine the length of V. (确定V的长度)
 	tlvData.Value = make([]byte, tlvData.Length)
 
-	//5.获取V
+	//Get V
 	binary.Read(bytes.NewBuffer(data[8:8+tlvData.Length]), binary.BigEndian, tlvData.Value)
 
 	//zlog.Ins().DebugF("TLV-DecodeData size:%d data:%+v\n", unsafe.Sizeof(data), tlvData)
@@ -81,30 +111,33 @@ func (tlv *TLVDecoder) decode(data []byte) *TLVDecoder {
 
 func (tlv *TLVDecoder) Intercept(chain ziface.IChain) ziface.IcResp {
 
-	//1. 获取zinx的IMessage
+	//1. Get the IMessage of zinx
 	iMessage := chain.GetIMessage()
 	if iMessage == nil {
-		//进入责任链下一层
+		// Go to the next layer in the chain of responsibility
 		return chain.ProceedWithIMessage(iMessage, nil)
 	}
 
-	//2. 获取数据
+	//2. Get Data
 	data := iMessage.GetData()
 	//zlog.Ins().DebugF("TLV-RawData size:%d data:%s\n", len(data), hex.EncodeToString(data))
 
-	//3. 读取的数据不超过包头，直接进入下一层
+	//3. If the amount of data read is less than the length of the header, proceed to the next layer directly.
+	// (读取的数据不超过包头，直接进入下一层)
 	if len(data) < TLV_HEADER_SIZE {
 		return chain.ProceedWithIMessage(iMessage, nil)
 	}
 
-	//4. TLV解码
+	//4. TLV Decode
 	tlvData := tlv.decode(data)
 
-	//5. 将解码后的数据重新设置到IMessage中, Zinx的Router需要MsgID来寻址
+	//5. Set the decoded data back to the IMessage, the Zinx Router needs MsgID for addressing
+	// (将解码后的数据重新设置到IMessage中, Zinx的Router需要MsgID来寻址)
 	iMessage.SetMsgID(tlvData.Tag)
 	iMessage.SetData(tlvData.Value)
 	iMessage.SetDataLen(tlvData.Length)
 
-	//6. 将解码后的数据进入下一层
+	//6. Pass the decoded data to the next layer.
+	// (将解码后的数据进入下一层)
 	return chain.ProceedWithIMessage(iMessage, *tlvData)
 }

ziface/iclient.go

@@ -1,5 +1,5 @@
 // @Title  iclient.go
-// @Description  提供Client抽象层全部接口声明
+// @Description  Provides all interface declarations for the Client abstraction layer.
 // @Author  Aceld - 2023-2-28
 package ziface
 
@@ -11,19 +11,58 @@ type IClient interface {
 	Stop()
 	AddRouter(msgID uint32, router IRouter)
 	Conn() IConnection
-	SetOnConnStart(func(IConnection))                         //设置该Client的连接创建时Hook函数
-	SetOnConnStop(func(IConnection))                          //设置该Client的连接断开时的Hook函数
-	GetOnConnStart() func(IConnection)                        //获取该Client的连接创建时Hook函数
-	GetOnConnStop() func(IConnection)                         //设置该Client的连接断开时的Hook函数
-	GetPacket() IDataPack                                     //获取Client绑定的数据协议封包方式
-	SetPacket(IDataPack)                                      //设置Client绑定的数据协议封包方式
-	GetMsgHandler() IMsgHandle                                //获取Client绑定的消息处理模块
-	StartHeartBeat(time.Duration)                             //启动心跳检测
-	StartHeartBeatWithOption(time.Duration, *HeartBeatOption) //启动心跳检测(自定义回调)
+
+	// SetOnConnStart Set the Hook function to be called when a connection is created for this Client
+	// (设置该Client的连接创建时Hook函数)
+	SetOnConnStart(func(IConnection))
+
+	// SetOnConnStop Set the Hook function to be called when a connection is closed for this Client
+	// (设置该Client的连接断开时的Hook函数)
+	SetOnConnStop(func(IConnection))
+
+	// GetOnConnStart Get the Hook function that is called when a connection is created for this Client
+	// (获取该Client的连接创建时Hook函数)
+	GetOnConnStart() func(IConnection)
+
+	// GetOnConnStop Get the Hook function that is called when a connection is closed for this Client
+	// (设置该Client的连接断开时的Hook函数)
+	GetOnConnStop() func(IConnection)
+
+	// GetPacket Get the data protocol packet binding method for this Client
+	// (获取Client绑定的数据协议封包方式)
+	GetPacket() IDataPack
+
+	// SetPacket Set the data protocol packet binding method for this Client
+	// (设置Client绑定的数据协议封包方式)
+	SetPacket(IDataPack)
+
+	// GetMsgHandler Get the message handling module bound to this Client
+	// (获取Client绑定的消息处理模块)
+	GetMsgHandler() IMsgHandle
+
+	// StartHeartBeat Start heartbeat detection(启动心跳检测)
+	StartHeartBeat(time.Duration)
+
+	// StartHeartBeatWithOption Start heartbeat detection with custom callbacks 启动心跳检测(自定义回调)
+	StartHeartBeatWithOption(time.Duration, *HeartBeatOption)
+
+	// GetLengthField Get the length field of this Client
 	GetLengthField() *LengthField
+
+	// SetDecoder Set the decoder for this Client 设置解码器
 	SetDecoder(IDecoder)
+
+	// AddInterceptor Add an interceptor for this Client 添加拦截器
 	AddInterceptor(IInterceptor)
-	GetErrChan() chan error // 获取客户端错误管道
+
+	// Get the error channel for this Client 获取客户端错误管道
+	GetErrChan() chan error
+
+	// Set the name of this Clien
+	// 设置客户端Client名称
 	SetName(string)
+
+	// Get the name of this Client
+	// 获取客户端Client名称
 	GetName() string
 }