dds::domain::DomainParticipant Class Reference

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

#include "DomainParticipant.hpp"

Inheritance diagram for dds::domain::DomainParticipant:

Public Types
typedef dds::domain::DomainParticipantListener	Listener

Public Member Functions
	DomainParticipant (uint32_t id)
	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::none())
void	assert_liveliness ()
void	close ()
bool	contains_entity (const ::dds::core::InstanceHandle &handle)
void	create_persistent_snapshot (const std::string &partition_expression, const std::string &topic_expression, const std::string &uri)
dds::core::Time	current_time () const
dds::pub::qos::PublisherQos	default_publisher_qos () const
DomainParticipant &	default_publisher_qos (const ::dds::pub::qos::PublisherQos &qos)
dds::sub::qos::SubscriberQos	default_subscriber_qos () const
DomainParticipant &	default_subscriber_qos (const ::dds::sub::qos::SubscriberQos &qos)
dds::topic::qos::TopicQos	default_topic_qos () const
DomainParticipant &	default_topic_qos (const dds::topic::qos::TopicQos &qos)
uint32_t	domain_id () const
void	enable ()
uint64_t	get_memory_usage ()
std::string	get_property (std::string property)
const dds::core::InstanceHandle	instance_handle () const
bool	is_nil () const
void	listener (Listener *listener, const ::dds::core::status::StatusMask &event_mask)
Listener *	listener () const
template<typename R >
bool	operator!= (const R &ref) const
bool	operator!= (const null_type nil) const
DELEGATE *	operator-> ()
const DELEGATE *	operator-> () const
DomainParticipant &	operator<< (const dds::domain::qos::DomainParticipantQos &qos)
template<typename R >
bool	operator== (const R &ref) const
bool	operator== (const null_type) const
const DomainParticipant &	operator>> (dds::domain::qos::DomainParticipantQos &qos) const
const dds::domain::qos::DomainParticipantQos &	qos () const
void	qos (const dds::domain::qos::DomainParticipantQos &qos)
void	retain ()
void	set_property (std::string property, std::string value)
const dds::core::status::StatusMask	status_changes ()

Static Public Member Functions
static dds::domain::qos::DomainParticipantQos	default_participant_qos ()
static void	default_participant_qos (const ::dds::domain::qos::DomainParticipantQos &qos)
static void	detach_all_domains (bool block_operations, bool delete_entities)

Detailed Description

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

Definition at line 64 of file DomainParticipant.hpp.

Member Typedef Documentation

Listener

typedef dds::domain::DomainParticipantListener dds::domain::DomainParticipant::Listener

Local representation of the dds::domain::DomainParticipantListener

Definition at line 70 of file DomainParticipant.hpp.

Constructor & Destructor Documentation

DomainParticipant() [1/2]

dds::domain::DomainParticipant::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

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

Definition at line 44 of file DomainParticipantImpl.hpp.

DomainParticipant() [2/2]

dds::domain::DomainParticipant::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::none()
	)

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.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.

Definition at line 56 of file DomainParticipantImpl.hpp.

Member Function Documentation

assert_liveliness()

void dds::domain::DomainParticipant::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.

Exceptions

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.

Definition at line 107 of file DomainParticipantImpl.hpp.

close()

void dds::core::Entity::close ( )

inherited

This function closes the entity and releases related resources.

Resource management for some reference types might involve relatively heavyweight operating- system resources — such as e.g., threads, mutexes, and network sockets — in addition to memory. These objects therefore provide a method close() that shall halt network communication (in the case of entities) and dispose of any appropriate operating-system resources.

Users of this PSM are recommended to call close on objects of all reference types once they are finished using them. In addition, implementations may automatically close objects that they deem to be no longer in use, subject to the following restrictions:

• Any object to which the application has a direct reference is still in use.
• Any object that has been explicitly retained is still in use
• The creator of any object that is still in use is itself still in use.

Returns

void

Definition at line 68 of file EntityImpl.hpp.

contains_entity()

bool dds::domain::DomainParticipant::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

Returns

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

Exceptions

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.

Definition at line 114 of file DomainParticipantImpl.hpp.

create_persistent_snapshot()

void dds::domain::DomainParticipant::create_persistent_snapshot	(	const std::string &	partition_expression,
		const std::string &	topic_expression,
		const std::string &	uri
	)

This operation will create a snapshot of all persistent data matching the provided partition and topic expressions and store the snapshot at the location indicated by the URI. Only persistent data available on the local node is considered.

Note

This is a proprietary OpenSplice extension.

Detailed Description

This operation will create a snapshot of all persistent data matching the provided partition and topic expressions and store the snapshot at the location indicated by the URI. Only persistent data available on the local node is considered. This operation will fire an event to trigger the snapshot creation by the durability service and then return while the durability service fulfills the snapshot request. The created snapshot can then be used as the persistent store for the durability service next time it starts up by configuring the location of the snapshot as the persistent store in the configuration file. The durability service will then use the snapshot as the regular store (and can thus also alter its contents).

Call
This is a proprietary operation and can be called by using the operator->.

dds::domain::DomainParticipant dp(domainId);
dp->create_persistent_snapshot(...);

Parameters

partition_expression	The expression of all partitions involved in the snapshot; this may contain wildcards.
topic_expression	The expression of all topics involved in the snapshot; this may contain wildcards.
uri	The location where to store the snapshot. Currently only directories are supported.

current_time()

dds::core::Time dds::domain::DomainParticipant::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.

Returns

the current time

Exceptions

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.

Definition at line 121 of file DomainParticipantImpl.hpp.

default_participant_qos() [1/2]

dds::domain::qos::DomainParticipantQos dds::domain::DomainParticipant::default_participant_qos ( )

static

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.

Returns

the default DomainParticipantQos

Exceptions

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.

Definition at line 128 of file DomainParticipantImpl.hpp.

default_participant_qos() [2/2]

void dds::domain::DomainParticipant::default_participant_qos ( const ::dds::domain::qos::DomainParticipantQos &  qos )

static

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

Exceptions

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.

Definition at line 135 of file DomainParticipantImpl.hpp.

default_publisher_qos() [1/2]

dds::pub::qos::PublisherQos dds::domain::DomainParticipant::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.

Returns

the default PublisherQos

Exceptions

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.

Definition at line 142 of file DomainParticipantImpl.hpp.

default_publisher_qos() [2/2]

DomainParticipant & dds::domain::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

Exceptions

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.

Definition at line 149 of file DomainParticipantImpl.hpp.

default_subscriber_qos() [1/2]

dds::sub::qos::SubscriberQos dds::domain::DomainParticipant::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.

Returns

the default SubscriberQos

Exceptions

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.

Definition at line 158 of file DomainParticipantImpl.hpp.

default_subscriber_qos() [2/2]

DomainParticipant & dds::domain::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

Exceptions

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.

Definition at line 165 of file DomainParticipantImpl.hpp.

default_topic_qos() [1/2]

dds::topic::qos::TopicQos dds::domain::DomainParticipant::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.

Returns

the default TopicQos

Exceptions

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.

Definition at line 174 of file DomainParticipantImpl.hpp.

default_topic_qos() [2/2]

DomainParticipant & dds::domain::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

Exceptions

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.

Definition at line 181 of file DomainParticipantImpl.hpp.

detach_all_domains()

static void dds::domain::DomainParticipant::detach_all_domains ( bool  block_operations, bool  delete_entities  )

static

This operation safely detaches the application from all domains it is currently participating in.

Note

This is a proprietary OpenSplice extension.

Detailed Description

This operation safely detaches the application from all domains it is currently participating in. When this operation has been performed successfully, the application is no longer connected to any Domain. For Federated domains finishing this operation successfully means that all shared memory segments have been safely un-mapped from the application process. For SingleProcess mode domains this means all services for all domains have been stopped. This allows graceful termination of the OSPL services that run as threads within the application. Graceful termination of services in this mode would for instance allow durability flushing of persistent data and networking termination announcement over the network. When this call returns further access to all domains will be denied and it will not be possible for the application to open or re-open any DDS domain.

The behavior of the detach_all_domains operation is determined by the block_operations and delete_entities parameters:

block_operations:

This parameter specifies if the application wants any DDS operation to be blocked or not while detaching. When true, any DDS operation called during this operation will be blocked and remain blocked forever (so also after the detach operation has completed and returns to the caller). When false, any DDS operation called during this operation may return RETCODE_ALREADY_DELETED. Please note that a listener callback is not considered an operation in progress. Of course, if a DDS operation is called from within the listener callback, that operation will be blocked during the detaching if this attribute is set to TRUE.

delete_entities:

This parameter specifies if the application wants the DDS entities created by the application to be deleted (synchronously) while detaching from the domain or not. If true, all application entities are guaranteed to be deleted when the call returns. If false, application entities will not explicitly be deleted by this operation. In case of federated mode, the splice-daemon will delete them asynchronously after this operation has returned. In case of SingleProcess mode this attribute is ignored and clean up will always be performed, as this cannot be delegated to a different process.

Note

In federated mode when the detach_all_domain operation is called with block_operations is false and delete_entities is false then the DDS operations which are in progress and which are waiting for some condition to become true or waiting for an event to occur while the detach operation is performed may be blocked.

Call
This is a proprietary operation and can be called by using the operator->.

dds::domain::DomainParticipant dp(domainId);
dp->detach_all_domains(...);

or use

org::opensplice::domain::DomainParticipant::detach_all_domains(...)

Parameters

block_operations	Indicates whether the application wants any operations that are called while detaching to be blocked or not.
delete_entities	Indicates whether the application DDS entities in the 'connected' domains must be deleted synchronously during detaching.

domain_id()

uint32_t dds::domain::DomainParticipant::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.

Returns

the domain id

Exceptions

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.

Definition at line 100 of file DomainParticipantImpl.hpp.

enable()

void dds::core::Entity::enable ( )

inherited

Enable entity.

This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the dds::core::policy::EntityFactory QoS policy on the corresponding factory for the Entity.

Enabled entities are immediately activated at creation time meaning all their immutable QoS settings can no longer be changed. Disabled Entities are not yet activated, so it is still possible to change there immutable QoS settings. However, once activated the immutable QoS settings can no longer be changed.

Creating disabled entities can make sense when the creator of the Entity does not yet know which QoS settings to apply, thus allowing another piece of code to set the QoS later on.

The default setting of dds::core::policy::EntityFactory is such that, by default, it is not necessary to explicitly call enable on newly- created entities.

The enable operation is idempotent. Calling enable on an already- enabled Entity does not raise exceptions and has no effect.

If an Entity has not yet been enabled, the only operations that can be invoked on it are: the ones to set, get or copy the QosPolicy settings, the ones that set (or get) the listener, the ones that get the StatusCondition, the get_status_changes operation (although the status of a disabled entity never changes), and the ‘factory’ operations that create, delete or lookup other Entities. Other operations will throw the exception dds::core::NotEnabledError.

Entities created from a factory that is disabled are created disabled regardless of the setting of the dds::core::policy::EntityFactory Qos policy. Calling enable on an Entity whose factory is not enabled will fail and throw an dds::core::PreconditionNotMetError exception.

If the dds::core::policy::EntityFactory QoS policy has autoenable_created_entities set to TRUE, the enable operation on the factory will automatically enable all entities created from the factory.

The Listeners associated with an entity are not called until the entity is enabled. Conditions associated with an entity that is not enabled are inactive; that is, they have a trigger_value==false (dds::core::cond::Condition and dds::core::cond::WaitSet).

eg.

dds::domain::qos::DomainParticipantQos dpq;
dpq << dds::core::policy::EntityFactory::ManuallyEnable();
...
dds::sub::DataReader<Foo::Bar> dr(dp, topic, drqos);
dr.enable();

In addition to the general description, the enable operation on a dds::sub::Subscriber has special meaning in specific usecases. This applies only to Subscribers with PresentationQoS coherent-access set to true with access-scope set to group.

In this case the subscriber is always created in a disabled state, regardless of the auto-enable created entities setting on the corresponding participant. While the subscriber remains disabled, DataReaders can be created that will participate in coherent transactions of the subscriber.

See dds::sub::CoherentAccess for more information.

All DataReaders will also be created in a disabled state. Coherency with group access-scope requires data to be delivered as a transaction, atomically, to all eligible readers. Therefore data should not be delivered to any single DataReader immediately after it's created, as usual, but only after the application has finished creating all DataReaders for a given Subscriber. At this point, the application should enable the Subscriber which in turn enables all its DataReaders.

Note that for a dds::pub::DataWriter which has a corresponding dds::pub::Publisher with a PresentationQoS with coherent-access set to true and access-scope set to topic or group that the HistoryQoS of the dds::pub::DataWriter should be set to keep-all otherwise the enable operation will fail.

See dds::pup::DataWriter for more information.

Returns

void

Exceptions

dds::core::PreconditionNotMetError

Entities' factory is not enabled.

Definition at line 44 of file EntityImpl.hpp.

get_memory_usage()

uint64_t dds::domain::DomainParticipant::get_memory_usage

(

)

This operation will return the amount of Domain memory currently used.

Note

This is a proprietary OpenSplice extension.

Detailed Description

This operation will return the amount of Domain memory currently used.

Call
This is a proprietary operation and can be called by using the operator->.

dds::domain::DomainParticipant dp(domainId);
dp->get_memory_usage(...);

get_property()

std::string dds::domain::DomainParticipant::get_property

(

std::string

property

)

This operation get a property from the domainparticipant

Note

This is a proprietary OpenSplice extension.

Detailed Description

This operation gets a property from the domain participant.

Currently, the following properties are defined: isolateNode : The isolateNode property allows applications to isolate the federation from the rest of the Domain, i.e. at network level disconnect the node from the rest of the system. Additionally, they also need to be able to issue a request to reconnect their federation to the domain again after which the durability merge-policy that is configured needs to be applied. To isolate a federation, the application needs to set the isolateNode property value to ‘true’ and to (de)isolate the federation the same property needs to set to ‘false’. The default value of the isolateNode property is ‘false’. All data that is published after isolateNode is set to true will not be sent to the network and any data received from the network will be ignored. Be aware that data being processed by the network service at time of isolating a node may still be sent to the network due to asynchronous nature of network service internals.

Call
This is a proprietary operation and can be called by using the operator->.

dds::domain::DomainParticipant dp(domainId);
dp->get_property(...);

Parameters

name	Indicates the name of the property to get

Returns

the value of the property

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::UnsupportedError	The name specifies an undefined property or the operation is not supported in this version.

instance_handle()

const dds::core::InstanceHandle dds::core::Entity::instance_handle ( ) const

inherited

This operation returns the InstanceHandle_t that represents the Entity.

The relevant state of some Entity objects are distributed using built-in topics. Each built-in topic sample represents the state of a specific Entity and has a unique instance_handle. This operation returns the instance_handle of the built-in topic sample that represents the specified Entity.
Some Entities (dds::pub::Publisher and dds::sub::Subscriber) do not have a corresponding built-in topic sample, but they still have an instance_handle that uniquely identifies the Entity. The instance_handles obtained this way can also be used to check whether a specific Entity is located in a specific DomainParticipant (dds::domain::DomainParticipant::contains_entity()).

Returns

dds::core::InstanceHandle Result value is the instance_handle of the built-in topic sample that represents the state of this Entity.

Definition at line 60 of file EntityImpl.hpp.

is_nil()

template<typename DELEGATE >

bool dds::core::Reference< DELEGATE >::is_nil ( ) const

inherited

Check if the referenced object is nil.

In other words, check if the reference is pointing to a null object.

Returns

true if the referenced object is null.

Definition at line 143 of file ReferenceImpl.hpp.

listener() [1/2]

void dds::domain::DomainParticipant::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.

Exceptions

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.

Definition at line 70 of file DomainParticipantImpl.hpp.

listener() [2/2]

DomainParticipant::Listener * dds::domain::DomainParticipant::listener

(

)

const

Get the listener of this DomainParticipant.

See also listener information.

Returns

the listener

Exceptions

dds::core::NullReferenceError

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

Definition at line 78 of file DomainParticipantImpl.hpp.

operator!=() [1/2]

template<typename DELEGATE >

template<typename R >

bool dds::core::Reference< DELEGATE >::operator!= ( const R &  ref ) const

inherited

Compares two Reference objects and returns true if they are not equal.

Inequality is based on the referential inequality of the object being pointed to.

Parameters

ref	the other Reference object

Returns

true when not equal

Definition at line 100 of file ReferenceImpl.hpp.

operator!=() [2/2]

template<typename DELEGATE >

bool dds::core::Reference< DELEGATE >::operator!= ( const null_type  nil ) const

inherited

Special operator!= used to check if this reference object does not equal the dds::core::null reference.

The non-null-check can be done like this:

if (r != dds::core::null) {
   // Use the dds reference object r
}

Returns

true if this reference is not null.

Definition at line 157 of file ReferenceImpl.hpp.

operator->() [1/2]

template<typename DELEGATE >

DELEGATE * dds::core::Reference< DELEGATE >::operator-> ( )

inherited

The operator->() is provided to be able to directly invoke functions on the delegate.

The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:

my_dds_entity.standard_function();
my_dds_entity->vendor_specific_extension();

Returns

a reference to delegate.

Definition at line 180 of file ReferenceImpl.hpp.

operator->() [2/2]

template<typename DELEGATE >

const DELEGATE * dds::core::Reference< DELEGATE >::operator-> ( ) const

inherited

The operator->() is provided to be able to directly invoke functions on the delegate.

The decision to provide direct access to the delegate was motivated by the need for providing a way that was not invasive with respect to the CXXDDS API and yet would allow for vendor-specific extension. Thus vendor-specific extensions can be invoked on the Reference and on all its subclasses as follows:

my_dds_entity.standard_function();
my_dds_entity->vendor_specific_extension();

Returns

a reference to delegate.

Definition at line 188 of file ReferenceImpl.hpp.

operator<<()

DomainParticipant & dds::domain::DomainParticipant::operator<<

(

const dds::domain::qos::DomainParticipantQos &

qos

)

Sets the DomainParticipantQos setting for this instance.

Parameters

qos

the qos

Exceptions

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.

Definition at line 189 of file DomainParticipantImpl.hpp.

operator==() [1/2]

template<typename DELEGATE >

template<typename R >

bool dds::core::Reference< DELEGATE >::operator== ( const R &  ref ) const

inherited

Compares two Reference objects and returns true if they are equal.

Equality is based on the referential equality of the object being pointed.

Parameters

ref	the other Reference object

Returns

true when equal

Definition at line 83 of file ReferenceImpl.hpp.

operator==() [2/2]

template<typename DELEGATE >

bool dds::core::Reference< DELEGATE >::operator== ( const null_type  ) const

inherited

Special operator== used to check if this reference object equals the dds::core::null reference.

The null-check can be done like this:

if (r == dds::core::null) {
   // Do not use the dds reference object r in its current state
}

Returns

true if this reference is null.

Definition at line 150 of file ReferenceImpl.hpp.

operator>>()

const DomainParticipant & dds::domain::DomainParticipant::operator>>

(

dds::domain::qos::DomainParticipantQos &

qos

)

const

Gets the DomainParticipantQos setting for this instance.

Returns

the qos

Exceptions

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.

Definition at line 197 of file DomainParticipantImpl.hpp.

qos() [1/2]

const dds::domain::qos::DomainParticipantQos & dds::domain::DomainParticipant::qos

(

)

const

Gets the DomainParticipantQos setting for this instance.

Returns

the qos

Exceptions

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.

Definition at line 86 of file DomainParticipantImpl.hpp.

qos() [2/2]

void dds::domain::DomainParticipant::qos

(

const dds::domain::qos::DomainParticipantQos &

qos

)

Sets the DomainParticipantQos setting for this instance.

Parameters

qos

the qos

Exceptions

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.

Definition at line 93 of file DomainParticipantImpl.hpp.

retain()

void dds::core::Entity::retain ( )

inherited

Retain the Entity, even when it goes out of scope.

This function indicates that references to this object may go out of scope but that the application expects to look it up again later. Therefore the Service must consider this object to be still in use and may not close it automatically.

Returns

void

Definition at line 76 of file EntityImpl.hpp.

set_property()

void dds::domain::DomainParticipant::set_property	(	std::string	property,
		std::string	value
	)

This operation set a property in the domainparticipant

Note

This is a proprietary OpenSplice extension.

Detailed Description

This operation sets a property in the domain participant to the specified value.

Currently, the following properties are defined: isolateNode : The isolateNode property allows applications to isolate the federation from the rest of the Domain, i.e. at network level disconnect the node from the rest of the system. Additionally, they also need to be able to issue a request to reconnect their federation to the domain again after which the durability merge-policy that is configured needs to be applied. To isolate a federation, the application needs to set the isolateNode property value to ‘true’ and to (de)isolate the federation the same property needs to set to ‘false’. The default value of the isolateNode property is ‘false’. All data that is published after isolateNode is set to true will not be sent to the network and any data received from the network will be ignored. Be aware that data being processed by the network service at time of isolating a node may still be sent to the network due to asynchronous nature of network service internals. The value can any of: ‘true’, ‘false’, 'deaf', 'mute'. false (default): The federation is connected to the domain. true: The federation is disconnected from the domain meaning that data is neither published nor received deaf: The federation is disconnected from the domain only in receiving functionality mute: The federation is disconnected from the domain only in publishing functionality on the network and data from the network is ignored.

Call
This is a proprietary operation and can be called by using the operator->.

dds::domain::DomainParticipant dp(domainId);
dp->set_property(...);

Parameters

name	Indicates the name of the property to be set
value	Indicates the value to set

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::InvalidArgumentError	an invalid value has been specified.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::UnsupportedError	The name specifies an undefined property or the operation is not supported in this version.

status_changes()

const dds::core::status::StatusMask dds::core::Entity::status_changes ( )

inherited

This operation returns a mask with the communication statuses in the Entity that are “triggered”.

This operation retrieves the list of communication statuses in the Entity that are triggered. That is the set of communication statuses whose value have changed since the last time the application called this operation. This operation shows whether a change has occurred even when the status seems unchanged because the status changed back to the original status.

When the Entity is first created or if the Entity is not enabled, all communication statuses are in the “un-triggered” state so the mask returned by the operation is empty.

The result value is a bit mask in which each bit shows which value has changed. The relevant bits represent one of the following statuses:

• dds::core::status::StatusMask::inconsistent_topic()
• dds::core::status::StatusMask::offered_deadline_missed()
• dds::core::status::StatusMask::requested_deadline_missed()
• dds::core::status::StatusMask::offered_incompatible_qos()
• dds::core::status::StatusMask::requested_incompatible_qos()
• dds::core::status::StatusMask::sample_lost()
• dds::core::status::StatusMask::sample_rejected()
• dds::core::status::StatusMask::data_on_readers()
• dds::core::status::StatusMask::data_available()
• dds::core::status::StatusMask::liveliness_lost()
• dds::core::status::StatusMask::liveliness_changed()
• dds::core::status::StatusMask::publication_matched()
• dds::core::status::StatusMask::subscription_matched()
• dds::core::status::StatusMask::all_data_disposed_topic()

When the entity is first created, or if the entity is not enabled, all communication statuses are in the untriggered state so the list returned by the status_changes operation will be empty.

Each status bit is declared as a constant and can be used in an AND operation to check the status bit against the result of type StatusMask. Not all statuses are relevant to all Entity objects. See the respective Listener interfaces for each Entity for more information.

The list of statuses returned by the status_changes operation refers to the statuses that are triggered on the Entity itself, and does not include statuses that apply to contained entities.

Returns

dds::core::status::StatusMask a bit mask in which each bit shows which value has changed.

Definition at line 52 of file EntityImpl.hpp.

---

The documentation for this class was generated from the following files:

• include/dcps/C++/isocpp2/dds/domain/DomainParticipant.hpp
• include/dcps/C++/isocpp2/dds/domain/detail/DomainParticipantImpl.hpp