optional Field
Last updated
Was this helpful?
Last updated
Was this helpful?
This field wraps other and makes the wrapped field optional, i.e. the serialization of the latter may be skipped if it is marked as "missing". The <optional> field has all the properties as well as extra properties and elements described below.
Every <optional> must specify its inner . The wrapped field can be defined as XML child of the <optional> definition.
In case other properties of the <optional> field are defined as child XML elements, then the element field definition needs to be wrapped by <field> XML child.
The allowed cond expressions are:
$set_field_name.bit_name - The wrapped field exists if specified bit is set to true (1).
!$set_field_name.bit_name - The wrapped field exists if specified bit is set to false (0).
$field_name compare_op value - The wrapped field exists if comparison
of the specified field with specified value is true. The compare_op can be:
= (equality), != (inequality), < (less than), <= (less than or equal),
> (greater than), >= (greater than or equal).
$field_name compare_op $other_field_name - The wrapped field exists if comparison
of the specified fields is true.
NOTE, that XML doesn't allow usage of < or > symbols in condition values directly. They need to be substituted with < and > strings respectively.
For example, there are 2 normal fields followed by a third optional one. The latter exists, only if value of F1 is less than value of F2
The CommsDSL also allows usage of multiple existence condition statements. However, they need to be wrapped by either <and> or <or> XML child elements, which represent "and" and "or" logical conditions respectively.
In the example the F3 field exists in one of the following conditions:
Value of F1 is 0.
Value of F1 is 1 and value of F2 is not 0.
The CommsDSL also allows reference of externally defined field to be specified as inner (wrapped) field type using field .
Every <optional> field has 3 modes: tenative (default), exist, and missing. The exist and missing modes are self explanatory. The tentative mode is there to perform read operation on the inner field only if there are non-consumed bytes left in the input buffer. This mode can be useful with protocols that just add fields at the end of the in the new version, but the protocol itself doesn't report its version in any other way.
The default mode of the newly constructed <optional> field can be specified using defaultMode .
Many protocols introduce optional fields, and the existence of such fields depend on the value of some other field. Classic example would be having some kind of flags field (see ) where some bit specifies whether other field that follows exists or not. Such conditions can be expressed using cond .
NOTE, that cond property can be used only for <optional> field that is a member of a or a . The cond expression specifies condition when the <optional> field exists, and must always reference other sibling field. Such reference is always prefixed with $ character to indicate that the field is a sibling of the <optional> and not some external field.
By default GUI protocol analysis tools should allow manual update of the <optional> field mode. However, if the mode is controlled by the values of other fields, it is possible to disable manual update of the mode by using displayExtModeCtrl (stands for "display external mode control") with value.
Use for future references.