Class DomainParticipant

Inheritance Relationships

Base Type

Class Documentation

class DomainParticipant : public dds::core::TEntity<detail::DomainParticipant>

A DomainParticipant represents the local membership of the application in a Domain.

The DomainParticipant represents the participation of the application on a communication plane that isolates applications running on the same set of physical computers from each other. A domain establishes a virtual network linking all applications that share the same domainId and isolating them from applications running on different domains. In this way, several independent distributed applications can coexist in the same physical network without interfering, or even being aware of each other.

See also

Domain Participant

Public Types

using Listener = DomainParticipantListener

Local representation of the dds::domain::DomainParticipantListener

Public Functions

OMG_DDS_REF_TYPE_PROTECTED_DC (DomainParticipant, dds::core::TEntity, detail::DomainParticipant) OMG_DDS_EXPLICIT_REF_BASE_DECL(DomainParticipant
dds::core::Entity OMG_DDS_API DomainParticipant (uint32_t id)

Creates a new DomainParticipant object. The DomainParticipant signifies that the calling application intends to join the Domain identified by the domain_id argument.

The DomainParticipant will be created with the QoS values specified on the last successful call to DomainParticipant::default_publisher_qos(qos) or, if the call was never made, the default values.

Parameters

id – the id of the domain joined by the new DomainParticipant

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

OMG_DDS_API DomainParticipant(uint32_t id, const dds::domain::qos::DomainParticipantQos &qos, dds::domain::DomainParticipantListener *listener = NULL, const dds::core::status::StatusMask &event_mask = dds::core::status::StatusMask::all())

Creates a new DomainParticipant object. The DomainParticipant signifies that the calling application intends to join the Domain identified by the domain_id argument.

The DomainParticipant will be created with the DomainParticipantQos passed as an argument.

Parameters

  • id – the id of the domain joined by the new DomainParticipant

  • qos – the QoS settings for the new DomainParticipant

  • listener – the listener

  • event_mask – the mask defining the events for which the listener will be notified.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

OMG_DDS_API void listener (Listener *listener, const ::dds::core::status::StatusMask &event_mask)

Register a listener with the DomainParticipant.

The notifications received by the listener depend on the status mask with which it was registered.

Listener un-registration is performed by setting the listener to NULL.

See also listener information.

Parameters

  • listener – the listener

  • event_mask – the mask defining the events for which the listener will be notified.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::UnsupportedError – A status was selected that cannot be supported because the infrastructure does not maintain the required connectivity information.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

OMG_DDS_API Listener * listener () const

Get the listener of this DomainParticipant.

See also listener information.

Throws

dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

Returns

the listener

OMG_DDS_API const qos::DomainParticipantQos & qos () const

Gets the DomainParticipantQos setting for this instance.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the qos

OMG_DDS_API void qos (const qos::DomainParticipantQos &qos)

Sets the DomainParticipantQos setting for this instance.

Parameters

qos – the qos

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

OMG_DDS_API uint32_t domain_id () const

This operation retrieves the domain_id used to create the DomainParticipant. The domain_id identifies the DDS domain to which the DomainParticipant belongs.

Each DDS domain represents a separate data communication plane isolated from other domains.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

Returns

the domain id

OMG_DDS_API void assert_liveliness ()

This operation will manually assert the liveliness for the DomainParticipant.

This way, the Data Distribution Service is informed that the DomainParticipant is still alive. This operation only needs to be used when the DomainParticipant contains DataWriters with the dds:core::policy::LivelinessQosPolicy::ManualByParticipant(), and it will only affect the liveliness of those DataWriters.

Writing data via the write operation of a DataWriter will assert the liveliness on the DataWriter itself and its DomainParticipant. Therefore, assert_liveliness is only needed when not writing regularly. The liveliness should be asserted by the application, depending on the LivelinessQosPolicy.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

OMG_DDS_API bool contains_entity (const ::dds::core::InstanceHandle &handle)

This operation checks whether or not the given handle represents an Entity that was created by using this DomainParticipant.

The containment applies recursively. That is, it applies both to entities (TopicDescription, Publisher, or Subscriber) created directly using the DomainParticipant as well as entities created using a contained Publisher, or Subscriber as the factory, and so forth.

Parameters

handle – the instance handle for which the containement relationship has to be checked

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

Returns

true if the handle belongs to an Entity belonging to this DomainParticipant

OMG_DDS_API dds::core::Time current_time () const

This operation returns the current value of the time that the service uses to time-stamp data writes and to set the reception timestamp for the data updates it receives.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

Returns

the current time

OMG_DDS_API DomainParticipant & operator<< (const qos::DomainParticipantQos &qos)

Sets the DomainParticipantQos setting for this instance.

Parameters

qos – the qos

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

OMG_DDS_API const DomainParticipant & operator>> (qos::DomainParticipantQos &qos) const

Gets the DomainParticipantQos setting for this instance.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the qos

OMG_DDS_API dds::pub::qos::PublisherQos default_publisher_qos () const

Gets the default PublisherQos of the DomainParticipant.

This operation gets an object with the default Publisher QosPolicy settings of the DomainParticipant (that is the PublisherQos) which is used for newly created Publisher objects, in case no QoS was provided during the creation.

The values retrieved by this operation match the set of values specified on the last successful call to dds::domain::DomainParticipant::default_publisher_qos(const ::dds::pub::qos::PublisherQos& qos), or, if the call was never made, the default values.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the default PublisherQos

OMG_DDS_API DomainParticipant & default_publisher_qos (const ::dds::pub::qos::PublisherQos &qos)

Sets the default PublisherQos of the DomainParticipant.

This operation sets the default PublisherQos of the DomainParticipant which is used for newly created Publisher objects, when no QoS is provided.

The PublisherQos is always self consistent, because its policies do not depend on each other. This means that this operation never throws dds::core::InconsistentPolicyError.

The values set by this operation are returned by dds::domain::DomainParticipant::default_publisher_qos().

Parameters

qos – the default PublisherQos

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::UnsupportedError – One or more of the selected QosPolicy values are currently not supported by OpenSplice.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

OMG_DDS_API dds::sub::qos::SubscriberQos default_subscriber_qos () const

Gets the default SubscriberQos of the DomainParticipant.

This operation gets an object with the default Subscriber QosPolicy settings of the DomainParticipant (that is the SubscriberQos) which is used for newly created Subscriber objects, in case no QoS was provided during the creation.

The values retrieved by this operation match the set of values specified on the last successful call to dds::domain::DomainParticipant::default_subscriber_qos(const :dds::sub::qos::SubscriberQos& qos), or, if the call was never made, the default values.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the default SubscriberQos

OMG_DDS_API DomainParticipant & default_subscriber_qos (const ::dds::sub::qos::SubscriberQos &qos)

Sets the default SubscriberQos of the DomainParticipant.

This operation sets the default SubscriberQos of the DomainParticipant which is used for newly created Subscriber objects, when no QoS is provided.

The SubscriberQos is always self consistent, because its policies do not depend on each other. This means that this operation never throws dds::core::InconsistentPolicyError.

The values set by this operation are returned by dds::domain::DomainParticipant::default_subscriber_qos().

Parameters

qos – the default SubscriberQos

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::UnsupportedError – One or more of the selected QosPolicy values are currently not supported by OpenSplice.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

OMG_DDS_API dds::topic::qos::TopicQos default_topic_qos () const

Gets the default TopicQos of the DomainParticipant.

This operation gets an object with the default Topic QosPolicy settings of the DomainParticipant (that is the TopicQos) which is used for newly created Topic objects, in case no QoS was provided during the creation.

The values retrieved by this operation match the set of values specified on the last successful call to dds::domain::DomainParticipant::default_topic_qos(const dds::topic::qos::TopicQos& qos), or, if the call was never made, the default values.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the default TopicQos

OMG_DDS_API DomainParticipant & default_topic_qos (const dds::topic::qos::TopicQos &qos)

Sets the default TopicQos of the DomainParticipant.

This operation sets the default SubscriberQos of the DomainParticipant which is used for newly created Subscriber objects, when no QoS is provided.

This operation checks if the TopicQos is self consistent. If it is not, the operation has no effect and throws dds::core::InconsistentPolicyError.

The values set by this operation are returned by dds::domain::DomainParticipant::default_topic_qos().

Parameters

qos – the default TopicQos

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::UnsupportedError – One or more of the selected QosPolicy values are currently not supported by OpenSplice.

  • dds::core::InconsistentPolicyError – The parameter qos contains conflicting QosPolicy settings, e.g. a history depth that is higher than the specified resource limits.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Public Static Functions

static OMG_DDS_API qos::DomainParticipantQos default_participant_qos ()

Gets the default DomainParticipantQos.

This operation gets an object with the default global DomainParticipant QosPolicy settings which is used for newly created DomainParticipant objects, in case no QoS was provided during the creation.

The values retrieved by this operation match the set of values specified on the last successful call to dds::domain::DomainParticipant::default_participant_qos(const ::dds::domain::qos::DomainParticipantQos& qos), or, if the call was never made, the default values.

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.

Returns

the default DomainParticipantQos

static OMG_DDS_API void default_participant_qos (const ::dds::domain::qos::DomainParticipantQos &qos)

Sets the default DomainParticipantQos.

This QoS will be used by all following DomainParticipant creations when no QoS was given during those creations or the QoS is given that was returned by dds::domain::DomainParticipant::default_participant_qos().

Parameters

qos – the default DomainParticipantQos

Throws

  • dds::core::Error – An internal error has occurred.

  • dds::core::NullReferenceError – The entity was not properly created and references to dds::core::null.

  • dds::core::AlreadyClosedError – The entity has already been closed.

  • dds::core::OutOfResourcesError – The Data Distribution Service ran out of resources to complete this operation.