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

Link to this type fieldDecodeFun()
fieldDecodeFun() :: (pdu, bitstring -> {pdu, bitstring})

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.

Link to this type fieldEncodeFun()
fieldEncodeFun() :: (term -> bitstring)

A custom encoding function that is meant to take the value of the field and return its binary represantion.

Link to this type fieldName()
fieldName() :: atom

Name of the field.

Link to this type fieldParam()
fieldParam ::
  {:size, non_neg_integer} |
  {:type, fieldType} |
  {:encode, fieldEncodeFun} |
  {:decode, fieldDecodeFun} |
  {:version, Version.requirement}

Parameters of the given field

Link to this type fieldType()
fieldType() :: :subrecord | :constant

The type of the field.

Link to this type pdu()
pdu() :: %{}

A PDU, that is an Elixir structure representing a PDU.

Link to this type pduName()
pduName() :: module

PDU name, must be a structure name

Link to this section Functions

Link to this macro defpdu(name, originalFieldList) (macro)
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"],