 |
Apama
10.7.2.2
|
|
Apama
10.7.2.2
|
AP_EventTransport_Functions. More...
#include <EventTransport.h>
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.
| 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.
| transport | The event transport instance |
| name | The name of the decoder to be added |
| decoder | The 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.
| transport | The event transport instance |
| 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.
| transport | The event transport instance |
| 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.
| transport | The event transport instance |
| 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.
| transport | The event transport instance |
| status | The 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.
| transport | The event transport instance |
| name | The 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.
| transport | The event transport instance |
| event | The event to be sent on the external transport. Ownership is transferred to the callee. |
| timeStamp | Timestamps associated with this event. Ownership is transferred to the callee. |
| 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.
| transport | The event transport instance |
| 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.
| transport | The event transport instance |
| 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.
| transport | The event transport instance |
| properties | The new transport property set derived from the IAF configuration file |
| timestampConfig | Timestamp recording/logging settings |
1.8.15