5.6.7. UDP Transport¶
This section describes the builtin RTI Connext Micro UDP transport and how to configure it.
The builtin UDP transport (UDP) is a fairly generic UDPv4 transport. Connext Micro supports the following functionality:
Unicast
Multicast
Automatic detection of available network interfaces
Manual configuration of network interfaces
Allow/Deny lists to select which network interfaces can be used to receive data
Simple NAT configuration
Configuration of receive threads
Note
Connext Micro supports up to four network interfaces at once for each of the following:
Unicast user-data
Multicast user-data
Unicast discovery data
Multicast discovery data
5.6.7.1. Registering the UDP Transport¶
The builtin UDP transport is a Connext Micro component that is automatically registered when the DDS_DomainParticipantFactory_get_instance() method is called. To change the UDP configuration, it is necessary to first unregister the transport as shown below:
DDS_DomainParticipantFactory *factory = NULL;
RT_Registry_T *registry = NULL;
factory = DDS_DomainParticipantFactory_get_instance();
registry = DDS_DomainParticipantFactory_get_registry(factory);
/* The builtin transport does not return any properties (3rd param) or
* listener (4th param)
*/
if (!RT_Registry_unregister(registry, "_udp", NULL, NULL))
{
/* ERROR */
}
When a component is registered, the registration takes the properties and a listener as the 3rd and 4th parameters. In general, it is up to the caller to manage the memory for the properties and the listeners. There is no guarantee that a component makes a copy.
The following code-snippet shows how to register the UDP transport with new parameters.
struct UDP_InterfaceFactoryProperty *udp_property = NULL;
/* Allocate a property structure for the heap, it must be valid as long
* as the component is registered
*/
udp_property = (struct UDP_InterfaceFactoryProperty *)
malloc(sizeof(struct UDP_InterfaceFactoryProperty));
if (udp_property != NULL)
{
*udp_property = UDP_INTERFACE_FACTORY_PROPERTY_DEFAULT;
/* Only allow network interface "eth0" to be used;
*/
REDA_StringSeq_set_maximum(&udp_property->allow_interface, 1);
REDA_StringSeq_set_length(&udp_property->allow_interface, 1);
*REDA_StringSeq_get_reference(&udp_property->allow_interface, 0) =
REDA_String_dup("eth0");
/* Register the transport again, using the builtin name
*/
if (!RT_Registry_register(registry, "_udp",
UDP_InterfaceFactory_get_interface(),
(struct RT_ComponentFactoryProperty*)udp_property,
NULL))
{
/* ERROR */
}
}
else
{
/* ERROR */
}
It should be noted that the UDP transport can be registered with any name, but all transport QoS policies and initial peers must refer to this name. If a transport is referred to and it does not exist, an error message is logged.
It is possible to register multiple UDP transports with a DomainParticipantFactory. It is also possible to use different UDP transports within the same DomainParticipant when multiple network interfaces are available (either physical or virtual).
When UDP transformations are enabled, this feature is always enabled and determined by the allow_interface and deny_interface lists. If any of the lists are non-empty the UDP transports will bind each receive socket to the specific interfaces.
When UDP transformations are not enabled, this feature is determined by the value of the enable_interface_bind. If this value is set to RTI_TRUE and the allow_interface and/or deny_interface properties are non-empty, the receive sockets are bound to specific interfaces.
5.6.7.2. Threading Model¶
The UDP transport creates one receive thread for each unique UDP receive address and port. Thus, by default, three UDP threads are created:
A multicast receive thread for discovery data (assuming multicast is available and enabled)
A unicast receive thread for discovery data
A unicast receive thread for user data
Additional threads may be created depending on the transport configuration for a DomainParticipant, DataReader, and DataWriter. The UDP transport creates threads based on the following criteria:
Each unique unicast port creates a new thread
Each unique multicast address and port creates a new thread
For example, if a DataReader specifies its own multicast receive address, a new receive thread will be created.
5.6.7.2.1. Configuring UDP Receive Threads¶
All threads in the UDP transport share the same thread settings. It is important to note that all the UDP properties must be set before the UDP transport is registered. Connext Micro preregisters the UDP transport with default settings when the DomainParticipantFactory is initialized. To change the UDP thread settings, use the following code.
struct UDP_InterfaceFactoryProperty *udp_property = NULL;
struct UDP_InterfaceFactoryProperty udp_property =
UDP_INTERFACE_FACTORY_PROPERTY_DEFAULT;
/* Allocate a property structure for the heap, it must be valid as long
* as the component is registered
*/
udp_property = (struct UDP_InterfaceFactoryProperty *)
malloc(sizeof(struct UDP_InterfaceFactoryProperty));
*udp_property = UDP_INTERFACE_FACTORY_PROPERTY_DEFAULT;
/* Please refer to OSAPI_ThreadOptions for possible options */
udp_property->recv_thread.options = ...;
/* The stack-size is platform dependent, it is passed directly to the OS */
udp_property->recv_thread.stack_size = ....
/* The priority is platform dependent, it is passed directly to the OS */
udp_property->recv_thread.priority = ....
if (!RT_Registry_register(registry, "_udp",
UDP_InterfaceFactory_get_interface(),
(struct RT_ComponentFactoryProperty*)udp_property,
NULL))
{
/* ERROR */
}
5.6.7.3. UDP Configuration¶
All the configuration of the UDP transport is done via the UDP_InterfaceFactoryProperty.
struct UDP_InterfaceFactoryProperty
{
/* Inherited from */
struct NETIO_InterfaceFactoryProperty _parent;
/* Sequence of allowed interface names */
struct REDA_StringSeq allow_interface;
/* Sequence of denied interface names */
struct REDA_StringSeq deny_interface;
/* The size of the send socket buffer */
RTI_INT32 max_send_buffer_size;
/* The size of the receive socket buffer */
RTI_INT32 max_receive_buffer_size;
/* The maximum size of the message which can be received */
RTI_INT32 max_message_size;
/* The maximum TTL */
RTI_INT32 multicast_ttl;
#ifndef RTI_CERT
struct UDP_NatEntrySeq nat;
#endif
/* The interface table if interfaces are added manually */
struct UDP_InterfaceTableEntrySeq if_table;
/* The network interface to use to send to multicast */
REDA_String_T multicast_interface;
/* If this should be considered the default UDP interfaces if
* no other UDP interface is found to handle a route
*/
RTI_BOOL is_default_interface;
/* Disable reading of available network interfaces using system
* information and instead rely on the manually configured
* interface table
*/
RTI_BOOL disable_auto_interface_config;
/* Thread properties for each receive thread created by this
* NETIO interface.
*/
struct OSAPI_ThreadProperty recv_thread;
/* Bind to specific interfaces
*/
RTI_BOOL enable_interface_bind;
struct UDP_TransformRuleSeq source_rules;
/* Rules for how to transform sent UDP payloads based on the
* destination address.
*/
struct UDP_TransformRuleSeq destination_rules;
/* Determines how regular UDP is supported when transformations
* are supported.
*/
UDP_TransformUdpMode_T transform_udp_mode;
/* The locator to use for locators that have transformations.
*/
RTI_INT32 transform_locator_kind;
};
5.6.7.3.1. allow_interface¶
The allow_interface string sequence determines which interfaces are allowed to be used for communication. Each string element is the name of a network interface, such as “en0” or “eth1”.
If this sequence is empty, all interface names pass the allow test. The default value is empty. Thus, all interfaces are allowed.
5.6.7.3.2. deny_interface¶
The deny_interface string sequence determines which interfaces are not allowed to be used for communication. Each string element is the name of a network interface, such as “en0” or “eth1”.
If this sequence is empty, the test is false. That is, the interface is allowed. Note that the deny list is checked after the allow list. Thus, if an interface appears in both, it is denied. The default value is empty, thus no interfaces are denied.
5.6.7.3.3. max_send_buffer_size¶
The max_send_buffer_size is the maximum size of the send socket buffer and it must be at least as big as the largest sample. Typically, this buffer should be a multiple of the maximum number of samples that can be sent at any given time. The default value is 256KB.
5.6.7.3.4. max_receive_buffer_size¶
The max_receive_buffer_size is the maximum size of the receive socket buffer and it must be at least as big as the largest sample. Typically, this buffer should be a multiple of the maximum number of samples that can be received at any given time. The default value is 256KB.
5.6.7.3.5. max_message_size¶
The max_message_size is the maximum size of the message which can be received, including any packet overhead. The default value is 65507 bytes.
5.6.7.3.6. multicast_ttl¶
The multicast_ttl is the Multicast Time-To-Live (TTL). This value is only used for multicast. It limits the number of hops a packet can pass through before it is dropped by a router. The default value is 1.
5.6.7.3.7. nat¶
Connext Micro supports firewalls with NAT. However, this feature has limited use and only supports translation between a private and public IP address. UDP ports are not translated. Furthermore, because Connext Micro does not support any hole punching technique or WAN server, this feature is only useful when the private and public address mapping is static and known in advance. For example, to test between an Android emulator and the host, the following configuration can be used:
UDP_NatEntrySeq_set_maximum(&udp_property->nat,2);
UDP_NatEntrySeq_set_length(&udp_property->nat,2);
/* Translate the local emulator eth0 address 10.10.2.f:7410 to
* 127.0.0.1:7410. This ensures that the address advertised by the
* emulator to the host machine is the host's loopback interface, not
* the emulator's host interface
*/
UDP_NatEntrySeq_get_reference(&udp_property->nat,0)->
local_address.kind = NETIO_ADDRESS_KIND_UDPv4;
UDP_NatEntrySeq_get_reference(&udp_property->nat,0)->
local_address.port = 7410;
UDP_NatEntrySeq_get_reference(&udp_property->nat,0)->
local_address.value.ipv4.address = 0x0a00020f;
UDP_NatEntrySeq_get_reference(&udp_property->nat,0)->
public_address.kind = NETIO_ADDRESS_KIND_UDPv4;
UDP_NatEntrySeq_get_reference(&udp_property->nat,0)->
public_address.port = 7410;
UDP_NatEntrySeq_get_reference(&udp_property->nat,0)->
public_address.value.ipv4.address = 0x7f000001;
/* Translate the local emulator eth0 address 10.10.2.f:7411 to
* 127.0.0.1:7411. This ensures that the address advertised by the
* emulator to the host machine is the host's loopback interface
*/
UDP_NatEntrySeq_get_reference(&udp_property->nat,1)->
local_address.kind = NETIO_ADDRESS_KIND_UDPv4;
UDP_NatEntrySeq_get_reference(&udp_property->nat,1)->
local_address.port = 7411;
UDP_NatEntrySeq_get_reference(&udp_property->nat,1)->
local_address.value.ipv4.address = 0x0a00020f;
UDP_NatEntrySeq_get_reference(&udp_property->nat,1)->
public_address.kind = NETIO_ADDRESS_KIND_UDPv4;
UDP_NatEntrySeq_get_reference(&udp_property->nat,1)->
public_address.port = 7411;
UDP_NatEntrySeq_get_reference(&udp_property->nat,1)->
public_address.value.ipv4.address = 0x7f000001;
5.6.7.3.8. if_table¶
The if_table provides a method to manually configure which interfaces are available for use; for example, when using IP stacks that do not support reading interface lists. The following example shows how to manually configure the interfaces.
/* The arguments to the UDP_InterfaceTable_add_entry functions are:
* The if_table itself
* The network address of the interface
* The netmask of the interface
* The name of the interface
* Interface flags. Valid flags are:
* UDP_INTERFACE_INTERFACE_UP_FLAG - The interface is UP
* UDP_INTERFACE_INTERFACE_MULTICAST_FLAG - The interface supports multicast
*/
if (!UDP_InterfaceTable_add_entry(&udp_property->if_table,
0x7f000001,0xff000000,"loopback",
UDP_INTERFACE_INTERFACE_UP_FLAG |
UDP_INTERFACE_INTERFACE_MULTICAST_FLAG))
{
/* Error */
}
5.6.7.3.9. multicast_interface¶
The multicast_interface may be used to select a particular network interface to be used to send multicast packets. The default value is any interface (that is, the OS selects the interface).
5.6.7.3.10. is_default_interface¶
The is_default_interface flag is used to indicate that this Connext Micro network transport shall be used if no other transport is found. The default value is RTI_TRUE.
5.6.7.3.11. disable_auto_interface_config¶
Normally, the UDP transport will try to read out the interface list (on platforms that support it). Setting disable_auto_interface_config to RTI_TRUE will prevent the UDP transport from reading the interface list.
5.6.7.3.12. recv_thread¶
The recv_thread field is used to configure all the receive threads. Please refer to Threading Model for details.
5.6.7.3.13. enable_interface_bind¶
When this is set to TRUE the UDP transport binds each receive port to a specific interface when the allow_interface/deny_interface lists are non-empty. This allows multiple UDP transports to be used by a single DomainParticipant at the expense of an increased number of threads. This property is ignored when transformations are enabled and the allow_interface/deny_interface lists are non-empty.
5.6.7.3.14. source_rules¶
Rules for how to transform received UDP payloads based on the source address.
5.6.7.3.15. destination_rules¶
Rules for how to transform sent UDP payloads based on the destination address.
5.6.7.3.16. transform_udp_mode¶
Determines how regular UDP is supported when transformations are supported. When transformations are enabled the default value is UDP_TRANSFORM_UDP_MODE_DISABLED.
5.6.7.3.17. transform_locator_kind¶
The locator to use for locators that have transformations. When transformation rules have been enabled, they are announced as a vendor specific locator. This property overrides this value.
NOTE: Changing this value may prevent communication.
5.6.7.4. UDP Transformations¶
The UDP transform feature enables custom transformation of incoming and outgoing UDP payloads based on transformation rules between a pair of source and destination IP addresses. Some examples of transformations are encrypted data or logging.
This section explains how to implement and use transformations in an application and is organized as follows:
5.6.7.4.1. Overview¶
The UDP transformation feature enables custom transformation of incoming and outgoing UDP payloads. For the purpose of this section, a UDP payload is defined as a sequence of octets sent or received as a single UDP datagram excluding UDP headers – typically UDP port numbers – and trailers, such as the optional used checksum.
An outgoing payload is the UDP payload passed to the network stack. The transformation feature allows a custom transformation of this payload just before it is sent. The UDP transport receives payloads to send from an upstream layer. In Connext Micro this layer is typically RTPS, which creates payloads containing one or more RTPS messages. The transformation feature enables transformation of the entire RTPS payload before it is passed to the network stack.
The same RTPS payload may be sent to one or more locators. A locator identifies a destination address, such as an IPv4 address, a port, such as a UDP port, and a transport kind. The address and port are used by the UDP transport to reach a destination. However, only the destination address is used to determine which transformation to apply.
An incoming payload is the UDP payload received from the network stack. The transformation feature enables transformation of the UDP payload received from the network stack before it is passed to the upstream interface, typically RTPS. The UDP transport only receives payloads destined for one of its network interface addresses, but may receive UDP payloads destined for many different ports. The transformation does not take a port into account, only the source address. In Connext Micro the payload is typically a RTPS payload containing one or more RTPS messages.
UDP transformations are registered with Connext Micro and used by the UDP transport to determine how to transform payloads based on a source or destination address. Please refer to Creating a Transformation Library for details on how to implement transformations and Creating Transformation Rules for how to add rules.
Transformations are local resources. There is no exchange between different UDP transports regarding what a transformation does to a payload. This is considered a-priori knowledge and depends on the implementation of the transformation. Any negotiation of e.g. keys must be handled before the UDP transport is registered. Thus, if a sender and receiver do not apply consistent rules, they may not be able to communicate, or incorrect data may result. Note that while information is typically in the direction from a DataWriter to a DataReader, a reliable DataReader also send protocol data to a DataWriter. These messages are also transformed.
5.6.7.4.1.1. Network Interface Selection¶
When a DomainParticipant is created, it first creates an instance of each transport configured in the DDS_DomainParticipantQos::transports QoS policy. Thus, each UDP transport registered with Connext Micro must have a unique name (up to 7 characters). Each registered transport can be configured to use all or some of the available interfaces using the allow_interface and deny_interface properties. The registered transports may now be used for either discovery data (specified in DomainParticipantQos::discovery), user_traffic (specified in DomainParticipantQos::user_traffic) or both. The DomainParticipant also queries the transport for which addresses it is capable of sending to.
When a participant creates multiple instances of the UDP transport, it is important that instances use non-overlapping networking interface resources.
5.6.7.4.1.2. Data Reception¶
Which transport to use for discovery data is determined by the DomainParticipantQos::discovery QoS policy. For each transport listed, the DomainParticipant reserves a network address to listen to. This network address is sent as part of the discovery data and is used by other DomainParticipants as the address to send discovery data for this DomainParticipant. Because a UDP transformation only looks at source and destination addresses, if different transformations are needed for discovery and user-data, different UDP transport registrations must be used and hence different network interfaces.
5.6.7.4.1.3. Data Transmission¶
Which address to send data to is based on the locators received as part of discovery and the peer list.
Received locators are analyzed and a transport locally registered with a DomainParticipant is selected based on the locator kind, address and mask. The first matching transport is selected. If a matching transport is not found, the locator is discarded.
NOTE: A transport is not a matching criteria at the same level as a QoS policy. If a discovered entity requests user data on a transport that doesn’t exist, it is not unmatched.
The peer list, as specified by the application, is a list of locators to send participant discovery announcements to. If the transport to use is not specified, e.g. “udp1@192.168.1.1”, but instead “192.168.1.1”, then all transports that understand this address will send to it. Thus, in this case the latter is used, and two different UDP transports are registered; they will both send to the same address. However, one transport may send transformed data and the other may not depending on the destination address.
5.6.7.4.2. Creating a Transformation Library¶
The transformation library is responsible for creating and performing transformations. Note that a library is a logical concept and does not refer to an actual library in, for example, UNIX. A library in this context is a collection of routines that together creates, manages, and performs transformations. How these routines are compiled and linked with an application using Connext Micro is out of scope of this section.
The transformation library must be registered with Connext Micro’s run-time and must implement the required interfaces. This ensures proper life-cycle management of transformation resources as well as clear guidelines regarding concurrency and memory management.
From Connext Micro’s run-time point of view, the transformation library must implement methods so that:
A library can be initialized.
A library can be instantiated.
An instance of the library performs and manages transformations.
The first two tasks are handled by Connext Micro’s run-time factory interface which is common for all libraries managed by Connext Micro. The third task is handled by the transformation interface, which is specific to UDP transformations.
The following describes the relationship between the different interfaces:
A library is initialized once when it is registered with Connext Micro.
A library is finalized once when it is unregistered from Connext Micro.
Multiple library instances can be created. If a library is used twice, for example registered with two different transports, two different library contexts are created using the factory interface. Connext Micro assumes that concurrent access to two different instances is allowed.
Different instances of the library can be deleted independently. An instance is deleted using the factory interface.
A library instance creates specific source or destination transformations. Each transformation is expected to transform a payload to exactly one destination or from one source.
The following relationship is true between the UDP transport and a UDP transformation library:
Each registered UDP transport may make use of one or more UDP transformation libraries.
A DDS DomainParticipant creates one instance of each registered UDP transport.
Each instance of the UDP transport creates one instance of each enabled transformation library registered with the UDP transport.
Each Transformation rule created by the UDP transport creates one send or one receive transformation.
5.6.7.4.3. Creating Transformation Rules¶
Transformation rules decide how a payload should be transformed based on either a source or destination address. Before a UDP transport is registered, it must be configured with the transformation libraries to use, as well as which library to use for each source and destination address. For each UDP payload sent or received, an instance of the UDP transport searches for a matching source or destination rule to determine which transformation to apply.
The transformation rules are added to the UDP_InterfaceFactoryProperty before registration takes place.
If no transformation rules have been configured, all payloads are treated as regular UDP packets.
If no send rules have been asserted, the payload is sent as is. If all outgoing messages are to be transformed, a single entry is sufficient (address = 0, mask = 0).
If no receive rules have been asserted, it is passed upstream as is. If all incoming messages are to be transformed, a single entry is sufficient (address = 0, mask = 0).
If no matching rule is found, the packet is dropped and an error is logged.
NOTE: UDP_InterfaceFactoryProperty is immutable after the UDP transport has been registered.
5.6.7.4.4. Interoperability¶
When the UDP transformations has enabled at least one transformation, it will only inter-operate with another UDP transport which also has at least one transformation.
UDP transformations does not interoperate with RTI Connext Professional.
5.6.7.4.5. Error Handling¶
The transformation rules are applied on a local basis and correctness is based on configuration. It is not possible to detect that a peer participant is configured for different behavior and errors cannot be detected by the UDP transport itself. However, the transformation interface can return errors which are logged.
5.6.7.4.6. Example Code¶
Example Header file MyUdpTransform.h:
#ifndef MyUdpTransform_h
#define MyUdpTransform_h
#include "rti_me_c.h"
#include "netio/netio_udp.h"
#include "netio/netio_interface.h"
struct MyUdpTransformFactoryProperty
{
struct RT_ComponentFactoryProperty _parent;
};
extern struct RT_ComponentFactoryI*
MyUdpTransformFactory_get_interface(void);
extern RTI_BOOL
MyUdpTransformFactory_register(RT_Registry_T *registry,
const char *const name,
struct MyUdpTransformFactoryProperty *property);
extern RTI_BOOL
MyUdpTransformFactory_unregister(RT_Registry_T *registry,
const char *const name,
struct MyUdpTransformFactoryProperty **);
#endif
Example Source file MyUdpTransform.c:
/*ce
* \file
* \defgroup UDPTransformExampleModule MyUdpTransform
* \ingroup UserManuals_UDPTransform
* \brief UDP Transform Example
*
* \details
*
* The UDP interface is implemented as a NETIO interface and NETIO interface
* factory.
*/
/*ce \addtogroup UDPTransformExampleModule
* @{
*/
#include <stdio.h>
#include "MyUdpTransform.h"
/*ce
* \brief The UDP Transformation factory class
*
* \details
* All Transformation components must have a factory. A factory creates one
* instance of the component as needed. In the case of UDP transformations,
* \rtime creates one instance per UDP transport instance.
*/
struct MyUdpTransformFactory
{
/*ce
* \brief Base-class. All \rtime Factories must inherit from RT_ComponentFactory.
*/
struct RT_ComponentFactory _parent;
/*ce
* \brief A pointer to the properties of the factory.
*
* \details
*
* When a factory is registered with \rtime it can be registered with
* properties specific to the component. However \rtime does not
* make a copy ( that would require additional methods). Furthermore, it
* may not be desirable to make a copy. Instead, this decision is
* left to the implementer of the component. \rtime does not access
* any custom properties.
*/
struct MyUdpTransformFactoryProperty *property;
};
/*ce
* \brief The custom UDP transformation class.
*
* \details
* The MyUdpTransformFactory creates one instance of this class for each
* UDP interface created. In this example one packet buffer (NETIO_Packet_T),
* is allocated and a buffer to hold the transformed data (\ref buffer)
*
* Only one transformation can be done at a time and it is synchronous. Thus,
* it is sufficient with one buffer to transform input and output per
* instance of the MyUdpTransform.
*/
struct MyUdpTransform
{
/*ce
* \brief Base-class. All UDP transforms must inherit from UDP_Transform
*/
struct UDP_Transform _parent;
/*ce \brief A reference to its own factory, if properties must be accessed
*/
struct MyUdpTransformFactory *factory;
/*ce \brief NETIO_Packet to hold a transformed payload.
*
* \details
*
* \rtime uses a NETIO_Packet_T to abstract data payload and this is
* what is being passed betweem the UDP transport and the transformation.
* The transformation must convert a payload into a NETIO_Packet. This
* is done with NETIO_Packet_initialize_from. This function saves all
* state except the payload buffer.
*/
NETIO_Packet_T packet;
/*ce \brief The payload to assign to NETIO_Packet_T
*
* \details
*
* A transformation cannot do in-place transformations because the input
* buffer may be sent multiple times (for example due to reliability).
* A transformation instance can only transform one buffer at a time
* (send or receive). The buffer must be large enough to hold a transformed
* payload. When the the transformation is created it receives a
* \ref UDP_TransformProperty. This property has the max send and
* receive buffers for transport and can be used to sise the buffer.
* Please refer to \ref UDP_InterfaceFactoryProperty::max_send_message_size
* and \ref UDP_InterfaceFactoryProperty::max_message_size.
*/
char *buffer;
/*ce \brief The maximum length of the buffer. NOTE: The buffer must
* be 1 byte larger than the largest buffer.
*/
RTI_SIZE_T max_buffer_length;
};
/*ce \brief Forward declaration of the interface implementation
*/
static struct UDP_TransformI MyUdpTransform_fv_Intf;
/*ce \brief Forward declaration of the interface factory implementation
*/
static struct RT_ComponentFactoryI MyUdpTransformFactory_fv_Intf;
/*ce \brief Method to create an instance of MyUdpTransform
*
* \param[in] factory The factory creating this instance
* \param[in] property Generic UDP_Transform properties
*
* \return A pointer to MyUdpTransform on sucess, NULL on failure.
*/
RTI_PRIVATE struct MyUdpTransform*
MyUdpTransform_create(struct MyUdpTransformFactory *factory,
const struct UDP_TransformProperty *const property)
{
struct MyUdpTransform *t;
OSAPI_Heap_allocate_struct(&t, struct MyUdpTransform);
if (t == NULL)
{
return NULL;
}
/* All component instances must initialize the parent using this
* call.
*/
RT_Component_initialize(&t->_parent._parent,
&MyUdpTransform_fv_Intf._parent,
0,
(property ? &property->_parent : NULL),
NULL);
t->factory = factory;
/* Allocate a buffer that is the larger of the send and receive
* size.
*/
t->max_buffer_length = property->max_receive_message_size;
if (property->max_send_message_size > t->max_buffer_length )
{
t->max_buffer_length = property->max_send_message_size;
}
/* Allocate 1 extra byte */
OSAPI_Heap_allocate_buffer(&t->buffer,t->max_buffer_length+1,
OSAPI_ALIGNMENT_DEFAULT);
if (t->buffer == NULL)
{
OSAPI_Heap_free_struct(t);
t = NULL;
}
return t;
}
/*ce \brief Method to delete an instance of MyUdpTransform
*
* \param[in] t Transformation instance to delete
*/
RTI_PRIVATE void
MyUdpTransform_delete(struct MyUdpTransform *t)
{
OSAPI_Heap_free_buffer(t->buffer);
OSAPI_Heap_free_struct(t);
}
/*ce \brief Method to create a transformation for an destination address
*
* \details
*
* For each asserted destination rule a transform is created by the transformation
* instance. This method determines how a UDP payload is transformed before
* it is sent to an address that matches destination & netmask.
*
* \param[in] udptf UDP Transform instance that creates the transformation
* \param[out] context Pointer to a transformation context
* \param[in] destination Destination address for the transformation
\param[in] netmask The netmask to apply to this destination.
* \param[in] user_data The user_data the rule was asserted with
* \param[in] property UDP transform specific properties
* \param[out] ec User defined error code
*
* \return RTI_TRUE on success, RTI_FALSE on failure
*/
RTI_PRIVATE RTI_BOOL
MyUdpTransform_create_destination_transform(
UDP_Transform_T *const udptf,
void **const context,
const struct NETIO_Address *const destination,
const struct NETIO_Netmask *const netmask,
void *user_data,
const struct UDP_TransformProperty *const property,
RTI_INT32 *const ec)
{
struct MyUdpTransform *self = (struct MyUdpTransform*)udptf;
UNUSED_ARG(self);
UNUSED_ARG(destination);
UNUSED_ARG(user_data);
UNUSED_ARG(property);
UNUSED_ARG(ec);
UNUSED_ARG(netmask);
/* Save the user-data to determine which transform to apply later */
*context = (void*)user_data;
return RTI_TRUE;
}
/*ce \brief Method to delete a transformation for an destination address
*
*
* \param[in] udptf UDP Transform instance that created the transformation
* \param[out] context Pointer to a transformation context
* \param[in] destination Destination address for the transformation
* \param[in] netmask The netmask to apply to this destination.
* \param[out] ec User defined error code
*
* \return RTI_TRUE on success, RTI_FALSE on failure
*/
RTI_PRIVATE RTI_BOOL
MyUdpTransform_delete_destination_transform(UDP_Transform_T *const udptf,
void *context,
const struct NETIO_Address *const destination,
const struct NETIO_Netmask *const netmask,
RTI_INT32 *const ec)
{
UNUSED_ARG(udptf);
UNUSED_ARG(context);
UNUSED_ARG(destination);
UNUSED_ARG(ec);
UNUSED_ARG(netmask);
return RTI_TRUE;
}
/*ce \brief Method to create a transformation for an source address
*
* \details
*
* For each asserted source rule a transform is created by the transformation
* instance. This method determines how a UDP payload is transformed when
* it is received from an address that matches source & netmask.
*
* \param[in] udptf UDP Transform instance that creates the transformation
* \param[out] context Pointer to a transformation context
* \param[in] source Destination address for the transformation
\param[in] netmask The netmask to apply to this destination.
* \param[in] user_data The user_data the rule was asserted with
* \param[in] property UDP transform specific properties
* \param[out] ec User defined error code
*
* \return RTI_TRUE on success, RTI_FALSE on failure
*/
RTI_PRIVATE RTI_BOOL
MyUdpTransform_create_source_transform(UDP_Transform_T *const udptf,
void **const context,
const struct NETIO_Address *const source,
const struct NETIO_Netmask *const netmask,
void *user_data,
const struct UDP_TransformProperty *const property,
RTI_INT32 *const ec)
{
struct MyUdpTransform *self = (struct MyUdpTransform*)udptf;
UNUSED_ARG(self);
UNUSED_ARG(source);
UNUSED_ARG(user_data);
UNUSED_ARG(property);
UNUSED_ARG(ec);
UNUSED_ARG(netmask);
*context = (void*)user_data;
return RTI_TRUE;
}
/*ce \brief Method to delete a transformation for an source address
*
*
* \param[in] udptf UDP Transform instance that created the transformation
* \param[out] context Pointer to a transformation context
* \param[in] source Source address for the transformation
* \param[in] netmask The netmask to apply to this destination.
* \param[out] ec User defined error code
*
* \return RTI_TRUE on success, RTI_FALSE on failure
*/
RTI_PRIVATE RTI_BOOL
MyUdpTransform_delete_source_transform(UDP_Transform_T *const udptf,
void *context,
const struct NETIO_Address *const source,
const struct NETIO_Netmask *const netmask,
RTI_INT32 *const ec)
{
UNUSED_ARG(udptf);
UNUSED_ARG(context);
UNUSED_ARG(source);
UNUSED_ARG(ec);
UNUSED_ARG(netmask);
return RTI_TRUE;
}
/*ce \brief Method to transform data based on a source address
*
* \param[in] udptf UDP_Transform_T that performs the transformation
* \param[in] context Reference to context created by \ref MyUdpTransform_create_source_transform
* \param[in] source Source address for the transformation
* \param[in] in_packet The NETIO packet to transform
* \param[out] out_packet The transformed NETIO packet
* \param[out] ec User defined error code
*
* \return RTI_TRUE on success, RTI_FALSE on failure
*/
RTI_PRIVATE RTI_BOOL
MyUdpTransform_transform_source(UDP_Transform_T *const udptf,
void *context,
const struct NETIO_Address *const source,
const NETIO_Packet_T *const in_packet,
NETIO_Packet_T **out_packet,
RTI_INT32 *const ec)
{
struct MyUdpTransform *self = (struct MyUdpTransform*)udptf;
char *buf_ptr,*buf_end;
char *from_buf_ptr,*from_buf_end;
UNUSED_ARG(context);
UNUSED_ARG(source);
*ec = 0;
/* Assigned the transform buffer to the outgoing packet
* saving state from the incoming packet. In this case the
* outgoing length is the same as the incoming. How to buffer
* is filled in is of no interest to \rtime. All it cares about is
* where it starts and where it ends.
*/
if (!NETIO_Packet_initialize_from(
&self->packet,in_packet,
self->buffer,self->max_buffer_length,
0,NETIO_Packet_get_payload_length(in_packet)))
{
return RTI_FALSE;
}
*out_packet = &self->packet;
buf_ptr = NETIO_Packet_get_head(&self->packet);
buf_end = NETIO_Packet_get_tail(&self->packet);
from_buf_ptr = NETIO_Packet_get_head(in_packet);
from_buf_end = NETIO_Packet_get_tail(in_packet);
/* Perform a transformation based on the user-data */
while (from_buf_ptr < from_buf_end)
{
if (context == (void*)1)
{
*buf_ptr = ~(*from_buf_ptr);
}
else if (context == (void*)2)
{
*buf_ptr = (*from_buf_ptr)+1;
}
++buf_ptr;
++from_buf_ptr;
}
return RTI_TRUE;
}
/*ce \brief Method to transform data based on a destination address
*
* \param[in] udptf UDP_Transform_T that performs the transformation
* \param[in] context Reference to context created by \ref MyUdpTransform_create_destination_transform
* \param[in] destination Source address for the transformation
* \param[in] in_packet The NETIO packet to transform
* \param[out] packet_out The transformed NETIO packet
* \param[out] ec User defined error code
*
* \return RTI_TRUE on success, RTI_FALSE on failure
*/
RTI_PRIVATE RTI_BOOL
MyUdpTransform_transform_destination(UDP_Transform_T *const udptf,
void *context,
const struct NETIO_Address *const destination,
const NETIO_Packet_T *const in_packet,
NETIO_Packet_T **packet_out,
RTI_INT32 *const ec)
{
struct MyUdpTransform *self = (struct MyUdpTransform*)udptf;
char *buf_ptr,*buf_end;
char *from_buf_ptr,*from_buf_end;
UNUSED_ARG(context);
UNUSED_ARG(destination);
*ec = 0;
if (!NETIO_Packet_initialize_from(
&self->packet,in_packet,
self->buffer,8192,
0,NETIO_Packet_get_payload_length(in_packet)))
{
return RTI_FALSE;
}
*out_packet = &self->packet;
buf_ptr = NETIO_Packet_get_head(&self->packet);
buf_end = NETIO_Packet_get_tail(&self->packet);
from_buf_ptr = NETIO_Packet_get_head(in_packet);
from_buf_end = NETIO_Packet_get_tail(in_packet);
while (from_buf_ptr < from_buf_end)
{
if (context == (void*)1)
{
*buf_ptr = ~(*from_buf_ptr);
}
else if (context == (void*)2)
{
*buf_ptr = (*from_buf_ptr)-1;
}
++buf_ptr;
++from_buf_ptr;
}
return RTI_TRUE;
}
/*ce \brief Definition of the transformation interface
*/
RTI_PRIVATE struct UDP_TransformI MyUdpTransform_fv_Intf =
{
RT_COMPONENTI_BASE,
MyUdpTransform_create_destination_transform,
MyUdpTransform_create_source_transform,
MyUdpTransform_transform_source,
MyUdpTransform_transform_destination,
MyUdpTransform_delete_destination_transform,
MyUdpTransform_delete_source_transform
};
/*ce \brief Method called by \rtime to create an instance of transformation
*/
MUST_CHECK_RETURN RTI_PRIVATE RT_Component_T*
MyUdpTransformFactory_create_component(struct RT_ComponentFactory *factory,
struct RT_ComponentProperty *property,
struct RT_ComponentListener *listener)
{
struct MyUdpTransform *t;
UNUSED_ARG(listener);
t = MyUdpTransform_create(
(struct MyUdpTransformFactory*)factory,
(struct UDP_TransformProperty*)property);
return &t->_parent._parent;
}
/*ce \brief Method called by \rtime to delete an instance of transformation
*/
RTI_PRIVATE void
MyUdpTransformFactory_delete_component(
struct RT_ComponentFactory *factory,
RT_Component_T *component)
{
UNUSED_ARG(factory);
MyUdpTransform_delete((struct MyUdpTransform*)component);
}
/*ce \brief Method called by \rtime when a factory is registered
*/
MUST_CHECK_RETURN RTI_PRIVATE struct RT_ComponentFactory*
MyUdpTransformFactory_initialize(struct RT_ComponentFactoryProperty* property,
struct RT_ComponentFactoryListener *listener)
{
struct MyUdpTransformFactory *fac;
UNUSED_ARG(property);
UNUSED_ARG(listener);
OSAPI_Heap_allocate_struct(&fac,struct MyUdpTransformFactory);
fac->_parent._factory = &fac->_parent;
fac->_parent.intf = &MyUdpTransformFactory_fv_Intf;
fac->property = (struct MyUdpTransformFactoryProperty*)property;
return &fac->_parent;
}
/*ce \brief Method called by \rtime when a factory is unregistered
*/
RTI_PRIVATE void
MyUdpTransformFactory_finalize(struct RT_ComponentFactory *factory,
struct RT_ComponentFactoryProperty **property,
struct RT_ComponentFactoryListener **listener)
{
struct MyUdpTransformFactory *fac =
(struct MyUdpTransformFactory*)factory;
UNUSED_ARG(property);
UNUSED_ARG(listener);
if (listener != NULL)
{
*listener = NULL;
}
if (property != NULL)
{
*property = (struct RT_ComponentFactoryProperty*)fac->property;
}
OSAPI_Heap_free_struct(factory);
return;
}
/*ce \brief Definition of the factory interface
*/
RTI_PRIVATE struct RT_ComponentFactoryI MyUdpTransformFactory_fv_Intf =
{
UDP_INTERFACE_INTERFACE_ID,
MyUdpTransformFactory_initialize,
MyUdpTransformFactory_finalize,
MyUdpTransformFactory_create_component,
MyUdpTransformFactory_delete_component,
NULL
};
struct RT_ComponentFactoryI*
MyUdpTransformFactory_get_interface(void)
{
return &MyUdpTransformFactory_fv_Intf;
}
/*ce \brief Method to register this transformation in a registry
*/
RTI_BOOL
MyUdpTransformFactory_register(RT_Registry_T *registry,
const char *const name,
struct MyUdpTransformFactoryProperty *property)
{
return RT_Registry_register(registry, name,
MyUdpTransformFactory_get_interface(),
&property->_parent, NULL);
}
/*ce \brief Method to unregister this transformation from a registry
*/
RTI_BOOL
MyUdpTransformFactory_unregister(RT_Registry_T *registry,
const char *const name,
struct MyUdpTransformFactoryProperty **property)
{
return RT_Registry_unregister(registry, name,
(struct RT_ComponentFactoryProperty**)property,
NULL);
}
/*! @} */
Example configuration of rules:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "common.h"
void
MyAppApplication_help(char *appname)
{
printf("%s [options]\n", appname);
printf("options:\n");
printf("-h - This text\n");
printf("-domain <id> - DomainId (default: 0)\n");
printf("-udp_intf <intf> - udp interface (no default)\n");
printf("-peer <address> - peer address (no default)\n");
printf("-count <count> - count (default -1)\n");
printf("-sleep <ms> - sleep between sends (default 1s)\n");
printf("\n");
}
struct MyAppApplication*
MyAppApplication_create(const char *local_participant_name,
const char *remote_participant_name,
DDS_Long domain_id, char *udp_intf, char *peer,
DDS_Long sleep_time, DDS_Long count)
{
DDS_ReturnCode_t retcode;
DDS_DomainParticipantFactory *factory = NULL;
struct DDS_DomainParticipantFactoryQos dpf_qos =
DDS_DomainParticipantFactoryQos_INITIALIZER;
struct DDS_DomainParticipantQos dp_qos =
DDS_DomainParticipantQos_INITIALIZER;
DDS_Boolean success = DDS_BOOLEAN_FALSE;
struct MyAppApplication *application = NULL;
RT_Registry_T *registry = NULL;
struct UDP_InterfaceFactoryProperty *udp_property = NULL;
struct DPDE_DiscoveryPluginProperty discovery_plugin_properties =
DPDE_DiscoveryPluginProperty_INITIALIZER;
UNUSED_ARG(local_participant_name);
UNUSED_ARG(remote_participant_name);
/* Uncomment to increase verbosity level:
OSAPILog_set_verbosity(OSAPI_LOG_VERBOSITY_WARNING);
*/
application = (struct MyAppApplication *)malloc(sizeof(struct MyAppApplication));
if (application == NULL)
{
printf("failed to allocate application\n");
goto done;
}
application->sleep_time = sleep_time;
application->count = count;
factory = DDS_DomainParticipantFactory_get_instance();
if (DDS_DomainParticipantFactory_get_qos(factory,&dpf_qos) != DDS_RETCODE_OK)
{
printf("failed to get number of components\n");
goto done;
}
dpf_qos.resource_limits.max_components = 128;
if (DDS_DomainParticipantFactory_set_qos(factory,&dpf_qos) != DDS_RETCODE_OK)
{
printf("failed to increase number of components\n");
goto done;
}
registry = DDS_DomainParticipantFactory_get_registry(
DDS_DomainParticipantFactory_get_instance());
if (!RT_Registry_register(registry, DDSHST_WRITER_DEFAULT_HISTORY_NAME,
WHSM_HistoryFactory_get_interface(), NULL, NULL))
{
printf("failed to register wh\n");
goto done;
}
if (!RT_Registry_register(registry, DDSHST_READER_DEFAULT_HISTORY_NAME,
RHSM_HistoryFactory_get_interface(), NULL, NULL))
{
printf("failed to register rh\n");
goto done;
}
if (!MyUdpTransformFactory_register(registry,"T0",NULL))
{
printf("failed to register T0\n");
goto done;
}
if (!MyUdpTransformFactory_register(registry,"T1",NULL))
{
printf("failed to register T0\n");
goto done;
}
/* Configure UDP transport's allowed interfaces */
if (!RT_Registry_unregister(registry, NETIO_DEFAULT_UDP_NAME, NULL, NULL))
{
printf("failed to unregister udp\n");
goto done;
}
udp_property = (struct UDP_InterfaceFactoryProperty *)
malloc(sizeof(struct UDP_InterfaceFactoryProperty));
if (udp_property == NULL)
{
printf("failed to allocate udp properties\n");
goto done;
}
*udp_property = UDP_INTERFACE_FACTORY_PROPERTY_DEFAULT;
/* For additional allowed interface(s), increase maximum and length, and
set interface below:
*/
udp_property->max_send_message_size = 16384;
udp_property->max_message_size = 32768;
if (udp_intf != NULL)
{
REDA_StringSeq_set_maximum(&udp_property->allow_interface,1);
REDA_StringSeq_set_length(&udp_property->allow_interface,1);
*REDA_StringSeq_get_reference(&udp_property->allow_interface,0) =
DDS_String_dup(udp_intf);
}
/* A rule that says: For payloads received from 192.168.10.* (netmask is
* 0xffffff00), apply transformation T0.
*/
if (!UDP_TransformRules_assert_source_rule(
&udp_property->source_rules,
0xc0a80ae8,0xffffff00,"T0",(void*)2))
{
printf("Failed to assert source rule\n");
goto done;
}
/* A rule that says: For payloads sent to 192.168.10.* (netmask is
* 0xffffff00), apply transformation T0.
*/
if (!UDP_TransformRules_assert_destination_rule(
&udp_property->destination_rules,
0xc0a80ae8,0xffffff00,"T0",(void*)2))
{
printf("Failed to assert source rule\n");
goto done;
}
/* A rule that says: For payloads received from 192.168.20.* (netmask is
* 0xffffff00), apply transformation T1.
*/
if (!UDP_TransformRules_assert_source_rule(
&udp_property->source_rules,
0xc0a81465,0xffffff00,"T1",(void*)1))
{
printf("Failed to assert source rule\n");
goto done;
}
/* A rule that says: For payloads received from 192.168.20.* (netmask is
* 0xffffff00), apply transformation T1.
*/
if (!UDP_TransformRules_assert_destination_rule(
&udp_property->destination_rules,
0xc0a81465,0xffffff00,"T1",(void*)1))
{
printf("Failed to assert source rule\n");
goto done;
}
if (!RT_Registry_register(registry, NETIO_DEFAULT_UDP_NAME,
UDP_InterfaceFactory_get_interface(),
(struct RT_ComponentFactoryProperty*)udp_property, NULL))
{
printf("failed to register udp\n");
goto done;
}
DDS_DomainParticipantFactory_get_qos(factory, &dpf_qos);
dpf_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;
DDS_DomainParticipantFactory_set_qos(factory, &dpf_qos);
if (peer == NULL)
{
peer = "127.0.0.1"; /* default to loopback */
}
if (!RT_Registry_register(registry,
"dpde",
DPDE_DiscoveryFactory_get_interface(),
&discovery_plugin_properties._parent,
NULL))
{
printf("failed to register dpde\n");
goto done;
}
if (!RT_ComponentFactoryId_set_name(&dp_qos.discovery.discovery.name,"dpde"))
{
printf("failed to set discovery plugin name\n");
goto done;
}
DDS_StringSeq_set_maximum(&dp_qos.discovery.initial_peers,1);
DDS_StringSeq_set_length(&dp_qos.discovery.initial_peers,1);
*DDS_StringSeq_get_reference(&dp_qos.discovery.initial_peers,0) = DDS_String_dup(peer);
DDS_StringSeq_set_maximum(&dp_qos.discovery.enabled_transports,1);
DDS_StringSeq_set_length(&dp_qos.discovery.enabled_transports,1);
/* Use network interface 192.168.10.232 for discovery. T0 is used for
* discovery
*/
*DDS_StringSeq_get_reference(&dp_qos.discovery.enabled_transports,0) = DDS_String_dup("_udp://192.168.10.232");
DDS_StringSeq_set_maximum(&dp_qos.user_traffic.enabled_transports,1);
DDS_StringSeq_set_length(&dp_qos.user_traffic.enabled_transports,1);
/* Use network interface 192.168.20.101 for user-data. T1 is used for
* this interface.
*/
*DDS_StringSeq_get_reference(&dp_qos.user_traffic.enabled_transports,0) = DDS_String_dup("_udp://192.168.20.101");
/* if there are more remote or local endpoints, you need to increase these limits */
dp_qos.resource_limits.max_destination_ports = 32;
dp_qos.resource_limits.max_receive_ports = 32;
dp_qos.resource_limits.local_topic_allocation = 1;
dp_qos.resource_limits.local_type_allocation = 1;
dp_qos.resource_limits.local_reader_allocation = 1;
dp_qos.resource_limits.local_writer_allocation = 1;
dp_qos.resource_limits.remote_participant_allocation = 8;
dp_qos.resource_limits.remote_reader_allocation = 8;
dp_qos.resource_limits.remote_writer_allocation = 8;
application->participant =
DDS_DomainParticipantFactory_create_participant(factory, domain_id,
&dp_qos, NULL,
DDS_STATUS_MASK_NONE);
if (application->participant == NULL)
{
printf("failed to create participant\n");
goto done;
}
sprintf(application->type_name, "HelloWorld");
retcode = DDS_DomainParticipant_register_type(application->participant,
application->type_name,
HelloWorldTypePlugin_get());
if (retcode != DDS_RETCODE_OK)
{
printf("failed to register type: %s\n", "test_type");
goto done;
}
sprintf(application->topic_name, "HelloWorld");
application->topic =
DDS_DomainParticipant_create_topic(application->participant,
application->topic_name,
application->type_name,
&DDS_TOPIC_QOS_DEFAULT, NULL,
DDS_STATUS_MASK_NONE);
if (application->topic == NULL)
{
printf("topic == NULL\n");
goto done;
}
success = DDS_BOOLEAN_TRUE;
done:
if (!success)
{
if (udp_property != NULL)
{
free(udp_property);
}
free(application);
application = NULL;
}
return application;
}
DDS_ReturnCode_t
MyAppApplication_enable(struct MyAppApplication * application)
{
DDS_Entity *entity;
DDS_ReturnCode_t retcode;
entity = DDS_DomainParticipant_as_entity(application->participant);
retcode = DDS_Entity_enable(entity);
if (retcode != DDS_RETCODE_OK)
{
printf("failed to enable entity\n");
}
return retcode;
}
void
MyAppApplication_delete(struct MyAppApplication *application)
{
DDS_ReturnCode_t retcode;
RT_Registry_T *registry = NULL;
retcode = DDS_DomainParticipant_delete_contained_entities(application->participant);
if (retcode != DDS_RETCODE_OK)
{
printf("failed to delete conteined entities (retcode=%d)\n",retcode);
}
if (DDS_DomainParticipant_unregister_type(application->participant,
application->type_name) != HelloWorldTypePlugin_get())
{
printf("failed to unregister type: %s\n", application->type_name);
return;
}
retcode = DDS_DomainParticipantFactory_delete_participant(
DDS_DomainParticipantFactory_get_instance(),
application->participant);
if (retcode != DDS_RETCODE_OK)
{
printf("failed to delete participant: %d\n", retcode);
return;
}
registry = DDS_DomainParticipantFactory_get_registry(
DDS_DomainParticipantFactory_get_instance());
if (!RT_Registry_unregister(registry, "dpde", NULL, NULL))
{
printf("failed to unregister dpde\n");
return;
}
if (!RT_Registry_unregister(registry, DDSHST_READER_DEFAULT_HISTORY_NAME, NULL, NULL))
{
printf("failed to unregister rh\n");
return;
}
if (!RT_Registry_unregister(registry, DDSHST_WRITER_DEFAULT_HISTORY_NAME, NULL, NULL))
{
printf("failed to unregister wh\n");
return;
}
free(application);
DDS_DomainParticipantFactory_finalize_instance();
}
5.6.7.4.7. Examples¶
The following examples illustrate how this feature can be used in a system with a mixture of different types of UDP transport configurations.
For the purpose of the examples, the following terminology is used:
Plain communication – No transformations have been applied.
Transformed User Data – Only the user-data is transformed, discovery is plain.
Transformed Discovery – Only the discovery data is transformed, user-data is plain.
Transformed Data – Both discovery and user-data are transformed. Unless stated otherwise the transformations are different.
A transformation Tn is a transformation such that an outgoing payload transformed with Tn can be transformed back to its original state by applying Tn to the incoming data.
A network interface can be either physical or virtual.
5.6.7.4.7.1. Plain Communication Between 2 Nodes¶
In this system two Nodes, A and B, are communicating with plain communication. Node A has one interface, a0, and Node B has one interface, b0.
Node A:
Register the UDP transport Ua with allow_interface = a0.
DomainParticipantQos.transports.enabled_transports = “Ua”
DomainParticipantQos.discovery.enabled_transports = ”Ua://”
DomainParticipantQos.user_data.enabled_transports = ”Ua://”
Node B:
Register the UDP transport Ub with allow_interface = b0.
DomainParticipantQos.transports.enabled_transports = “Ub”
DomainParticipantQos.discovery.enabled_transports = ”Ub://”
DomainParticipantQos.user_data.enabled_transports = ”Ub://”
5.6.7.4.7.2. Transformed User Data Between 2 Nodes¶
In this system two Nodes, A and B, are communicating with transformed user data. Node A has two interfaces, a0 and a1, and Node B has two interfaces, b0 and b1. Since each node has only one peer, a single transformation is sufficient.
Node A:
Add a destination transformation T0 to Ua0, indicating that all sent data is transformed with T0.
Add a source transformation T1 to Ua0, indicating that all received data is transformed with T1.
Register the UDP transport Ua0 with allow_interface = a0.
Register the UDP transport Ua1 with allow_interface = a1.
No transformations are registered with Ua1.
DomainParticipantQos.transports.enabled_transports = “Ua0”,”Ua1”
DomainParticipantQos.discovery.enabled_transports = ”Ua1://”
DomainParticipantQos.user_traffic.enabled_transports = ”Ua0://”
Node B:
Add a destination transformation T1 to Ub0, indicating that all sent data is transformed with T1.
Add a source transformation T0 to Ub0, indicating that all received data is transformed with T0.
Register the UDP transport Ub0 with allow_interface = b0.
Register the UDP transport Ub1 with allow_interface = b1.
No transformations are registered with Ub1.
DomainParticipantQos.transports.enabled_transports = “Ub0”,”Ub1”
DomainParticipantQos.discovery.enabled_transports = ”Ub1://”
DomainParticipantQos.user_traffic.enabled_transports = ”Ub0://”
Ua0 and Ub0 perform transformations and are used for user-data. Ua1 and Ub1 are used for discovery and no transformations takes place.
5.6.7.4.7.3. Transformed Discovery Data Between 2 Nodes¶
In this system two Nodes, A and B, are communicating with transformed user data. Node A has two interfaces, a0 and a1, and Node B has two interfaces, b0 and b1. Since each node has only one peer, a single transformation is sufficient.
Node A:
Add a destination transformation T0 to Ua0, indicating that all sent data is transformed with T0.
Add a source transformation T1 to Ua0, indicating that all received data is transformed with T1.
Register the UDP transport Ua0 with allow_interface = a0.
Register the UDP transport Ua1 with allow_interface = a1.
No transformations are registered with Ua1.
DomainParticipantQos.transports.enabled_transports = “Ua0”,”Ua1”
DomainParticipantQos.discovery.enabled_transports = ”Ua0://”
DomainParticipantQos.user_data.enabled_transports = ”Ua1://”
Node B:
Add a destination transformation T1 to Ub0, indicating that all sent data is transformed with T1.
Add a source transformation T0 to Ub0, indicating that all received data is transformed with T0.
Register the UDP transport Ub0 with allow_interface = b0.
Register the UDP transport Ub1 with allow_interface = b1.
No transformations are registered with Ub1.
DomainParticipantQos.transports.enabled_transports = “Ub0”,”Ub1”
DomainParticipantQos.discovery.enabled_transports = ”Ub0://”
DomainParticipantQos.user_data.enabled_transports = ”Ub1://”
Ua0 and Ub0 perform transformations and are used for discovery. Ua1 and Ub1 are used for user-data and no transformation takes place.
5.6.7.4.7.4. Transformed Data Between 2 Nodes (same transformation)¶
In this system two Nodes, A and B, are communicating with transformed data using the same transformation for user and discovery data. Node A has one interface, a0, and Node B has one interface, b0.
Node A:
Add a destination transformation T0 to Ua0, indicating that all sent data is transformed with T0.
Add a source transformation T1 to Ua0, indicating that all received data is transformed with T1.
Register the UDP transport Ua0 with allow_interface = a0.
DomainParticipantQos.transports.enabled_transports = “Ua0”
DomainParticipantQos.discovery.enabled_transports = ”Ua0://”
DomainParticipantQos.user_data.enabled_transports = ”Ua0://”
Node B:
Add a destination transformation T1 to Ub0, indicating that all sent data is transformed with T1.
Add a source transformation T0 to Ub0, indicating that all received data is transformed with T0.
Register the UDP transport Ub0 with allow_interface = b0.
DomainParticipantQos.transports.enabled_transports = “Ub0”
DomainParticipantQos.discovery.enabled_transports = ”Ub0://”
DomainParticipantQos.user_data.enabled_transports = ”Ub0://”
Ua0 and Ub0 performs transformations and are used for discovery and for user-data.
5.6.7.4.7.5. Transformed Data Between 2 Nodes (different transformations)¶
In this system two Nodes, A and B, are communicating with transformed data using different transformations for user and discovery data. Node A has two interfaces, a0 and a1, and Node B has two interfaces, b0 and b1.
Node A:
Add a destination transformation T0 to Ua0, indicating that all sent data is transformed with T0.
Add a source transformation T1 to Ua0, indicating that all received data is transformed with T1.
Add a destination transformation T2 to Ua1, indicating that all sent data is transformed with T2.
Add a source transformation T3 to Ua1, indicating that all received data is transformed with T3.
Register the UDP transport Ua0 with allow_interface = a0.
Register the UDP transport Ua1 with allow_interface = a1.
DomainParticipantQos.transports.enabled_transports = “Ua0”,”Ua1”
DomainParticipantQos.discovery.enabled_transports = ”Ua0://”
DomainParticipantQos.user_data.enabled_transports = ”Ua1://”
Node B:
Add a destination transformation T1 to Ub0, indicating that all sent data is transformed with T1.
Add a source transformation T0 to Ub0, indicating that all received data is transformed with T0.
Add a destination transformation T3 to Ub1, indicating that all sent data is transformed with T3.
Add a source transformation T2 to Ub1, indicating that all received data is transformed with T2.
Register the UDP transport Ub0 with allow_interface = b0.
Register the UDP transport Ub1 with allow_interface = b1.
DomainParticipantQos.transports.enabled_transports = “Ub0”,”Ub1”
DomainParticipantQos.discovery.enabled_transports = ”Ub0://”
DomainParticipantQos.user_data.enabled_transports = ”Ub1://”
Ua0 and Ub0 perform transformations and are used for discovery. Ua1 and Ub1 perform transformations and are used for user-data.
5.6.7.4.7.6. OS Configuration¶
In systems with several network interfaces, Connext Micro cannot ensure which network interface should be used to send a packet. Depending on the UDP transformations configured, this might be a problem.
To illustrate this problem, let’s assume a system with two nodes, A and B. Node A has two network interfaces, a0 and a1, and Node B has two network interfaces, b0 and b1. In this system, Node A is communicating with Node B using a transformation for discovery and a different transformation for user data.
Node A:
Add a destination transformation T0 to Ua0, indicating that sent data to b0 is transformed with T0.
Add a source transformation T1 to Ua0, indicating that received data from b0 is transformed with T1.
Add a destination transformation T2 to Ua1, indicating that sent data to b1 is transformed with T2.
Add a source transformation T3 to Ua1, indicating that received data from b1 is transformed with T3.
Register the UDP transport Ua0 with allow_interface = a0.
Register the UDP transport Ua1 with allow_interface = a1.
DomainParticipantQos.transports.enabled_transports = “Ua0”,”Ua1”
DomainParticipantQos.discovery.enabled_transports = ”Ua0://”
DomainParticipantQos.user_data.enabled_transports = ”Ua1://”
Node B:
Add a destination transformation T1 to Ub0, indicating that sent data to a0 is transformed with T1.
Add a source transformation T0 to Ub0, indicating that received data from a0 transformed with T0.
Add a destination transformation T3 to Ub1, indicating that sent data to a1 is transformed with T3.
Add a source transformation T2 to Ub1, indicating that received data from a1 transformed with T2.
Register the UDP transport Ub0 with allow_interface = b0.
Register the UDP transport Ub1 with allow_interface = b1.
DomainParticipantQos.transports.enabled_transports = “Ub0”,”Ub1”
DomainParticipantQos.discovery.enabled_transports = ”Ub0://”
DomainParticipantQos.user_data.enabled_transports = ”Ub1://”
Node A sends a discovery packet to Node B to interface b0. This packet will be transformed using T0 as specified by Node A’s configuration. When this packet is received in Node B, it will be transformed using either T0 or T2 depending on the source address. Node’s A OS will use a0 or a1 to send this packet but Connext Micro cannot ensure which one will be used. In case the OS sends the packet using a1, the wrong transformation will be applied in Node B.
Some systems have the possibility to configure the source address that should be
used when a packet is sent. In POSIX systems, the command ip route add <string> dev
<interface> can be used.
By typing the command ip route add < b0 ip >/32 dev a0 in Node A, the OS will send
all packets to Node B’s b0 IP address using interface a0. This would ensure that
the correct transformation is applied in Node B. The same should be done to ensure
that user data is sent with the right address ip route add < b1 ip >/32 dev a1.
Of course, similar configuration is needed in Node B.