/*
 * (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_transformation_h
#define routingservice_transformation_h

#include "routingservice/routingservice_infrastructure.h"

#ifdef __cplusplus
    extern "C" {
#endif

/*e \file
  @brief RTI Routing Service Transformation API
*/

/*e \defgroup RTI_RoutingServiceTransformationModule RTI Routing Service Transformation API
 \ingroup ROUTER
 @brief This module describes the Transformation API.

 An \product route transforms the incoming data using a \em transformation, which is an
 object created by a transformation plugin.<br>

 Transformation plugins implement the transformation API described in this module and
 must be provided as shared libraries that RTI \product will load dynamically.

 To register a transformation plugin with \product, you must use the tag
 &lt;transformation_plugin&gt; within &lt;transformation_library&gt;. For example:

 \verbatim
 <dds>
     ...
     <transformation_library name="MyTransfLib">
         <transformation_plugin name="MyTransfPlugin">
             <dll>mytransformation</dll>
             <create_function>
                MyTransfPlugin_create
            </create_function>
        </transformation_plugin>
        ...
     </transformation_library>
     ...
     <routing_service>
     ...
     </routing_service>
     ...
 </dds>
 \endverbatim

 Once a transformation plugin is registered, an Output can use it to create a data transformation.
 For example:

 \verbatim
 <topic_route name="SquareSwitchCoord">
     <input participant="1">
         <topic_name>Square</topic_name>
         <registered_type_name>ShapeType</registered_type_name>
     </input>
     <output>
         <topic_name>Square</topic_name>
         <registered_type_name>ShapeType</registered_type_name>
     </output>
     <transformation plugin_name="MyTransfLib::MyTransPlugin">
         <property>
             <value>
                 <element>
                     <name>X</name>
                     <value>Y</value>
                 </element>
                 <element>
                     <name>Y</name>
                     <value>X</value>
                 </element>
             </value>
         </property>
     </transformation>
 </topic_route>
 \endverbatim

 For additional information on configuring transformations, see the \ref_url_routing_service_users_manual.

 \section Requirements Development Requirements

 <table border="1" cellspacing="1">
    <tr>
        <td></td>
        <td>Linux or macOS Systems</td>
        <td>Windows Systems</td>
    </tr>
    <tr>
        <td><b>Shared Library</b></td>
        <td>librtirsinfrastructure.so<br>
            <br>
            If the transformation must work with adapters providing DDS_DynamicData or DDS_SampleInfo (such as the built-in DDS adapter):<br>
            libnddsc.so and libnddscore.so
        </td>
        <td>rtirsinfrastructure.dll<br>
            <br>
            If the transformation must work with adapters providing DDS_DynamicData or DDS_SampleInfo (such as the built-in DDS adapter):<br>
            nddsc.dll and nddscore.dll
        </td>
    </tr>
    <tr>
        <td><b>Header</b></td>
        <td colspan="2">
            routingservice_transformation.h<br>
            <br>
            If the transformation must work with adapters providing DDS_DynamicData or DDS_SampleInfo (such as the built-in DDS adapter):
            ndds_c.h
        </td>
    </tr>
 </table>
*/
struct RTI_RoutingServiceTransformationPlugin;

/*e \ingroup RTI_RoutingServiceTransformationModule
  \brief Transformation.

  A route can transform the incoming data using transformation objects.

  The transformation objects are created by transformation plugins.
*/
typedef void * RTI_RoutingServiceTransformation;

/*e \ingroup RTI_RoutingServiceTransformationModule
 \brief Prototype of the function that creates a transformation plugin.

 The name of the function that implements this prototype
 must be provided to \product using the tag &lt;create_function&gt;
 when the transformation plugin is registered.

 For example:

 \verbatim
 <plugin_library name="MyTransfLib">
     <transformation_plugin name="MyTransfPlugin">
         <dll>mytransformation</dll>
         <create_function>
            MyTransfPlugin_create
         </create_function>
     </transformation_plugin>
     ...
 </plugin_library>
 \endverbatim

 This is the only function that is not part of
 \ref RTI_RoutingServiceTransformationPlugin.

 <b>Required:</b> yes

 @param properties \rs_st_in Configuration properties for the transformation.

 @param env \rs_st_inout Environment for error indications.

 @return New plugin instance if successful. Otherwise, NULL.

 @see \ref RTI_RoutingServiceTransformationPlugin_DeleteFcn
*/
typedef struct RTI_RoutingServiceTransformationPlugin *(
        *RTI_RoutingServiceTransformationPlugin_CreateFcn)(
        const struct RTI_RoutingServiceProperties *properties,
        RTI_RoutingServiceEnvironment *env);

/*e \ingroup RTI_RoutingServiceTransformationModule
 \brief Prototype of the function that deletes a transformation plugin.

 Transformation plugins are deleted when \product is closed.

 <b>Required:</b> yes

 @param plugin \rs_st_in Transformation plugin to be deleted.
 @param env \rs_st_inout Environment for error indications.

 @see \ref RTI_RoutingServiceTransformationPlugin_CreateFcn
*/
typedef void (*RTI_RoutingServiceTransformationPlugin_DeleteFcn)(
        struct RTI_RoutingServiceTransformationPlugin *plugin,
        RTI_RoutingServiceEnvironment *env);

/*e \ingroup RTI_RoutingServiceTransformationModule
 \brief Prototype of the function that creates a route transformation.

 This function is called when the route containing the transformation
 is ready to forward data.

 The format associated with the input and output types depends on
 the format provided by the route adapters.

 For the built-in DDS adapter, the format of the types is DDS_TypeCode.

 <b>Required:</b> yes

 @param plugin \rs_st_in Transformation plugin that will be used to create the transformation.
 @param input_type_info \rs_st_in Type information associated with the input samples.
 @param output_type_info \rs_st_in Type information associated with the output samples.
 @param properties \rs_st_in Configuration properties for the transformation.
 These properties corresponds to the properties specified within the tag &lt;transformation&gt;.
 @param env \rs_st_inout Environment for error indications.

 @return New transformation if successful. Otherwise, error.

 @see \ref RTI_RoutingServiceTransformationPlugin_DeleteTransformationFcn
*/
typedef RTI_RoutingServiceTransformation (
        *RTI_RoutingServiceTransformationPlugin_CreateTransformationFcn)(
        struct RTI_RoutingServiceTransformationPlugin *plugin,
        const struct RTI_RoutingServiceTypeInfo *input_type_info,
        const struct RTI_RoutingServiceTypeInfo *output_type_info,
        const struct RTI_RoutingServiceProperties *properties,
        RTI_RoutingServiceEnvironment *env);

/*e \ingroup RTI_RoutingServiceTransformationModule
 \brief Prototype of the function that deletes a transformation.

 This function is called when the route containing the transformation is disabled.

 @param plugin \rs_st_in Transformation plugin that will be used to delete the transformation.
 @param transformation \rs_st_in Transformation to be deleted.
 @param env \rs_st_inout Environment for error indications.

 @see \ref RTI_RoutingServiceTransformationPlugin_CreateTransformationFcn
*/
typedef void (*RTI_RoutingServiceTransformationPlugin_DeleteTransformationFcn)(
        struct RTI_RoutingServiceTransformationPlugin *plugin,
        RTI_RoutingServiceTransformation transformation,
        RTI_RoutingServiceEnvironment *env);

/*e \ingroup RTI_RoutingServiceTransformationModule

 \brief Prototype of the function that transforms a sequence of input
 samples into a sequence of output samples.

 When \product is done using the output samples, it will 'return the loan'
 to the transformation by calling \ref RTI_RoutingServiceTransformation_ReturnLoanFcn.

 The number of output samples can be different than the number of input samples.

 The memory used by the output samples and sample infos is managed by the transformation.
 The transformation must allocate the memory for the output samples and sample infos
 and free it when \product calls \ref RTI_RoutingServiceTransformation_ReturnLoanFcn.

 The format associated with the input and output samples and sample infos depends on
 the format provided and consumed by the route StreamReader and StreamWriter.

 For the built-in DDS adapter, the format of the samples is DDS_DynamicData and the format
 of the sample info is DDS_SampleInfo.

 <b>Required:</b> yes

 @param transformation \rs_st_in Transformation that will transform the samples.
 @param out_sample_lst \rs_st_out Array that will hold the output samples.
 This array will be provided by the transformation. *Note*: A transformation
 cannot return the input sample array as the output sample array;
 otherwise \product will fail. In general, the memory used for the output samples
 should be managed by the transformation.
 @param out_info_lst \rs_st_out Array that will hold the output sample infos.
 This array will be provided by the transformation. *Note*: A transformation
 cannot return the input sample info array as the output info array;
 otherwise \product will fail. In general, the memory used for the
 output sample infos should be managed by the transformation and freed when
 \product calls \ref RTI_RoutingServiceTransformation_ReturnLoanFcn.
 @param out_count \rs_st_out Number of output samples. The value must be greater
 than or equal to zero.
 @param in_sample_lst \rs_st_in Array of input samples.
 @param in_info_lst \rs_st_in Array of input sample infos.
 @param in_count \rs_st_in Number of input samples.
 @param env \rs_st_inout Environment for error indications.

 @see \ref RTI_RoutingServiceTransformation_ReturnLoanFcn
*/
typedef void (*RTI_RoutingServiceTransformation_TransformFcn)(
        RTI_RoutingServiceTransformation transformation,
        RTI_RoutingServiceSample **out_sample_lst,
        RTI_RoutingServiceSampleInfo **out_info_lst,
        int *out_count,
        RTI_RoutingServiceSample *in_sample_lst,
        RTI_RoutingServiceSampleInfo *in_info_lst,
        int in_count,
        RTI_RoutingServiceEnvironment *env);

/*e \ingroup RTI_RoutingServiceTransformationModule
 \brief Prototype of the function that returns the loan on the output samples
 and infos.

 This function is called by \product to indicate that it is done accessing the
 array of data samples obtained by an earlier invocation of
 \ref RTI_RoutingServiceTransformation_TransformFcn.

 The memory used by the output samples and sample infos is managed by the
 transformation and should be freed in this call if it was allocated when
 \product calls \ref RTI_RoutingServiceTransformation_ReturnLoanFcn.

 <b>Required:</b> yes

 @param transformation \rs_st_in Transformation that owns the samples and sample infos.
 @param sample_lst \rs_st_in Array of samples.
 @param info_lst \rs_st_in Array of sample infos.
 @param count \rs_st_in Number of samples in the array.
 @param env \rs_st_inout Environment for error indications.
*/
typedef void (*RTI_RoutingServiceTransformation_ReturnLoanFcn)(
        RTI_RoutingServiceTransformation transformation,
        RTI_RoutingServiceSample *sample_lst,
        RTI_RoutingServiceSampleInfo *info_lst,
        int count,
        RTI_RoutingServiceEnvironment *env);

/*e \ingroup RTI_RoutingServiceTransformationModule
 \brief Prototype of the function that updates a transformation configuration.

 @param transformation \rs_st_in Transformation.
 @param properties \rs_st_in New configuration properties.
 @param env \rs_st_inout Environment for error indications.
*/
typedef void (*RTI_RoutingServiceTransformation_UpdateFcn)(
        RTI_RoutingServiceTransformation transformation,
        const struct RTI_RoutingServiceProperties *properties,
        RTI_RoutingServiceEnvironment *env);

/*e \ingroup RTI_RoutingServiceTransformationModule
  \brief Transformation plugin.

  This structure contains the plugin implementation as a set of function pointers.
*/
struct RTI_RoutingServiceTransformationPlugin {
    int _init;
    struct RTI_RoutingServiceVersion _rs_version;

    /*e \brief The version of this transformation plugin */
    struct RTI_RoutingServiceVersion plugin_version;

    /*e \brief Handles the deletion of the transformation plugin. */
    RTI_RoutingServiceTransformationPlugin_DeleteFcn
        transformation_plugin_delete;
    /*e \brief Handles the creation of transformations. */
    RTI_RoutingServiceTransformationPlugin_CreateTransformationFcn
	transformation_plugin_create_transformation;
    /*e \brief Handles the deletion of transformations. */
    RTI_RoutingServiceTransformationPlugin_DeleteTransformationFcn
	transformation_plugin_delete_transformation;

    /*e \brief Handles the transformation of samples. */
    RTI_RoutingServiceTransformation_TransformFcn transformation_transform;
    /*e \brief Handles the return of the loan taken on the transformed samples. */
    RTI_RoutingServiceTransformation_ReturnLoanFcn transformation_return_loan;
    /*e \brief Handles the update of the transformation configuration. */
    RTI_RoutingServiceTransformation_UpdateFcn transformation_update;

    /*e @brief A place for transformation implementors to keep a pointer to data that
        may be needed by the implementation. */
    void * user_object;
};



#define RTI_ROUTING_SERVICE_TRANSFORMATION_PLUGIN_INIT_NUMBER (9876543)
/*e \ingroup RTI_RoutingServiceTransformationModule
 \hideinitializer
 @brief Initializes the plugin structure.

 This macro must be called to initialize the
 return value of RTI_RoutingServiceTransformationPlugin_CreateFcn

 @param transf Pointer to the transformation plugin structure

 @see \ref RTI_RoutingServiceTransformationPlugin_CreateFcn
*/
#define RTI_RoutingServiceTransformationPlugin_initialize(transf)             \
{                                                                             \
    struct RTI_RoutingServiceVersion rsVersion = RTI_ROUTING_SERVICE_VERSION; \
    struct RTI_RoutingServiceVersion transfVersion = {0,0,0,0};               \
    (transf)->_init = RTI_ROUTING_SERVICE_TRANSFORMATION_PLUGIN_INIT_NUMBER;  \
    (transf)->_rs_version = rsVersion;                                        \
    (transf)->plugin_version = transfVersion;                                 \
    (transf)->transformation_plugin_delete = 0;                               \
    (transf)->transformation_plugin_create_transformation = 0;                \
    (transf)->transformation_plugin_delete_transformation = 0;                \
    (transf)->transformation_transform = 0;                                   \
    (transf)->transformation_return_loan = 0;                                 \
    (transf)->transformation_update = 0;                                      \
    (transf)->user_object = 0;                                                \
}

#ifdef __cplusplus
}	/* extern "C" */
#endif

#endif /* routingservice_transformation_h */