Decoder Data Object Syntax

A Decoder Data Object is defined as a special kind of C++ class that is similar to a Frame Recognizer. It takes the following form:

DECODER_STATIC name [PER_STREAM] [VERSION number]

<class stuff such as declaration of member variables.>

@CTOR

<code - Constructor>

@DTOR

<code - Destructor>

@RESET

<code - Called when there is a reset. This means forget everything! Called, for example, when the protocol stack changes.>

@EVENT_HANDLER

<code - Called to NOTIFY type events. See below.>

@PUT_DATA_INTO_A_BYTE_ARRAY

<code - Called to save data from the data object.>

@OPTIMIZE_DATA

<code - Called to save data from the data object.>

@GET_DATA_FROM_A_BYTE_ARRAY

<code - Called to load data into the data object.>

@IMPLEMENTATION

<code - Anything else that needs to be defined, such as private functions.>

@END_STATIC

With one exception, all of the code blocks are optional. If a block is omitted then its tag (e.g. @RESET) should be omitted as well. The exception is that OPTIMIZE_DATA will run only if PUT_DATA_INTO_A_BYTE_ARRAY is defined (PUT_DATA_INTO_A_BYTE_ARRAY can be empty however).

At this point we can explain how a data object works. You define a data class for each set of data that you want to maintain. Then, in your custom methods, you call member functions in the data object to manipulate the data as needed. You can use any number of instances of a data class, each distinguished by a unique name. This is the data name referenced in the section on Intra-frame and Inter-frame Data in "Putting It All Together".

If PER_STREAM is present in the data class definition, then any instance of the data class is created strictly for use within the current stream. In other words, if you use a data object called ABC then a separate ABC will exist for each stream. The instance for one stream cannot "see" another stream's instance. If you need to pass data between streams then, obviously enough, you use a data class that does not have the PER_STREAM attribute.

If VERSION is not present, the version is zero. Otherwise, it is whatever number is given. This is important because the output of the data object is saved to the FRM file, and is read back in when a capture file is opened. If the data to be saved changes, it won't be read in correctly from an old FRM file. Therefore, if you change the data format in a data object, you must change the version number so that the FRM file is thrown away and rebuilt.

Just before the first time a data object is called in a frame during the compilation phase, PUT_DATA_INTO_A_BYTE_ARRAY is called to get a copy of the beginning value of the data object. Note that this is done for each frame, and the beginning value is the value the data object had when the frame was first encountered.

OPTIMIZE_DATA is called to get a copy of the value of the data object after the frame has been compiled.

GET_DATA_FROM_A_BYTE_ARRAY is used to initialize data objects during the reconstruction phase and load them with the data that was saved in the FRM file.

You cannot define parameters for a data object.