.. _transport_netio_dgram: NETIO Datagram Transport ======================== This section describes the built-in |me| Datagram transport and how to configure it. The built-in Datagram transport (DGRAM) is a generic transport plugin service. DGRAM is part of the |me| core library that is compiled for a specific CPU architecture with a specific compiler. However, the DGRAM transport does not include integration with any particular network stack. Instead, the DGRAM transport provides a simplified interface which can integrate with a variety of different networking technologies. The DGRAM plugin supports transmission and reception of RTPS messages over a connectionless network link. Note that while the DGRAM transport itself has no knowledge of the underlying network stack, the DGRAM API does not include an API related to establishing connections, such as TCP. Registering a Datagram interface -------------------------------- DGRAM is a |me| component that can be registered with :link_connextmicro_dds_api_c_up_two:`NETIO_DGRAM_InterfaceFactory_register() ` as shown below: .. code-block:: c DDS_DomainParticipantFactory *factory = NULL; RT_Registry_T *registry = NULL; factory = DDS_DomainParticipantFactory_get_instance(); registry = DDS_DomainParticipantFactory_get_registry(factory); The factory gets the registry. The registry then registers the Datagram. When a component is registered, the registration parses the DGRAM interface as the third parameter and the properties as the fourth parameter. In general, the caller is responsible to manage the memory for the properties and ensure they are valid as long as the DGRAM transport is registered. There is no guarantee that a component makes a copy. The DGRAM interface is a component that interfaces with the |me| core library. You must implement the ``NETIO_DGRAM_InterfaceI``, which integrates with a specific network technology. This ``struct`` must be compliant with the ``NETIO_DGRAM_InterfaceI`` structure, as shown below: .. code-block:: c /* Create the DGRAM User Interface property struct */ struct MyDgramInterfaceProperty { RTI_INT32 a_property; struct UTEST_Context *setting; } MyDgramInterfaceProperty = {10,NULL}; /* Example operation */ struct NETIO_Interface* MyDgramInterface_create_instance(NETIO_Interface_T *upstream,void *property) { /* Perform operations */ ... return myInterface; } ... /* Create the DGRAM Interface struct where each member points to it's * respective operation */ RTI_PRIVATE struct NETIO_DGRAM_InterfaceI MyDgramInterface = { MyDgramInterface_create_instance, MyDgramInterface_get_interface_list, MyDgramInterface_release_address, MyDgramInterface_resolve_address_udpv4, MyDgramInterface_send, MyDgramInterface_get_route_table, MyDgramInterface_bind_address }; The following code snippet shows how to register the DGRAM interface with new parameters. The Datagram needs to register the DGRAM interface with a property that has the interface to call: .. code-block:: c /* Register the transport again, using the builtin name */ if (!NETIO_DGRAM_InterfaceFactory_register(registry, "name", &MyDgramInterface, &MyDgramInterfaceProperty)) { /* ERROR */ } .. note:: The Datagram 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 will be logged. Addressing a Datagram transport ------------------------------- The interface may also set the enabled transports to receive data, as shown below: .. code-block:: c struct DDS_DomainParticipantQos dp_qos = DDS_DomainParticipantQos_INITIALIZER; /* Datagram enable transport xyz. A second transport can be added * by setting the enabled_transports value to 2 and adding a second * transport name. enabled_transport indicates what addresses the entity is * listening on. */ DDS_StringSeq_set_maximum(&dp_qos.transports.enabled_transports,1); DDS_StringSeq_set_length(&dp_qos.transports.enabled_transports,1); *DDS_StringSeq_get_reference(&dp_qos.transports.enabled_transports,0) = DDS_String_dup("xyz"); /* Receive discovery traffic on xyz */ DDS_StringSeq_set_maximum(&dp_qos.discovery.enabled_transports,1); DDS_StringSeq_set_length(&dp_qos.discovery.enabled_transports,1); *DDS_StringSeq_get_reference(&dp_qos.discovery.enabled_transports,0) = DDS_String_dup("xyz://"); /* Receive user-data traffic on xyz. */ DDS_StringSeq_set_maximum(&dp_qos.user_traffic.enabled_transports,1); DDS_StringSeq_set_length(&dp_qos.user_traffic.enabled_transports,1); *DDS_StringSeq_get_reference(&dp_qos.user_traffic.enabled_transports,0) = DDS_String_dup("xyz://"); An address may set up peers to send messages over this interface. For example, interface xyz may set its initial peers as: .. code-block:: c /* Send discovery data on address 0x0A00020F*/ 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("0x0A00020F"); Setting up the Datagram UDP --------------------------- The built-in Datagram transport can support UDP integration. The built-in Datagram transport for UDP registers differently than the generic Datagram component. Use ``UDP_Interface_register()`` with UDP properties to create the datagram instance for UDP, as shown below: .. code-block:: c struct UDP_InterfaceFactoryProperty udp_property = UDP_InterfaceFactoryProperty_INITIALIZER; /* To enable sharing this property must be set to RTI_FALSE */ udp_property->enable_interface_bind = RTI_TRUE; /* */ 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(intf); /* To enable multicast operations the multicast flag and multicast_interface * property must be set */ if (is_multicast) { flags |= UDP_INTERFACE_INTERFACE_MULTICAST_FLAG; udp_property->multicast_interface = DDS_String_dup(intf); } else { /* Set the mutlicast interface to NULL when not used*/ udp_property->multicast_interface = NULL; } /* Add an available interface for UDP */ if (!UDP_InterfaceTable_add_entry(&udp_property->if_table, address, netmask, intf_name, flags)) { /* error */ } /* Buffer properties */ udp_property->max_send_buffer_size = MAX_SEND_BUFFER_SIZE; udp_property->max_receive_buffer_size = MAX_RECV_BUFFER_SIZE; udp_property->max_message_size = MAX_RECV_BUFFER_SIZE; /* Register the datagram */ if(!UDP_Interface_register(registry, "_udp", udp_property)) { /* error */ } Enabled transports can be configured with ``"_udp://"``. This will use all interfaces. Enabling a UDP is similar to generic addressing, as shown below: .. code-block:: c struct DDS_DomainParticipantQos dp_qos = DDS_DomainParticipantQos_INITIALIZER; DDS_StringSeq_set_maximum(&dp_qos.transports.enabled_transports,1); DDS_StringSeq_set_length(&dp_qos.transports.enabled_transports,1); DDS_StringSeq_set_maximum(&dp_qos.discovery.enabled_transports,1); DDS_StringSeq_set_length(&dp_qos.discovery.enabled_transports,1); DDS_StringSeq_set_maximum(&dp_qos.user_traffic.enabled_transports,1); DDS_StringSeq_set_length(&dp_qos.user_traffic.enabled_transports,1); /* This only requires the transport name */ *DDS_StringSeq_get_reference(&dp_qos.transports.enabled_transports,0) = DDS_String_dup("_udp"); /* _udp:// indicates to use all available locators */ *DDS_StringSeq_get_reference(&dp_qos.discovery.enabled_transports,0) = DDS_String_dup("_udp://"); /* _udp://10.10.0.1 would indicate to use only that address */ *DDS_StringSeq_get_reference(&dp_qos.user_traffic.enabled_transports,0) = DDS_String_dup("_udp://"); Datagram shared port flag ......................... |me| can work with two different types of transports: ones that use shared ports and ones that do not. |me| supports a flag for the Datagram transport, :link_connextmicro_dds_api_c_up_two:`NETIO_DGRAM_INTERFACE_SHARED_PORT_FLAG `, to enable the use of shared ports on a per-transport basis. When the shared port flag is enabled, it doesn't matter which network interface the transport receives messages on; only the port matters. For example, consider a computer with two network interfaces, **A** and **B**, which is listening for messages on port **P**. As long as the message is received on any network interface capable of receiving on port **P**, the transport will accept the message; it doesn't matter if the message is received on **A** or **B**. However, when the shared port flag is *not* enabled, it does matter which network interface the transport receives messages on. For example, consider a computer with two network interfaces, **A** and **B**, which is listening for messages on port **P** like before. However, this computer has specified that network interface **A** should only receive on port **P**. The transport will then ignore messages received on network interface **B** and port **P**. When the transport accepts a message, the transport routes it to all relevant *DataReaders* and *DataWriters*; thus, the :link_connextmicro_dds_api_c_up_two:`NETIO_DGRAM_INTERFACE_SHARED_PORT_FLAG ` cannot be used to control whether some DDS topics should only be accepted when received on a specific network interface. However, this feature allows different *DomainParticipants* to use the same port with different network interfaces. User interface -------------- :link_connextmicro_dds_api_c_up_two:`NETIO_DGRAM_InterfaceFactory_register() ` registers a user interface structure that is passed in via ``user_intf``. The *DomainParticipant* utilizes these functions for network operations, such as creating a Datagram interface instance and getting the interface list. .. list-table:: Structure for the User Interface :name: User Interface :widths: 30 70 :header-rows: 1 :class: longtable * - Interface Attribute - Description * - ``create_instance`` - Creates an instance of the NETIO_DGRAM interface. * - ``delete_instance`` - Deletes an instance of the NETIO_DGRAM interface. * - ``get_interface_list`` - Reads the available interfaces from the NETIO_DGRAM interface. * - ``release_address`` - Instructs the NETIO_DGRAM interface to stop listening for messages on the source address. * - ``resolve_address`` - Instructs the NETIO_DGRAM interface to determine if the address string is valid. * - ``send`` - Instructs the NETIO_DGRAM interface to send a message. * - ``get_route_table`` - Instructs the NETIO_DGRAM interface ``netio_intf`` to return a sequence of address and netmask pairs that this interface can send to. * - ``bind_address`` - Instructs the NETIO_DGRAM interface to listen for messages on the source address.