exgencode v1.2.0 Exgencode
Documentation for Exgencode.
Link to this section Summary
Types
Parameters of the given field
A custom decoding function that receives the PDU decoded so far and remaining binary and is meant to return PDU with the field decoded and remaining binary
A custom encoding function that is meant to take the value of the field and return its binary represantion
The endianness the field should be encoded/decoded with
Name of the field
The type of the field
A PDU, that is an Elixir structure representing a PDU
PDU name, must be a structure name
Functions
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
Link to this section Types
fieldParam() :: {:size, non_neg_integer()} | {:type, field_type()} | {:encode, field_encode_fun()} | {:decode, field_decode_fun()} | {:version, Version.requirement()} | {:endianness, field_endianness()}
Parameters of the given field
A custom decoding function that receives the PDU decoded so far and remaining binary and is meant to return PDU with the field decoded and remaining binary.
A custom encoding function that is meant to take the value of the field and return its binary represantion.
The endianness the field should be encoded/decoded with
Name of the field.
field_type() :: :subrecord | :constant | :string | :binary | :float | :integer
The type of the field.
A PDU, that is an Elixir structure representing a PDU.
PDU name, must be a structure name
Link to this section Functions
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 :constant
, :subrecord
, :string
, :binary
, :float
and :integer
types.
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}}, <<>>}
: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.
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"}, <<>>}
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)>>