exgencode v1.0.0 Exgencode
Documentation for Exgencode.
Link to this section Summary
Types
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
Name of the field
Parameters of the given 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
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.
Name of the field.
fieldParam :: {:size, non_neg_integer} | {:type, fieldType} | {:encode, fieldEncodeFun} | {:decode, fieldDecodeFun} | {:version, Version.requirement}
Parameters of the given field
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(pduName, [{fieldName, fieldParam}]) :: none
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 or :subrecord types. If the field is meant to be a normal numerical value no type should be specified.
: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]
: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.
defpdu SubPdu,
someField: [size: 10, default: 1]
defpdu TopPdu,
aField: [size: 24],
subPdu: [type: :subrecord, default: %SupPud{}]
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.
defpdu CustomPdu,
normalField: [size: 16, default: 3],
customField: [encode: fn(val) -> << val :: size(12) >> end,
decode: fn(pdu, << val :: size(12) >>) -> {struct(pdu, :customField => val), <<>>} end]
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"],