.. _section-transport-registration:

Transport Registration
----------------------

|rti_me| supports different transports, and transports must be registered with
|me| before they can be used by an application. 

Transports must be registered with a unique name; this name is later used to 
configure where to send and receive discovery and user data. A transport name 
cannot exceed seven (7) UTF-8 characters. 

.. note::

  The name the transport is registered with has no meaning to |me|. A transport 
  plugin may allow multiple registerations under different names. For example,
  two UDPv4 transport plugins may be registered, one for discovery and one for
  user data, with different properties.

The following example registers the UDP transport with |rti_me| and makes
it available to all DDS applications within the same memory space. Please
note that each DDS applications creates its *own* instance of a transport
based on its QoS policies. Resources are *not* shared between instances of a 
transport unless otherwise stated.

For example, to register two UDP transports with the names "myudp1" and "myudp2", 
the following code is required:

::

    DDS_DomainParticipantFactory *factory;
    RT_Registry_T *registry;

    /* In general properties must be available for the lifetime of the
     * transport.
     */    
    struct UDP_InterfaceFactoryProperty udp_property1;
    struct UDP_InterfaceFactoryProperty udp_property2;

    factory = DDS_DomainParticipantFactory_get_instance();
    registry = DDS_DomainParticipantFactory_get_registry(factory);

    /* Set UDP properties */
    if (!RT_Registry_register(registry,"myudp1",
                              UDP_InterfaceFactory_get_interface(),
                              &udp_property2._parent._parent,NULL))
    {
        return error;
    }

    /* Set UDP properties */
    if (!RT_Registry_register(registry,"myudp2",
                              UDP_InterfaceFactory_get_interface(),
                              &udp_property2._parent._parent,NULL))
    {
        return error;
    }

Before a *DomainParticipant* can make use of a registered transport, it must 
enable it for use within the *DomainParticipant*. This is done by setting
the :link_connextmicro_dds_api_c_up_two:`TransportQoS <structDDS__TransportQosPolicy.html>`.
For example, to enable only "myudp1", the following
code is required (error checking is not shown for clarity):

::

    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) =
                                                     REDA_String_dup("myudp1");


To enable both transports:

::

    DDS_StringSeq_set_maximum(&dp_qos.transports.enabled_transports,2);
    DDS_StringSeq_set_length(&dp_qos.transports.enabled_transports,2);
    *DDS_StringSeq_get_reference(&dp_qos.transports.enabled_transports,0) =
                                                     REDA_String_dup("myudp1");
    *DDS_StringSeq_get_reference(&dp_qos.transports.enabled_transports,1) =
                                                     REDA_String_dup("myudp2");

Before enabled transports may be used for communication in |me|, they must be
registered and added to the :link_connextmicro_dds_api_c_up_two:`DiscoveryQos <structDDS__DiscoveryQosPolicy.html>`
and :link_connextmicro_dds_api_c_up_two:`UserTrafficQos <structDDS__UserTrafficQosPolicy.html>` policies. 
Please see the section on :doc:`../discovery` for details.