Transport Use Cases
[Programming How-To's]

Working with pluggable transports. More...

Changing the automatically registered built-in transports

• The DDS_TRANSPORTBUILTIN_MASK_DEFAULT specifies the transport plugins that will be automatically registered with a newly created DDSDomainParticipant by default.

• This default can be changed by changing the value of the value of TRANSPORT_BUILTIN Qos Policy on the DDSDomainParticipant

• To change the DDS_DomainParticipantQos::transport_builtin Qos Policy:

      DDS_DomainParticipantQos participant_qos;
      
      factory->get_default_participant_qos(participant_qos);
      
      participant_qos.transport_builtin.mask = DDS_TRANSPORTBUILTIN_SHMEM |
                                               DDS_TRANSPORTBUILTIN_UDPv4;
  

Changing the properties of the automatically registered builtin transports

The behavior of the automatically registered builtin transports can be altered by changing their properties.

• Tell the DDSDomainParticipantFactory to create the participants disabled, as described in Turning off auto-enable of newly created participant(s)

• Get the property of the desired builtin transport plugin, say ::UDPv4 Transport

      struct NDDS_Transport_UDPv4_Property_t property = NDDS_TRANSPORT_UDPV4_PROPERTY_DEFAULT;
                  
      if (NDDSTransportSupport::get_builtin_transport_property(
                                            participant,
                                            DDS_TRANSPORTBUILTIN_UDPv4,              
                                            (struct NDDS_Transport_Property_t&)property)
             != DDS_RETCODE_OK) {
          printf("***Error: get builtin transport property\n");                           
      }    
  

• Change the property fields as desired. Note that the properties should be changed carefully, as inappropriate values may prevent communications. For example, the ::UDPv4 Transport properties can be changed to support large messages (assuming the underlying operating system's UDPv4 stack supports the large message size). Note: if message_size_max is increased from the default for any of the built-in transports, then the DDS_ReceiverPoolQosPolicy::buffer_size on the DomainParticipant should also be changed.

    /* Increase the UDPv4 maximum message size to 64K (large messages). */    
    property.parent.message_size_max =  65535; 
    property.recv_socket_buffer_size =  65535;
    property.send_socket_buffer_size =  65535;            

• Set the property of the desired builtin transport plugin, say ::UDPv4 Transport

      if (NDDSTransportSupport::set_builtin_transport_property(
                                            participant,
                                            DDS_TRANSPORTBUILTIN_UDPv4,              
                                            (struct NDDS_Transport_Property_t&)property)
             != DDS_RETCODE_OK) {
          printf("***Error: set builtin transport property\n");                           
      }    
  

• Enable the participant to turn on communications with other participants in the domain using the new properties for the automatically registered builtin transport plugins.

Creating a transport

• A transport plugin is created using methods provided by the supplier of the transport plugin.

• For example to create an instance of the ::UDPv4 Transport

      NDDS_Transport_Plugin* transport = NULL; 
  
      struct NDDS_Transport_UDPv4_Property_t property = NDDS_TRANSPORT_UDPV4_PROPERTY_DEFAULT;
  
      transport = NDDS_Transport_UDPv4_new(&property);
  
      if (transport == NULL) {
         printf("***Error: creating transport plugin\n");
      }    
  

Deleting a transport

• A transport plugin can only be deleted only after the DDSDomainParticipant with which it is registered is deleted.

• The virtual destructor provided by the abstract transport plugin API can be used to delete a transport plugin.

      transport->delete_cEA(transport, NULL);
  

Registering a transport with a participant

The basic steps for setting up transport plugins for use in an RTI Data Distribution Service application are described below.

• Tell the DDSDomainParticipantFactory to create the participants disabled, as described in Turning off auto-enable of newly created participant(s)

• [Optionally] Changing the automatically registered built-in transports

• [Optionally] Changing the properties of the automatically registered builtin transports

• Create a disabled DDSDomainParticipant, as described in Setting up a participant

• Decide on the network address for the transport plugin. The network address should be chosen so that the resulting fully qualified address is globally unique (across all transports used in the domain).

      /* Decide on a network address (96 bits for UDPv4), such that the fully 
         qualified unicast address for the transport's interfaces will be
         globally unique. For example, we use the network address:
                   1234:1234:1234:0000
         It will be prepended to the unicast addresses of the transport plugin's
         interfaces, to give a fully qualified address that is unique in the 
         domain.
      */
      NDDS_Transport_Address_t network_address = {{1,2,3,4, 1,2,3,4, 1,2,3,4, 0,0,0,0}};  
  

• Decide on the aliases for the transport plugin. An alias can refer to one or more transport plugins. The transport class name (see Builtin Transport Class Names) are automatically appended to the user-provided aliases. Alias names are useful in creating logical groupings of transports, e.g. all the transports that are configured to support large messages may be given the alias "large_message".

      /* Decide aliases, i.e. the names by which this transport plugin will be known */
      const char* ALIASES[] = {
          "my",
          "large_message",        
      };
      const DDS_Long ALIASES_LENGTH = sizeof(ALIASES)/sizeof(const char*);
      
      /* Initialize the aliases StringSeq */
      DDS_StringSeq aliases;
      if (!aliases.from_array(ALIASES, ALIASES_LENGTH)) {
          printf("***Error: creating initializing aliases\n"); 
      }
  

• Register the transport plugin with the DDSDomainParticipant. Note that a transport plugin should NOT be registered with more than one DomainParticipant. It is the responsibility of the application programmer to ensure that this requirement is not violated.

      NDDS_Transport_Handle_t handle = NDDS_TRANSPORT_HANDLE_NIL;
      
      handle = NDDSTransportSupport::register_transport(
                             participant,          /* Disabled Domain Participant */
                             transport,            /* Transport plugin */
                             aliases,              /* Transport aliases */
                             network_address);     /* Transport network address */
  
      if (NDDS_Transport_Handle_is_nil(&handle)) {
         printf("***Error: registering transport\n");       
      }     
  

• [Optionally] Adding receive routes for a transport

• [Optionally] Adding send routes for a transport

• Enable the participant to turn on communications with other participants in the domain, using the newly registered transport plugins, and automatically registered builtin transport plugins (if any).

Adding receive routes for a transport

• Receive routes can be added to restrict address ranges on which incoming messages can be received. Any number of receive routes can be added, but these must be done before the participant is enabled.

• To restrict the address range from which incoming messages can be received by the transport plugin:

      /* Restrict to receiving messages only on interfaces 
                  1234:1234:1234:10.10.*.* 
      */
      NDDS_Transport_Address_t subnet = {{1,2,3,4, 1,2,3,4, 1,2,3,4, 10,10,0,0}};
  
      if (NDDSTransportSupport::add_receive_route(handle, subnet, 112) 
                                  != DDS_RETCODE_OK) {
         printf("***Error: adding receive route\n");
      }     
  

Adding send routes for a transport

• Send routes can be added to restrict the address ranges to which outgoing messages can be sent by the transport plugin. Any number of send routes can be added, but these must be done before the participant is enabled.

• To restrict address ranges to which outgoing messages can be sent by the transport plugin:

      /* Restrict to sending messages only to addresses (subnets)
                    1234:1234:1234:10.10.30.*
      */
      NDDS_Transport_Address_t subnet = {{1,2,3,4, 1,2,3,4, 1,2,3,4, 10,10,30,0}};
  
      if (NDDSTransportSupport::add_send_route(handle, subnet, 120) 
                                  != DDS_RETCODE_OK) {
         printf("***Error: adding send route\n");
      }