1.1.1. Config

class eprosima::is::core::internal::Config

Internal representation of the configuration provided to the Integration Service instance, by means of a YAML file.

Public Types

using SubscriptionCallbacks = std::vector<std::unique_ptr<is::TopicSubscriberSystem::SubscriptionCallback>>

Signature for the container used to store the subscription callbacks for a certain Integration Service instance.

using RequestCallbacks = std::vector<std::unique_ptr<is::ServiceClientSystem::RequestCallback>>

Signature for the container used to store the service request callbacks for a certain Integration Service instance.

Public Functions

Config(const YAML::Node &node = YAML::Node(), const std::string &filename = "<text>")

Constructor.

Parameters
  • [in] node: Parsed representation of the YAML configuration file. It defaults to empty.

  • [in] filename: The path of the YAML configuration file.

bool parse(const YAML::Node &node, const std::string &filename = "<text>")

Parses the provided configuration, according to the configuration file scheme defined for Integration Service.

Configuration files typically contain the following sections:

  1. types: Specifies the IDL types used by Integration Service to transmit messages. These IDL definitions will be parsed using eprosima::xtypes parser for IDL files, and the resulting Dynamic Types will be added to the available types database.

    The following subsections are permitted:

    1.1. idl: IDL content.

    1.2. paths: includes paths containing IDL definitions that will also be parsed and added to the types database.

  2. systems: Lists the middlewares involved in the communication, allowing to configure them. Custom aliases can be given to any system.

    The following subsections are permitted:

    2.1. type: to be selected among the middlewares supported by Integration Service: ros2, dds, websocket, ros1

    2.2. types-from: allows to inherit type definitions from one system to another. In this way, users do not have to redefine types for each system.

    2.3. Custom configuration parameters, such as domain_id (for ROS 2). Each SystemHandle may define its own configuration fields, please refer to their documentation for more details.

  3. routes: Lists the communication bridges that Integration Service needs to establish among systems. Each route has a specific name.

    The following subsections are permitted:

    3.1. from/to: publisher/subscriber communication.

    3.2. server/clients: server/client communication.

  4. topics/services: Allows to configure the topics exchanged over the routes described above, in either publisher/subscriber or client/server communication, and provides detailed information about them. Each topic or service must have a unique name in the YAML file.

    The following subsections are permitted:

    4.1. type: Type involved in the communication. It can be a built-in type, usually coming from a mix library; or a custom user-defined type, by means of an IDL definition.

    4.2. route: Communication bridge, of the ones defined above, that must perform the communication.

    4.3. remap: allows to establish equivalences between topic names and types for each system involved in the communication.

    4.4. Custom configuration parameters, which are specific for each middleware. Please refer to the specific SystemHandle documentation.

Return

True if the parsing was correct, false if some error occurred.

Parameters
  • [in] node: The parsed YAML representation of the configuration file provided.

  • [in] filename: The path of the configuration file.

bool okay() const

Checks if everything is okay with the configuration process.

Return

The _okay boolean parameter.

operator bool() const

bool operator overload.

Return

The okay() parameter.

bool load_middlewares(is::internal::SystemHandleInfoMap &info_map) const

Performs a search and loads the dynamic libraries required for each middleware, that is, the SystemHandle entities.

After the SystemHandle shared library is loaded successfully, the required types to be found during the SystemHandle configuration phase are registered, according to what was specified in the YAML configuration.

Next, the types-from parameter is checked, which specifies the middleware from which each SystemHandle wants to inherit types from, as declared in the configuration.

Finally, for each SystemHandle, the configure method is called. If one of the middlewares listed is not properly configured, the whole process fails.

Return

Boolean value indicating whether the load process was successful or not.

Parameters
  • [out] info_map: Map between the middlewares and their SystemHandle instances information (handle pointer, topic publisher and subscriber and service client and provider systems, as well as its type registry). This map should be filled with the information for all the SystemHandle defined in the configuration, once this method succeeds.

bool configure_topics(const is::internal::SystemHandleInfoMap &info_map, SubscriptionCallbacks &subscription_callbacks) const

Configures topics communication, according to the specified route, type and remapping parameters.

First, compatibility between the type defined in the from endpoint and the to (destination) endpoint is checked, because it could happen that, because of a remapping, the type definition in the source and destination systems is slightly (or completely) different. To do that, check_topic_compatibility is called. Please refer to its documentation for more details.

If the types are compatible, the next step is to check the publishing capabilities of the destination endpoint, and if everything is correct, that is, if the system has an associated TopicPublisherSystem, the SystemHandle advertises the topic. This publication will transmit the data to the user application, which must define a subscriber capable of receiving and processing the data.

Then, in the source endpoint, the existence of subscribing capabilities is checked, and, if so, the subscriber defines a SubscriptionCallback lambda, that iterates through the previous constructed list of publishers and ensures that each defined destination endpoint gets the data published. This callback is used to call to TopicSubscriberSystem::subscribe method.

If any of the defined topics cannot find publishing or subscription capabilities (i.e. invalid routes), the returned value will be false and the process will fail.

Return

true if all the topics were successfully configured, false otherwise.

Parameters
  • [in] info_map: Map filled during the load_middlewares phase and containing the information for each loaded SystemHandle, in terms of its instance, supported types and publish/subscribe or client/server capabilities.

  • [in] subscription_callbacks: Reference to the map used to store all of the active subscription callbacks for a certain SystemHandle instance.

bool configure_services(const is::internal::SystemHandleInfoMap &info_map, RequestCallbacks &request_callbacks) const

Configures services, according to the specified route, type and remapping parameters.

First, compatibility between the request and reply types defined in the server endpoint and the clients endpoints is checked, because it could happen that, because of a remapping, the types defined for request/reply is slightly (or completely) different in the server and client endpoints. To do that, check_service_compatibility is called. Please refer to its documentation for more details.

If the types are compatible, the next step is to check the service providing capabilities of the server endpoint, and if everything is correct, that is, if the system has an associated ServiceProviderSystem, the SystemHandle creates the corresponding service provider proxy.

Then, for all the defined clients, ServiceClientSystem capabilities are checked, and a request callback is defined, which basically executes the ServiceProvider::call_service method from the associated provider. This call_service is then responsible of sending back the response to the client, if applicable (that is, if a reply_type has been defined in the YAML configuration.)

If any of the defined services cannot find server or client capabilities (i.e. invalid routes), the returned value will be false and the process will fail.

Return

true if all the services were successfully configured, false otherwise.

Parameters
  • [in] info_map: Map filled during the load_middlewares phase and containing the information for each loaded SystemHandle, in terms of its instance, supported types and publish/subscribe and client/server capabilities.

  • [in] request_callbacks: Reference to the map used to store all of the active request callbacks for a certain SystemHandle instance.

bool check_topic_compatibility(const is::internal::SystemHandleInfoMap &info_map, const std::string &topic_name, const TopicConfig &config) const

Checks compatibility between the TopicInfo registered in the endpoints responsible for a topic publish/subscribe communication in Integration Service.

This compatibility check is ensured thanks to eProsima xtypes library and its TypeConsistency definition. If types are not equal, some policies might be automatically applied to try to make them compatible, such as ignoring member names, type signs, etc.

Return

true if the topic is compatible among the defined systems, false otherwise.

Parameters
  • [in] info_map: Map filled during the load_middlewares phase and containing the information for each loaded SystemHandle, in terms of its instance, supported types and publish/subscribe or client/server capabilities.

  • [in] topic_name: The topic whose compatibility will be checked between endpoints.

  • [in] config: TopicConfig structure containing information such as the type, the source/destination defined route and the remappings, as well as the specific middleware configurations for this topic.

bool check_service_compatibility(const is::internal::SystemHandleInfoMap &info_map, const std::string &service_name, const ServiceConfig &config) const

Checks compatibility between the ServiceConfig registered in the endpoints responsible of a server/client communication in the Integration Service.

This compatibility check is ensured thanks to eProsima xtypes library and its TypeConsistency definition. If types are not equal, some policies might be automatically applied to try to make them compatible, such as ignoring member names, type signs, etc.

The check is performed both for request and reply types.

Return

true if the service is compatible among the defined systems, false otherwise.

Parameters
  • [in] info_map: Map filled during the load_middlewares phase and containing the information for each loaded SystemHandle, in terms of its instance, supported types and publish/subscribe and client/server capabilities.

  • [in] service_name: The service whose compatibility will be checked between endpoints.

  • [in] config: ServiceConfig structure containing information such as the request and reply types, the server and clients defined route and the remappings, as well as the specific middleware configurations for this service.

const eprosima::xtypes::DynamicType *resolve_type(const TypeRegistry &types, const std::string &path) const

This function allows to retrieve a type member from an externally defined type containing it, to use it as the type for a certain configuration.

The used syntax when retrieving the inner type must be <outer_type>.<type_member_name>.

For example, if a type is defined like this in an IDL:

union MyUnion (switch uint8)
{
      case 0: int32 _zero;
      case 1: int64 _one;
      default: int128 _default;
};

You can define the following topic: ExampleTopic: { route: "a_to_b", type: MyUnion._zero }

Return

A pointer to the inner DynamicType representing the type requested by the user.

Parameters
  • [in] types: TypeRegistry containing all the available types where the search of the parent type will be performed.

  • [in] path: The whole type definition, as specified by the user. In the example, it would be MyUnion._zero.

Public Static Functions

Config from_file(const std::string &file)

Helper static constructor to retrieve a Config instance from a file path.

Parameters
  • [in] file: A string containing the configuration file path.

struct eprosima::is::core::internal::MiddlewareConfig

Holds information relative to each middleware configuration.

Public Members

std::string type

The name of the middleware.

std::vector<std::string> types_from

The name of middleware whose types want to be used.

YAML::Node config_node

YAML configuration associated with the specific middleware.

struct eprosima::is::core::internal::TopicRoute

Stores information relative to topic routes:

Public Functions

std::set<std::string> all() const

Helper method to retrieve at once from and to sets.

Return

A set containing all endpoints for this TopicRoute.

Public Members

std::set<std::string> from

Source middleware endpoint.

std::set<std::string> to

Destination middleware endpoint.

struct eprosima::is::core::internal::ServiceRoute

Stores information relative to service routes:

Public Functions

std::set<std::string> all() const

Helper method to retrieve at once server and clients sets.

Return

A set containing all endpoints for this ServiceRoute.

Public Members

std::set<std::string> clients

Client endpoints.

std::string server

Server endpoint.

struct eprosima::is::core::internal::TopicInfo

Struct containing information about a certain topic.

Public Members

std::string name

The name of the topic.

std::string type

The name of the type for the specific topic.

using eprosima::is::core::internal::ServiceInfo = TopicInfo

Struct containing information about a certain service.

  • std::string name

    The name of the service.

  • std::string type

    The name of the request type for the specific service.

  • std::string reply_type

    The name of the reply type for the specific service.

struct eprosima::is::core::internal::TopicConfig

Holds the configuration provided for a certain topic.

Public Members

std::string message_type

The name of the type for the specific topic.

TopicRoute route

The route followed by the specific topic.

std::map<std::string, TopicInfo> remap

A map with the remaps needed for the specific topic.

std::map<std::string, YAML::Node> middleware_configs

A map with the YAML configuration for the specific topic.

struct eprosima::is::core::internal::ServiceConfig

This struct stores the configuration provided for a certain service.

Public Members

std::string request_type

The name of the request type for the specific service.

std::string reply_type

The name of the reply type for the specific service.

ServiceRoute route

The route followed by the specific service.

std::map<std::string, ServiceInfo> remap

A map with the remaps needed for the specific service.

std::map<std::string, YAML::Node> middleware_configs

A map with the YAML configuration for the specific service.