The codec constructor, destructor and info functions
Every event codec needs to implement a constructor function, a destructor function and an ‘info’ function. These methods are called by the IAF to (respectively) to instantiate the event codec, to clean it up during unloading, and to provide information about the plug-in’s capabilities.
EventCodec.h provides the following definition for a pointer to the constructor function:
AP_EventCodecCtorPtr
/**
* Pointer to the constructor function for the codec library. Each codec
* plugin library must export a function with this signature, named using
* the AP_EVENTCODEC_CTOR_FUNCTION_NAME macro.
*
* Constructs a new instance of the event codec. This function will be
* called by the adapter main program when the adapter starts up.
*
* Note that the input parameters (name, properties, timestampConfig) are
* owned by the caller. The IAF framework guarantees that properties and
* timestampConfig will remain valid until after a subsequent call to
* updateProperties(), so it is safe to hold a pointer to this structure.
* You should, however, copy the name string if you wish to keep it. The
* contents of the output parameter errMsg belongs to the codec.
*
* @param name The name of this codec instance, also found in properties
* @param properties Codec property set derived from the IAF config file
* @param err 'Out' parameter for error code if constructor fails
* @param errMsg 'Out' parameter for error message if constructor fails
* @param timestampConfig Timestamp recording/logging settings
* @return Pointer to a new codec instance or NULL if the constructor fails
* for some reason. In the case of failure, err and errMsg should be filled
* in with an appropriate error code and message describing the failure.
*/
typedef AP_EVENTCODEC_API AP_EventCodec* (
AP_EVENTCODEC_CALL* AP_EventCodecCtorPtr)(
AP_char8* name, AP_EventCodecProperties* properties,
AP_EventCodecError* err, AP_char8** errMsg,
IAF_TimestampConfig* timestampConfig);
while the destructor function definition is as follows:
AP_EventCodecDtorPtr
/**
* Pointer to the destructor function for the codec library. Each codec
* plugin library must export a function with this signature, named using
* the AP_EVENTCODEC_DTOR_FUNCTION_NAME macro.
*
* Destroys an instance of the event codec that was previously created by
* AP_EventCodec_ctor. The codec may assume that it has been flushed
* before the destructor is called.
*
* @param codec The event codec object to be destroyed
*/
typedef AP_EVENTCODEC_API void
(AP_EVENTCODEC_CALL* AP_EventCodecDtorPtr)(AP_EventCodec* codec);
The IAF will search for these functions by the names AP_EventCodec_ctor and AP_EventCodec_dtor when the library is loaded, so you must use these exact names when implementing a codec plug-in.
In addition, every codec needs to implement an ‘information’ function. This is called by the IAF to obtain information as to the capabilities (encoder/decoder) of the codec. The definition is:
AP_EventCodecInfoPtr
/**
* Pointer to the info function for the codec library. Each codec plugin
* library must export a function with this signature, named using the
* AP_EVENTCODEC_INFO_FUNCTION_NAME macro.
*
* Returns basic information about the codecs implemented by this shared
* library, specifically whether they are encoders, decoders or
* bidirectional codecs.
*
* @param version 'Out' parameter for version number of codec library. This
* should be the value of AP_EVENTCODEC_VERSION that was defined in
* EventCodec.h when the codec was built. The IAF will check the version
* number to ensure that it can support all the capabilities offered by the
* codec.
* @param capabilities 'Out' parameter for the capabilities of the codecs
* provided by this library. This should be the sum of the appropriate
* AP_EVENTCODEC_CAP_* constants found in EventCodec.h.
*/
typedef AP_EVENTCODEC_API void
(AP_EVENTCODEC_CALL* AP_EventCodecInfoPtr)(AP_uint32* version,
AP_uint32* capabilities);
The IAF will search for and call this function by the name AP_EventCodec_info.