ApplicationSupport.h

#ifndef ApplicationSupport_h
#define ApplicationSupport_h

#include "rti_me_c.h"
#include "netio/netio_udp.h"
#include "disc_dpde/disc_dpde_discovery_plugin.h"
#include "disc_dpse/disc_dpse_dpsediscovery.h"

/*i
 * \addtogroup HWAppExModule_AppSupport
 * @{
 */

/*i
 * \brief Value returned by the application to the invoking
 * shell in case of a successful execution.
 */
#define APP_RETVAL_OK                    0
/*i
 * \brief Value returned by the application to the invoking
 * shell in case of an unsuccessful execution.
 */
#define APP_RETVAL_ERROR                -1

/*i
 * \brief Value to indicate that an unlimited number
 * of samples is expected to be written/received.
 */
#define APP_COUNT_UNLIMITED              -1

struct Application;
typedef struct Application Application_t;

/* e
 * \brief User-defined function to read data when some is available.
 */
typedef int (*Application_take_data_fn)(Application_t *application);

/*i
 * \brief Structure containing several configuration parameters exposed by
 * the application.
 *
 * Each member of this data-type represents a custom configuration parameter
 * that can be used to control the behavior of an application.
 * Initialization of instances of this type should be carried out using
 * \ref ApplicationConfig_INITIALIZER, for statically allocated values, or
 * \ref ApplicationConfig_initialize, for dynamically allocated ones.
 */
typedef struct ApplicationConfig {
    /*i
     * \brief DDS Domain ID to join.
     *
     * (default value: 0)
     */
    DDS_Long domain_id;
    /*i
     * \brief Whether the application should be publishing
     * or subscribing to data.
     *
     * (default value: false)
     */
    DDS_Boolean publish;
    /*i
     * \brief Whether a subscribing application should
     * wait for data by using a listener installed on
     * the DataReader or by using a WaitSet instance
     * with the DataReader's StatusCondition attached
     * to it.
     *
     * (default value: false)
     */
    DDS_Boolean use_waitset;
    /*i
     * \brief Whether a subscribing application should
     * filter data samples using callback
     * on_before_sample_commit of a DataReader's listener.
     *
     * If this functionality is enabled, then \ref filter_deserialized
     * must be disabled.
     *
     * (default value: false)
     */
    DDS_Boolean filter_commit;
    /*i
     * \brief Whether a subscribing application should
     * filter data samples using callback
     * on_before_sample_deserialize of a DataReader's listener.
     *
     * If this functionality is enabled, then \ref filter_commit
     * must be disabled.
     *
     * (default value: false)
     */
    DDS_Boolean filter_deserialized;
    /*i
     * \brief Whether the application should use dynamic or
     * static DDS discovery to detect other applications
     * in the same DDS domain.
     *
     * (default value: true)
     */
    DDS_Boolean use_dynamic_discovery;
    /*i
     * \brief Whether the application should rely on automatic
     * configuration of network interfaces based on information
     * provided by the OS or it should instead statically configure
     * the interface's parameters
     *
     * (default value: false)
     */
    DDS_Boolean use_static_interface;
    /*i
     * \brief A pointer to the TypePlugin to be used by the application.
     *
     * The TypePlugin is used to register the data type on the
     * application's DomainParticipant.
     *
     * (default value: NULL)
     */
    struct NDDS_Type_Plugin *type_plugin;
    /*i
     * \brief Numerical ID of the DataWriter used by the application
     * (if publishing).
     *
     * This value is used along with static
     * DDS discovery, to identify the writer's end-point when
     * statically asserting the existence of its remote publication.
     *
     * (default value: \ref DEFAULT_ENTITY_ID_WRITER)
     */
    DDS_BUILTIN_TOPIC_KEY_TYPE_NATIVE entity_id_writer;
    /*i
     * \brief Numerical ID of the DataReader used by the application
     * (if subscribing).
     *
     * This value is used along with static
     * DDS discovery, to identify the reader's end-point when
     * statically asserting the existence of its remote subscription.
     *
     * (default value: \ref DEFAULT_ENTITY_ID_READER)
     */
    DDS_BUILTIN_TOPIC_KEY_TYPE_NATIVE entity_id_reader;
    /*i
     * \brief Name of the participant used by the application when publishing data.
     *
     * This value is used along with static DDS discovery, to identify
     * the remote DomainParticipant and assert his existence.
     *
     * (default value: \ref DEFAULT_PART_NAME_WRITER)
     */
    DDS_Char part_name_writer[DDS_ENTITYNAME_QOS_NAME_MAX];
    /*i
     * \brief Name of the participant used by the application when subscribing data.
     *
     * This value is used along with static DDS discovery, to identify
     * the remote DomainParticipant and assert his existence.
     *
     * (default value: \ref DEFAULT_PART_NAME_READER)
     */
    DDS_Char part_name_reader[DDS_ENTITYNAME_QOS_NAME_MAX];
    /*i
     * \brief Name of the topic that will be used by the application to exchange
     * data.
     *
     * (default value: \ref DEFAULT_TOPIC_NAME)
     */
    DDS_Char topic_name[RTPS_PATHNAME_LEN_MAX+1];
    /*i
     * \brief Name of the type that will be used by the application.
     *
     * This is a custom name that is specified when a data-type's TypePlugin
     * is registered on a DomainParticipant. It can be any non-empty value,
     * but every DomainParticipant that wants to exchange samples through a
     * topic of this type must have registered it with the same name in order
     * for discovery and endpoint matching to be carried out successfully.
     *
     * (default value: \ref DEFAULT_TOPIC_NAME).
     */
    DDS_Char type_name[RTPS_PATHNAME_LEN_MAX+1];
    /*i
     * \brief Name of the loopback network interface that will be enabled for
     * communication.
     *
     * (default value: \ref DEFAULT_INTERFACE_LOOP)
     */
    DDS_Char interface_loop[DDS_ENTITYNAME_QOS_NAME_MAX];
    /*i
     * \brief Name of the external network interface that will be enabled for
     * communication.
     *
     * (default value: \ref DEFAULT_INTERFACE_UDP)
     */
    DDS_Char interface_udp[DDS_ENTITYNAME_QOS_NAME_MAX];
    /*i
     * \brief Address or hostname of a network peer that will be added to the
     * list of peers initially contacted for DDS endpoint discovery.
     *
     * (default value: \ref DEFAULT_PEER)
     */
    DDS_Char initial_peer[DDS_ENTITYNAME_QOS_NAME_MAX];
    /*i
     * \brief Number of seconds between successive application operations.
     *
     * Used to determine:
     * - Time between successive data sample writes.
     * - Time-out of reading operations (when using \ref DDS_WaitSet_wait
     *   or when actively waiting for samples to be received by an
     *   asynchronous listener).
     *
     * (default value: \ref DEFAULT_SLEEP_SEC)
     */
    DDS_Long sleep_time;
    /*i
     * \brief Number of samples that an application must wait to
     * write/receive before terminating
     *
     * (default value: \ref APP_COUNT_UNLIMITED)
     */
    DDS_Long count_expected;
    /*i
     * \brief QoS configuration for DDS_DomainParticipantFactory.
     *
     * (default value: \ref DDS_DomainParticipantFactoryQos_INITIALIZER)
     */
    struct DDS_DomainParticipantFactoryQos qos_factory;
    /*i
     * \brief QoS configuration for DDS_DomainParticipant.
     *
     * (default value: \ref DDS_DomainParticipantQos_INITIALIZER)
     */
    struct DDS_DomainParticipantQos qos_participant;
    /*i
     * \brief QoS configuration for DDS_DataReader.
     *
     * (default value: \ref DDS_DataReaderQos_INITIALIZER)
     */
    struct DDS_DataReaderQos qos_reader;
    /*i
     * \brief QoS configuration for DDS_DataWriter.
     *
     * (default value: \ref DDS_DataWriterQos_INITIALIZER)
     */
    struct DDS_DataWriterQos qos_writer;
    /*i
     * \brief DDS_DataReaderListener that will be installed on the
     * DataReader used by the application.
     *
     * (default value: \ref DDS_DataReaderListener_INITIALIZER)
     */
    struct DDS_DataReaderListener listener_reader;
    /*i
     * \brief DDS_DataWriterListener that will be installed on the
     * DataWriter used by the application.
     *
     * (default value: \ref DDS_DataWriterListener_INITIALIZER)
     */
    struct DDS_DataWriterListener listener_writer;
    /*i
     * \brief DDS_StatusMask used to install the configured DDS_DataReaderListener.
     *
     * (default value: \ref DDS_STATUS_MASK_NONE)
     */
    DDS_StatusMask listener_reader_mask;
    /*i
     * \brief DDS_StatusMask used to install the configured DDS_DataWriterListener.
     *
     * (default value: \ref DDS_STATUS_MASK_NONE)
     */
    DDS_StatusMask listener_writer_mask;
    /*i
     * \brief DDS_StatusMask used to enable statuses on the
     * DataReader's StatusCondition when using a DDS_WaitSet
     * to receive data or consume other DDS events.
     *
     * (default value: \ref DDS_STATUS_MASK_NONE)
     */
    DDS_StatusMask waitset_mask;
    /*i
     * \brief Call-back function provided by the user that will be invoked
     * whenever new data samples are received.
     *
     * (default value: NULL)
     */
    Application_take_data_fn take_data;
    /*i
     * \brief Type-specific function used to determine whether a data-type
     * has a key or is unkeyed. Required when asserting a remote
     * subscription/publication to enable static endpoint discovery.
     *
     * (default value: NULL)
     */
    NDDS_PluginHelper_GetKeyKindFunc get_key_kind;
} ApplicationConfig_t;

/*i
 * \brief Default DDS domain ID
 */
#define DEFAULT_DOMAIN_ID           0

/*i
 * \brief Default numerical ID of a DataWriter
 */
#define DEFAULT_ENTITY_ID_WRITER    100

/*i
 * \brief Default numerical ID of a DataReader
 */
#define DEFAULT_ENTITY_ID_READER    200

/*i
 * \brief Default name of a publishing DomainParticipant
 */
#define DEFAULT_PART_NAME_WRITER    "HelloWorldPublisher"

/*i
 * \brief Default name of a subscribing DomainParticipant
 */
#define DEFAULT_PART_NAME_READER    "HelloWorldSubscriber"

/*i
 * \brief Default name of the topic used by the application
 */
#define DEFAULT_TOPIC_NAME          "HelloWorldTopic"

/*i
 * \brief Default name of the data type used by the application
 */
#define DEFAULT_TYPE_NAME           "HelloWorldType"

/*i
 * \brief Default address of the network peer that will be initially
 * contacted for DDS endpoint discovery.
 */
#define DEFAULT_PEER                "127.0.0.1"

#if defined(RTI_DARWIN)
/*i
 * \brief Default UDP network interface.
 */
#define DEFAULT_UDP_INTERFACE        "en1"
#elif defined (RTI_LINUX)
#define DEFAULT_UDP_INTERFACE        "eth0"
#elif defined (RTI_VXWORKS)
#define DEFAULT_UDP_INTERFACE        "geisc0"
#elif defined(RTI_WIN32)
#define DEFAULT_UDP_INTERFACE        "Local Area Connection"
#else
#define DEFAULT_UDP_INTERFACE        "ce0"
#endif

#if defined(RTI_DARWIN)
/*i
 * \brief Default loopback network interface.
 */
#define DEFAULT_LOOP_INTERFACE        "lo0"
#elif defined (RTI_LINUX)
#define DEFAULT_LOOP_INTERFACE        "lo"
#elif defined (RTI_VXWORKS)
#define DEFAULT_LOOP_INTERFACE        "lo0"
#elif defined(RTI_WIN32)
#define DEFAULT_LOOP_INTERFACE        "Loopback Pseudo-Interface 1"
#else
#define DEFAULT_LOOP_INTERFACE        "lo0"
#endif

/*i
 * \brief Default sleep_time in seconds.
 */
#define DEFAULT_SLEEP_SEC             1

/*i
 * \brief Initialization value for statically allocated instances
 * of \ref ApplicationConfig_t.
 */
#define ApplicationConfig_INITIALIZER \
{\
    DEFAULT_DOMAIN_ID,\
    DDS_BOOLEAN_FALSE,\
    DDS_BOOLEAN_FALSE,\
    DDS_BOOLEAN_FALSE,\
    DDS_BOOLEAN_FALSE,\
    DDS_BOOLEAN_TRUE,\
    DDS_BOOLEAN_FALSE,\
    NULL,\
    DEFAULT_ENTITY_ID_WRITER,\
    DEFAULT_ENTITY_ID_READER,\
    DEFAULT_PART_NAME_WRITER,\
    DEFAULT_PART_NAME_READER,\
    DEFAULT_TOPIC_NAME,\
    DEFAULT_TYPE_NAME,\
    DEFAULT_LOOP_INTERFACE,\
    DEFAULT_UDP_INTERFACE,\
    DEFAULT_PEER,\
    DEFAULT_SLEEP_SEC,\
    APP_COUNT_UNLIMITED,\
    DDS_DomainParticipantFactoryQos_INITIALIZER,\
    DDS_DomainParticipantQos_INITIALIZER,\
    DDS_DataReaderQos_INITIALIZER,\
    DDS_DataWriterQos_INITIALIZER,\
    DDS_DataReaderListener_INITIALIZER,\
    DDS_DataWriterListener_INITIALIZER,\
    DDS_STATUS_MASK_NONE,\
    DDS_STATUS_MASK_NONE,\
    DDS_STATUS_MASK_NONE,\
    NULL,\
    NULL\
}

/*i
 * \brief Initializes an instance of \ref ApplicationConfig_t to its
 * default values.
 */
extern void
ApplicationConfig_initialize(ApplicationConfig_t *config);

/*i
 * \brief Finalizes an instance of \ref ApplicationConfig_t, releasing
 * any memory allocated by its members.
 */
extern void
ApplicationConfig_finalize(ApplicationConfig_t *config);

/*i
 * \brief Populates an instance of \ref ApplicationConfig_t using
 * values passed by users through the command line.
 */
extern DDS_Boolean
ApplicationConfig_parse_arguments(
        ApplicationConfig_t *config, int argc, char** argv);

/*i
 * \brief Prints the contents of an instance of \ref ApplicationConfig_t
 * to the standard output for debug purposes.
 */
extern void
ApplicationConfig_print(ApplicationConfig_t *config);

/*i
 * \brief State of a generic DDS application.
 *
 *  This data-type contains references to any resource/entity created by
 *  the application and required to carry out its functionalities.
 *  It is used to access these resources in the application code and to
 *  properly manage their life-cycle (i.e. finalizing them at shutdown).
 */
typedef struct Application {
    /*i
     * \brief User-specified configuration
     */
    ApplicationConfig_t config;
    /*i
     * \brief Property used to initialize UDP transport
     */
    struct UDP_InterfaceFactoryProperty property_udp;
    /*i
     * \brief Property used to initialize DPDE module for dynamic DDS discovery.
     */
    struct DPDE_DiscoveryPluginProperty property_dpde;
    /*i
     * \brief Property used to initialize DPSE module for static DDS discovery.
     */
    struct DPSE_DiscoveryPluginProperty property_dpse;
    /*i
     * \brief Value used to assert the existence of a remote publication, when
     * using static DDS discovery.
     */
    struct DDS_PublicationBuiltinTopicData rem_publication_data;
    /*i
     * \brief Value used to assert the existence of a remote subscription, when
     * using static DDS discovery.
     */
    struct DDS_SubscriptionBuiltinTopicData rem_subscription_data;
    /*
     * \brief DDS_DomainParticipant used to access a DDS domain.
     */
    DDS_DomainParticipant *participant;
    /*i
     * \brief DDS_Publisher used to create DDS_DataWriter endpoints.
     */
    DDS_Publisher *publisher;
    /*i
     * \brief DDS_Subscriber used to create DDS_DataReader endpoints.
     */
    DDS_Subscriber *subscriber;
    /*i
     * \brief DDS_Topic used to communicate between remote applications.
     */
    DDS_Topic *topic;
    /*i
     * \brief DDS_DataReader used to received data from the DDS domain.
     */
    DDS_DataReader *reader;
    /*i
     * \brief DDS_DataWriter used to publish data to the DDS domain.
     */
    DDS_DataWriter *writer;
    /*i
     * \brief DDS_WaitSet used to wait for data to be received
     * from the DDS domain.
     */
    DDS_WaitSet *waitset;
    /*i
     * \brief DDS_StatusCondition of the DDS_DataReader.
     */
    DDS_StatusCondition *condition_dr;
    /*i
     * \brief Sequence of DDS_Condition used to store the result of
     * DDS_WaitSet_wait, when waiting for data to be received.
     */
    struct DDS_ConditionSeq active_conditions;
    /*i
     * \brief Current number of data-samples that have been processed
     * (written/received) by the application so far.
     */
    DDS_Long count_processed;
} Application_t;


/*i
 * \brief Creates a new instance of \ref Application_t and initializes
 * it using the specified configuration.
 */
extern Application_t*
Application_create(ApplicationConfig_t *config);

/*i
 * \brief Deletes an instance of \ref Application_t created using
 * \ref Application_create.
 */
extern void
Application_delete(Application_t *application);

/*i
 * \brief Enables the DDS entities of an application
 */
extern DDS_Boolean
Application_enable(Application_t *application);

/*i
 * \brief Blocks the invoking thread until new data samples have been received.
 */
extern void
Application_wait_for_data(Application_t *application);

/*i
 * \brief Prints help text for the application to standard output
 */
extern void
Application_help(char *appname);

/*i
 * \brief Implementation of \ref DDS_DataReaderListener::on_data_available
 */
extern void
Application_ListenerHelper_on_data_available(
            void *listener_data,
            DDS_DataReader * reader);

/*i
 * \brief Implementation of \ref DDS_DataReaderListener::on_subscription_matched
 */
extern void
Application_ListenerHelper_on_subscription_matched(
            void *listener_data,
            DDS_DataReader * reader,
            const struct
            DDS_SubscriptionMatchedStatus *status);

/*i
 * \brief Implementation of \ref DDS_DataWriterListener::on_publication_matched
 */
extern void
Application_ListenerHelper_on_publication_matched(
            void *listener_data,
            DDS_DataWriter * writer,
            const struct DDS_PublicationMatchedStatus *status);

/*i
 * @}
 */

#endif