Codec functions to implement
EventCodec.h provides the definition for a number of functions whose implementation needs to be provided by the event transport author.
However, in contrast to the Transport Layer Plug-in Development Specification, the set of functions that need to be implemented varies depending on whether the codec is to implement only a message decoder, only a message encoder, or a bidirectional encoder/decoder.
In all cases implementations need to be provided for the following functions:
updateProperties
/**
* Update the configuration of the codec. The codec may assume that
* flushUpstream() and flushDownstream() have been called before this
* function is invoked. The recommended procedure for updating properties
* is to first compare the new property set with the existing stored
* properties -- if there are no changes, no action should be taken. Any
* pointer to the old property set becomes invalid as soon as this
* function returns; any such pointers should therefore be discarded in
* favour of the supplied new properties.
*
* @param codec The event codec instance
* @param properties The new codec property set derived from the IAF
* configuration file
* @param timestampConfig Timestamp recording/logging settings
* @return Event codec error code. If this is not AP_EventCodec_OK, the
* getLastError() function of the codec should be called to get a more
* detailed description of what went wrong.
*/
AP_EventCodecError (*updateProperties)(struct AP_EventCodec* codec,
AP_EventCodecProperties* properties,
IAF_TimestampConfig* timestampConfig);
It is recommended that updateProperties is invoked by the codec constructor.
getLastError
/**
* Return the codec's stored error message, if any. The message string is
* owned by the codec so should not be modified or freed by the caller.
*
* @param codec The event codec instance
* @return The last error message generated by the codec
*/
const AP_char8* (*getLastError)(struct AP_EventCodec* codec);
getStatus
/**
* Fill in the supplied AP_EventCodecStatus structure with up-to-date
* status information for the codec. Note that any data pointed to by the
* returned structure (such as strings) remains owned by the codec. The
* caller must copy this data if it wishes to modify it.
*
* @param codec The event codec instance
* @param status The status structure to be filled in
*/
void (*getStatus)(struct AP_EventCodec* codec, AP_EventCodecStatus* status);
The AP_EventCodecStatus structure contains four fields. The first field is a free-form text string that the transport can use to report any custom status information it might have. The iaf_watch tool will display the contents of this string. Note that the length of the status string is limited, currently to 1024 characters. Longer strings will be silently truncated. The next two fields report the total number of events encoded and decoded by the codec. The last field, a pointer to an AP_NormalisedEvent, can contain custom information such as the state of the adapter.