routingservice_processor.h

Go to the documentation of this file.

/*
 * (c) Copyright, Real-Time Innovations, 2002-2024.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */
 
#ifndef routingservice_processor_h
#define routingservice_processor_h
 
#include "routingservice/routingservice_infrastructure.h"
#include "routingservice/routingservice_adapter_new.h"
 
#ifdef __cplusplus
    extern "C" {
#endif
 
/*e \file
  @brief RTI Routing Service Processor API
*/
 
/*****************************************************************************/
/* Route                                                                     */
/*****************************************************************************/
 
/*e \defgroup RTI_RoutingServiceProcessorModule RTI Routing Service Processor API
 *
 * \ingroup ROUTER
 *
 * @brief Entity responsible for administering inputs and outputs
 *
 */
struct RTI_RoutingServiceRouteImpl;
 
typedef struct RTI_RoutingServiceRouteImpl RTI_RoutingServiceRoute;
 
/*
 * --- RTI_RoutingServiceInput ------------------------------------------------
 */
 
/*e
 * \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief A pair of sample and sample info arrays. They are assumed to be of the
 *        same length.
 *
 * @see RTI_RoutingServiceSample
 * @see RTI_RoutingServiceSampleInfo
 */
struct RTI_RoutingServiceLoanedSamples {
    RTI_RoutingServiceSample *data_array;
    RTI_RoutingServiceSampleInfo *info_array;
    int length;
};
 
#define RTI_RoutingServiceLoanedSamples_INITIALIZER {\
    NULL,\
    NULL,\
    0 \
}
 
struct RTI_RoutingServiceInputImpl;
 
typedef struct RTI_RoutingServiceInputImpl RTI_RoutingServiceInput;
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the name of the specified input.
 *
 * The input name is given by the attribute of the corresponding XML tag
 * in the configuration.
 *
 * @param self \b In. Input for which the name is returned.
 *
 */
extern ROUTERDllExport
const char* RTI_RoutingServiceInput_get_name(RTI_RoutingServiceInput *self);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * Returns the type information associated with the specified Input.
 * The TypeInformation refers to the format of the stream that the specified
 * Input's read operation expects to receive.
 *
 * @param self \b In. Input for which the type information is returned.
 */
extern ROUTERDllExport
const struct RTI_RoutingServiceStreamInfo *
RTI_RoutingServiceInput_get_stream_info(RTI_RoutingServiceInput *self);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Checks whether an Input is active
 *
 * An Input is active when it has data available but not yet read. That is,
 * the data available notification has been received but a call to read or take the
 * samples has not been made.
 *
 * @param self \b In. Input to be checked. Cannot be null.
 *
 * @return \c DDS_BOOLEAN_FALSE if the Input is inactive, otherwise,
 *         \c DDS_BOOLEAN_TRUE.
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceInput_is_active(RTI_RoutingServiceInput *self);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Takes all the available samples in this Input into the specified
 *        loaned samples instance.
 *
 * @pre Input is enabled
 *
 * This operation will call \c take() on the underlying
 * RTI_RoutingServiceStreamReader, and the samples will be loaned into the
 * given loaned samples collection. Samples loaned have to be returned by
 * calling RTI_RoutingServiceInput_return_loan().
 *
 * @param self \b In. Input to take the samples from. Cannot be null.
 * @param loaned_samples \b Out. Samples taken will be stored here. Cannot be
 *                null.
 *
 * @return \c DDS_BOOLEAN_FALSE if the samples could not be taken,
 *         \c DDS_BOOLEAN_TRUE otherwise.
 *
 * @see RTI_RoutingServiceLoanedSamples
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceInput_take(
        RTI_RoutingServiceInput *self,
        struct RTI_RoutingServiceLoanedSamples *loaned_samples);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Takes all the available samples in this Input into the specified
 *        loaned samples instance, filtering samples based on the given
 *        data selector.
 *
 * @pre Input is enabled
 *
 * This operation will call \c take() on the underlying
 * RTI_RoutingServiceStreamReader, and the samples will be loaned into the
 * given loaned samples collection. Samples loaned have to be returned by
 * calling RTI_RoutingServiceInput_return_loan().
 *
 * @param self \b In. Input to take the samples from.
 * @param loaned_samples \b Out. Samples taken will be stored here.
 * @param selector \b In. Selection criteria for the samples to be taken.
 *
 * @return \c DDS_BOOLEAN_FALSE if the samples could not be taken,
 *         \c DDS_BOOLEAN_TRUE otherwise.
 *
 * @see RTI_RoutingServiceLoanedSamples
 * @see RTI_RoutingServiceSelectorState
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceInput_take_w_selector(
        RTI_RoutingServiceInput *self,
        struct RTI_RoutingServiceLoanedSamples *loaned_samples,
        const struct RTI_RoutingServiceSelectorState *selector);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Reads all the available samples in this Input into the specified
 *        loaned samples instance.
 *
 * @pre Input is enabled
 *
 * This operation will call \c read() on the underlying
 * RTI_RoutingServiceStreamReader, and the samples will be loaned into the
 * given loaned samples collection. Samples loaned have to be returned by
 * calling RTI_RoutingServiceInput_return_loan().
 *
 * @param self \b In. Input to read the samples from.
 * @param loaned_samples \b Out. Samples read will be stored here.
 *
 * @return \c DDS_BOOLEAN_FALSE) if the samples could not be read,
 *         \c DDS_BOOLEAN_TRUE otherwise.
 * @see RTI_RoutingServiceLoanedSamples
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceInput_read(
        RTI_RoutingServiceInput *self,
        struct RTI_RoutingServiceLoanedSamples *loaned_samples);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Reads all the available samples in this Input into the
 *        specified loaned samples instance, filtering samples based on the
 *        given data selector. Cannot be null.
 *
 * @pre Input is enabled
 *
 * This operation will call \c read() on the underlying
 * RTI_RoutingServiceStreamReader, and the samples will be loaned into the
 * given loaned samples collection. Samples loaned have to be returned by
 * calling RTI_RoutingServiceInput_return_loan().
 *
 * @param self \b In. Input to read the samples from. Cannot be null.
 * @param loaned_samples \b Out. Samples taken will be stored here. Cannot be
 *                null.
 * @param selector \b In. Selection criteria for the samples to be taken.
 *
 * @return \c DDS_BOOLEAN_FALSE if the samples could not be read,
 *         \c DDS_BOOLEAN_TRUE otherwise.
 *
 * @see RTI_RoutingServiceLoanedSamples
 * @see RTI_RoutingServiceSelectorState
 * @see RTI_RoutingServiceInput_return_loan
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceInput_read_w_selector(
        RTI_RoutingServiceInput *self,
        struct RTI_RoutingServiceLoanedSamples *loaned_samples,
        const struct RTI_RoutingServiceSelectorState *selector);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns a loan on the read or taken samples.
 *
 * Call this method to indicate that you're done accessing
 * the collection of samples obtained by an earlier
 * invocation of RTI_RoutingServiceInput_take(),
 * RTI_RoutingServiceInput_take_w_selector(), RTI_RoutingServiceInput_read() or
 * RTI_RoutingServiceInput_read_w_selector().
 *
 * @param self \b In. Input the samples were taken/read from. Cannot be null.
 * @param loaned_samples \b Inout. The loaned samples to be returned. Cannot be
 *                null.
 *
 * @return \c DDS_BOOLEAN_FALSE if the samples could not be returned successfully,
 *         \c DDS_BOOLEAN_TRUE otherwise.
 *
 * @see RTI_RoutingServiceLoanedSamples
 * */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceInput_return_loan(
        RTI_RoutingServiceInput *self,
        struct RTI_RoutingServiceLoanedSamples *loaned_samples);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Creates a query object that selects the data with the specified
 * filter.
 *
 * @pre Input is enabled.
 *
 * This operation allows reading data with a SelectorState that contains
 * a query object returned by this operation.
 *
 * A query object type is implementation-dependent and guaranteed to
 * to be used only within the same StreamReader that created it. Because
 * a query object may be an expensive resource, this operation allows
 * receiving a previously created query for a potential reuse and update of
 * its filter.
 *
 * @param self \b In. Input used to create the content query. Cannot be null.
 * @param old_query_data \b Inout. A previously created query object that
 *            is provided for potential reuse and update of its filter.
 * @param content \b In. The filter to be applied. Cannot be null.
 *
 * @return The new or updated query object.
 *
 * @see RTI_RoutingServiceSelectorStateQueryData
 * @see RTI_RoutingServiceSelectorContent
 */
extern ROUTERDllExport
RTI_RoutingServiceSelectorStateQueryData
RTI_RoutingServiceInput_create_content_query(
        RTI_RoutingServiceInput *self,
        RTI_RoutingServiceSelectorStateQueryData old_query_data,
        const struct RTI_RoutingServiceSelectorContent *content);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Deletes a content query created from this Input.
 *
 * @pre Input is enabled
 *
 * @param self \b In. Input used to create the content query. Cannot be null.
 * @param query_data \b In. The query object to be deleted. Cannot be null.
 *
 * @return \c DDS_BOOLEAN_FALSE if the operation fails, \c DDS_BOOLEAN_TRUE
 *         otherwise.
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceInput_delete_content_query(
        RTI_RoutingServiceInput *self,
        RTI_RoutingServiceSelectorStateQueryData query_data);
 
/*
 * --- RTI_RoutingServiceOutput -----------------------------------------------
 */
 
struct RTI_RoutingServiceOutputImpl;
 
typedef struct RTI_RoutingServiceOutputImpl RTI_RoutingServiceOutput;
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the name of the specified output.
 *
 * The output name is given by the attribute of the corresponding XML tag
 * in the configuration.
 *
 * @param self \b In. Output for which the name is required.
 *
 */
extern ROUTERDllExport
const char* RTI_RoutingServiceOutput_get_name(RTI_RoutingServiceOutput *self);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the type information associated with the specified Output.
 * The type information refers to the format of the stream that this Output's
 * write operation expects to receive from the processor of the route.
 *
 * The TypeInformation may be the one coming from the Transformation if this
 * Output has one. In this case, the type information is the one corresponding
 * to the Output side of the Transformation.
 *
 * @param self \b In. Output for which the type information is required. Cannot
 *            be null.
 */
extern ROUTERDllExport
const struct RTI_RoutingServiceStreamInfo *
RTI_RoutingServiceOutput_get_stream_info(RTI_RoutingServiceOutput *self);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Writes a list of data and information samples.
 *
 * @pre Output enabled
 *
 * @param self \b In. The Output where to write the samples. Cannot be null.
 * @param sample_array \b In. Array of samples to write. Cannot be null.
 * @param sample_info_array \b In. Array of information samples to write.
 * @param array_length \b Inout. The length of the sample and info arrays.
 *            Output is the number of samples written. Cannot be null.
 *
 * @return \c DDS_BOOLEAN_FALSE if the write operation was not successful.
 *         \c DDS_BOOLEAN_TRUE otherwise.
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceOutput_write(
        RTI_RoutingServiceOutput *self,
        const RTI_RoutingServiceSample *sample_array,
        const RTI_RoutingServiceSampleInfo *sample_info_array,
        int *array_length);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Writes a single sample, optionally with metatada indicated by an info
 * sample
 *
 * @pre Output enabled
 *
 * @param self \b In. The Output where to write the samples. Cannot be null.
 * @param data \b In. Data sample to be written. Cannot be null.
 * @param info \b In. Associated information sample.
 *
 * @return \c DDS_BOOLEAN_FALSE if the sample could not be written,
 *         \c DDS_BOOLEAN_TRUE otherwise.
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceOutput_write_sample(
        RTI_RoutingServiceOutput *self,
        const RTI_RoutingServiceSample data,
        const RTI_RoutingServiceSampleInfo info);
 
/*
 * --- RTI_RoutingServiceRoute ------------------------------------------------
 */
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the number of inputs associated with this Route.
 *
 */
extern ROUTERDllExport
int RTI_RoutingServiceRoute_get_input_count(RTI_RoutingServiceRoute *self);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Checks whether the Input with the specified index is enabled.
 *
 * @pre index >= 0 and index < RTI_RoutingServiceRoute_get_input_count(self)
 *
 * Note: This function will return \c DDS_BOOLEAN_FALSE both when all the parameters
 * are correct and the input is disabled, or when any of the parameters are
 * incorrect. It's the responsibility of the caller to ensure the parameters are
 * valid, so that the returned value is, too.
 *
 * @param self \b In. The Route for which to check the Input status. Cannot be
 *            null.
 * @param index \b In. The index, starting at 0, of the Input for which the
 *            status is required.
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceRoute_is_input_enabled(
        RTI_RoutingServiceRoute *self,
        int index);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the Input at the specified index.
 *
 * @pre index >= 0 and index < RTI_RoutingServiceRoute_get_input_count(self)
 *
 * Inputs are ordered according to the order of input declarations in the XML
 * configuration. Then indexes are assigned increasingly starting at zero from
 * the first declaration.
 *
 * @return The Input at the specified index, or \c NULL if the Input is not
 *         enabled or the index is out of bounds.
 */
extern ROUTERDllExport
RTI_RoutingServiceInput * RTI_RoutingServiceRoute_get_input_at(
        RTI_RoutingServiceRoute *self,
        int index);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Looks up the specified Input by its configuration name.
 *
 * The Input configuration name is the value of the name attribute specified
 * within the &lt;input&gt; tag in the XML configuration.
 *
 * \b NOTE: The condition that the input must be enabled will be removed
 * in a future version. This is being tracked with issue ID ROUTING-1131.
 *
 * @param self \b In. The Route for which to obtain the Input. Cannot be null.
 * @param input_name \b In. Name of the input configuration. Cannot be null.
 *
 * @return The Input corresponding to the specified configuration name or
 * NULL if it could not be found or if the input is not enabled.
 */
extern ROUTERDllExport
RTI_RoutingServiceInput * RTI_RoutingServiceRoute_lookup_input_by_name(
        RTI_RoutingServiceRoute *self,
        const char *input_name);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the number of outputs associated with this Route.
 *
 */
extern ROUTERDllExport
int RTI_RoutingServiceRoute_get_output_count(RTI_RoutingServiceRoute *self);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Checks whether the Output at the specified index is enabled.
 *
 * @pre index >= 0 and index < RTI_RoutingServiceRoute_get_output_count(self)
 *
 * Note: This function will return \c DDS_BOOLEAN_FALSE both when all the parameters
 * are correct and the output is disabled, or when any of the parameters are
 * incorrect. It's the responsibility of the caller to ensure the parameters are
 * valid, so that the returned value is, too.
 *
 * @param self \b In. The Route for which to check the Output status. Cannot be
 *            null.
 * @param index \b In. The index, starting at 0, of the Output for which the
 *            status is required.
 */
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceRoute_is_output_enabled(
        RTI_RoutingServiceRoute *self,
        int index);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the Output at the specified index.
 *
 * @pre index >= 0 and index < RTI_RoutingServiceRoute_get_output_count(self)
 *
 * Outputs are ordered according to the order of output declarations in the XML
 * configuration. Then indexes are assigned increasingly starting at zero from
 * the first declaration.
 *
 * @return The Output at the specified index, or \c NULL if the Output is not
 *         enabled or the index is out of bounds.
 */
extern ROUTERDllExport
RTI_RoutingServiceOutput * RTI_RoutingServiceRoute_get_output_at(
        RTI_RoutingServiceRoute *self,
        int index);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Looks up the specified Output by its configuration name.
 *
 * The Output configuration name is the value of the name attribute specified
 * within the &lt;output&gt; tag in the XML configuration.
 *
 * \b NOTE: The condition that the input must be enabled will be removed
 * in a future version. This is being tracked with issue ID ROUTING-1131.
 *
 * @param self \b In. The Route for which to obtain the Output. Cannot be null.
 * @param output_name \b In. Name of the output configuration. Cannot be null.
 *
 * @return The Output corresponding to the specified configuration name or
 * NULL if it could not be found or if the output is not enabled.
 */
extern ROUTERDllExport
RTI_RoutingServiceOutput * RTI_RoutingServiceRoute_lookup_output_by_name(
        RTI_RoutingServiceRoute *self,
        const char * output_name);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Sends a wakeup event to the specified Route.
 * This operation can be safely called from any thread context.
 */
extern ROUTERDllExport
void RTI_RoutingServiceRoute_wakeup_route(RTI_RoutingServiceRoute *route);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Get the current period of the periodic event for this Route.
 *
 * @param self \b In. The Route for which to obtain the period. Cannot be null.
 * @param period \b Out. The current periodic event period.
 */
extern ROUTERDllExport
void RTI_RoutingServiceRoute_get_period(
        RTI_RoutingServiceRoute *self,
        struct DDS_Duration_t *period);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Changes the periodic event period for this route.
 *
 * @pre not DDS_Duration_is_zero(period)
 * @pre not DDS_Duration_is_infinite(period)
 *
 * This operation can be called many times within the same periodic event, in
 * which only the last call will make effect.
 *
 * The operation has no effect if the periodic event is not enabled in the
 * route.
 *
 * @param self \b In. The Route for which to set the period. Cannot be null.
 * @param period \b In. New session period for periodic events.
 *
 */
extern ROUTERDllExport
void RTI_RoutingServiceRoute_set_period(
        RTI_RoutingServiceRoute *self,
        const struct DDS_Duration_t *period);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the first enabled Input in this route.
 *
 * This function, along with RTI_RoutingServiceRoute_get_next_input(), provides
 * iterator-based capabilities to iterate through a Route's enabled Inputs.
 *
 */
extern ROUTERDllExport
RTI_RoutingServiceInput * RTI_RoutingServiceRoute_get_first_input(
        RTI_RoutingServiceRoute *self);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the next enabled Input sibling to the specified input.
 *
 * This function, along with RTI_RoutingServiceRoute_get_first_input(), provides
 * iterator-based capabilities to iterate through a Route's enabled Inputs.
 */
extern ROUTERDllExport
RTI_RoutingServiceInput * RTI_RoutingServiceRoute_get_next_input(
        RTI_RoutingServiceRoute *self,
        RTI_RoutingServiceInput *prev_input);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the first enabled output in this route
 *
 * This function, along with RTI_RoutingServiceRoute_get_next_output(), provides
 * iterator-based capabilities to iterate through a Route's enabled Outputs.
 */
extern ROUTERDllExport
RTI_RoutingServiceOutput * RTI_RoutingServiceRoute_get_first_output(
        RTI_RoutingServiceRoute *self);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the next enabled Output sibling to the specified output.
 *
 * This function, along with RTI_RoutingServiceRoute_get_first_output(), provides
 * iterator-based capabilities to iterate through a Route's enabled Outputs.
 */
extern ROUTERDllExport
RTI_RoutingServiceOutput * RTI_RoutingServiceRoute_get_next_output(
        RTI_RoutingServiceRoute *self,
        RTI_RoutingServiceOutput *prev_output);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the fully-qualified name of this Route, derived from the
 * XML configuration.
 *
 */
extern ROUTERDllExport
const char* RTI_RoutingServiceRoute_get_full_name(
        RTI_RoutingServiceRoute *self);
 
/*****************************************************************************/
/* RouteEvent                                                                */
/*****************************************************************************/
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Representation of the different event kinds triggered for a Route.
 *
 */
typedef enum {
 
    RTI_ROUTING_SERVICE_ROUTE_EVENT_NONE = 0,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_INPUT_ENABLED,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_INPUT_DISABLED,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_OUTPUT_ENABLED,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_OUTPUT_DISABLED,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_ROUTE_STARTED,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_ROUTE_STOPPED,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_ROUTE_RUNNING,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_ROUTE_PAUSED,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_DATA_ON_INPUTS,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_PERIODIC_ACTION,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_OUTPUT_STREAM_REQUEST,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_WAKEUP,
    RTI_RoutingServiceRouteEventKind_COUNT,
    RTI_ROUTING_SERVICE_ROUTE_EVENT_ALL = 0xffffffff,
 
} RTI_RoutingServiceRouteEventKind;
 
 
/*i \ingroup RTI_RoutingServiceProcessorModule
 *
 */
struct RTI_RoutingServiceRouteEventImpl;
 
/*i \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief An event which indicates that an action occurred in a Route.
 *
 */
typedef struct RTI_RoutingServiceRouteEventImpl RTI_RoutingServiceRouteEvent;
 
/*e
 * \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the kind of this RouteEvent.
 *
 * @return The Route that triggered the event, or
 *         \c RTI_ROUTING_SERVICE_ROUTE_EVENT_NONE if the parameter passed is
 *         \c null.
 */
extern ROUTERDllExport
RTI_RoutingServiceRouteEventKind RTI_RoutingServiceRouteEvent_get_kind(
        RTI_RoutingServiceRouteEvent *self);
 
/*e
 * \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the Route that triggered the event.
 *
 * @return The Route that triggered the event, or \c NULL if the parameter
 *         passed is null.
 */
extern ROUTERDllExport
RTI_RoutingServiceRoute * RTI_RoutingServiceRouteEvent_get_route(
        RTI_RoutingServiceRouteEvent *self);
 
/*e
 * \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the data associated with the event.
 *
 * The event data depends on the kind of events. See documentation of individual
 * events for the type of event data they provide.
 *
 * @return The data associated with the event, or \c NULL if the parameter
 *         passed is null.
 */
extern ROUTERDllExport
void * RTI_RoutingServiceRouteEvent_get_event_data(
        RTI_RoutingServiceRouteEvent *self);
 
/*e
 * \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Returns the entity that is directly affected by the event.
 *
 * Each kind of event can be affected by different types of entities.
 * See documentation of individual events for the type of affected entity.
 *
 * @return The entity affected by the event, or \c NULL if the parameter
 *         passed is null.
 */
extern ROUTERDllExport
void * RTI_RoutingServiceRouteEvent_get_affected_entity(
        RTI_RoutingServiceRouteEvent *self);
 
/*
-----------------------------------------------------------------------------
 Processor
-----------------------------------------------------------------------------
*/
 
struct RTI_RoutingServiceProcessor;
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Prototype of the function that processes an event that occurred in the
 * Route where the Processor is installed.
 *
 * @param processor_data \b In. Implementation data of the Processor associated
 *             with the Route that triggered the event.
 * @param route_event \b In. Event that was triggered within the Route.
 * @param env \b Out. Environment for error indications.
 *
*/
typedef void (*RTI_RoutingServiceProcessor_OnRouteEventFcn)(
        void * processor_data,
        RTI_RoutingServiceRouteEvent * route_event,
        RTI_RoutingServiceEnvironment * env);
 
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Prototype of the function that updates a Processor configuration.
 *
 * @param processor_data \b In. Implementation data.
 * @param properties \b In. New configuration properties.
 * @param env \b Out. Environment for error indications.
 *
 */
typedef void (*RTI_RoutingServiceProcessor_UpdateFcn)(
        void * processor_data,
        const struct RTI_RoutingServiceProperties * properties,
        RTI_RoutingServiceEnvironment * env);
 
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Main Processor class.
 *
 * A Route can notify a Processor about different events related to inputs
 * and outputs.
 *
 * @see RTI_RoutingServiceRouteEvent
 */
struct RTI_RoutingServiceProcessor{
 
    /*e @brief Handles event processing (\b required). */
    RTI_RoutingServiceProcessor_OnRouteEventFcn on_route_event;
 
    /*e @brief Handles configuration changes in a Processor (\b optional). */
    RTI_RoutingServiceProcessor_UpdateFcn update;
 
    /*e
     * @brief Implementation data. Provided by implementors, and passed back
     *         in API calls.
     */
    void * processor_data;
};
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Entry point for creating and deleting Processor objects.
 *
 */
struct RTI_RoutingServiceProcessorPlugin;
 
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Prototype of the function that creates a ProcessorPlugin.
 *
 * @param properties \b In. Configuration properties for the ProcessorPlugin.
 * @param env \b Out. Environment for error indications.
 *
 * @return New ProcessorPlugin instance if successful. Otherwise, \c NULL.
 *
 * @see RTI_RoutingServiceProcessorPlugin_DeleteFcn
 */
typedef struct RTI_RoutingServiceProcessorPlugin *
(*RTI_RoutingServiceProcessorPlugin_CreateFcn)(
        const struct RTI_RoutingServiceProperties * properties,
        RTI_RoutingServiceEnvironment * env);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Prototype of the function that deletes a ProcessorPlugin.
 *
 * @param plugin \b In. ProcessorPlugin to be deleted.
 * @param env \b Out. Environment for error indications.
 *
 * @see RTI_RoutingServiceProcessorPlugin_CreateFcn
 */
typedef void (*RTI_RoutingServiceProcessorPlugin_DeleteFcn)(
        struct RTI_RoutingServiceProcessorPlugin * plugin,
        RTI_RoutingServiceEnvironment * env);
 
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Prototype of the function that creates a route Processor.
 *
 * This function is called when a Processor is created.
 *
 * @param processor_plugin_data implementation data of the plugin from which the
 *            Processor is created
 * @param route Processor to be deleted.
 * @param properties Configuration properties for the Processor.
 *            These properties correspond to the properties specified
 *            within the tag &lt;processor&gt;.
 * @param env Environment for error indications.
 *
 * @return New processor if successful. Otherwise, error.
 *
 * @see RTI_RoutingServiceProcessorPlugin#DeleteProcessorFcn
*/
typedef struct RTI_RoutingServiceProcessor *
(*RTI_RoutingServiceProcessorPlugin_CreateProcessorFcn)(
        void * processor_plugin_data,
        RTI_RoutingServiceRoute * route,
        const struct RTI_RoutingServiceProperties * properties,
        RTI_RoutingServiceEnvironment * env);
 
/*i \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Prototype of the function that deletes a Processor.
 *
 * This function is called when a Processor is deleted
 *
 * @param processor_plugin_data implementation data of the plugin from which the
 *            Processor is deleted.
 * @param processor Processor to be deleted.
 * @param env Environment for error indications.
 *
 * @see RTI_RoutingServiceProcessorPlugin_CreateProcessorFcn
*/
typedef void (*RTI_RoutingServiceProcessorPlugin_DeleteProcessorFcn)(
        void * processor_plugin_data,
        struct RTI_RoutingServiceProcessor * processor,
        RTI_RoutingServiceRoute * route,
        RTI_RoutingServiceEnvironment * env);
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief ProcessorPlugin class.
 *
 * ProcessorPlugins are the entry points to the Processor API. They provide a
 * factory for Processors.
*/
struct RTI_RoutingServiceProcessorPlugin {
    int _init;
    struct RTI_RoutingServiceVersion _rs_version;
 
    /*e
     * @brief The version of this ProcessorPlugin.
     */
    struct RTI_RoutingServiceVersion plugin_version;
 
    /*e
     * @brief Handles the deletion of the ProcessorPlugin.
     */
    RTI_RoutingServiceProcessorPlugin_DeleteFcn plugin_delete;
 
    /*e
     * @brief Handles the creation of Processors.
     */
    RTI_RoutingServiceProcessorPlugin_CreateProcessorFcn create_processor;
 
    /*e
     * @brief Handles the deletion of Processors.
     */
    RTI_RoutingServiceProcessorPlugin_DeleteProcessorFcn delete_processor;
 
    /*e
     * @brief A placeholder for Processor implementors to keep a pointer to data
     *        that may be needed by the implementation.
     */
    void * processor_plugin_data;
};
 
#define RTI_ROUTING_SERVICE_PROCESSOR_PLUGIN_INIT_NUMBER (8765432)
 
/*e \ingroup RTI_RoutingServiceProcessorModule
 *
 * @brief Utility macro to initialize a ProcessorPlugin object.
 *
 * This macro must be called to initialize the value returned by
 * RTI_RoutingServiceProcessorPlugin_CreateFcn.
 *
 * @param plugin Pointer to the ProcessorPlugin object.
 *
 * @see RTI_RoutingServiceProcessorPlugin_CreateFcn
*/
#define RTI_RoutingServiceProcessorPlugin_initialize(plugin)                  \
{                                                                             \
    struct RTI_RoutingServiceVersion rsVersion = RTI_ROUTING_SERVICE_VERSION; \
    struct RTI_RoutingServiceVersion processorVersion = {0,0,0,0};            \
    (plugin)->_init = RTI_ROUTING_SERVICE_PROCESSOR_PLUGIN_INIT_NUMBER;       \
    (plugin)->_rs_version = rsVersion;                                        \
    (plugin)->plugin_version = processorVersion;                              \
    (plugin)->plugin_delete = 0;                                              \
    (plugin)->create_processor = 0;                                           \
    (plugin)->delete_processor = 0;                                           \
    (plugin)->processor_plugin_data = 0;                                      \
}
 
#ifdef __cplusplus
}       /* extern "C" */
#endif
 
#endif /* routingservice_processor_h */