Communication with other layers
A decoding codec plug-in’s role is to decode messages from a transport layer plug-in into a normalized format that can be processed by the Semantic Mapper. To achieve this it needs to be able to communicate with the Semantic Mapper. The accessible Semantic Mapper functionality is presented in SemanticMapper.h.
When a decoding codec starts it is passed a handle to an AP_SemanticMapper object through its setSemanticMapper function. This object is defined in SemanticMapper.h as follows:
**
* AP_SemanticMapper
*
* External (client-visible) interface to the Semantic Mapper component of
* an IAF instance. The AP_SemanticMapper struct contains contains a table
* of function pointers, declared in the AP_SemanticMapper_Functions struct
* above. The implementation of these functions is private. Users of the
* Semantic Mapper should invoke functions on it as in the following
* example (mapper is of type AP_SemanticMapper*):
*
* i = mapper->functions->sendNormalisedEvent(mapper, event);
*/
struct AP_SemanticMapper{
/**
* Pointer to private internal data.
*/
void* reserved;
/**
* Function table of Semantic Mapper operations. See documentation for
* AP_SemanticMapper_Functions for details.
*/
struct AP_SemanticMapper_Functions* functions;
};
typedef struct AP_SemanticMapper AP_SemanticMapper;
where functions, (of type AP_SemanticMapper_Functions*) points to the definitions for two functions: sendNormalisedEvent and getLastError:
/**
* AP_SemanticMapper_Functions
*
* Table of client visible functions exported by a Semantic Mapper
* instance. These functions declare the only operations that may be
* performed by users of a Semantic Mapper.
*
* Note that all of these functions take an initial AP_SemanticMapper*
* argument; this is analogous to the (hidden) 'this' pointer passed to a
* C++ object when a member function is invoked on it.
*/
struct AP_SemanticMapper_Functions {
/**
* sendNormalisedEvent
*
* Send a customer-specific event to the Semantic Mapper. The event will
* be translated into a single Apama event that will be queued for
* injection into the Engine.
*
* @param mapper The Semantic Mapper to send the event to.
* @param event The event to send, represented as a set of name-value
* pairs.
* @param timeStamp Timestamps associated with this event
* @return Semantic Mapper error code. If this is not
* AP_SemanticMapper_OK, the getLastError() function should be called to
* get a more detailed description of what went wrong.
*/
AP_SemanticMapperError (*sendNormalisedEvent)(
struct AP_SemanticMapper* mapper, AP_NormalisedEvent* event,
AP_TimestampSet* timeStamp);
/**
* getLastError
*
* Return the Semantic Mapper's stored error message, if any. The message
* string is owned by the mapper so should not be modified or freed by the
* caller.
*
* @param mapper The Semantic Mapper instance
* @return The last error message generated by the mapper
*/
const AP_char8* (*getLastError)(struct AP_SemanticMapper* mapper);
};
Code inside a decoding codec that calls these functions on the Semantic Mapper looks as follows. Assuming that mapper holds a reference to the AP_SemanticMapper object:
errorCode = mapper->functions->sendNormalisedEvent(mapper, NormalisedEvent);
and likewise for getLastError.
The error codes that may be returned by sendNormalisedEvent are as follows:
/**
* AP_SemanticMapperError
*
* Error codes that can be returned by operations on the Semantic Mapper. The
* enumeration values follow the normal UNIX convention of zero == OK and
* non-zero == error.
*/
typedef enum {
AP_SemanticMapper_OK = 0, /* Everything is fine */
AP_SemanticMapper_InternalError, /* Some unspecified internal error occurred */
AP_SemanticMapper_MappingFailure, /* Couldn't convert customer event to Apama event */
AP_SemanticMapper_InjectionFailure /* Couldn't queue converted event for injection into Engine */
} AP_SemanticMapperError;
On the other hand, an encoding codec plug-in’s role is to encode messages in normalized format into some specific format that can then be accepted by a transport layer plug-in for transmission to an external message sink (like a message bus). To achieve this it needs to be able to communicate with a transport layer plug-in loaded in the IAF.
When an encoding codec starts its
addEventTransport function will be called once for each available transport. For each, it is passed a handle to an
AP_EventTransport object. This object is defined in
EventTransport.h and was described in detail in
C/C++ Transport Plug-in Development. As stated in
Defining the codec function tables, it contains a pointer to
AP_EventTransport_Functions, which in turn references the functions available in the transport layer plug-in. Of these, only two are relevant to the author of an encoding codec:
sendTransportEvent
AP_EventTransportError (*sendTransportEvent)(
struct AP_EventTransport* transport, AP_TransportEvent event,
AP_TimestampSet* timeStamp);
getLastError
const AP_char8* (*getLastError)(struct AP_EventTransport* transport);
Code inside an encoding codec that calls these functions on the transport layer plug-in looks as follows. Assuming that transport holds a reference to the AP_EventTransport object:
errorCode = transport->functions->sendTransportEvent(transport, event);
and likewise for getLastError.