The LwDFX protocol describes a lightweight data frame exchange protocol used for transmitting data frames. It provides connection based duplex transmissions. The design purpose of this protocol is to allow both communicating parties to easily parse and construct the data structures to be transmitted.
-
Message Frame
A frame is the basic unit of a connection that carries pieces of data. Each frame includes a header and a body, where the header is a fixed-length binary chunk in all frames, and the body is a variable-length binary chunk in different frames.
The frame is not the same as the TCP frame. The frame is a logical unit of the connection, while the TCP frame is a physical unit of the TCP protocol.
First of all, the frame is a binary chunk, which is composed of a header and a body payload, where the header is a fixed-length binary chunk and the body is a variable-length binary chunk. All data fields are in the little-endian format.
All data structure below are described in C language, but there is no memory alignment required in the LwDFX protocol. So these structure are always compacted, which means these data structure are actually aligned to 1 byte.
In LwDFX protocol, there are 3 types of frames:
The CLIENT_HELLO
frame is used to initiate a stream. It is a binary chunk, used to negotiate the version of the stream.
typedef struct {
/**
* The byte-length of content.
*/
uint8_t cByteLength;
/**
* Byte string, without null-terminator.
*/
uint8_t content[];
} var_string_t;
struct lwdfxHelloFrame {
uint32_t dwByteLength;
uint32_t dwMagic;
uint8_t cVersionQty;
uint8_t aVersionList[];
uint8_t cAlpQty;
var_string_t aAlpList[];
};
Here are the explanations of the fields:
-
dwByteLength
The byte-length of the rest fields. It is a 32-bit unsigned integer.
-
dwMagic
The magic number of the
HELLO
frame. It is a 32-bit unsigned integer. It must be0x5442774c
. -
cVersionQty
The quantity of the LwDFX protocol versions that the client-side can apply to. It is a 8-bit unsigned integer.
-
aVersionList
The list of the LwDFX protocol versions that the client-side can apply to. It is an array of 8-bit unsigned integer.
-
cAlpQty
The number of application-layer protocols that the client-side preferring. It is a 8-bit unsigned integer.
-
aAlpList
The identities of application-layer protocols to be transported insides LwDFXv1, that the client-side preferring. It is a variable-length byte string.
The
aAlpList
field is a variable-length byte string, which is composed of severalvar_string_t
structures. Eachvar_string_t
structure is a variable-length byte string, which is composed of acByteLength
field and acontent
field.Here are the explanations of the fields:
-
cByteLength
The byte-length of the
content
field. It is a 8-bit unsigned integer. -
content
The content of the
var_string_t
structure. It is a variable-length byte string.The
content
field is not null-terminated.
-
The SERVER_HELLO
frame is used to response the CLIENT_HELLO
frame. It is a binary chunk.
struct lwdfxHiFrame {
uint32_t dwByteLength;
uint32_t dwMagic;
uint32_t dwMaxFrameSize;
uint8_t cVersion;
var_string_t sAlp;
};
Here are the explanations of the fields:
-
dwByteLength
The byte-length of the rest fields. It is a 32-bit unsigned integer.
-
dwMagic
The magic number of the
HI
frame. It is a 32-bit unsigned integer. It must be0x5442774d
. -
dwMaxFrameSize
The maximum byte-length of each frame that the server-side would accept or send. It is a 32-bit unsigned integer.
If the client-side sends a frame whose byte-length is greater than
dwMaxFrameSize
, the server-side should close the connection. -
cVersion
The version of the LwDFX protocol that the server-side applied to. It is a 8-bit unsigned integer.
If server accepts the client's version, it must be the a version in client-sent
aVersionList
.Otherwise, it must be
0xFF
. And then server must close the connection. -
sAlp
The identity of application-layer protocol that the server-side selected. It is a variable-length byte string.
The
sAlp
field is a variable-length byte string, which is composed of avar_string_t
structure.
The DATA
frame is used to transmit data.
It's recommended that the
DATA
frame should be sent after theSERVER_HELLO
frame is replied. However, there is no effect even if sendingDATA
frame immediately after sendingCLIENT_HELLO
frame, because the server side will reject if protocol handshake failed, and then close the connection, so that the sentDATA
frame will be dropped.
struct lwdfxDataFrame {
uint32_t dwMagic;
uint32_t dwMessageLength;
uint8_t aMessageBody[];
};
Here are the explanations of the fields:
-
dwMagic
The magic of data frame, to ensure data transported correctly. The value of
dwMagic
should be always0x86989330
. -
dwMessageLength
The length of the message body, in bytes. It is a 32-bit unsigned integer.
If a
DATA
frame whosedwMessageLength
equal to0
is received, it means the end of the stream, both communicating parties must close the connection. -
aMessageBody
The message body of the frame. It is a variable-length binary chunk.