Messages
Last updated
Was this helpful?
Last updated
Was this helpful?
Every message is defined using <message> XML element.
Every message definition must specify its using name .
Every message definition must specify its ID using id .
It is recommended to share the displayName with relevant <validValue> of <enum> that lists numeric IDs of the messages:
Sometimes different messages have the same fields. In order to avoid duplication, use copyFieldsFrom property to specify original message.
In the example above Msg2 will have the same fields as Msg1.
After copying fields from other message, all other defined fields will be appended to copied ones.
In the example above Msg2 will have 2 fields: F1 and F2.
All the order values for the same numeric ID must be unique, but not necessarily sequential.
CommsDSL allows providing an information in what version the message was added to the protocol, as well as in what version it was deprecated, and whether it was removed (not supported any more) after deprecation.
To specify the version in which message was introduced, use sinceVersion property. To specify the version in which the message was deprecated, use deprecated property. To specify whether the message was removed after being deprecated use removed property in addition to deprecated.
In the example above SomeMessage was introduced in version 2, and SomeOtherMessage was introduced in version 3, but deprecated and removed in version 4.
The code generator is expected to be able to generate support for specific versions and include / exclude support for some messages based on their version information.
In the example above Msg1 is supported only for platforms Plat1 and Plat4, while Msg2 is NOT supported in Plat1, and Plat2 (i.e. supported in Plat3 and Plat4).
The main consideration for what format to choose should be whether the platforms support for the message should or should NOT be added automatically when new <platform> is defined.
In most protocols there are uni-directional messages. The CommsDSL allows definition of entity that sends a particular message using sender property. Available values are both (default), server, and client. The code generator may use provided information and generate some auxiliary code and/or data structures to be used for client and/or server implementation.
In the example above Msg1 and Msg2 are uni-directional messages, while Msg3 is bi-directional.
It is highly recommended to define "message ID" numeric values as external field and reuse its values.
It is possible to provide a description of the message 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.
When various analysis tools display message details, the preference is to display proper space separated name (which is defined using displayName ) rather than using a .
In case displayName is empty, the analysis tools are expected to use value of name instead.
Every <message> has zero or more that can be specified as child XML elements.
If there is any other defined as XML child of the <message>, then all the fields must be wrapped in <fields> XML element for separation.
There are protocols that may define various forms of the same message, which share the same numeric ID, but are differentiated by a serialization length or value of some particular field inside the message. It can be convenient to define such variants as separate classes. In case there are multiple <message>-es with the same , it is required to specify order in which they are expected to be processed (read). The ordering is specified using order with unsigned value. The message object with lower order value gets created and its read operation attempted before message object with higher value.
NOTE that there is a need to set nonUniqueMsgIdAllowed property of the to true to allow multiple message objects with the same numeric ID.
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.
Some protocols may be used in multiple independent platforms, while having some platform-specific messages. The CommsDSL allows listing of the supported platforms using XML nodes. Every message may list platforms in which it must be supported using platforms . In case the property's value is empty (default), the message is supported in all the available platforms (if any defined). The platforms property value is coma-separated list of platform names with preceding + if the listed platforms are the one supported, or - if the listed platforms need to be excluded from all available ones.
The code generator is expected to allow some level of compile time customization of the generated code, such as enable/disable generation of particular virtual functions. 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 message class to be customizable regardless of the customization level requested from the code generator. CommsDSL provides customizable property with value to force any message to being customizable at compile time.
Sometimes an existing member field may be renamed and/or moved. It is possible to create alias names for the fields to keep the old client code being able to compile and work. Please refer to chapter for more details.
Use for future references.