rt_rt.h

/*
 * FILE: rt_log.h - RT API
 *
 * Copyright 2011-2014 Real-Time Innovations, Inc.
 *
 * 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.
 *
 * Modification History
 * --------------------
 * 15may2014,tk MICRO-791 Return RTI_INT32, not RTI_BOOL, in compare function
 * 05may2014,tk MICRO-72  Updated based on CR-232
 * 22apr2014,tk MICRO-82  Removed run method, kept base interface class
 * 12dec2011,tk Written
 */
/*ci
 * \file
 *
 * \brief The Run-Time interface provides generic mechanism to handle
 *        extension to RTI Connext Micro.
 *
 * \defgroup RT_RunTimeClass RT
 * \ingroup RTModule
 *
 * \details
 *
 * The Run-Time (RT) provides a basic mechanism to handle optional components.
 * Components can be registered and looked up based on a name.
 */
/*ci \addtogroup RT_RunTimeClass
 *   @{
 */
#ifndef rt_rt_h
#define rt_rt_h

#ifndef rt_dll_h
#include "rt/rt_dll.h"
#endif

#ifndef osapi_types_h
#include "osapi/osapi_types.h"
#endif

#ifndef osapi_timer_h
#include "osapi/osapi_timer.h"
#endif

#ifndef reda_circularlist_h
#include "reda/reda_circularlist.h"
#endif

#ifndef db_api_h
#include "db/db_api.h"
#endif

#ifdef __cplusplus
extern "C"
{
#endif

/*ci
 *   @}
 */
#ifndef NULL
#define NULL ((void*)0)
#endif

/*******************************************************************************
 *                               RTConstants
 ******************************************************************************/
#define RT_MKINTERFACEID(class_,instance_) \
                       ((((class_)<<16)&0xffff0000) | (instance_))

#define RT_INTERFACE_CLASS(id_)     ((id_) >> 16)
#define RT_INTERFACE_INSTANCE(id_)  ((id_) & 0xffff)

/* INTERFACE CLASSES */
#define RT_COMPONENT_CLASS_UNKNOWN              (0x0000)
#define RT_COMPONENT_CLASS_DISCOVERY            (0x0001)
#define RT_COMPONENT_CLASS_WHISTORY             (0x0002)
#define RT_COMPONENT_CLASS_RHISTORY             (0x0003)
#define RT_COMPONENT_CLASS_NETIO                (0x0004)

/* DDS Discovery class components */
#define RT_COMPONENT_INSTANCE_DISCOVERY_DPDE   (1)
#define RT_COMPONENT_INSTANCE_DISCOVERY_DPSE   (2)
#define RT_COMPONENT_INSTANCE_DISCOVERY_GROUP  (3)

/* DDS WriterHistory class components */
#define RT_COMPONENT_INSTANCE_WHISTORY_SM      (1)

/* DDS ReaderHistory class components */
#define RT_COMPONENT_INSTANCE_RHISTORY_SM      (1)

/* NETIO class components */
#define RT_COMPONENT_INSTANCE_UDP              (1)
#define RT_COMPONENT_INSTANCE_RTPS             (2)
#define RT_COMPONENT_INSTANCE_INTRA            (3)
#define RT_COMPONENT_INSTANCE_DDSWI            (4)
#define RT_COMPONENT_INSTANCE_DDSRI            (5)

/*ci \addtogroup RT_RunTimeClass
 *   @{
 */

/*ci
 * \brief Type used to identify components
 */
typedef RTI_UINT32 RT_ComponentInterfaceId_t;

/*******************************************************************************
 *                               RT_Component
 ******************************************************************************/
struct RT_Component;

/*ci
 * \brief Abstract RT_Component type
 */
typedef struct RT_Component RT_Component_T;

/*ci
 * \brief Notify listeners on changes in component state.
 *
 * \details
 *
 * The RT_ComponentListener structure is for future extensions.
 */
struct RT_ComponentListener
{
    /*ci
     * \brief data passed in listeners
     */
    void *data;
};

/*ci
 * \brief Initializer for RT_ComponentListener
 */
#define RT_ComponentListener_INITIALIZER \
{ \
    NULL \
}

/*ci
 * \brief Properties a component can be created with
 */
struct RT_ComponentProperty
{
    /*ci
     * \brief A database to create tables in if needed
     */
    DB_Database_T db;

    /*ci
     * \brief A timer to create timeouts from if needed
     */
    OSAPI_Timer_T timer;
};

#define RT_ComponentProperty_INITIALIZER \
{\
   NULL,\
   NULL \
}

/*ci
 * \brief The component base interface
 */
struct RT_ComponentI
{
    /*ci
     * \brief Some compilers do not allow empty structures. There are
     *        currently no base interface functions required
     */
    RTI_INT32 dummy;
};

/*ci
 * \brief The component base class
 */
struct RT_Component
{
    /*ci
     *\brief All components are are linked together
     */
    REDA_CircularListNode_T _node;

    /*ci
     *\brief Pointer to the component interface
     */
    struct RT_ComponentI *_intf;

    /*ci
     *\brief Implementation specific flags
     */
    RTI_INT32 _flags;

    /*ci
     *\brief The component ind
     */
    RTI_UINT32 id;

    /*ci
     *\brief The listener specified when the component was created
     */
    struct RT_ComponentListener _listener;

    /*ci
     *\brief The properties specified when the component was created
     */
    struct RT_ComponentProperty _property;
};

/*ci
 *
 * \brief Initialize a RT_Component base-class
 *
 * \details
 *
 * All components must initialized the RT_Component base-class by
 * calling this function
 *
 * \param[in] c         The component to initialize
 * \param[in] intf      Pointer to implementation of the RT_ComponentI interface
 * \param[in] id        Unique ID for the component
 * \param[in] property  Properties for the component
 * \param[in] listener  Listeners to call when a component changes
 *
 * \sa \ref RT_Component_finalize
 */
RTDllExport void
RT_Component_initialize(RT_Component_T *c,
                        struct RT_ComponentI *intf,
                        RTI_UINT32 id,
                        const struct RT_ComponentProperty *const property,
                        const struct RT_ComponentListener *const listener);

/*ci
 *
 * \brief Finalize a RT_Component base-class
 *
 * \details
 *
 * All components must be finalized by calling this function
 *
 * \param[in] c The component to finalize
 *
 * \sa \ref RT_Component_initialize
 */
RTDllExport void
RT_Component_finalize(RT_Component_T *c);

#define RT_COMPONENTI_BASE {0}

/*******************************************************************************
 *                               RT_ComponentFactoryI
 ******************************************************************************/
struct RT_ComponentFactory;

/*ci
 * \brief Properties a RT_ComponentFactory can be created with
 */
struct RT_ComponentFactoryProperty
{
    DB_Database_T db;
};

/*ci
 * \brief Initializer for \ref RT_ComponentFactoryProperty
 */
#define RT_ComponentFactoryProperty_INITIALIZER \
{ \
  NULL\
}

/*ci
 * \brief Listeners that can be installed on a RT_ComponentFactoryProperty
 *        when it is created
 */
struct RT_ComponentFactoryListener
{
    void *dummy;
};

/*ci
 * \brief Initializer for \ref RT_ComponentFactoryListener
 */
#define RT_ComponentFactoryListener_INITIALIZER \
{\
   NULL\
}

FUNCTION_MUST_TYPEDEF(
struct RT_ComponentFactory*
(*RT_ComponentFactory_initializeFactoryFunc)(
                                struct RT_ComponentFactoryProperty *property,
                                struct RT_ComponentFactoryListener *listener)
)

typedef void
(*RT_ComponentFactory_finalizeFactoryFunc)(struct RT_ComponentFactory *factory,
                                struct RT_ComponentFactoryProperty **property,
                                struct RT_ComponentFactoryListener **listener);

FUNCTION_MUST_TYPEDEF(
RT_Component_T*
(*RT_ComponentFactory_createFunc)(struct RT_ComponentFactory *factory,
                                  struct RT_ComponentProperty *property,
                                  struct RT_ComponentListener *listener)
)

typedef void
(*RT_ComponentFactory_deleteFunc)(struct RT_ComponentFactory *factory,
                                 RT_Component_T* component);

FUNCTION_MUST_TYPEDEF(
struct RT_ComponentI*
(*RT_ComponentFactory_get_ifFunc)(struct RT_ComponentFactory *factory)
)

#define RT_COMPONENT_FACTORY_ID_DEFAULT (0)

/*ci
 * \brief The RT_ComponentFactory interface
 */
struct RT_ComponentFactoryI
{
    /*ci
     * \brief interface id
     */
    RTI_INT32 id;

    /*ci
     * \brief function to call when the factory is first registered
     */
    RT_ComponentFactory_initializeFactoryFunc initialize;

    /*ci
     * \brief function to call when the factory is unregistered
     */
    RT_ComponentFactory_finalizeFactoryFunc finalize;

    /*ci
     * \brief function to call to create an new instance of a component
     */
    RT_ComponentFactory_createFunc create_component;

    /*ci
     * \brief function to call to delete an instance of a component
     */
    RT_ComponentFactory_deleteFunc delete_component;

    /*ci
     * \brief function to get the components interface implementation
     */
    RT_ComponentFactory_get_ifFunc get_if;
};

#define RT_ComponentFactory_create_component(f_) ((f_)->intf)->create_component

#define RT_ComponentFactory_delete_component(f_) ((f_)->intf)->delete_component

#define RT_ComponentFactory_get_if(f_) ((f_)->intf)->get_if

/*ci
 * \def RT_MAX_FACTORY_NAME
 * \brief Maximum length of a factory name, it does _not_ include \0
 */
#define RT_MAX_FACTORY_NAME 7

/*
 * Structure to represent a compnent name as either a 64 bit integer
 * or name
 */
union RT_ComponentFactoryId
{
    struct
    {
        char _name[RT_MAX_FACTORY_NAME+1];
    } _name;
    struct
    {
        RTI_UINT32 _high;
        RTI_UINT32 _low;
    } _value;
};

/*
 * Abstract type for the factory id
 */
typedef union RT_ComponentFactoryId  RT_ComponentFactoryId_T;

/*ci
 * \def RT_ComponentFactoryId_clear
 *
 * \brief Clear a factory id
 */
#define RT_ComponentFactoryId_clear(id_) \
    { (id_)->_value._high = 0; (id_)->_value._low = 0; }

/*ci
 * \brief A ComponentFactory base-class. All component factories must derive
 *        from this class
 */
struct RT_ComponentFactory
{
    struct RT_ComponentFactoryI *intf;
    struct RT_ComponentFactory *_factory;
    union RT_ComponentFactoryId _id;
};

/*ci
 * \brief Initializer for the \ref RT_ComponentFactory
 */
#define RT_ComponentFactory_INITIALIZER \
{ \
    NULL,\
    NULL,\
    {{0,0}}\
}

typedef struct RT_ComponentFactory RT_ComponentFactory_T;

/*ci
 * \brief Properties a \ref RT_Registry can be created with
 */
struct RT_RegistryProperty
{
    /*ci
     * \brief The maximum number of component factories which can be registered
     */
    RTI_SIZE_T max_factories;

    /*ci
     * \brief A database the component factory can use, if needed
     */
    DB_Database_T db;
};

/*ci
 * \brief Initializer for \ref RT_RegistryProperty
 */
#define RT_RegistryProperty_INITIALIZER \
{ \
    1,\
    NULL\
}

/*ci
 * \brief Default values for \ref RT_RegistryProperty
 */
extern RTDllVariable struct RT_RegistryProperty
                                 RTCOMPONENTFACTORY_REGISTRY_PROPERTY_DEFAULT;

struct RT_Registry;

/*ci
 * \brief Abstract RT_Registry type
 */
typedef struct RT_Registry RT_Registry_T;

/*ci
 * \brief Get the RT_Registry
 *
 * \details
 *
 * The RT_Registry exists as a single instance within a process.
 *
 * \return pointer to registry on success, NULL on failure
 *
 * \sa ref RT_Registry_finalize
 */
SHOULD_CHECK_RETURN RTDllExport RT_Registry_T*
RT_Registry_get_instance(void);

#ifndef RTI_CERT
/*ci
 * \brief Finalize the RT_Registry
 *
 * \details
 *
 * The RT_Registry exists as a single instance within a process. This
 * call finalizes the registry instance. If an already finalized registry
 * is finalized again nothing is done.
 *
 * \return RTI_TRUE on success, RTI_FALSE on failure
 *
 * \sa ref RT_Registry_get_instance
 */
SHOULD_CHECK_RETURN RTDllExport RTI_BOOL
RT_Registry_finalize(RT_Registry_T*);
#endif

/*ci
 * \brief Register a component factory
 *
 * \details
 *
 * In order to make a component available it is necessary to register
 * a factory for the components. The factory is responsible for
 * creating and deleting components. The name must be unqiue, if a factory
 * already exists with the the name the call will fail.
 *
 * \param[in] registry  Registry to register the component factory with
 * \param[in] name      The name of the component factory
 * \param[in] intf      Pointer to the implementation of the factory interface
 * \param[in] property  The properties to create the factory with
 * \param[in] listener  The listener to install with the factory

 * \return RTI_TRUE on success, RTI_FALSE on failure
 *
 * \sa ref RT_Registry_unregister
 */
MUST_CHECK_RETURN RTDllExport RTI_INT32
RT_Registry_register(RT_Registry_T *registry,
                            const char *name,
                            struct RT_ComponentFactoryI *intf,
                            struct RT_ComponentFactoryProperty *property,
                            struct RT_ComponentFactoryListener *listener);

/*ci
 * \brief Unregister a component factory
 *
 * \details
 *
 *  Remove a component factory from the registry. After it is unregistered
 *  it will no longer be possible to create or delete components from this
 *  factory.
 *
 * \param[in]  registry  Registry to register the component factory with
 * \param[in]  name      The name of the component factory
 * \param[out] property  The properties the factory was created with
 * \param[out] listener  The listener to installed with the factory

 * \return RTI_TRUE on success, RTI_FALSE on failure
 *
 * \sa ref RT_Registry_register
 */
SHOULD_CHECK_RETURN RTDllExport RTI_BOOL
RT_Registry_unregister(RT_Registry_T *registry,
                            const char *name,
                            struct RT_ComponentFactoryProperty **property,
                            struct RT_ComponentFactoryListener **listener);

/*ci
 * \brief Find a component factory based on the name
 *
 * \details
 *
 * This function is used to find a component based on its name.
 *
 * \param[in] registry  Registry to search for the component factory in
 * \param[in] name      The name of the component factory to find

 * \return pointer to \ref RT_ComponentFactory on success, NULL on failure
 *
 * \sa ref RT_Registry_lookup_cid
 */
MUST_CHECK_RETURN RTDllExport struct RT_ComponentFactory*
RT_Registry_lookup(RT_Registry_T *registry,const char *name);

/*ci
 * \brief Find a component factory based on the name and class id
 *
 * \details
 *
 * This function is used to find a component based on its name <em> and
 * </em> the class id. If the name exists but is of the wrong class id
 * NULL is returned.
 *
 * \param[in]  registry Registry to search for the component factory in
 * \param[in]  name     The name of the component factory to find
 * \param[in]  cid      Component ID to choose from

 * \return pointer to \ref RT_ComponentFactory on success, NULL on failure
 *
 * \sa ref RT_Registry_lookup
 */
MUST_CHECK_RETURN RTDllExport struct RT_ComponentFactory*
RT_Registry_lookup_cid(RT_Registry_T *registry,const char *name,RTI_INT32 cid);

/*ci
 * \brief Get the current properties for the registry
 *
 * \details
 *
 * This function returns the current properties for the registry
 *
 * \param[in]   registry  Registry to return properties for
 * \param[out]  property  Current properties on successful return

 * \return RTI_TRUE on success, RTI_FALSE on failure
 *
 * \sa ref RT_Registry_set_property
 */
MUST_CHECK_RETURN RTDllExport RTI_BOOL
RT_Registry_get_property(RT_Registry_T *registry,
                        struct RT_RegistryProperty *property);

/*ci
 * \brief Set the properties for the registry
 *
 * \details
 *
 * This function sets the properties for the registry. Note that the properties
 * can only be changed until the first registration takes place.
 *
 * \param[in]  registry  Registry to set properties on
 * \param[in]  property  New registry properties

 * \return RTI_TRUE on success, RTI_FALSE on failure
 *
 * \sa ref RT_Registry_get_property
 */
MUST_CHECK_RETURN RTDllExport RTI_BOOL
RT_Registry_set_property(RT_Registry_T *registry,
                        struct RT_RegistryProperty *property);

/*ci
 * \brief Get the interface of a component factory
 *
 * \details
 *
 * Get the interface of a component factory
 *
 * \param[in]  factory  Factory to return id for
 *
 * \return Factory id
 */
RTDllExport RTI_INT32
RT_ComponentFactory_get_id(struct RT_ComponentFactory *factory);

/*ci
 * \brief Initialize a RT_ComponentFactoryId_T based on the name
 *
 * \details
 *
 * Initialize a RT_ComponentFactoryId_T variable based on the name
 *
 * \param[in]  id   Id to initialize
 * \param[in]  name Name to initialize with
 *
 * \return Factory id
 */
MUST_CHECK_RETURN RTDllExport RTI_BOOL
RT_ComponentFactoryId_set_name(RT_ComponentFactoryId_T *id,
                               const char *const name);

/*ci
 * \brief Return the component factory id as a name
 *
 * \details
 *
 * Return the component factory id as a name
 *
 * \param[in] id Id to return name from
 *
 * \return id as name
 */
MUST_CHECK_RETURN RTDllExport const char*
RT_ComponentFactoryId_get_name(RT_ComponentFactoryId_T *id);

/*ci
 * \brief Compare a component factory id to a name
 *
 * \details
 *
 * Compare a component factory id to a name
 *
 * \param[in] id   Id to compare
 * \param[in] name Name to compare against
 *
 * \return RTI_TRUE if the id is equal to the name
 */
MUST_CHECK_RETURN RTDllExport RTI_BOOL
RT_ComponentFactoryId_equals(RT_ComponentFactoryId_T *id,
                             const char *const name);

/*ci
 * \brief Compare a two component factory ids
 *
 * \details
 *
 * Compare a two component factory ids
 *
 * \param[in] id1 Left side of comparison
 * \param[in] id2 Right side of comparison
 *
 * \return 0 if left = right, < 0 if left < right, > 0 if left > right
 */
MUST_CHECK_RETURN RTDllExport RTI_INT32
RT_ComponentFactoryId_compare(const RT_ComponentFactoryId_T *id1,
                              const RT_ComponentFactoryId_T *id2);

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

#endif

/*ci @} */