enum Field
Last updated
Was this helpful?
Last updated
Was this helpful?
This field stores and abstracts away value of integral , where every valid value has its name. The <enum> field has all the properties as well as extra properties and elements described below.
Every <enum> field must provide its underlying storage type using type . Available values are:
int8 - 1 byte signed integer.
uint8 - 1 byte unsigned integer.
int16 - 2 bytes signed integer.
uint16 - 2 bytes unsigned integer.
int32 - 4 bytes signed integer.
uint32 - 4 bytes unsigned integer.
int64 - 8 bytes signed integer.
uint64 - 8 bytes unsigned integer.
intvar - up to 8 bytes variable length signed integer
uintvar - up to 8 bytes variable length unsigned integer
All the valid values must be listed as <validValue> child of the <enum> XML element.
Every <validValue> has extra optional properties:
description - Extra description and documentation on how to use the value.
displayName - String specifying how to name the value in various analysis tools.
sinceVersion - Version of the protocol when the value was introduced.
deprecated - Version of the protocol when the value was deprecated.
The default value of the <enum> field when constructed can be specified using defaultValue property. If not specified, defaults to 0.
The default value can also be specified using the name of one of the <validValue>-es:
The generated enum type is expected to look something like this:
instead of
In the example above values 0 and 5 will always be considered valid. However value 10 will be considered valid only if reported protocol version is greater than or equal to 2. The value 15 will be considered valid only for protocol version 3.
The variable length types are encoded using Base-128 form, such as for little endian or similar for big endian.
Every <validValue> must define a valid (using name ) as well as value (using val ), that fits chosen . The <validValue>-es may be listed in any order, not necessarily sorted.
All these extra properties are described in detail in .
The default serialization endian of the protocol is specified in endian property of the . It is possible to override the default endian value with extra endian property.
The dictates the serialization length of the <enum> field. However, there may be protocols that limit serialization length of the field to non-standard lengths, such as 3 bytes. In this case use length property to specify custom serialization length.
IMPORTANT: When length property is used with variable length (intvar and uintvar), it means maximum allowed length.
<enum> field can be a member of field. In this case the serialization length may be specified in bits using bitLength .
The code generator is expected to generate appropriate enum types using decimal values assigned to enumeration names. However, some protocol specifications may list valid values using hexadecimal format. To make the reading of the generated code more convenient, use hexAssign with value to force code generator make the assignments using hexadecimal values.
By default, non-unqiue values are not allowed, the code generator must report an error if two different <validValue>-es use the same value of the val property. It is done as protection against copy-paste errors. However, CommsDSL allows usage of non-unique values in case nonUniqueAllowed has been set to true.
The code generator is expected to generate functionality checking that <enum> field contains a valid value. By default any specified <validValue> is considered to be valid regardless of version it was introduced and/or deprecated. However, it is possible to force code generator to generate validity check code that takes into account reported version of the protocol by using validCheckVersion , which is set to true.
Use for future references.