Protocol Versioning Summary

This chapter summarizes all version related aspects of the protocol definition.

Version of the Schema

The protocol definition <schema> has the version property, that specifies numeric version of the protocol.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" version="5">
    ...
</schema>

Version in the Interface

If protocol reports its version via transport framing or via some special "connection" message, and the protocol version must influence how some messages are deserialized / handled, then there is a need for <interface> definition, which must contain version field, marked as such using semanticType="version" property.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" version="5">
    <interface name="Interface">
        <int field="SomeName" type="uint16" semanticType="version" /> 
    </interface>
    ...
</schema>

Version in the Frame

In addition to the <interface> containing version information, the transport <frame> is also expected to contain <value> layer, which will reassign the received version information to the message object (via <interface>).

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" version="5">
    <interface name="Interface">
        <int field="SomeName" type="uint16" semanticType="version" /> 
    </interface>

    <frame name="Frame">
        <size name="Size">
            <int name="SizeField" type="uint16" serOffset="2"/>
        </size>
        <id name="Id">
            <int name="IdField" type="uint8" />  
        </id>
        <value name="Version" interfaces="Interface" interfaceFieldName="SomeName">
            <int name="VersionField" type="uint16" /> 
        </value>
        <payload name="Data" />
    </frame>
</schema>

Version of the Fields and Messages

Every message and field support the following properties, wich can be used to supply version related information.

  • sinceVersion - Version when the message / field has been introduced.
  • deprecated - Version when the message / field has been deprecated.
  • removed - Indication that deprecated message / field must be removed from serialization and code generation.

Version Dependency of the Code

The generated code is expected to be version dependent (i.e. presence of some messages / fields is determined by the reported version value), if at least one of the defined <interface>-es contains version field (marked by semanticType="version").

If none of the interfaces has such field, then the generated code cannot be version dependent and all the version related properties become for documentation purposes only and cannot influence the presence of the messages / fields. In such cases the code generator is expected to receive required protocol version in its command line parameters and generate code for requested protocol version.

Compatibility Recommendation

In case CommsDSL is used to define new protocol developed from scratch and backward / forward compatibility of the protocol is a desired feature, then there are few simple rules below, following of which can insure such compatibility.

  • Use <size> layer in the transport framing to report remaining length of the message.
  • Use <value> layer to report protocol version in the transport framing or define special "connect" message that is sent to establish connection and report protocol version (mark the <value> layer to be pseudo).
  • Always add new fields at the end of the <message>. Don't forget to specify their version using sinceVersion property.
  • Don't remove deprecated fields.
  • Always add new fields at the bottom of the <list> element.
  • Add element serialization length report before every element of the <list> field (done using elemLengthPrefix property).
  • In case elemFixedLength property is assigned for the <list> (to avoid redundant report of the same element length before every element), never add variable length fields to the element of the list.

results matching ""

    No results matching ""