Common Properties of Fields
Last updated
Was this helpful?
Last updated
Was this helpful?
Every field is different, and defines its own properties and/or other aspects. However, there are common properties, that are applicable to every field. They are summarized below.
Every field must define it's , which is expected to be used by a code generator when defining a relevant class. The name is defined using name .
It is possible to provide a description of the field about what it is and how it is expected to be used. This description is only for documentation purposes and may find it's way into the generated code as a comment for the generated class. The is description.
Sometimes two different fields are very similar, but differ in one particular aspect. CommsDSL allows copying all the properties from previously defined field (using reuse property) and change some of them after the copy. For example:
In the example above member of the bitfield Member1 copies all the properties from SomeIntField field, then overrides its name and adds bitLength one to specify its length in bits.
CommsDSL supports generation of not only field's serialization and value access functionality, but also of various GUI protocol visualization, debugging and analysis tools. There are some allowed properties, that indicate how the field is expected to be displayed by such tools.
If displayName is not specified, the code generator must use value of property name instead. In order to force empty displayName, use "_" (underscore) value.
CommsDSL allows providing an information in what version the field was added to a particular message, as well as in what version it was deprecated, and whether it was removed from being serialized after deprecation.
To specify the version in which field was introduced, use sinceVersion property. To specify the version in which the field was deprecated, use deprecated property. To specify whether the field was removed after being deprecated use removed property in addition to deprecated.
In the example above:
F1 was introduced in version 0 and hasn't been deprecated yet.
F2 was also introduced in version 0, deprecated in version 5, but not
removed from being serialized.
F3 was introduced in version 2 and hasn't been deprecated yet.
F4 was introduced in version 3, deprecated in removed in version 4.
Some fields may specify what values are considered to be valid, and there may be a need to fail the read operation in case the received value is invalid.
Sometimes code generator may generate a bit different (or better) code for fields that are used for some particular purpose. To specify such purpose use semanticType property.
Available semantic types are:
messageId - Used to specify what type/field is used for holding numeric
version - Used to specify that the field is used to hold protocol version.
length - Used to specify that the field holds total serialization length
The length semantic type makes sense only for
all other cases. The length semantic type
was introduced in v2.0 of CommsDSL specification.
The reuse is allowed only from the field of the same kind. For example, it is NOT allowed for field to reuse definition of , only other .
The displayName property is there to specify proper string of the field's name, with spaces, dots and other characters that are not allowed to exist in the .
Sometimes the values of some fields may be controlled by other fields. In this case, it could be wise to disable manual update of such fields. To enable/disable such behavior use displayReadOnly property with value.
Also sometimes it can be desirable to completely hide some field from being displayed in the protocol analysis GUI application. In this case use displayHidden property with value.
NOTE, that all the specified versions mustn't be greater that the version of the . Also value of sinceVersion must be less than value of deprecated.
The version information on the field in global <fields> area or inside some does NOT make sense and should be ignored by the code generator. It is allowed when field is a member of a or a field.
To achieve this failOnInvalid property with value can be used. There are two main scenarios that may require usage of this property. One is the protocol being implemented requires such behavior in its specification. The second is when there are multiple forms of the same message which are differentiated by the value of some specific field in its payload. For example:
The example above defined 3 variants of the message with numeric ID equals to 1. When new message with this ID comes in, the code is expected to try reading all of the variants and choose one, on which read operation doesn't fail. The order property of the message specifies in what order the messages with the same ID must be read. It described in more detail in chapter.
Sometimes there may be a need to have "psuedo" fields, which are implemented using proper field abstration, and are handled as any other field, but not actually getting serialized when written (or deserialized when read). It can be achieved using pseudo property with value.
The code generator is expected to allow some level of compile time customization of the generated code, such as choosing different data structures and/or adding/replacing some runtime logic. The code generator is also expected to provide command line options to choose required level of customization. Sometimes it may be required to allow generated field abstraction to be customizable regardless of the customization level requested from the code generator. CommsDSL provides customizable property with value to force any field being customizable at compile time.
message ID. Applicable to fields.
Applicable to field (or referening
an ).
of the subsequent fields. Applicable to field
(or referening an ).
a member of field and should be ignored in
Use for future references.