list Field
Last updated
Was this helpful?
Last updated
Was this helpful?
This field stores and abstracts away a list of other fields. The <list> field has all the properties as well as extra properties and elements described below.
Every <list> must specify its element . The element field can be defined as XML child of the <list> definition.
If a list element contains multiple fields, they must be bundled as members of the field.
In case other properties of the <list> field are defined as child XML elements, then the element field definition needs to be wrapped by <element> XML child.
Most protocols prefix the variable length lists with number of elements that are going to follow, use countPrefix child XML element to specify a field that is going to be used as such prefix.
The code generator is expected to take the existence of such detached prefix into account and generate correct code for various field operations (read, write, etc...).
NOTE, that count, countPrefix and lengthPrefix properties are mutually exclusive, i.e. cannot be used together.
Some protocols prefix every element with its serialization length for the forward / backward compatibility of the protocol. If there is such need, use elemLengthPrefix to specify a field that will prefix every element of the list.
The code generator must report an error when element of such list (with elemFixedLength property set to true) has variable length.
The CommsDSL also allows reference of externally defined field to be an element using element .
If the defined list must contain predefined number of elements, use count to provide the required information.
In case the count prefix field is defined as external field, CommsDSL allows usage of countPrefix as , value of which contains name of the referenced field.
The CommsDSL also supports detached count prefix, when there are several other fields in the or in the between the count field and the <list>.
NOTE, the existence of $ prefix when specifying countPrefix value. It indicates that the referenced field is a sibling in the containing or the field.
There are protocols that prefix a list with serialization length rather than number of elements. In this case use lengthPrefix instead of countPrefix. The allowed usage scenarios are exactly the same as described above in the section.
In case every list element has fixed length and protocol specification doesn't allow adding extra variable length fields to the element in the future, some protocols prefix only first element in the list with its serialization length. CommsDSL supports such lists with elemFixedLength , that has value.
Use for future references.