DDS Domains
===========

This section discusses how to use *DomainParticipants*. It describes the types 
of operations that are available for them and their QosPolicies.

.. only:: not cert

    The goal of this section is to help you become familiar with the objects you need for setting
    up your |rti_me| application. For specific details on any mentioned operations, see the
    :link_connextmicro_dds_api_cpp_up_one:`C API Reference <index.html>` and
    :link_connextmicro_dds_api_cpp_up_one:`C++ API Reference <index.html>` documentation.

.. only:: cert

    The goal of this section is to help you become familiar with the objects you need for setting
    up your |rti_me| application. For specific details on any mentioned operations, see the
    :link_connextmicro_dds_api_cpp_up_one:`C API Reference <index.html>` documentation.

Fundamentals of DDS Domains and DomainParticipants
--------------------------------------------------

*DomainParticipants* are the focal point for creating, destroying (only 
in |me_micro|), and managing other |rti_me| objects. A DDS *domain* is a 
logical network of applications: only applications that belong to the same 
DDS *domain* may communicate using |me|. A DDS *domain* is identified by a 
unique integer value known as a domain ID. An application participates 
in a DDS domain by creating a *DomainParticipant* for that domain ID.

.. _`Figure 4.2: Relationship between Applications and DDS Domains`:

.. figure:: ../images/ApplicationsAndDomains.png

   Relationship between Applications and DDS Domains
   
   Applications can belong to multiple DDS domains—*A* belongs to DDS 
   domains 1 and 2. Applications in the same DDS domain can communicate 
   with each other, such as *A* and *B*, or *A* and *C*. Applications in 
   different DDS domains, such as *B* and *C*, are not even aware of 
   each other and will not exchange messages.
   
As seen in `Figure 4.2: Relationship between Applications and DDS Domains`_, 
a single application can participate in multiple DDS domains by creating 
multiple *DomainParticipants* with different domain IDs. *DomainParticipants* 
in the same DDS domain form a logical network; they are isolated from 
*DomainParticipants* of other DDS domains, even those running on the same 
set of physical computers sharing the same physical network. 
*DomainParticipants* in different DDS domains will never exchange messages 
with each other. Thus, a DDS domain establishes a “virtual network” 
linking all *DomainParticipants* that share the same domain ID.

An application that wants to participate in a certain DDS domain will need 
to create a *DomainParticipant*. As seen in `Figure 4.3: DDS Domain Module`_, 
a *DomainParticipant* object is a container for all other *Entities* that 
belong to the same DDS domain. It acts as factory for the *Publisher*, 
*Subscriber*, and *Topic* entities. (As seen in :doc:`sending` and 
:doc:`receiving`, in turn, *Publishers* are factories for 
*DataWriters* and *Subscribers* are factories for *DataReaders*.) 
*DomainParticipants* cannot contain other *DomainParticipants*.

Like all *Entities*, *DomainParticipants* have QosPolicies and *Listeners*. 
The *DomainParticipant* entity also allows you to set ‘default’ values for 
the QosPolicies for all the entities created from it or from the entities 
that it creates (*Publishers*, *Subscribers*, *Topics*, *DataWriters*, 
and *DataReaders*).

.. _`Figure 4.3: DDS Domain Module`:

.. figure:: ../images/DDSDomainPackage.png

   DDS Domain Module
   
   Note: MultiTopics are not supported.
   
Discovery Announcements
-----------------------

Each *DomainParticipant* announces information about itself, 
such as which locators other *DomainParticipants* must use to communicate 
with it. A locator is an address that consists of an address kind, a
port number, and an address. Four locator types are defined:
 
- A **unicast meta-traffic locator**. This locator type is used to identify
  where unicast discovery messages shall be sent. A maximum of four 
  locators of this type can be specified.   
- A **multicast meta-traffic locator**. This locator type is used to identify
  where multicast discovery messages shall be sent. A maximum of four 
  locators of this type can be specified.   
- A **unicast user-traffic locator**. This locator type is used to identify
  where unicast user-traffic messages shall be sent. A maximum of four 
  locators of this type can be specified.   
- A **multicast user-traffic locator**. This locator type is used to identify
  where multicast user-traffic messages shall be sent. A maximum of four 
  locators of this type can be specified.

It is important to note that a maximum of *four* locators of 
*each* kind can be sent in a *DomainParticipant* discovery message.

The locators in a *DomainParticipant*'s discovery announcement is used for 
two purposes:

- It informs other *DomainParticipants* where to send their discovery
  announcements to this *DomainParticipants*.
- It informs the *DataReaders* and *DataWriters* in other *DomainParticipants*
  where to send data to the *DataReaders* and *DataWriters* in this 
  *DomainParticipant* unless a *DataReader* or *DataWriter* specifies its own
  locators.

If a *DataReader* or *DataWriter* specifies their own locators, only 
user-traffic locators can be specified, then the exact same rules apply 
as for the *DomainParticipant*.

This document uses *address* and *locator* interchangeably. An address 
corresponds to the port and address part of a locator. The same address 
may exist as different kinds, in which case they are unique.

For more details about the discovery process, see 
the :doc:`discovery` section.