clouddiscoveryservice_service.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016-2025 Real-Time Innovations, Inc. 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 clouddiscoveryservice_service_h
#define clouddiscoveryservice_service_h
 
 
#ifndef clouddiscoveryservice_dll_h
  #include "clouddiscoveryservice/clouddiscoveryservice_dll.h"
#endif
#ifndef clouddiscoveryservice_infrastructure_h
  #include "clouddiscoveryservice/clouddiscoveryservice_infrastructure.h"
#endif
#ifndef routingservice_infrastructure_h
  #include "routingservice/routingservice_infrastructure.h"
#endif
#ifndef ndds_c_h
  #include "ndds/ndds_c.h"
#endif
#ifndef core_version_version_h
  #include "core_version/core_version_version.h"
#endif
#ifndef ndds_config_c_h
  #include "ndds/ndds_config_c.h"
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*e \file
    \brief Implements the @product.
*/
 
extern CDSDllVariable const struct RTI_CDS_DomainListProperty
        RTI_CDS_DOMAIN_LIST_DEFAULT;
 
extern CDSDllVariable const char *RTI_CDS_TRANSPORT_UNICAST_ALIAS_DEFAULT;
 
extern CDSDllVariable int RTI_CDS_TRANSPORT_UNICAST_RECEIVE_PORT_DEFAULT;
 
extern CDSDllVariable struct RTI_CDS_TransportSelectionProperty
        RTI_CDS_TRANSPORT_SELECTION_DEFAULT;
 
extern CDSDllVariable const RTI_UINT64
        CDS_FLOW_CONTROLLER_OUTPUT_BANDWITH_UNLIMITED;
 
extern CDSDllVariable const struct RTI_CDS_FlowControllerProperty
        RTI_CDS_FLOW_CONTROLLER_PROPERTY_DEFAULT;
 
extern CDSDllVariable const struct RTI_CDS_ForwarderEventProperty
        RTI_CDS_FORWARDER_EVENT_PROPERTY_DEFAULT;
 
 
#define RTI_CDS_FLOW_CONTROLLER_PROPERTY_DEFAULT_VALUE \
    { \
        RTI_CDS_FLOW_CONTROLLER_JOBS_UNLIMITED, \
                RTI_CDS_FLOW_CONTROLLER_JOBS_UNLIMITED, { 40, 30, 30 }, \
                DDS_DURATION_INFINITE_VALUE \
    }
 
/*e \defgroup RTI_CDS_ServiceProperty Service Property
 *
 * \ingroup RTI_CDS_ServiceLibModule
 *
 * @brief Service Property for @product. Use this in conjunction with
 * \ref RTI_CDS_ServiceLibModule, to configure @product in your code.
 */
 
/*e \ingroup RTI_CDS_ServiceProperty
 *
 * @brief Configuration property for @product.
 */
struct RTI_CDS_Property {
    /*e
     * @brief Path to an @product configuration file
     *
     * If not \c NULL, this file is loaded; otherwise,
     * if \c cfg_strings is not \c NULL, that XML code is loaded
     *
     * \default NULL.
     */
    char *cfg_file;
 
    /*e
     * @brief XML configuration represented as strings
     *
     * An array of strings that altogether make up an
     * XML document to configure @product. This parameter is used
     * only if \ref cfg_file is \c NULL.
     *
     * For example:
     *
     * \code
     * int MY_CLOUD_DISCOVERY_SERVICE_CFG_SIZE = 3;
     * const char *
     * MY_CLOUD_DISCOVERY_SERVICE_CFG[MY_CLOUD_DISCOVERY_SERVICE_CFG_SIZE] =
     *      {"<dds>
     *             <cloud_discovery_service name=\"MyServiceName\">"
     *              ...
     *             </cloud_discovery_service>
     *       </dds>"};
     *
     * property.cfg_strings = MY_CLOUD_DISCOVERY_SERVICE_CFG;
     * property.cfg_strings_count = MY_CLOUD_DISCOVERY_SERVICE_CFG_SIZE;
     * \endcode
     *
     * The reason for using an array instead of one single string is to
     * get around the limited size of literal strings in C.
     * In general, if you create the XML string dynamically
     * using one single string in the array,
     * setting \ref cfg_strings_count to 1 is enough:
     *
     * \code
     * property.cfg_strings = malloc(sizeof(char *));
     * property.cfg_strings[0] = "<dds><cloud_discovery_service>...</dds>";
     * property.cfg_strings_count = 1;
     * \endcode
     *
     * If your target system doesn't support a file system, you can use
     * XML strings to configure the service. To ease this process, a
     * utility is shipped to generate a C string array from a text file.
     * You can find this utility in
     * [@product installation directory]/resource/perl/cStringifyFile.pl
     *
     * \default NULL.
     */
    const char **cfg_strings;
 
    /*e
     * @brief Size of the array \ref cfg_strings
     *
     * \default 0.
     */
    unsigned int cfg_strings_count;
 
    /*e
     * @brief The name of the @product instance to run
     *
     * This is the name used to find the
     * \verbatim <cloud_discovery_service> \endverbatim
     * XML tag in the configuration file; this is the default name that will
     * be used to refer to this execution in remote administration and
     * monitoring if application_name isn't specified.
     *
     * \default NULL (use built-in configuration)
     */
    char *service_name;
 
    /*e
     * @brief Assigns a name to the execution of the @product
     *
     * Remote commands and status information will refer to the RTI Cloud
     * Discovery Service using this name.
     *
     * \default service_name if this value is NULL.
     */
    char *application_name;
 
    /*e
     * @brief Controls whether the service applies XSD validation to the loaded
     * configuration.
     *
     * \default DDS_BOOLEAN_TRUE
     */
    DDS_Boolean enforce_xsd_validation;
 
    /*e
     * @brief Set it to true to avoid loading the standard files usually loaded
     * by @product
     *
     * Only the configuration in \ref cfg_file or \ref cfg_strings will be
     * loaded.
     *
     * \default DDS_BOOLEAN_FALSE
     */
    DDS_Boolean skip_default_files;
 
    /*e
     * @brief The verbosity of the service
     *
     * Values:
     *  <ul>
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_SILENT
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_EXCEPTIONS
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_WARNINGS
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_INFO
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_ALL
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_DEBUG
     *  </ul>
     *
     * \default RTI_CDS_LOG_VERBOSITY_EXCEPTIONS
     */
    int service_verbosity;
 
    /*e
     * @brief The verbosity of \ndds core libraries
     *
     * Values:
     *  <ul>
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_SILENT
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_EXCEPTIONS
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_WARNINGS
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_INFO
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_ALL
     *  <li> \ref RTI_CDS_LOG_VERBOSITY_DEBUG
     *  </ul>
     *
     * \default RTI_CDS_LOG_VERBOSITY_EXCEPTIONS
     */
    int dds_verbosity;
 
    /*e
     * @brief Specifies the transport and receive ports used to receive and
     * send discovery traffic. Specifically, a receive resource is uniquely
     * identified by a transport class-receive port pair.
     * Overrides XML configuration if specified.
     */
    struct RTI_CDS_TransportSelectionProperty transport_selection;
 
    /*e
     * @brief Specifies the set of domain IDs the service will accept
     *        announcements from.
     *
     * \default Unspecified. Use value from XML configuration.
     */
    struct RTI_CDS_DomainListProperty domain_list;
 
    /*e
     * @brief Set this to true to enable remote administration
     * or false to disable it.
     *
     * \default DDS_BOOLEAN_FALSE
     */
    DDS_Boolean enable_administration;
 
    /*e
     * @brief If \ref enable_administration is true, this is
     * the domain ID to use for remote administration.
     *
     * Takes precedence over the XML configuration.
     * If \ref enable_administration is false, this value is not used
     * even if remote administration is enabled in the XML configuration.
     *
     * \default 0
     */
    int administration_domain_id;
 
    /*e
     * @brief Set this to true to enable monitoring or false to disable it.
     *
     * \default DDS_BOOLEAN_FALSE
     */
    DDS_Boolean enable_monitoring;
 
    /*e
     * @brief If \ref enable_monitoring is true, this is
     * the domain ID to use for publishing monitoring topics.
     *
     * Takes precedence over the XML configuration.
     * If \ref enable_monitoring is false, this value is not used
     * even if monitoring is enabled in the XML configuration.
     *
     * \default 0
     */
    int monitoring_domain_id;
 
    /*e
     * @brief Path to an @product license file
     *
     * If not \c NULL, this file is checked for a valid license; otherwise,
     * default location will be used. This parameter is only used if your
     * installation requires a license file.
     *
     * \default NULL.
     */
    char *license_file_name;
 
    /*e
     * @brief Dictionary of user variables.
     * The dictionary provides a parallel way to expand XML configuration
     * variables in the form $(my_var), when they are not defined in the
     * environment.
     *
     * \default empty
     */
    struct RTI_RoutingServiceProperties user_environment;
};
 
#define RTI_CDS_Property_INITIALIZER \
    { \
        NULL,                      /* cfg_file */ \
                NULL,              /* cfg_strings */ \
                0,                 /* cfg_strings_count */ \
                NULL,              /* service_name */ \
                NULL,              /* application_name */ \
                DDS_BOOLEAN_FALSE, /* enforce_xsd_validation */ \
                DDS_BOOLEAN_FALSE, /* skip_default_files */ \
                0,                 /* service_verbosity */ \
                0,                 /* dds_verbosity */ \
                RTI_CDS_TransportSelectionProperty_INITIALIZER, /* transport_selection \
                                                                 */ \
                RTI_CDS_DomainListProperty_INITIALIZER, /* domain_list */ \
                0,    /* enable_administration */ \
                0,    /* administration_domain_id */ \
                0,    /* enable_monitoring */ \
                0,    /* monitoring_domain_id */ \
                NULL, /* license_file_name */ \
        { \
            NULL, 0, 1 \
        } /* user_environment */ \
    }
 
extern CDSDllVariable const struct RTI_CDS_Property RTI_CDS_PROPERTY_DEFAULT;
 
extern CDSDllExport DDS_Boolean
RTI_CDS_Property_initialize(struct RTI_CDS_Property *self);
 
extern CDSDllExport struct RTI_CDS_Property *RTI_CDS_Property_copy(
        struct RTI_CDS_Property *to,
        const struct RTI_CDS_Property *from);
 
extern CDSDllExport void RTI_CDS_Property_finalize(
        struct RTI_CDS_Property *self);
 
/*e \defgroup RTI_CDS_ServiceLibModule Library API
 * \ingroup CDS
 * @brief @product can be deployed as a C library linked into your application
 * on select architectures.
 *
 * This API allows you to create, configure and start @product instances from
 * your application.
 *
 * The following code shows the typical use of the API:
 *
 * \code
 *
 * struct RTI_CDS_Property property = RTI_CDS_Property_INITIALIZER;
 * struct RTI_CDS_Service *service = NULL;
 *
 * property.cfg_file = "my_cloud_discovery_service_cfg.xml";
 * property.service_name = "my_cloud_discovery_service";
 * ...
 *
 * service = RTI_CDS_Service_new(&property);
 * if (service == NULL) {
 *    printf("Error ...");
 *    return -1;
 * }
 *
 * if (!RTI_CDS_Service_start(service)) {
 *    printf("Error ...");
 *    RTI_CDS_Service_delete(service);
 *    return -1;
 * }
 *
 * while (keep_running) {
 *     sleep();
 *     ...
 * }
 *
 * RTI_CDS_Service_delete(service);
 *
 * return 0;
 *
 * \endcode
 *
 * Instead of a file, you can use XML strings to configure @product.
 * See \ref RTI_CDS_ServiceProperty for more information.
 * <p>
 * To build your application you need to link with the @product library
 * in <b> &lt;@ndds home&gt;/bin/&lt;architecture&gt;/ </b>
 *
 * An example is provided at
 * <b>https://github.com/rticommunity/rticonnextdds-examples/tree/master/examples/cloud_discovery_service/library_api</b>.
 *
 * ### Development Requirements
 *
 * |                               | Linux Systems                  | Windows
 * Systems               | | ----------------------------: |
 * :----------------------------: | :---------------------------: | | Link
 * Libraries (Compile Time) | librticlouddiscoveryservice.so |
 * rticlouddiscoveryservice.dll  | | Shared Libraries (Run Time)   |
 * librtiroutingservice.so        | rtiroutingservice.dll         | | ^ |
 * librtidlc.so                   | rtidlc.dll                    | | ^ |
 * librticonnextmsgc.so           | rticonnextmsgc.dll            | | ^ |
 * libnddsmetp.so                 | nddsmetp.dll                  | | ^ |
 * librtiapputilsc.so             | rtiapputilsc.dll              | | ^ |
 * librtixml2.so                  | rtixml2.dll                   | | ^ |
 * libnddsc.so                    | nddsc.dll                     | | ^ |
 * libnddscore.so                 | nddscore.dll                  | | Static
 * Libraries              | librticlouddiscoveryservicez.a |
 * rticlouddiscoveryservicez.lib | | ^                             |
 * librtiroutingservicez.a        | rtiroutingservicez.lib        | | ^ |
 * librtidlcz.a                   | rtidlcz.lib                   | | ^ |
 * librticonnextmsgcz.a           | rticonnextmsgcz.lib           | | ^ |
 * libnddsmetpz.a                 | nddsmetpz.lib                 | | ^ |
 * librtiapputilscz.a             | rtiapputilscz.lib             | | ^ |
 * librtixml2z.a                  | rtixml2z.lib                  | | ^ |
 * libnddscz.a                    | nddscz.lib                    | | ^ |
 * libnddscorez.a                 | nddscorez.lib                 | | Headers |
 * clouddiscoveryservice/clouddiscoveryservice_service.h | |
 *
 * <b>NOTE:</b> If you are using debug libraries, remember to add the 'd' suffix
 * to the library name. For shared libraries on macOS systems, the library name
 * is the same as that for Linux except the extension is '.dylib' instead of
 * '.so'.
 */
 
#ifdef DOXYGEN_DOCUMENTATION_ONLY
struct RTI_CDS_Service { };
#endif
 
struct RTI_CDS_Service;
 
extern CDSDllExport struct RTI_CDS_Service *RTI_CDS_Service_new(
        const struct RTI_CDS_Property *property);
 
extern CDSDllExport void RTI_CDS_Service_delete(struct RTI_CDS_Service *self);
 
extern CDSDllExport DDS_Boolean
RTI_CDS_Service_start(struct RTI_CDS_Service *self);
 
extern CDSDllExport DDS_Boolean
RTI_CDS_Service_stop(struct RTI_CDS_Service *self);
 
extern CDSDllExport DDS_Boolean RTI_CDS_Service_finalize_globals(void);
 
extern CDSDllExport DDS_Boolean
RTI_CDS_Service_is_started(struct RTI_CDS_Service *self);
 
extern CDSDllExport DDS_Boolean
RTI_CDS_Service_update_rtps_psk_secret_passphrase(
        struct RTI_CDS_Service *self,
        const char *rtps_psk_secret_passphrase);
 
/*e \ingroup CDSLogModule
 * @brief Logs a message with the specified level within the running instance of
 * @product. The message will be printed under the log of the currently
 * executing
 * @product, if the instance was started with \p log_level or higher verbosity.
 *
 * The message is specified with a format and a format parameter, in a similar
 * fashion to the standard C printf() operation.
 *
 * The generated log will be part of logging stream of the running
 * @product, if the \p log_level is part of the configured verbosity.
 * The result log message may include additional information according to the
 * Connext logging configuration, such as Advlog Context, thread ID, line
 * number, etc. Additionally, the result log message will contain a newline
 * character at the end, so the format does not need to contain it.
 *
 * @param [in] log_level Log level associated to the message
 * @param [in] format message format specification
 * @param [in] ... variablelength argument (stdarg)
 */
extern CDSDllExport void RTI_CDS_Logger_log(
        NDDS_Config_LogLevel log_level,
        const char *format,
        ...);
 
/*e \ingroup CDSLogModule
 * @brief Log verbosity level: exceptions + warnings + info + periodic + content
 */
extern CDSDllVariable const int RTI_CDS_LOG_VERBOSITY_DEBUG;
 
/*e \ingroup CDSLogModule
 * @brief Log verbosity level: exceptions + warnings + info + periodic
 */
extern CDSDllVariable const int RTI_CDS_LOG_VERBOSITY_ALL;
 
/*e \ingroup CDSLogModule
 * @brief Log verbosity level: exceptions + warnings + info
 */
extern CDSDllVariable const int RTI_CDS_LOG_VERBOSITY_INFO;
 
/*e \ingroup CDSLogModule
 * @brief Log verbosity level: exceptions + warnings
 */
extern CDSDllVariable const int RTI_CDS_LOG_VERBOSITY_WARNINGS;
 
/*e \ingroup CDSLogModule
 * @brief Log verbosity level: exceptions
 */
extern CDSDllVariable const int RTI_CDS_LOG_VERBOSITY_EXCEPTIONS;
 
/*e \ingroup CDSLogModule
 * @brief Log verbosity level: silent
 */
extern CDSDllVariable const int RTI_CDS_LOG_VERBOSITY_SILENT;
 
extern CDSDllExport void RTI_CDS_Service_print_available_configI(
        struct RTI_CDS_Service *self);
 
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* clouddiscoveryservice_service_h */