Agent API

The Micro XRCE-DDS Agent is developed using a fully compliant C++11 API. This allowed to focus its development on modularity and usability, while keeping it simple for the final user.

Keeping up with this philosophy, the API provided to the user attempts to be as much intuitive as possible, while allowing to configure all the different aspects related to the Agent’s behaviour.

That being said, most user will find out that, with te provided MicroXRCEAgent standalone application, it is more than enough to launch an Agent and start the communication process with Micro XRCE-DDS Client applications. This is possible thanks to the intuitive built-in Agent CLI and its multiple configuration parameters.

Alternatively, users can access the underneath Agent implementation and fine-tune all of its parameters, options, and behaviour in their final application. This is specially useful when dealing with a Custom Transport implementation.

The Agent API section is organized as follows:

eprosima::uxr::AgentInstance

The CLI manager, along with all the built-in Agents available for the supported transports (UDP, TCP, Serial, CAN) are encapsulated in the eprosima::uxr::AgentInstance class.


AgentInstance& getInstance();

This function gets a reference to the singleton AgentInstance wrapper class, which allows launching a Micro XRCE-DDS Agent with user-given parameters.


bool create(int argc, char** argv);

This function creates a UDP/TCP/Serial/CAN Micro XRCE-DDS Agent, based on the given arguments. The created Agent will start automatically on success.

Returns true if the arguments were valid and an Agent was successfully created, false otherwise.

argc

Number of arguments provided by the user via the CLI. This is usually inherited from the main loop.

argv

List of arguments to be parsed by the CLI engine.


void run();

This function blocks until the previously created Agent is ended by the stop function, a user’s interrupt or a process error.


void stop();

Stops a previously created Agent, blocking until the stop process is completed. Note that this will trigger a call on the transport::fini method.

To restart a stopped agent, the create method should be used.


template <typename ... Args>
void add_middleware_callback(const Middleware::Kind& middleware_kind, const middleware::CallbackKind& callback_kind, std::function<void (Args ...)>&& callback_function);

This function sets a user-defined callback function for a specific create/delete middleware entity operation.

middleware_kind

Enum defining all the supported middlewares (see Middleware Abstraction Layer).

callback_kind

Enum holding all the possible create/delete operations:

enum class CallbackKind : uint8_t
{
    CREATE_PARTICIPANT,
    CREATE_DATAWRITER,
    CREATE_DATAREADER,
    CREATE_REQUESTER,
    CREATE_REPLIER,
    DELETE_PARTICIPANT,
    DELETE_DATAWRITER,
    DELETE_DATAREADER,
    DELETE_REQUESTER,
    DELETE_REPLIER
};
callback_function

Callback to be defined by the user. It must follow a certain signature, depending on the middleware used.


eprosima::uxr::Agent

However, it is also possible for users to create and instantiate their own Agent, for example, to implement a Custom transport. Also, in some scenarios, it could be useful to have all the necessary ProxyClients and their associated DDS entities created by the Agent even before Clients are started, so that Clients applications can avoid the process of creating the session and the DDS entities, and can focus on the communication.

This would allow a Micro XRCE-DDS Client application to be as tiny as it can be in terms of memory consumption.

The following API is provided to fulfill these requirements:


bool create_client(uint32_t key, uint8_t session, uint16_t mtu, Middleware::Kind middleware_kind, OpResult& op_result);

This function allows to create a ProxyClient entity, which can act on behalf of an external Client to request the creation/deletion of DDS entities.

It returns true if the creation was successful, false otherwise.

key

The ProxyClient’s identifier.

session

The session ID to which the created ProxyClient is attached to.

mtu

The Maximum Transmission Unit size.

middleware_kind

The middleware used by the ProxyClient, to be chosen among the ones presented in the Middleware Abstraction Layer.

op_result

The result status of this operation.


bool delete_client(uint32_t key, OpResult& op_result);

This function deletes a given ProxyClient from the client proxy database, given its ID.

Returns true if the operation was completed successfully, false otherwise (for example, if the provided ID was not registered to any ProxyClient).

key

The identifier of the ProxyClient to be removed.

op_result

The result status of the operation.


bool create_participant_by_xml(uint32_t client_key, uint16_t participant_id, int16_t domain_id, const char* xml, uint8_t flag, OpResult& op_result);

This function creates a DDS participant for a given Client, given its self-contained description in an XML file.

The participant will act as an entry point for the rest of the DDS entities to be created.

It returns true if the creation was successful, false otherwise.

client_key

The identifier of the ProxyClient to which the resulting participant will be attached to.

participant_id

The identifier of the participant to be created.

domain_id

The DDS domain ID associated to the participant.

xml

The XML describing the participant properties.

flag

It determines the creation mode of the new participant (see Creation Mode: Client and Creation Mode: Agent).

op_result

The result status of this operation.


bool create_participant_by_ref(uint32_t client_key, uint16_t participant_id, int16_t domain_id, const char* ref, uint8_t flag, OpResult& op_result);

This function creates a DDS participant for a given Client, given a reference to its description hosted in a certain XML descriptor file.

This reference file must have been previously loaded to the Agent.

The participant will act as an entry point for the rest of the DDS entities to be created.

Returns true if the creation was successful, false otherwise.

client_key

The identifier of the ProxyClient to which the resulting participant will be attached to.

participant_id

The identifier of the participant to be created.

domain_id

The DDS domain ID associated to the participant.

ref

The reference tag which will retrieve the participant description from the file where the references are defined, previously loaded to the Agent.

flag

It determines the creation mode of the new participant (see Creation Mode: Client and Creation Mode: Agent).

op_result

The result status of this operation.


bool delete_participant(uint32_t client_key, uint16_t participant_id, OpResult& op_result);

This function removes a DDS participant from a certain client proxy. Returns true if the participant was deleted, false otherwise.

client_key

The identifier of the ProxyClient from which the participant must be deleted.

participant_id

The ID of the participant to be deleted.

op_result

The result status of the operation.


bool create_<entity>_by_xml(uint32_t client_key, uint16_t <entity>_id, uint16_t <associated_entity>_id, const char* xml, uint8_t flag, OpResult& op_result);

This function creates a certain DDS entity attached to an existing ProxyClient, given its client key.

An XML must be provided, containing the DDS description of the entity to be created.

There are as many methods available as existing DDS entities, replacing the parameters <entity> and <associated_entity> as follows:

Agent’s API available DDS entities and their associated entities

<entity>

<associated_entity>

topic

participant

publisher

participant

subscriber

participant

datawriter

publisher

datareader

subscriber

requester

participant

replier

participant

This operation returns true if the entity is successfully created and linked to its associated entity (which must previously exist in the given ProxyClient), false otherwise.

client_key

The identifier of the ProxyClient to which the resulting entity will be attached to.

<entity>_id

The ID of the DDS entity to be created.

<associated_entity>_id

The identifier of the DDS entity to which this one will be assocciated.

xml

The XML describing the entity properties.

flag

It determines the creation mode of the new entity (see see Creation Mode: Client and Creation Mode: Agent).

op_result

The result status of this operation.


bool create_<entity>_by_ref(uint32_t client_key, uint16_t <entity>_id, uint16_t <associated_entity>_id, const char* ref, uint8_t flag, OpResult& op_result);

This function creates a certain DDS entity attached to an existing ProxyClient, given its client key.

The description of the entity to be created is hosted in a certain file where all the required references are defined, and must be tagged with the same tag name, provided as the ref parameter to this method.

There are as many methods available as existing DDS entities, replacing the parameters <entity> and <associated_entity> as shown above in the previous method description (see Agent’s API available DDS entities and their associated entities).

This operation returns true if the entity is successfully created and linked to its associated entity (which must previously exist in the given ProxyClient), false otherwise.

client_key

The identifier of the ProxyClient to which the resulting entity will be attached to.

<entity>_id

The ID of the DDS entity to be created.

<associated_entity>_id

The identifier of the DDS entity to which this one will be assocciated.

ref

The reference tag which will retrieve the DDS entity description from the file hosting the referenced entities definitions.

flag

It determines the creation mode of the new entity (see see Creation Mode: Client and Creation Mode: Agent).

op_result

The result status of this operation.


bool delete_<entity>(uint32_t client_key, uint16_t <entity>_id, OpResult& op_result);

This function deletes a certain entity from a ProxyClient. Its associated entities will also be deleted, if applicable.

There exist as many method signatures of this type in the agent’s API as available entities. See the Agent’s API available DDS entities and their associated entities table for further information.

It returns true if the entity is correctly removed, false otherwise.

client_key

The identifier of the ProxyClient from which the entity must be deleted.

<entity>_id

The ID of the DDS entity to be deleted.

op_result

The result status of the operation.


bool load_config_file(const std::string& file_path);

This function loads a configuration file that provides the tagged XML definitions of the desired XRCE entities that can be created using the reference creation mode (see see Creation Mode: Client and Creation Mode: Agent).

The used syntax must match the one defined for FastDDS XML profile syntax, where the profile name attributes represent the reference names.

It returns true if the file was correctly loaded, false otherwise.

file_path

Relative path to the file containing the DDS entities description in XML format, tagged accordingly to be referenced by the API.

Note

This function needs to be called when implementing a Custom transport in the case creation of entities by reference is used. This function must be called before eprosima::uxr::Server start method.


void reset();

This function deletes all the ProxyClient instances and their associated DDS entities.


void set_verbose_level(uint8_t verbose_level);

This function sets the verbose level of the logger, from 0 (logger is off) to 6 (critical, error, warning, info, debug, and trace messages are displayed).

Intermediate tracing levels display information up to the position in the aforementioned list; for example, level 4 shows critical, error, warning and info messages.

Note

This function must be called before eprosima::uxr::Server start method.

verbose_level

The level to be set.


template <typename ... Args>
void add_middleware_callback(const Middleware::Kind& middleware_kind, const middleware::CallbackKind& callback_kind, std::function<void (Args ...)>&& callback_function);

This function exposes the same functionality as the one described in add_middleware_callback, for eprosima::uxr::AgentInstance.

Note

This function must be called before eprosima::uxr::Server start method.

eprosima::uxr::Server

This class inherits from eprosima::uxr::Agent and it is the base class used for implementing any of the built-in Agent servers that are available by default in the standalone executable that is generated when the library is compiled and installed (see Installation Manual), and that can be launched and used by means of the built-in Agent CLI.

Also, when creating a Custom Agent, which inherits directly from eprosima::uxr::Server users will need to call the start() method after configuring the Agent, if applicable (namely, by using load_config_file, set_verbose_level or add_middleware_callback methods). An example on how to do this can be found here.


bool start();

Launches the threads involved in the Agent server communication, namely, receiver and sender thread for getting/dispatching messages; processing thread, to process the messages; and a heartbeat and an error handler thread. After calling this method, the communication between the Agent and the Clients can effectively start.

This method returns true if the server has been correctly started, or false if some error happened during startup.


bool stop();

Stops a previously launched eprosima::uxr::Server and all of its associated threads.

This method returns true if the stopping process was successful, or false otherwise.