Create DomainParticipant, Topic, and Type
=========================================

.. highlight:: c

A DomainParticipantFactory_ creates *DomainParticipants*, and a
*DomainParticipant* itself is the factory for creating *Publishers*, *Subscribers*,
and *Topics*.

When creating a *DomainParticipant*, you may need to customize
DomainParticipantQos_, notably for:

- **Resource limits**.  Default resource limits are set at
  minimum values.
- **Initial peers**.
- **Discovery**. The name of the registered discovery component (typically 
  "dpde" or "dpse") must be assigned to DiscoveryQosPolicy_'s name. Please
  note that in |me_cert|, only the DPSE discovery plugin is supported.
- **Participant Name**. Every *DomainParticipant* is given the same default
  name.  Must be unique when using DPSE discovery.

Example code:

- Create a *DomainParticipant* with configured DomainParticipantQos_:
  
  ::
  
    DDS_DomainParticipant *participant = NULL;
    struct DDS_DomainParticipantQos dp_qos =
         DDS_DomainParticipantQos_INITIALIZER;
    DDS_DomainParticipantFactory *factory = NULL;
    RT_Registry_T *registry = NULL;

    /* DDS domain of DomainParticipant */
    DDS_Long domain_id = 0;

    
    factory = DDS_DomainParticipantFactory_get_instance();
    
    if (factory == NULL)
    {
        /* something failed, exit */
        exit(-1);
    }

    registry = DDS_DomainParticipantFactory_get_registry(factory);
                    
    if (registry == NULL)
    {
        /* something failed, exit */
        exit(-1);
    }

    if (!RT_Registry_register(registry, DDSHST_WRITER_DEFAULT_HISTORY_NAME,
                              WHSM_HistoryFactory_get_interface(), NULL, NULL))
    {
        /* something failed, exit */
        exit(-1);
    }

    if (!RT_Registry_register(registry, DDSHST_READER_DEFAULT_HISTORY_NAME,
                              RHSM_HistoryFactory_get_interface(), NULL, NULL))
    {
        /* something failed, exit */
        exit(-1);
    }

    /* Name of your registered Discovery component */
    if (!RT_ComponentFactoryId_set_name(&dp_qos.discovery.discovery.name, "dpde"))
    {
         /* failure */
    }

    /* Initial peers: use only default multicast peer */
    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("239.255.0.1");

    /* Resource 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;

    /* Participant name */
    strcpy(dp_qos.participant_name.name, "Participant_1");

    participant =
         DDS_DomainParticipantFactory_create_participant(factory,
                                                         domain_id,
                                                         &dp_qos,
                                                         NULL,
                                                         DDS_STATUS_MASK_NONE);
     if (participant == NULL)
     {
         /* failure */
     }

Register Type
-------------

Your data types that have been generated from IDL need to be registered
with the *DomainParticipants* that will be using them. Each registered type
must have a unique name, preferably the same as its IDL defined name.

::

  DDS_ReturnCode_t retcode;

  retcode = DDS_DomainParticipant_register_type(participant,
                                                "HelloWorld",
                                                HelloWorldTypePlugin_get());
  if (retcode != DDS_RETCODE_OK)
  {
      /* failure */
  }

Create Topic of Registered Type
-------------------------------

DDS *Topics* encapsulate the types being communicated, and you can create
*Topics* for your type once your type is registered.

A topic is given a name at creation (e.g. "Example HelloWorld").  The type
associated with the *Topic* is specified with its registered name.

::

  DDS_Topic *topic = NULL;

  topic = DDS_DomainParticipant_create_topic(participant,
                                             "Example HelloWorld",
                                             "HelloWorld",
                                             &DDS_TOPIC_QOS_DEFAULT,
                                             NULL,
                                             DDS_STATUS_MASK_NONE);

  if (topic == NULL)
  {
      /* failure */
  }

DPSE Discovery: Assert Remote Participant
-----------------------------------------

DPSE Discovery relies on the application to specify the other, or remote,
*DomainParticipants* that its local *DomainParticipants* are allowed to
discover. Your application must call a DPSE_ API for each remote participant
to be discovered. The API takes as input the name of the remote
participant.

::

  /* Enable discovery of remote participant with name Participant_2 */
  retcode = DPSE_RemoteParticipant_assert(participant, "Participant_2");
  if (retcode != DDS_RETCODE_OK)
  {
      /* failure */
  }
  
For more information, see the :doc:`../usersmanual/domains` 
section in the *User's Manual*.