Apama  10.3.1.5
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
AP_EventTransport_Functions Struct Reference

AP_EventTransport_Functions. More...

#include <EventTransport.h>

Public Attributes

AP_EventTransportError(* updateProperties )(struct AP_EventTransport *transport, AP_EventTransportProperties *properties, IAF_TimestampConfig *timestampConfig)
 updateProperties More...
 
AP_EventTransportError(* sendTransportEvent )(struct AP_EventTransport *transport, AP_TransportEvent event, AP_TimestampSet *timeStamp)
 sendTransportEvent More...
 
void(* addEventDecoder )(struct AP_EventTransport *transport, const AP_char8 *name, struct AP_EventDecoder *decoder)
 addEventDecoder More...
 
void(* removeEventDecoder )(struct AP_EventTransport *transport, const AP_char8 *name)
 removeEventDecoder More...
 
AP_EventTransportError(* flushUpstream )(struct AP_EventTransport *transport)
 flushUpstream More...
 
AP_EventTransportError(* flushDownstream )(struct AP_EventTransport *transport)
 flushDownstream More...
 
AP_EventTransportError(* start )(struct AP_EventTransport *transport)
 start More...
 
AP_EventTransportError(* stop )(struct AP_EventTransport *transport)
 stop More...
 
const AP_char8 *(* getLastError )(struct AP_EventTransport *transport)
 getLastError More...
 
void(* getStatus )(struct AP_EventTransport *transport, AP_EventTransportStatus *status)
 getStatus More...
 

Detailed Description

AP_EventTransport_Functions.

Table of client visible functions exported by a transport library instance. These functions declare the only operations that may be performed by users of a transport.

Note that all of these functions take an initial AP_EventTransport* argument; this is analogous to the (hidden) 'this' pointer passed to a C++ object when a member function is invoked on it.

Member Data Documentation

void(* AP_EventTransport_Functions::addEventDecoder)(struct AP_EventTransport *transport, const AP_char8 *name, struct AP_EventDecoder *decoder)

addEventDecoder

Add a named event decoder to the set of decoders known to the transport. If the named decoder already exists, it should be replaced.

Parameters
transportThe event transport instance
nameThe name of the decoder to be added
decoderThe decoder object itself
AP_EventTransportError(* AP_EventTransport_Functions::flushDownstream)(struct AP_EventTransport *transport)

flushDownstream

Flush any pending transport events into the decoder. The transport may assume that the stop() function has been called before this function, so in many cases no action will be required to complete the flushing operation. Under no circumstances should any events be sent to the Correlator after flushDownstream() has returned.

Parameters
transportThe event transport instance
Returns
Event transport error code. If this is not AP_EventTransport_OK, the getLastError() function should be called to get a more detailed description of what went wrong.
AP_EventTransportError(* AP_EventTransport_Functions::flushUpstream)(struct AP_EventTransport *transport)

flushUpstream

Flush any pending normalized events onto the external transport. The transport may assume that the stop() function has been called before this function, so in many cases no action will be required to complete the flushing operation.

Parameters
transportThe event transport instance
Returns
Event transport error code. If this is not AP_EventTransport_OK, the getLastError() function should be called to get a more detailed description of what went wrong.
const AP_char8*(* AP_EventTransport_Functions::getLastError)(struct AP_EventTransport *transport)

getLastError

Return the transport's stored error message, if any. The message string is owned by the transport so should not be modified or freed by the caller.

Parameters
transportThe event transport instance
Returns
The last error message generated by the transport
void(* AP_EventTransport_Functions::getStatus)(struct AP_EventTransport *transport, AP_EventTransportStatus *status)

getStatus

Fill in the supplied AP_EventTransportStatus structure with up-to-date status information for the transport. Note that any data pointed to by the returned structure (such as strings) remains owned by the transport. The caller must copy this data if it wishes to modify it.

The AP_EventTransportStatus 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 received and sent by the transport. The last field, a pointer to an AP_NormalisedEvent, can contain custom information such as the state of the adapter.

Parameters
transportThe event transport instance
statusThe status structure to be filled in
void(* AP_EventTransport_Functions::removeEventDecoder)(struct AP_EventTransport *transport, const AP_char8 *name)

removeEventDecoder

Remove a named event decoder from the set of decoders known to the transport. If the named decoder does not exist, the function should do nothing.

Parameters
transportThe event transport instance
nameThe decoder to be removed
AP_EventTransportError(* AP_EventTransport_Functions::sendTransportEvent)(struct AP_EventTransport *transport, AP_TransportEvent event, AP_TimestampSet *timeStamp)

sendTransportEvent

Called by an event encoder to send a message to the external transport. Ownership of the message is transferred to the transport when this function is called. It is assumed that the encoder and transport share the same definition of the content of the event, so that the transport can effectively interpret the event and free any dynamically-allocated memory.

Parameters
transportThe event transport instance
eventThe event to be sent on the external transport. Ownership is transferred to the callee.
timeStampTimestamps associated with this event. Ownership is transferred to the callee.
Returns
Event transport error code. If this is not AP_EventTransport_OK, the getLastError() function should be called to get a more detailed description of what went wrong.
AP_EventTransportError(* AP_EventTransport_Functions::start)(struct AP_EventTransport *transport)

start

Establish a connection and start processing incoming data from the external transport.

When the start function is invoked the event transport is effectively signaled to start accepting incoming messages and pass them onto a codec. Events should not be sent to the correlator until the start function is called It is up to the event transport to determine which codec to communicate with from the list of codecs made available to it through addEventDecoder and removeEventDecoder.

Typically a configuration property would be used to specify the codec to be used. If a handle to the desired codec had been stored in a variable called decoder (of type AP_EventDecoder*) when addEventDecoder was called, an event could be passed on to the codec using:

decoder->functions->sendTransportEvent(decoder, event);

An adapter should send events to the correlator only after its start() method is called and before the stop() method returns. Therefore we strongly recommend that a transport should not change to a state where it is possible to receive events from any external transport until the start() method has been called. In many cases, adapters will also need to communicate with service monitors in the correlator to ensure that the required monitors and event definitions are injected before they begin to process messages from the external system. This is necessary in order to avoid events from the adapter being lost if the correlator is not yet ready to parse and process them.

Parameters
transportThe event transport instance
Returns
Event transport error code. If this is not AP_EventTransport_OK, the getLastError() function should be called to get a more detailed description of what went wrong.
AP_EventTransportError(* AP_EventTransport_Functions::stop)(struct AP_EventTransport *transport)

stop

Stop processing incoming data from the external transport, typically by pausing or closing down connections.

Adapter authors must ensure that no events are sent to the Correlator after stop() has returned (the only exception being rare cases where the transport sends buffered events in the Correlator in the flushDownstream() method, which is called by the IAF after stop()). If necessary any messages that are unavoidably received from the transport after stop() has returned should be blocked, queued or simply dropped.

Parameters
transportThe event transport instance
Returns
Event transport error code. If this is not AP_EventTransport_OK, the getLastError() function should be called to get a more detailed description of what went wrong.
AP_EventTransportError(* AP_EventTransport_Functions::updateProperties)(struct AP_EventTransport *transport, AP_EventTransportProperties *properties, IAF_TimestampConfig *timestampConfig)

updateProperties

Update the configuration of the transport. The transport may assume that stop(), flushUpstream() and flushDownstream() have all 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.

Parameters
transportThe event transport instance
propertiesThe new transport property set derived from the IAF configuration file
timestampConfigTimestamp recording/logging settings
Returns
Event transport error code. If this is not AP_EventTransport_OK, the getLastError() function should be called to get a more detailed description of what went wrong.

The documentation for this struct was generated from the following file: