/* * 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] = * {" * " * ... * * "}; * * 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] = "..."; * 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 \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: * * * \default RTI_CDS_LOG_VERBOSITY_EXCEPTIONS */ int service_verbosity; /*e * @brief The verbosity of \ndds core libraries * * Values: * * * \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; /**e \ingroup RTI_CDS_ServiceProperty * * @brief * Initialize an instance of the \ref RTI_CDS_ServiceProperty variable with * empty values. * * @param self * A \ref RTI_CDS_ServiceProperty instance * */ extern CDSDllExport DDS_Boolean RTI_CDS_Property_initialize(struct RTI_CDS_Property *self); /**e \ingroup RTI_CDS_ServiceProperty * * @brief * Copy the values of a \ref RTI_CDS_ServiceProperty variable into another. * * @param to * A \ref RTI_CDS_ServiceProperty instance to copy the values to * * @param from * A \ref RTI_CDS_ServiceProperty instance to copy the values from * * @return * The pointer to \ref RTI_CDS_ServiceProperty containing the copied values. * NULL otherwise. */ extern CDSDllExport struct RTI_CDS_Property *RTI_CDS_Property_copy( struct RTI_CDS_Property *to, const struct RTI_CDS_Property *from); /**e \ingroup RTI_CDS_ServiceProperty * * @brief * Finalize an instance of the \ref RTI_CDS_ServiceProperty variable. * * @param self * A \ref RTI_CDS_ServiceProperty instance * */ 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. *

* To build your application you need to link with the @product library * in <@ndds home>/bin/<architecture>/ * * An example is provided at * https://github.com/rticommunity/rticonnextdds-examples/tree/master/examples/cloud_discovery_service/library_api. * * ### 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 | | * * NOTE: 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 /**e \ingroup RTI_CDS_ServiceLibModule * * @brief @product * */ struct RTI_CDS_Service { }; #endif struct RTI_CDS_Service; /**e \ingroup RTI_CDS_ServiceLibModule * * @brief * Create a new @product instance * * @param property * The properties to configure @product * This parameter is copied internally, so the user is responsible * for releasing any memory allocated inside this structure. * * @mtsafety On non-Linux, non-Windows systems (i.e. VxWorks): * UNSAFE for multiple threads to simultaneously make the FIRST * call to RTI_CDS_Service_new(). Subsequent calls are thread safe. * On Windows and Linux systems, these calls are thread-safe. */ extern CDSDllExport struct RTI_CDS_Service *RTI_CDS_Service_new( const struct RTI_CDS_Property *property); /**e \ingroup RTI_CDS_ServiceLibModule * * @brief * Stop and delete an @product instance. * * @see \ref RTI_CDS_Service_stop * * @param self * An \ref RTI_CDS_Service instance created with \ref RTI_CDS_Service_new * */ extern CDSDllExport void RTI_CDS_Service_delete(struct RTI_CDS_Service *self); /**e \ingroup RTI_CDS_ServiceLibModule * * @brief Start @product * * This is a non-blocking operation. @product will create its own set of threads * to perform its tasks. * * @param self * An \ref RTI_CDS_Service instance created with \ref RTI_CDS_Service_new * * @return * True on success; False otherwise */ extern CDSDllExport DDS_Boolean RTI_CDS_Service_start(struct RTI_CDS_Service *self); /**e \ingroup RTI_CDS_ServiceLibModule * * @brief Stop @product * * This function won't return the execution control until the instance is fully * stopped. * * @param self * An \ref RTI_CDS_Service instance created with \ref RTI_CDS_Service_new * * @return * True on success; False otherwise * */ extern CDSDllExport DDS_Boolean RTI_CDS_Service_stop(struct RTI_CDS_Service *self); /**e \ingroup RTI_CDS_ServiceLibModule * * @deprecated * * Calling RTI_CDS_Service_finalize_globals() is no longer necessary and the * function will be removed in future versions. * */ extern CDSDllExport DDS_Boolean RTI_CDS_Service_finalize_globals(void); /**e \ingroup RTI_CDS_ServiceLibModule * * @brief Query whether this @product is currently started * */ extern CDSDllExport DDS_Boolean RTI_CDS_Service_is_started(struct RTI_CDS_Service *self); /**e \ingroup RTI_CDS_ServiceLibModule * * @brief Sets the dds.sec.crypto.rtps_psk_secret_passphrase property * for the @product instance started with \ref RTI_CDS_Service_start. * * This operation performs an update; if there was no value for the * dds.sec.crypto.rtps_psk_secret_passphrase in the XML configuration * when @product was started by calling \ref RTI_CDS_Service_start, the * operation would fail. * * @param self * An \ref RTI_CDS_Service instance started with \ref RTI_CDS_Service_start * * @param rtps_psk_secret_passphrase * The new value for the dds.sec.crypto.rtps_psk_secret_passphrase property */ 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 */