Files
qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/clouddiscoveryservice/clouddiscoveryservice_service.h
T
torstenandCopilot 342ffd3e5c Update submodule to latest BUILD_RTI fixes
- HandlerMinelayerData: BUILD_RTI Guards für RTI-Abhängigkeiten
- svcTabCommon: Export-Header-Fix via Fallback-Target
- TrainingAreaBase: Stub-Header für BUILD_RTI=OFF
- ddsfts: Include-Pfad und Dependency-Fixes
- BUILD_RTI=OFF Compilation vollständig unterstützt

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Entire-Checkpoint: 01M0JNZA586SACX1PRZ2DJAE5S
2026-08-21 19:30:20 +02:00

627 lines
20 KiB
C

/*
* 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;
/**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.
* <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
/**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 */