This package allows for simple definition of binary-based protocols together with an Elixir protocol that allows for simple transforming of binary packages into Elixir structures and vice versa.
The protocols are defined by creating a module for each protocole and utilising the PDU definitions to define all messages the protocol needs. See the following sections for more.
The package is available in Hex and can be installed
by adding exgencode to your list of dependencies in mix.exs:
def deps do
[
{:exgencode, "~> 1.0.0"}
]
endDocumentation can be generated with ExDoc. The documentation can also be found at https://hexdocs.pm/exgencode.
Protocol messages can be defined using the defpdu macro. Each message is defined with its name and a list of message fields
and their options. Each field should define the size (given in bits) for the particular and can define a default value. For example:
defpdu ExamplePdu,
firstField: [size: 10],
fieldWithADefault: [size: 14, default: 5]Once defined the code can use the messages as structure e.g. %ExamplePdu{firstField: 5}
Messages can also be nested within other messages. In that case the field must by of type :subrecord and must define the default
which indicates which what type of sub-structure should the field contain.
defpdu SubPdu,
someField: [size: 8, default: 1]
defpdu MainPdu,
section: [size: 16]
subSection: [type: :subrecord, default: %SubPdu{}]Alternatively each field may define custom encoding and decoding functions:
defpdu CustomPdu,
normalField: [size: 16, default: 3]
customField: [encode: fn(val) -> << val :: size(16) >> end,
decode: fn(pdu, << val :: size(16) >>) -> {struct(pdu, :customField => val), <<>>} end]With custom functions other parameters can be omitted.
It is reccommended to place all messages for a given interface in one module.
defmodule MyProtocol do
defpdu HelloMsg,
userId: [size: 256]
defpdu ByeMsg,
userId: [size: 256]
endPlease note that the total size of your PDU must be in full bytes, that is its total size in bits must be divisible by 8.
exgencode also provides the Exgencode.Pdu.Protocol protocol that each pdu defined with defpdu will automatically implement. The Exgencode.Pdu module can be used
to transform between binary and structures.
defpdu MsgSubSection,
someField: [default: 15, size: 8]
defpdu PzTestMsg,
testField: [default: 1, size: 12],
otherTestField: [size: 24],
subSection: [default: %MsgSubSection{}, type: :subrecord],
constField: [default: 10, size: 24, type: :constant]
test "encoding" do
pdu = %TestPdu.PzTestMsg{otherTestField: 100}
assert << 1 :: size(12), 100 :: size(24), 15 :: size(8), 10 :: size(24)>> == Exgencode.Pdu.encode(pdu)
end
test "decoding" do
pdu = %TestPdu.PzTestMsg{otherTestField: 100}
binary = << 1 :: size(12), 100 :: size(24), 15 :: size(8), 10 :: size(24)>>
assert {^pdu, <<>>} = Exgencode.Pdu.decode(%TestPdu.PzTestMsg{}, binary)
endThe fields can also be versioned allowing for specifications of versions of the protocol defined by the defpdu blocks. Both encode/2 and decode/3 can take the
version number that are meant to be used to encode or decode. This allows the protocol to easily operate in backwards compatibility.
test "versioning encode" do
pdu = %TestPdu.VersionedMsg{newerField: 111, evenNewerField: 7}
assert << 10 :: size(16), 111 :: size(8), 14 :: size(8) >> == Exgencode.Pdu.encode(pdu)
assert << 10 :: size(16) >> == Exgencode.Pdu.encode(pdu, "1.0.0")
assert << 10 :: size(16), 111 :: size(8) >> == Exgencode.Pdu.encode(pdu, "2.0.0")
assert << 10 :: size(16), 111 :: size(8), 14 :: size(8) >> == Exgencode.Pdu.encode(pdu, "2.1.0")
end
test "versioning decode" do
pdu = %TestPdu.VersionedMsg{}
binary = << 10 :: size(16) >>
assert {^pdu, <<>>} = Exgencode.Pdu.decode(%TestPdu.VersionedMsg{}, binary, "1.0.0")
pdu = %TestPdu.VersionedMsg{newerField: 111}
binary = << 10 :: size(16), 111 :: size(8) >>
assert {^pdu, <<>>} = Exgencode.Pdu.decode(%TestPdu.VersionedMsg{}, binary, "2.0.0")
pdu = %TestPdu.VersionedMsg{newerField: 111, evenNewerField: 7}
binary = << 10 :: size(16), 111 :: size(8), 14 :: size(8) >>
assert {^pdu, <<>>} = Exgencode.Pdu.decode(%TestPdu.VersionedMsg{}, binary)
assert {^pdu, <<>>} = Exgencode.Pdu.decode(%TestPdu.VersionedMsg{}, binary, "2.1.0")
assert {%TestPdu.VersionedMsg{}, << 111 :: size(8), 14 :: size(8) >>} = Exgencode.Pdu.decode(%TestPdu.VersionedMsg{}, binary, "1.0.0")
endSee the documentation for details.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent