Developing Apama Applications > Developing Adapters > C/C++ Transport Plug-in Development > The C/C++ transport plug-in development specification > Transport functions to implement
Transport functions to implement
EventTransport.h provides the definition for a number of functions whose implementation needs to be provided by the event transport author.
These functions are as follows:
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.
  *
  * @param transport The event transport instance
  * @param properties The new transport property set derived from the IAF
  * configuration file
  * @param timestampConfig Timestamp recording/logging settings
  * @return 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 (*updateProperties)(
     struct AP_EventTransport* transport,
     AP_EventTransportProperties* properties,
     IAF_TimestampConfig* timestampConfig);
 
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.
  *
  * @param transport The event transport instance
  * @param event The event to be sent on the external transport
  * @param timeStamp Timestamps associated with this event
  * @return 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 (*sendTransportEvent)(
     struct AP_EventTransport* transport,
     AP_TransportEvent event,
     AP_TimestampSet* timeStamp);
 
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.
  *
  * @param transport The event transport instance
  * @param name The name of the decoder to be added
  * @param decoder The decoder object itself
  */
  void (*addEventDecoder)(struct AP_EventTransport* transport,
     const AP_char8* name,
     struct AP_EventDecoder* decoder);
 
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.
  *
  * @param transport The event transport instance
  * @param name The decoder to be removed
  */
  void (*removeEventDecoder)(struct AP_EventTransport* transport,
     const AP_char8* name);
 
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.
  *
  * @param transport The event transport instance
  * @return 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 (*flushUpstream)(
     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.
  *
  * @param transport The event transport instance
  * @return 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 (*flushDownstream)(
     struct AP_EventTransport* transport);
 
start
 
/**
  * Establish a connection and start processing incoming data from the
* external transport.
*
* 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.
  *
  * @param transport The event transport instance
  * @return 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 (*start)(struct AP_EventTransport* 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);
This codec function is described in C/C++ Codec Plug-in Development.
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.
  *
  * @param transport The event transport instance
  * @return 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 (*stop)(struct AP_EventTransport* transport);
Events should not be sent to the correlator after the stop function has returned. The stop method must wait for any other threads sending events to complete before the stop method returns.
getLastError
 
/**
  * 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.
  *
  * @param transport The event transport instance
  * @return The last error message generated by the transport
  */
  const AP_char8* (*getLastError)(struct AP_EventTransport* transport);
getStatus/**
  * 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.
  *
  * @param codec The event transport instance
  * @param status The status structure to be filled in
  */
  void (*getStatus)(struct AP_EventTransport* transport,
     AP_EventTransportStatus* status);
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.
Copyright © 2013 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or Terracotta Inc., San Francisco, CA, USA, and/or Software AG (Canada) Inc., Cambridge, Ontario, Canada, and/or, Software AG (UK) Ltd., Derby, United Kingdom, and/or Software A.G. (Israel) Ltd., Or-Yehuda, Israel and/or their licensors.