routingservice_infrastructure.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_infrastructure_h
#define routingservice_infrastructure_h
 
#include "routingservice/routingservice_dll.h"
#include "dds_c/dds_c_infrastructure.h"
 
#ifdef __cplusplus
    extern "C" {
#endif
 
/*e \file
  @brief RTI Routing Service Infrastructure
*/
 
/*e
  @ingroup RTI_RoutingServiceInfrastructureModule
 
  @brief Utility macro that can be used to export symbols in a shared library
  on Windows platform.
  For non-windows, the definion of this macro is empty.
*/
 
#if (defined(RTI_WIN32) || defined(RTI_INTIME))
  #undef RTI_USER_DLL_EXPORT
  #define RTI_USER_DLL_EXPORT __declspec(dllexport)
#elif defined(RTI_VISIBILITY_HIDDEN)
  #undef RTI_USER_DLL_EXPORT
  #define RTI_USER_DLL_EXPORT __attribute__((visibility("default")))
#else
  #define RTI_USER_DLL_EXPORT
#endif
 
#define RTI_ROUTING_SERVICE_VERSION {7,7,0,0}
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 * @brief This can be used by C client and example code to avoid unused
 * parameter warnings in the compiler.
 * This is not strictly necessary in C++, where just removing the parameter name
 * should yield the same result.
 */
#define RTI_UNUSED_PARAMETER(x) (void)(x)
 
/*****************************************************************************/
/* Properties                                                                */
/*****************************************************************************/
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Configuration property.
 *
 * A property is a name/value pair.
 *
 */
struct RTI_RoutingServiceNameValue {
    /*e @brief Property name */
    char * name;
    /*e @brief Property value */
    void * value;
};
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Set of configuration properties.
 *
 * Configuration properties for adapters and transformations.
 */
struct RTI_RoutingServiceProperties {
    /*e @brief Array of configuration properties. */
    struct RTI_RoutingServiceNameValue * properties;
    /*e @brief Number of properties in the array. */
    int count;
    /*e @brief A non-zero value indicates that all the values of the
        properties are strings (char *) */
    DDS_Boolean string_values;
};
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Searches for a property given its name.
 *
 * @param_self
 * @param name \rs_st_in Property name. Cannot be NULL.
 *
 * @return On success, the function returns the value of the first property
 * with the given name. Otherwise, the function returns NULL.
 */
extern ROUTERDllExport
const char * RTI_RoutingServiceProperties_lookup_property(
    const struct RTI_RoutingServiceProperties * self,
    const char * name);
 
extern ROUTERDllExport
const char * RTI_RoutingServiceProperties_lookup_property_with_prefix(
        const struct RTI_RoutingServiceProperties * self,
        const char *prefix,
        const char *name);
 
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceProperties_add(
        struct RTI_RoutingServiceProperties *self,
        const char *name,
        const char *value);
 
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceProperties_assert(
        struct RTI_RoutingServiceProperties *self,
        const char *name,
        const char *value);
 
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceProperties_equals(
        const struct RTI_RoutingServiceProperties *left,
        const struct RTI_RoutingServiceProperties *right);
 
extern ROUTERDllExport
const struct RTI_RoutingServiceProperties *
RTI_RoutingServiceProperties_copy(
        struct RTI_RoutingServiceProperties *self,
        const struct RTI_RoutingServiceProperties *other);
 
extern ROUTERDllExport
void RTI_RoutingServiceProperties_finalize(
        struct RTI_RoutingServiceProperties *self);
 
extern ROUTERDllExport
DDS_Boolean RTI_RoutingServiceProperties_initialize(
    struct RTI_RoutingServiceProperties *self);
 
/*****************************************************************************/
/* Environment                                                               */
/*****************************************************************************/
 
/*e \defgroup RTI_RoutingServiceErrorCodeModule Standard Error Codes
 * \ingroup RTI_RoutingServiceInfrastructureModule
 * @brief Standard error codes.
 */
#define RTI_ROUTING_SERVICE_OK 0
 
/*e \ingroup RTI_RoutingServiceErrorCodeModule
 *
 * @brief Generic, unspecified error.
 * @hideinitializer
 */
#define RTI_ROUTING_SERVICE_ERROR 1
 
/*e \ingroup RTI_RoutingServiceErrorCodeModule
 *
 * @brief Fatal error. It will cause the routing service to shut down.
 * @hideinitializer 
 */
#define RTI_ROUTING_SERVICE_FATAL_ERROR 2
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 * @brief Maximum length of an error message.
 *
 * Error messages longer than this value are truncated.
 */
#define RTI_ROUTING_SERVICE_ERROR_MAX_LENGTH 1024
 
struct RTI_RoutingServiceEnvironmentImpl;
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief The environment permits the return of error information in the \product API and
 *        information retreival (version and verbosity).
 *
 * This is the last parameter of each operation.
 *
 * \see \ref RTI_RoutingServiceEnvironment_set_error
 * \see \ref RTI_RoutingServiceEnvironment_get_verbosity
 *
 */
typedef struct RTI_RoutingServiceEnvironmentImpl RTI_RoutingServiceEnvironment;
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Represents the version of a plugin or \product itself
 *
 */
struct RTI_RoutingServiceVersion {
    /*e
     * @brief Major version number
     */
    int major;
    /*e
     * @brief Minor version number
     */
    int minor;
    /*e
     * @brief Release version number
     */
    int release;
    /*e
     * @brief Revision of a release
     */
    int revision;
};
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Verbosity used by Routing Service
 *
 */
typedef enum {
    /*e
     * No logging (-verbosity 0)
     */
    RTI_ROUTING_SERVICE_VERBOSITY_NONE = 0,
    /*e
     * Exceptions (-verbosity 1)
     */
    RTI_ROUTING_SERVICE_VERBOSITY_EXCEPTION,
    /*e
     * Warnings (-verbosity 2)
     */
    RTI_ROUTING_SERVICE_VERBOSITY_WARN,
    /*e
     * Information (-verbosity 3)
     */
    RTI_ROUTING_SERVICE_VERBOSITY_INFO,
    /*e
     * Debug information (-verbosity 5 and 6)
     */
    RTI_ROUTING_SERVICE_VERBOSITY_DEBUG
} RTI_RoutingServiceVerbosity;
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Assigns an error into the environment.
 *
 * Routing Service will consider that a function call failed when an error has been
 * set into the environment
 *
 * @param_self
 * @param overwrite \rs_st_in If the environment already contains an error, setting
 * this parameter to DDS_BOOLEAN_TRUE will overwrite it.
 * @param error_code \rs_st_in One of the \ref RTI_RoutingServiceErrorCodeModule.
 * @param native_error_code \rs_st_in Native error code (specific to the transformation or
 * adapter plugin).
 * @param error_format \rs_st_in String that contains the error text.
 * It can optionally contain format tags that are substituted by the values
 * specified in subsequent argument(s). Cannot be NULL.
 * The format tags are the same tags used by the function printf in the ANSI C standard.
 *
 * @see \ref RTI_RoutingServiceEnvironment_set_error
 */
extern ROUTERDllExport void RTI_RoutingServiceEnvironment_set_error_w_params(
        RTI_RoutingServiceEnvironment *self,
        DDS_Boolean overwrite,
        int error_code,
        int native_error_code,
        const char *error_format,
        ...);
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Assigns an error into the environment.
 *
 * Routing Service will consider that a function call failed when an error has been
 * set into the environment
 *
 * This function sets the error code to \ref RTI_ROUTING_SERVICE_ERROR and the
 * native error code to 0.
 *
 * If the environment already contains an error, the error is not overwritten.
 *
 * @param_self
 * @param error_format \rs_st_in String that contains the error text.
 * It can optionally contain format tags that are substituted by the values
 * specified in subsequent argument(s). Cannot be NULL.
 * The format tags are the same tags used by the function printf in the ANSI C standard.
 *
 * @see \ref RTI_RoutingServiceEnvironment_set_error_w_params
 */
extern ROUTERDllExport void RTI_RoutingServiceEnvironment_set_error(
        RTI_RoutingServiceEnvironment *self,
        const char *error_format,
        ...);
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule 
 *
 * @brief Assigns a fatal error into the environment.
 *
 * Routing Service will consider that a function call failed when an error has been
 * set into the environment. Additionally, a fatal error will cause the routing
 * service to call the shutdown hook.
 * 
 * This function sets the error code to \ref RTI_ROUTING_SERVICE_FATAL_ERROR and the
 * native error code to 0. Any previous error in the environment will be overwritten.
 * 
 * @param_self
 * @param error_format \rs_st_in String that contains the error text.
 * It can optionally contain format tags that are substituted by the values
 * specified in subsequent argument(s). Cannot be NULL.
 * The format tags are the same tags used by the function printf in the ANSI C standard.
 * 
 * @see \ref RTI_RoutingServiceEnvironment_set_error_w_params 
 */
extern ROUTERDllExport void RTI_RoutingServiceEnvironment_fatal_error(
        RTI_RoutingServiceEnvironment *self,
        const char *error_format,
        ...);
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Clears an error (if any) set in this environment
 *
 * @param_self
 */
extern ROUTERDllExport void RTI_RoutingServiceEnvironment_clear_error(
        RTI_RoutingServiceEnvironment *self);
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Retrieves the verbosity that Routing Service is using
 *
 * @param_self
 * @return The verbosity
 */
extern ROUTERDllExport RTI_RoutingServiceVerbosity
RTI_RoutingServiceEnvironment_get_verbosity(
        const RTI_RoutingServiceEnvironment *self);
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Checks whether an error has been set in this environment
 *
 * @param_self
 *
 * @return A value different than zero if true
 */
extern ROUTERDllExport DDS_Boolean RTI_RoutingServiceEnvironment_error_occurred(
        const RTI_RoutingServiceEnvironment *self);
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Returns the error message this environment contains
 *
 * @param_self
 *
 * @return The error message or NULL if no error is set
 */
extern ROUTERDllExport const char *
RTI_RoutingServiceEnvironment_get_error_message(
        const RTI_RoutingServiceEnvironment *self);
 
/*i \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Returns the underlying native code associated to the last error
 *        this environment contains.
 *
 * The value is specific to the plug-in implementation that sets the native
 * code with RTI_RoutingServiceEnvironment_set_error_w_params.
 *
 * @param_self
 *
 * @return The native error code.
 */
extern ROUTERDllExport int RTI_RoutingServiceEnvironment_get_native_code(
        const RTI_RoutingServiceEnvironment *self);
 
extern ROUTERDllExport
int RTI_RoutingServiceVersion_compare(
        const struct RTI_RoutingServiceVersion *left,
        const struct RTI_RoutingServiceVersion *right);
 
/*****************************************************************************/
/* Type information                                                          */
/*****************************************************************************/
 
/*e
 * \dref_DYNAMIC_TYPE_REPRESENTATION
 */
#define RTI_ROUTING_SERVICE_TYPE_REPRESENTATION_DYNAMIC_TYPE 0
 
/*e
 * \dref_XML_TYPE_REPRESENTATION
 */
#define RTI_ROUTING_SERVICE_TYPE_REPRESENTATION_XML 1
 
/*e
 * \dref_JAVA_OBJECT_TYPE_REPRESENTATION
 */
#define RTI_ROUTING_SERVICE_TYPE_REPRESENTATION_JAVA_OBJECT 2
 
#define RTI_ROUTING_SERVICE_TYPE_REPRESENTATION_FIRST_CUSTOM_REPRESENTATION 100
 
/*e
 * \dref_DYNAMIC_DATA_REPRESENTATION
 */
#define RTI_ROUTING_SERVICE_DATA_REPRESENTATION_DYNAMIC_DATA 0
 
/*e
 * \dref_XML_DATA_REPRESENTATION
 */
#define RTI_ROUTING_SERVICE_DATA_REPRESENTATION_XML 1
 
/*e
 * \dref_JAVA_OBJECT_DATA_REPRESENTATION
 */
#define RTI_ROUTING_SERVICE_DATA_REPRESENTATION_JAVA_OBJECT 2
 
#define RTI_ROUTING_SERVICE_DATA_REPRESENTATION_FIRST_CUSTOM_REPRESENTATION 100
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 * @brief Type representation kind.
 *
 * The range [0-100] is reserved for RTI use. Within
 * that range are some predefined type representations (\ref RTI_RoutingServiceTypeRepresentationModule).
 *
 */
typedef int RTI_RoutingServiceTypeRepresentationKind;
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Type representation.
 *
 * If the representation kind is \ref RTI_ROUTING_SERVICE_TYPE_REPRESENTATION_DYNAMIC_TYPE,
 * the representation will be an \ndds TypeCode.
 *
 * If the representation kind is \ref RTI_ROUTING_SERVICE_TYPE_REPRESENTATION_XML,
 * the representation will be an XML string.
 */
typedef void * RTI_RoutingServiceTypeRepresentation;
 
/*e \dref_TypeInfo
 */
struct RTI_RoutingServiceTypeInfo {
    /*e \dref_TypeInfo_type_name */
    char * type_name;
 
    /*i
     * Whether this type can be optimized (avoid CDR deserialization). This is
     * assumed to be true but the service may determine otherwise by studying
     * counterpart type information.
     */
    DDS_Boolean can_be_optimized;
 
    /*e \dref_TypeInfo_representation_kind */
    RTI_RoutingServiceTypeRepresentationKind type_representation_kind;
 
    /*e \dref_TypeInfo_type_representation */
    RTI_RoutingServiceTypeRepresentation type_representation;
};
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 * @brief Data representation kind.
 *
 * The range [0-100] is reserved for RTI use. Within
 * that range are some predefined data representations (\ref RTI_RoutingServiceDataRepresentationModule).
 *
 */
typedef int RTI_RoutingServiceDataRepresentationKind;
 
/*****************************************************************************/
/* Sample and sample information                                             */
/*****************************************************************************/
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Stream sample.
 *
 * Samples are data messages generated by adapters and transformations.
 *
 * If the representation kind is \ref RTI_ROUTING_SERVICE_DATA_REPRESENTATION_DYNAMIC_DATA,
 * the sample will be a DynamicData object.
 *
 * If the representation kind is \ref RTI_ROUTING_SERVICE_DATA_REPRESENTATION_XML,
 * the sample will be an XML string.
 *
 */
typedef void * RTI_RoutingServiceSample;
 
/*e
 * \ingroup RTI_RoutingServiceInfrastructureModule
 * @brief Stream sample info.
 * In DDS, this is a DDS_SampleInfo object.
 */
typedef void * RTI_RoutingServiceSampleInfo;
 
/*e
 * \ingroup RTI_RoutingServiceInfrastructureModule
 * @brief Definition of a String sequence
 */
struct RTI_RoutingServiceStringSeq {
    /*e @brief Array of elements. */
    char **element_array;
    /*e @brief Number of elements in the array. */
    int element_count;
    /*e @brief maximum capacity of the array. */
    int element_count_max;
};
 
 
#define RTI_RoutingServiceStringSeq_INITIALIZER \
    {NULL, 0, 0}
 
extern ROUTERDllExport
struct RTI_RoutingServiceStringSeq *
RTI_RoutingServiceStringSeq_copy(
        struct RTI_RoutingServiceStringSeq *self,
        struct RTI_RoutingServiceStringSeq *other);
 
/*****************************************************************************/
/* Stream information                                                        */
/*****************************************************************************/
 
/*e
 * \dref_StreamInfo
 */
struct RTI_RoutingServiceStreamInfo {
    /*e
     * \dref_StreamInfo_stream_name
     */
    char *stream_name;
    /*e
     * \dref_StreamInfo_type_info
     */
    struct RTI_RoutingServiceTypeInfo type_info;
    /*i
     *
     * @brief Internal use only
     */
    struct RTI_RoutingServiceStringSeq partition;
    /*e
     * \dref_StreamInfo_disposed
     */
    DDS_Boolean disposed;
};
 
 
#define RTI_RoutingServiceStreamInfo_INITIALIZER {\
    NULL, \
    {NULL, DDS_BOOLEAN_TRUE, 0, NULL},\
    RTI_RoutingServiceStringSeq_INITIALIZER, \
    DDS_BOOLEAN_FALSE \
}
 
extern ROUTERDllExport void RTI_RoutingServiceStreamInfo_finalize(
        struct RTI_RoutingServiceStreamInfo *self);
 
extern ROUTERDllExport DDS_Boolean RTI_RoutingServiceStreamInfo_initialize(
        struct RTI_RoutingServiceStreamInfo *self,
        DDS_Boolean is_disposed_stream,
        const char *stream_name,
        const char *registered_type_name,
        int type_dfinition_format,
        RTI_RoutingServiceTypeRepresentation type_definition);
 
/*e
 * \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Creates a stream info for a newly discovered stream.
 *
 * @param stream_name \rs_st_in Stream name. Cannot be NULL.
 * @param registered_type_name \rs_st_in Type name. Cannot be NULL.
 * @param type_representation_kind \rs_st_in Type representation kind.
 * @param type_representation \rs_st_in Type representation. Cannot be NULL.
 *
 * @return Newly created stream info, or NULL if there is an error.
 */
extern ROUTERDllExport struct RTI_RoutingServiceStreamInfo *
RTI_RoutingServiceStreamInfo_new_discovered(
        const char *stream_name,
        const char *registered_type_name,
        RTI_RoutingServiceTypeRepresentationKind type_representation_kind,
        RTI_RoutingServiceTypeRepresentation type_representation);
 
/*e
 * \ingroup RTI_RoutingServiceInfrastructureModule
 * @brief Creates a stream info for a disposed stream.
 * Disposed streams are no longer available in a data domain.
 * @param stream_name \rs_st_in Stream name. Cannot be NULL.
 * @return Newly created stream info, or NULL if there is an error.
 */
extern ROUTERDllExport struct RTI_RoutingServiceStreamInfo *
RTI_RoutingServiceStreamInfo_new_disposed(const char *stream_name);
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Destroys a stream info.
 *
 * @param_self
 */
extern ROUTERDllExport
void RTI_RoutingServiceStreamInfo_delete(
    struct RTI_RoutingServiceStreamInfo * self);
 
 
#define RTI_ROUTING_SERVICE_PROPERTY_PREFIX \
    "rti.routing_service"
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Name of the property that provides the @product given application name
 *
 */
#define  RTI_ROUTING_SERVICE_APP_NAME_PROPERTY_NAME \
        RTI_ROUTING_SERVICE_PROPERTY_PREFIX".app_name"
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * Name of the property that provides the configured group name.
 *
 */
#define  RTI_ROUTING_SERVICE_GROUP_PROPERTY_NAME \
        RTI_ROUTING_SERVICE_PROPERTY_PREFIX".group_name"
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Name of the property that provides the @product version as string.
 *
 */
#define  RTI_ROUTING_SERVICE_VERSION_PROPERTY_NAME \
        RTI_ROUTING_SERVICE_PROPERTY_PREFIX".version"
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief  Name of the property that provides verbosity in use by @product.
 *
 * It can take on of the following stings:
 *      - NONE
 *      - EXCEPTION
 *      - WARN
 *      - INFO
 *      - DEBUG.
 *
 */
#define  RTI_ROUTING_SERVICE_VERBOSITY_PROPERTY_NAME \
        RTI_ROUTING_SERVICE_PROPERTY_PREFIX".verbosity"
 
/*e \ingroup RTI_RoutingServiceInfrastructureModule
 *
 * @brief Name of the property that provides the resource name of the entity
 *        that owns the adapter entity.
 *
 */
#define  RTI_ROUTING_SERVICE_ENTITY_RESOURCE_NAME_PROPERTY_NAME \
        RTI_ROUTING_SERVICE_PROPERTY_PREFIX".entity.resource_name"
 
#ifdef __cplusplus
}       /* extern "C" */
#endif
 
#endif /* routingservice_infrastructure_h */