<<singleton>> <<interface>> <<cert>> Allows creation and destruction of DDSDomainParticipant objects. More...

#include <dds_cpp_domain.hxx>

Public Member Functions
virtual DDSDomainParticipant *	create_participant (DDS_DomainId_t domainId, const DDS_DomainParticipantQos &qos, DDSDomainParticipantListener *listener, DDS_StatusMask mask)=0
	<<cert>> Creates a new DDSDomainParticipant object.
virtual DDS_ReturnCode_t	delete_participant (DDSDomainParticipant *a_participant)=0
	Deletes an existing DDSDomainParticipant.
virtual DDSDomainParticipant *	create_participant_from_config (const char *configuration_name)=0
	<<cert>> Creates a new DDSDomainParticipant given its configuration name from a description provided in configuration file.
virtual DDSDomainParticipant *	lookup_participant (DDS_DomainId_t domainId)=0
	<<cert>> Locates an existing DDSDomainParticipant.
virtual DDSDomainParticipant *	lookup_participant_by_name (const char *participant_name)=0
	<<cert>> Retrieves a DDSDomainParticipant by its entity name in the within the DDSDomainParticipantFactory
virtual DDS_ReturnCode_t	set_default_participant_qos (const DDS_DomainParticipantQos &qos)=0
	Sets the default DDS_DomainParticipantQos values for this domain participant factory.
virtual DDS_ReturnCode_t	get_default_participant_qos (DDS_DomainParticipantQos &qos)=0
	Initializes the DDS_DomainParticipantQos instance with default values.
virtual DDS_ReturnCode_t	get_qos (DDS_DomainParticipantFactoryQos &qos)=0
	<<cert>> Gets the value for participant factory QoS.
virtual DDS_ReturnCode_t	set_qos (const DDS_DomainParticipantFactoryQos &qos)=0
	<<cert>> Sets the value for a participant factory QoS.
virtual RTRegistry *	get_registry ()=0
	<<cert>> Retrieves the singleton registry instance associated with the factory.

Static Public Member Functions
static DDSDomainParticipantFactory *	get_instance ()
	<<cert>> Gets the singleton instance of this class.
static DDS_ReturnCode_t	finalize_instance ()
	<<eXtension>> Destroys the singleton instance of this class.

Detailed Description

<<singleton>> <<interface>> <<cert>> Allows creation and destruction of DDSDomainParticipant objects.

The sole purpose of this class is to allow the creation and destruction of DDSDomainParticipant objects. This class itself is a <<singleton>>, and accessed via the get_instance() method, and destroyed with finalize_instance() method.

A single application can participate in multiple domains by instantiating multiple DDSDomainParticipant objects.

An application may even instantiate multiple participants in the same domain. Participants in the same domain exchange data in the same way regardless of whether they are in the same application or different applications or on the same node or different nodes; their location is transparent.

There are two important caveats:

With multiple participants in the same domain on the same node (in the same application or different applications), each participant must be assigned its own receive ports. The receive ports are calculated based on the domain ID and the participant index set in the DDS_WireProtocolQosPolicy. The default index (-1) causes the participant to automatically search for the next available index, starting at 0, when it is created. If an index larger or equal to 0 is assigned then only that value will be used. If another participant with the same index already exists the participant creation will fail.

NOTE: An exception to this rule is multicast ports. Multicast ports are shared between between participants in the same domain on the same host). Thus, the index value is ignored.
You cannot mix entities from different participants. For example, you cannot delete a topic on a different participant than you created it from, and you cannot ask a subscriber to create a reader for a topic created from a participant different than the subscriber's own participant. (Note that it is permissable for an application built on top of RTI Connext DDS Micro to know about entities from different participants. For example, an application could keep references to a reader from one domain and a writer from another and then bridge the domains by writing the data received in the reader callback.)

See also:: DDSDomainParticipant

Member Function Documentation

static DDSDomainParticipantFactory* DDSDomainParticipantFactory::get_instance ( )

static

<<cert>> Gets the singleton instance of this class.

Returns:: the DDSDomainParticipantFactory instance.

MT Safety:: UNSAFE on the FIRST call to DDSDomainParticipantFactory::get_instance(). It is not safe for two threads to simultaneously make the first call to get an instance of the factory. Subsequent calls are thread safe.

DDSTheParticipantFactory can be used as an alias for the singleton factory returned by this operation.

Returns:: the singleton DDSDomainParticipantFactory instance.

See also:: DDSTheParticipantFactory

static DDS_ReturnCode_t DDSDomainParticipantFactory::finalize_instance ( )

static

<<eXtension>> Destroys the singleton instance of this class.

Only necessary to explicitly reclaim resources used by the participant factory singleton. Note that on many OSes, these resources are automatically reclaimed by the OS when the program terminates. Some memory checker tools still flag these as unreclaimed however. So this method provides a way to clean up memory used by the participant factory.

Precondition:: All participants created from the factory have been deleted.

Postcondition:: All resources belonging to the factory reclaimed. Another call to DDSDomainParticipantFactory::get_instance will return a new lifecycle of the singleton.

MT Safety:: UNSAFE for two threads to simultaneously call DDSDomainParticipantFactory::finalize_instance() or DDSDomainParticipantFactory::get_instance() at the same time.

Returns:: One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

virtual DDSDomainParticipant* DDSDomainParticipantFactory::create_participant	(	DDS_DomainId_t	domainId,
		const DDS_DomainParticipantQos &	qos,
		DDSDomainParticipantListener *	listener,
		DDS_StatusMask	mask
	)

pure virtual

<<cert>> Creates a new DDSDomainParticipant object.

Precondition:: The specified QoS policies must be consistent, or the operation will fail and no DDSDomainParticipant will be created.

If you want to create multiple participants on a given host in the same domain, make sure each one has a different participant index (set in the DDS_WireProtocolQosPolicy). This in turn will ensure each participant uses a different port number (since the unicast port numbers are calculated from the participant index and the domain ID).

Note that if there is a single participant per host in a given domain, the participant index can be left at the default value (-1).

Parameters:

domainId	<<in>> ID of the domain that the application intends to join. [range] [>=0], and does not violate guidelines stated in DDS_RtpsWellKnownPorts_t.
qos	<<in>> the domain participant's QoS. The special value DDS_PARTICIPANT_QOS_DEFAULT can be used to indicate that the DDSDomainParticipant should be created with the default DDS_DomainParticipantQos set in the DDSDomainParticipantFactory.
listener	<<in>> the domain participant's listener.
mask	<<in>> Changes of communication status to be invoked on the listener.

Returns:: domain participant or NULL on failure

See also:: Specifying QoS on entities for information on setting QoS before entity creation; DDS_DomainParticipantQos for rules on consistency among QoS; DDS_PARTICIPANT_QOS_DEFAULT

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::delete_participant ( DDSDomainParticipant * a_participant )

pure virtual

Deletes an existing DDSDomainParticipant.

Precondition:: All domain entities belonging to the participant must have already been deleted. Otherwise it fails with the error DDS_RETCODE_PRECONDITION_NOT_MET.

Postcondition:: Listener installed on the DDSDomainParticipant will not be called after this method returns successfully.

Parameters:

a_participant <<in>> DDSDomainParticipant to be deleted.

Returns:: One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

virtual DDSDomainParticipant* DDSDomainParticipantFactory::create_participant_from_config ( const char * configuration_name )

pure virtual

<<cert>> Creates a new DDSDomainParticipant given its configuration name from a description provided in configuration file.

This operation creates a DDSDomainParticipant and all the contained entities (DDSTopic, DDSPublisher, DDSSubscriber, DDSDataWriter, DDSDataReader) from a description given in a configuration file.

The configuration name is the fully qualified name of the application, consisting of the name of the application library plus the name of application configuration.

For example the name "MyApplicationLibrary::PublicationParticipant" can be used to create the application from the configuration with library name "MyApplicationLibrary" and participant name "PublicationParticipant"

The entities belonging to the newly created DDSDomainParticipant can be retrieved with the help of lookup operations such as: DDSDomainParticipant::lookup_publisher_by_name.

Parameters:

configuration_name <<in>> Name of RTI Connext DDS Micro application configuration in the configuration file. Cannot be NULL.

Returns:: Pointer to DDSDomainParticipant or NULL on failure

virtual DDSDomainParticipant* DDSDomainParticipantFactory::lookup_participant ( DDS_DomainId_t domainId )

pure virtual

<<cert>> Locates an existing DDSDomainParticipant.

If no such DDSDomainParticipant exists, the operation will return NULL value.

If multiple DDSDomainParticipant entities belonging to that domainId exist, then the operation will return one of them. It is not specified which one.

Parameters:

domainId <<in>> ID of the domain participant to lookup.

Returns:: domain participant if it exists, or NULL

virtual DDSDomainParticipant* DDSDomainParticipantFactory::lookup_participant_by_name ( const char * participant_name )

pure virtual

<<cert>> Retrieves a DDSDomainParticipant by its entity name in the within the DDSDomainParticipantFactory

This returned DDSDomainParticipant is either enabled or disabled.

Every DDSDomainParticipant in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.

This operation retrieves a DDSDomainParticipant within the DDSDomainParticipantFactory given the entity's name. If there are several DDSDomainParticipant with the same name within the DDSDomainParticipantFactory, this function returns the first matching occurrence.

Parameters:

participant_name <<in>> Entity name of the DDSDomainParticipant. Cannot be NULL.

Returns:: The first DDSDomainParticipant found with the specified name or NULL if it is not found.

MT Safety:: UNSAFE. It is not safe to lookup a DDSDomainParticipant in one thread while another thread is simultaneously creating or destroying that DDSDomainParticipant.

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::set_default_participant_qos ( const DDS_DomainParticipantQos & qos )

pure virtual

Sets the default DDS_DomainParticipantQos values for this domain participant factory.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters:

qos <<inout>> Qos to be used by the DDSDomainParticipant. The special value DDS_PARTICIPANT_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDSDomainParticipantFactory::set_default_participant_qos had never been called.

Returns:: One of the Standard Return Codes

See also:: DDS_PARTICIPANT_QOS_DEFAULT; DDSDomainParticipantFactory::create_participant

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_default_participant_qos ( DDS_DomainParticipantQos & qos )

pure virtual

Initializes the DDS_DomainParticipantQos instance with default values.

The retrieved qos will match the set of values specified on the last successful call to DDSDomainParticipantFactory::set_default_participant_qos, or else, if the call was never made, the default values listed in DDS_DomainParticipantQos.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters:

qos	<<out>> the domain participant's QoS

Returns:: One of the Standard Return Codes

See also:: DDS_PARTICIPANT_QOS_DEFAULT; DDSDomainParticipantFactory::create_participant

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_qos ( DDS_DomainParticipantFactoryQos & qos )

pure virtual

<<cert>> Gets the value for participant factory QoS.

Parameters:

qos	<<inout>> QoS to be filled up.

Returns:: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSDomainParticipantFactory::set_qos ( const DDS_DomainParticipantFactoryQos & qos )

pure virtual

<<cert>> Sets the value for a participant factory QoS.

The DDS_DomainParticipantFactoryQos::entity_factory can be changed. The other policies are immutable.

Note that despite having QoS, the DDSDomainParticipantFactory is not an DDSEntity.

Note that this function may cause RTI Connext DDS Micro to free and reallocate memory, depending on the QoS policies that are changed.

Parameters:

qos	<<in>> Set of policies to be applied to DDSDomainParticipantFactory. Policies must be consistent. Immutable policies can only be changed before calling any other RTI Connext DDS Micro methods except for DDSDomainParticipantFactory::get_qos

Returns:: One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY if immutable policy is changed, or DDS_RETCODE_INCONSISTENT_POLICY if policies are inconsistent

See also:: DDS_DomainParticipantFactoryQos for rules on consistency among QoS

virtual RTRegistry* DDSDomainParticipantFactory::get_registry ( )

pure virtual

<<cert>> Retrieves the singleton registry instance associated with the factory.

Returns:: the registry instance or NULL on failure.

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation