Exgencode.defpdu
defpdu
, go back to Exgencode module for more information.
Specs
defpdu(pdu_name(), [{field_name(), fieldParam()}]) :: any()
This macro allows for the definition of binary PDUs in a simple way allowing for convienient encoding and decoding them between binary format and Elixir structures.
PDUs
Each PDU for the protocol is defined given a name that must be a valid Elixir structure (module) name followed by a list of fields that the given PDU has.
Fields
Each field can have the following options specified:
size
Defines the size of field in bits. If the field is of type :subrecord the :size is unused.
defpdu SomePdu,
someField: [size: 12]
default
Defines the default value that the field should assume when building a new Elixir structure of the given PDU.
defpdu PduWithDefault,
aFieldWithDefault: [size: 10, default: 15]
type
Defines the type of the field. Field can be of type:
:constant
:subrecord
:string
:binary
:float
:integer
:variable
:skip
If no type should is specified it will default to :integer
. Both :integer
and :float
specify normal numerical values and have no special properties.
:constant
If the field is constant it will not become part of the Elixir structure and will not be accessible. However it will still be encoded into the binary representation and the decoding will expect the field to be present and have the given value in the decoded binary. Otherwise FunctionClauseError will be raised. A :constant field MUST have a default value specified.
defpdu PduWithConstant,
aConstantField: [size: 12, default: 10, type: :constant]
iex> Exgencode.Pdu.encode(%TestPdu.PduWithConstant{})
<< 10 :: size(16) >>
iex> %TestPdu.PduWithConstant{}.aConstantField
** (KeyError) key :aConstantField not found in: %Exgencode.TestPdu.PduWithConstant{}
:subrecord
If the field is meant to contain a sub-structure then it should be of type :subrecord. Such field must have either a default value specified that is of the type of the subrecord. Alternatively it must define custom decode and encode functions.
Examples:
defpdu SubPdu,
someField: [size: 10, default: 1]
defpdu TopPdu,
aField: [size: 24],
subPdu: [type: :subrecord, default: %SupPdu{}]
iex> Exgencode.Pdu.encode(%TestPdu.TopPdu{aField: 24})
<< 24 :: size(24), 1 :: size(16) >>
iex> Exgencode.Pdu.decode(%TestPdu.TopPdu{}, << 24 :: size(24), 1 :: size(16) >>)
{%TestPdu.TopPdu{aField: 24, subPdu: %TestPdu.SubPdu{someField: 1}}, <<>>}
:virtual
The virtual fields are never encoded into binaries and exist only in the Elixir structs. When decoding into a struct the virtual field will always assume the default value.
Examples:
defpdu VirtualPdu,
real_field: [size: 16],
virtual_field: [type: :virtual]
iex> Exgencode.Pdu.encode(%TestPdu.VirtualPdu{real_field: 12, virtual_field: "Any value goes here"})
<<12::size(16)>>
iex> Exgencode.Pdu.decode(%TestPdu.VirtualPdu{}, <<12::size(16)>>)
{%TestPdu.VirtualPdu{real_field: 12, virtual_field: nil}, <<>>}
:binary
If the field is an arbitrary binary value it can be specified with this type. In such case the size parameter indicates size in bytes
rather than bits. This type does not define any padding, that is the size of the binary that is contained in this field must be of at least the defined field size,
otherwise an ArgumentError
is raised. If the size is larger the binary will be trimmed.
:variable
Variable fields have no pre-defined size, instead the size is defined by the value of another field. When defining a :variable
field, the
:size
parameter must be set to the name of the field definining the size, which in turn should be an :integer
field. The size in that case
can only be specified in bytes. All :variable
fields are binary fields.
Examples:
defpdu VariablePdu,
some_field: [size: 16],
size_field: [size: 16],
variable_field: [type: :variable, size: :size_field]
iex> Exgencode.Pdu.encode(%TestPdu.VariablePdu{some_field: 52, size_field: 2, variable_field: "AB"})
<<52::size(16), 2::size(16), "A", "B">>
iex> Exgencode.Pdu.decode(%TestPdu.VariablePdu{}, <<52::size(16), 2::size(16), "A", "B">>)
{%TestPdu.VariablePdu{some_field: 52, size_field: 2, variable_field: "AB"}, <<>>}
Note that the field defining the size must be defined before the variable length field.
Examples:
defpdu BinaryMsg,
someHeader: [size: 8, default: 10],
binaryField: [size: 16, type: :binary]
iex> Exgencode.Pdu.encode(%TestPdu.BinaryMsg{binaryField: "16charactershere"})
<< 10 :: size(8), "16charactershere" :: binary>>
:string
The :string
type is similar to :binary
, however it will not raise any errors if the length of the value to be encoded is different than declared field size.
Instead, the string will be trimmed if its too long and padded with trailing 0-bytes if it is too short. Upon decoded all trailing 0-bytes will be removed.
For any other handling of padding or empty bytes custom decode and encode functions must be defined.
Examples:
defpdu StringMsg,
someHeader: [size: 8, default: 10],
stringField: [size: 16, type: :string]
iex> Exgencode.Pdu.encode(%TestPdu.StringMsg{stringField: "16charactershere"})
<< 10 :: size(8), "16charactershere" :: binary>>
iex> Exgencode.Pdu.encode(%TestPdu.StringMsg{stringField: "Too long string for field size"})
<< 10 :: size(8), "Too long string " :: binary>>
iex> Exgencode.Pdu.encode(%TestPdu.StringMsg{stringField: "Too short"})
<< 10 :: size(8), "Too short" :: binary, 0, 0, 0, 0, 0, 0, 0>>
iex> Exgencode.Pdu.decode(%TestPdu.StringMsg{}, << 10 :: size(8), "Too short" :: binary, 0, 0, 0, 0, 0, 0, 0>>)
{%TestPdu.StringMsg{stringField: "Too short"}, <<>>}
:skip
If the field will never be decoded into the struct. It's value will be set to :default
when encoding the struct.
defpdu SkippedPdu,
testField: [default: 1, size: 16],
skippedField: [size: 8, default: 5, type: :skip]
iex> Exgencode.Pdu.encode(%TestPdu.SkippedPdu{testField: 15})
<< 15 :: size(16), 5 :: size(8) >>
iex> %TestPdu.SkippedPdu{}.skippedField
** (KeyError) key :skippedField not found in: %Exgencode.TestPdu.SkippedPdu{testField: 1}
iex> Exgencode.Pdu.decode(%TestPdu.SkippedPdu{}, << 32 :: size(16), 11 :: size (8)>>)
{%TestPdu.SkippedPdu{testField: 32}, <<>>}
encode/decode
Defines a custom encode or decode function. See type specifications for the function specification. If a PDU has a custom encode function defined it must also define a custom decode function. Custom encode and decode functions can override any of the other parameters the field has if the user wishes it so.
Examples:
defpdu CustomPdu,
normalField: [size: 16, default: 3],
customField: [encode: fn(val) -> << val * 2 :: size(12) >> end,
decode: fn(pdu, << val :: size(12) >>) -> {struct(pdu, %{customField: div(val, 2)}), <<>>} end]
iex> Exgencode.Pdu.encode(%TestPdu.CustomPdu{customField: 10})
<< 3 :: size(16), 20 :: size(16) >>
iex> Exgencode.Pdu.decode(%TestPdu.CustomPdu{}, << 3 :: size(16), 20 :: size(16) >>)
{%TestPdu.CustomPdu{customField: 10}, <<>>}
version
Defines the requirement for the protocol version for the given field to be included in the message. When a version is specified encode/2
and decode/3
can take
an optional parameter with the given version name. If the given version matches the version requirement defined by this option in the PDU definition, the field will
be included. Otherwise it will be skipped.
defpdu VersionedMsg,
oldField: [default: 10, size: 16],
newerField: [size: 8, version: ">= 2.0.0"],
See documentation for Exgencode.Pdu./2
for examples.
endianness
Defines the endianness of the particular field. Allowed options are :big
, :little
and :native
. Defaults to :big
Examples:
defpdu EndianMsg,
bigField: [default: 15, size: 32, endianness: :big],
smallField: [default: 15, size: 32, endianness: :little]
iex> Exgencode.Pdu.encode(%TestPdu.EndianMsg{})
<< 15 :: big-size(32), 15 :: little-size(32)>>
conditional
Defines that the field is present in encoded binary format only if another field has a non-null value.
Examples:
defpdu ConditionalPdu,
normal_field: [size: 16],
flag_field: [size: 8],
conditional_field: [size: 8, conditional: :flag_field],
another_normal_field: [size: 8],
second_flag: [size: 8],
size_field: [size: 16, conditional: :second_flag],
conditional_variable_field: [type: :variable, size: :size_field, conditional: :second_flag]
iex> Exgencode.Pdu.encode(%TestPdu.ConditionalPdu{
...> normal_field: 12,
...> flag_field: 1,
...> conditional_field: 10,
...> another_normal_field: 200,
...> second_flag: 1,
...> size_field: 4,
...> conditional_variable_field: "test"
...> })
<<12::size(16), 1, 10, 200, 1, 4::size(16), "test">>
iex> Exgencode.Pdu.encode(%TestPdu.ConditionalPdu{
...> normal_field: 12,
...> flag_field: 1,
...> conditional_field: 10,
...> another_normal_field: 200,
...> second_flag: 0,
...> size_field: nil,
...> conditional_variable_field: nil
...> })
<<12::size(16), 1, 10, 200, 0>>
offset_to
Defines that the field contains the offset to another field. The offset is in bytes since the
beginning of the PDU. Note that offsets are automatically calculated when calling Exgencode.Pdu.encode/2
Examples:
defpdu OffsetPdu,
offset_to_field_a: [size: 16, offset_to: :field_a],
offset_to_field_b: [size: 16, offset_to: :field_b],
offset_to_field_c: [size: 16, offset_to: :field_c],
field_a: [size: 8],
size_field: [size: 16],
variable_field: [type: :variable, size: :size_field],
field_b: [size: 8],
field_c: [size: 8, conditional: :offset_to_field_c]
iex> Exgencode.Pdu.encode(%TestPdu.OffsetPdu{
...> field_a: 14,
...> size_field: 4,
...> variable_field: "test",
...> field_b: 15,
...> field_c: 20
...> })
<<6::size(16), 9 + 4::size(16),10 + 4::size(16), 14, 4::size(16)>> <> "test" <> <<15, 20>>
iex> Exgencode.Pdu.encode(%TestPdu.OffsetPdu{
...> field_a: 14,
...> size_field: 4,
...> variable_field: "test",
...> field_b: 15,
...> field_c: nil
...> })
<<6::size(16), 9 + 4::size(16), 0::size(16), 14, 4::size(16)>> <> "test" <> <<15>>