3.2.4. Creating a DomainParticipant¶

Creation of a DomainParticipant is done with the create_participant() member function on the DomainParticipantFactory singleton, that acts as a factory for the DomainParticipant.

Mandatory arguments are:

The DomainId that identifies the domain where the DomainParticipant will be created.

The DomainParticipantQos describing the behavior of the DomainParticipant. If the provided value is TOPIC_QOS_DEFAULT, the value of the DomainParticipantQos is used.

Optional arguments are:

A Listener derived from DomainParticipantListener, implementing the callbacks that will be triggered in response to events and state changes on the DomainParticipant. By default empty callbacks are used.

A StatusMask that activates or deactivates triggering of individual callbacks on the DomainParticipantListener. By default all events are enabled.

Warning

Following the DDSI-RTPS V2.2 standard (Section 9.6.1.1), the default ports are calculated depending on the DomainId, as it is explained in section Well Known Ports. Thus, it is encouraged to use DomainId lower than 200 (over DomainId 233 default port assign will fail consistently).

create_participant() will return a null pointer if there was an error during the operation, e.g. if the provided QoS is not compatible or is not supported. It is advisable to check that the returned value is a valid pointer.

// Create a DomainParticipant with default DomainParticipantQos and no Listener
// The value PARTICIPANT_QOS_DEFAULT is used to denote the default QoS.
DomainParticipant* participant_with_default_attributes =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant_with_default_attributes)
{
    // Error
    return;
}

// A custom DomainParticipantQos can be provided to the creation method
DomainParticipantQos custom_qos;

// Modify QoS attributes
// (...)

DomainParticipant* participant_with_custom_qos =
        DomainParticipantFactory::get_instance()->create_participant(0, custom_qos);
if (nullptr == participant_with_custom_qos)
{
    // Error
    return;
}

// Create a DomainParticipant with default QoS and a custom Listener.
// CustomDomainParticipantListener inherits from DomainParticipantListener.
// The value PARTICIPANT_QOS_DEFAULT is used to denote the default QoS.
CustomDomainParticipantListener custom_listener;
DomainParticipant* participant_with_default_qos_and_custom_listener =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT,
                &custom_listener);
if (nullptr == participant_with_default_qos_and_custom_listener)
{
    // Error
    return;
}

3.2.4.1. Profile based creation of a DomainParticipant¶

Instead of using a DomainParticipantQos, the name of a profile can be used to create a DomainParticipant with the create_participant_with_profile() member function on the DomainParticipantFactory singleton.

Mandatory arguments are:

The DomainId that identifies the domain where the DomainParticipant will be created. Do not use DomainId higher than 200 (see Creating a DomainParticipant).

The name of the profile to be applied to the DomainParticipant.

Optional arguments are:

A Listener derived from DomainParticipantListener, implementing the callbacks that will be triggered in response to events and state changes on the DomainParticipant. By default empty callbacks are used.

A StatusMask that activates or deactivates triggering of individual callbacks on the DomainParticipantListener. By default all events are enabled.

create_participant_with_profile() will return a null pointer if there was an error during the operation, e.g if the provided QoS is not compatible or is not supported. It is advisable to check that the returned value is a valid pointer.

Note

XML profiles must have been loaded previously. See Loading profiles from an XML file.

// First load the XML with the profiles
DomainParticipantFactory::get_instance()->load_XML_profiles_file("profiles.xml");

// Create a DomainParticipant using a profile and no Listener
DomainParticipant* participant_with_profile =
        DomainParticipantFactory::get_instance()->create_participant_with_profile(0, "participant_profile");
if (nullptr == participant_with_profile)
{
    // Error
    return;
}

// Create a DomainParticipant using a profile and a custom Listener.
// CustomDomainParticipantListener inherits from DomainParticipantListener.
CustomDomainParticipantListener custom_listener;
DomainParticipant* participant_with_profile_and_custom_listener =
        DomainParticipantFactory::get_instance()->create_participant_with_profile(0, "participant_profile",
                &custom_listener);
if (nullptr == participant_with_profile_and_custom_listener)
{
    // Error
    return;
}

3.2.4.2. Deleting a DomainParticipant¶

A DomainParticipant can be deleted with the delete_participant() member function on the DomainParticipantFactory singleton.

Note

A DomainParticipant can only be deleted if all Entities belonging to the participant (Publisher, Subscriber or Topic) have already been deleted. Otherwise, the function will issue an error and the DomainParticipant will not be deleted. This can be performed by using the delete_contained_entities() member function of the DomainParticipant.

// Create a DomainParticipant
DomainParticipant* participant =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
    // Error
    return;
}

// Use the DomainParticipant to communicate
// (...)

// Delete entities created by the DomainParticipant
if (participant->delete_contained_entities() != ReturnCode_t::RETCODE_OK)
{
    // DomainParticipant failed to delete the entities it created.
    return;
}

// Delete the DomainParticipant
if (DomainParticipantFactory::get_instance()->delete_participant(participant) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}