RTI Connext Traditional C++ API  Version 5.2.3
 All Classes Functions Variables Typedefs Enumerations Enumerator Groups Pages
DDSDomainParticipantFactory Class Referenceabstract

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

Public Member Functions

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 set_default_participant_qos_with_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Sets the default DDS_DomainParticipantQos values for this domain participant factory based on the input XML QoS profile.
 
virtual DDS_ReturnCode_t get_default_participant_qos (DDS_DomainParticipantQos &qos)=0
 Initializes the DDS_DomainParticipantQos instance with default values.
 
virtual DDS_ReturnCode_t set_default_library (const char *library_name)=0
 <<extension>> Sets the default XML library for a DDSDomainParticipantFactory.
 
virtual const char * get_default_library ()=0
 <<extension>> Gets the default XML library associated with a DDSDomainParticipantFactory.
 
virtual DDS_ReturnCode_t set_default_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Sets the default XML profile for a DDSDomainParticipantFactory.
 
virtual const char * get_default_profile ()=0
 <<extension>> Gets the default XML profile associated with a DDSDomainParticipantFactory.
 
virtual const char * get_default_profile_library ()=0
 <<extension>> Gets the library where the default XML profile is contained for a DDSDomainParticipantFactory.
 
virtual DDS_ReturnCode_t get_participant_factory_qos_from_profile (DDS_DomainParticipantFactoryQos &qos, const char *library_name, const char *profile_name)=0
 <<extension>> Gets the DDS_DomainParticipantFactoryQos values associated with the input XML QoS profile.
 
virtual DDS_ReturnCode_t get_participant_qos_from_profile (DDS_DomainParticipantQos &qos, const char *library_name, const char *profile_name)=0
 <<extension>> Gets the DDS_DomainParticipantQos values associated with the input XML QoS profile.
 
virtual DDS_ReturnCode_t get_publisher_qos_from_profile (DDS_PublisherQos &qos, const char *library_name, const char *profile_name)=0
 <<extension>> Gets the DDS_PublisherQos values associated with the input XML QoS profile.
 
virtual DDS_ReturnCode_t get_subscriber_qos_from_profile (DDS_SubscriberQos &qos, const char *library_name, const char *profile_name)=0
 <<extension>> Gets the DDS_SubscriberQos values associated with the input XML QoS profile.
 
virtual DDS_ReturnCode_t get_datawriter_qos_from_profile (DDS_DataWriterQos &qos, const char *library_name, const char *profile_name)=0
 <<extension>> Gets the DDS_DataWriterQos values associated with the input XML QoS profile.
 
virtual DDS_ReturnCode_t get_datawriter_qos_from_profile_w_topic_name (DDS_DataWriterQos &qos, const char *library_name, const char *profile_name, const char *topic_name)=0
 <<extension>> Gets the DDS_DataWriterQos values associated with the input XML QoS profile while applying topic filters to the input topic name.
 
virtual DDS_ReturnCode_t get_datareader_qos_from_profile (DDS_DataReaderQos &qos, const char *library_name, const char *profile_name)=0
 <<extension>> Gets the DDS_DataReaderQos values associated with the input XML QoS profile.
 
virtual DDS_ReturnCode_t get_datareader_qos_from_profile_w_topic_name (DDS_DataReaderQos &qos, const char *library_name, const char *profile_name, const char *topic_name)=0
 <<extension>> Gets the DDS_DataReaderQos values associated with the input XML QoS profile while applying topic filters to the input topic name.
 
virtual DDS_ReturnCode_t get_topic_qos_from_profile (DDS_TopicQos &qos, const char *library_name, const char *profile_name)=0
 <<extension>> Gets the DDS_TopicQos values associated with the input XML QoS profile.
 
virtual DDS_ReturnCode_t get_topic_qos_from_profile_w_topic_name (DDS_TopicQos &qos, const char *library_name, const char *profile_name, const char *topic_name)=0
 <<extension>> Gets the DDS_TopicQos values associated with the input XML QoS profile while applying topic filters to the input topic name.
 
virtual DDS_ReturnCode_t get_qos_profile_libraries (struct DDS_StringSeq &library_names)=0
 <<extension>> Gets the names of all XML QoS profile libraries associated with the DDSDomainParticipantFactory
 
virtual DDS_ReturnCode_t get_qos_profiles (struct DDS_StringSeq &profile_names, const char *library_name)=0
 <<extension>> Gets the names of all XML QoS profiles associated with the input XML QoS profile library.
 
virtual DDSDomainParticipantcreate_participant (DDS_DomainId_t domainId, const DDS_DomainParticipantQos &qos, DDSDomainParticipantListener *listener, DDS_StatusMask mask)=0
 Creates a new DDSDomainParticipant object.
 
virtual DDSDomainParticipantcreate_participant_with_profile (DDS_DomainId_t domainId, const char *library_name, const char *profile_name, DDSDomainParticipantListener *listener, DDS_StatusMask mask)=0
 <<extension>> Creates a new DDSDomainParticipant object using the DDS_DomainParticipantQos associated with the input XML QoS profile.
 
virtual DDS_ReturnCode_t delete_participant (DDSDomainParticipant *a_participant)=0
 Deletes an existing DDSDomainParticipant.
 
virtual DDSDomainParticipantlookup_participant (DDS_DomainId_t domainId)=0
 Locates an existing DDSDomainParticipant.
 
virtual DDS_ReturnCode_t set_qos (const DDS_DomainParticipantFactoryQos &qos)=0
 Sets the value for a participant factory QoS.
 
virtual DDS_ReturnCode_t get_qos (DDS_DomainParticipantFactoryQos &qos)=0
 Gets the value for participant factory QoS.
 
virtual DDS_ReturnCode_t load_profiles ()=0
 <<extension>> Loads the XML QoS profiles.
 
virtual DDS_ReturnCode_t reload_profiles ()=0
 <<extension>> Reloads the XML QoS profiles.
 
virtual DDS_ReturnCode_t unload_profiles ()=0
 <<extension>> Unloads the XML QoS profiles.
 
virtual DDS_ReturnCode_t unregister_thread ()=0
 <<extension>> Allows the user to release thread specific resources kept by the middleware.
 
virtual DDSDomainParticipantcreate_participant_from_config (const char *configuration_name)=0
 <<extension>> Creates a DDSDomainParticipant given its configuration name from a description provided in an XML configuration file.
 
virtual DDSDomainParticipantcreate_participant_from_config_w_params (const char *configuration_name, const DDS_DomainParticipantConfigParams_t &params)=0
 <<extension>> Creates a DDSDomainParticipant given its configuration name from a description provided in an XML configuration file and a set of parameters that allow chaging some properties of such configuration.
 
virtual DDSDomainParticipantlookup_participant_by_name (const char *participant_name)=0
 <<extension>> Looks up a DDSDomainParticipant by its entity name in the DDSDomainParticipantFactory.
 
virtual DDS_ReturnCode_t register_type_support (DDSDomainParticipantFactory_RegisterTypeFunction register_type_fcn, const char *type_name)=0
 <<extension>> Registers a DDSTypeSupport with the DDSDomainParticipantFactory to enable automatic registration if the corresponding type, should it be needed by a DDSDomainParticipant.
 
virtual DDS_ReturnCode_t get_participants (DDSDomainParticipantSeq &participants)=0
 <<extension>> Allows the application to access all the participants the DomainParticipantFactory has.
 
virtual DDS_ReturnCode_t set_thread_factory (DDSThreadFactory *thread_factory)=0
 <<extension>> Sets a DDSThreadFactory in the DDSDomainParticipantFactory that will be used to create the internal threads of the DDS middleware.
 

Static Public Member Functions

static
DDSDomainParticipantFactory
get_instance ()
 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>> 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:

  • When there are multiple participants on the same node (in the same application or different applications) in the same domain, the application(s) must make sure that the participants do not try to bind to the same port numbers. You must disambiguate between the participants by setting a participant ID for each participant (DDS_WireProtocolQosPolicy::participant_id). The port numbers used by a participant are calculated based on both the participant index and the domain ID, so if all participants on the same node have different participant indexes, they can coexist in the same domain.
  • 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 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

Gets the singleton instance of this class.

MT Safety:
On non-Linux systems: UNSAFE for multiple threads to simultaneously make the FIRST call to either DDSDomainParticipantFactory::get_instance() or DDSDomainParticipantFactory::finalize_instance(). Subsequent calls are thread safe. (On Linux systems, these calls are thread safe.)

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

Returns
The singleton DDSDomainParticipantFactory instance.
See Also
::DDS_TheParticipantFactory
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 OSs, these resources are automatically reclaimed by the OS when the program terminates. However, some memory-check tools still flag these as unreclaimed. 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 have been reclaimed. Another call to DDSDomainParticipantFactory::get_instance will return a new lifecycle of the singleton.
MT Safety:
On non-Linux systems: UNSAFE for multiple threads to simultaneously make the FIRST call to either DDSDomainParticipantFactory::get_instance() or DDSDomainParticipantFactory::finalize_instance(). Subsequent calls are thread safe. (On Linux systems, these calls are thread safe.)
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET
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.

MT Safety:
UNSAFE. It is not safe to retrieve the default QoS value from a domain participant factory while another thread may be simultaneously calling DDSDomainParticipantFactory::set_default_participant_qos
Parameters
qos<<inout>> Qos to be filled up. 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::set_default_participant_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Sets the default DDS_DomainParticipantQos values for this domain participant factory based on the input XML QoS profile.

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

This default value will be used for newly created DDSDomainParticipant if DDS_PARTICIPANT_QOS_DEFAULT is specified as the qos parameter when DDSDomainParticipantFactory::create_participant is called.

Precondition
The DDS_DomainParticipantQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to retrieve the default QoS value from a domain participant factory while another thread may be simultaneously calling DDSDomainParticipantFactory::set_default_participant_qos
Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).

If the input profile cannot be found the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See Also
DDS_PARTICIPANT_QOS_DEFAULT
DDSDomainParticipantFactory::create_participant_with_profile
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 DDSDomainParticipantFactory::set_default_participant_qos_with_profile, 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
MT Safety:
UNSAFE. It is not safe to retrieve the default QoS value from a domain participant factory while another thread may be simultaneously calling DDSDomainParticipantFactory::set_default_participant_qos
Returns
One of the Standard Return Codes
See Also
DDS_PARTICIPANT_QOS_DEFAULT
DDSDomainParticipantFactory::create_participant
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::set_default_library ( const char *  library_name)
pure virtual

<<extension>> Sets the default XML library for a DDSDomainParticipantFactory.

Any API requiring a library_name as a parameter can use null to refer to the default library.

See Also
DDSDomainParticipantFactory::set_default_profile for more information.
Parameters
library_name<<in>> Library name. If library_name is null any previous default is unset.
Returns
One of the Standard Return Codes
See Also
DDSDomainParticipantFactory::get_default_library
virtual const char* DDSDomainParticipantFactory::get_default_library ( )
pure virtual

<<extension>> Gets the default XML library associated with a DDSDomainParticipantFactory.

Returns
The default library or null if the default library was not set.
See Also
DDSDomainParticipantFactory::set_default_library
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::set_default_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Sets the default XML profile for a DDSDomainParticipantFactory.

This method specifies the profile that will be used as the default the next time a default DomainParticipantFactory profile is needed during a call to a DomainParticipantFactory method. When calling a DDSDomainParticipantFactory method that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

This method does not set the default QoS for newly created DomainParticipants; for this functionality, use DDSDomainParticipantFactory::set_default_participant_qos_with_profile (you may pass in NULL after having called set_default_profile()).

Parameters
library_name<<in>> The library name containing the profile.
profile_name<<in>> The profile name. If profile_name is null any previous default is unset.
Returns
One of the Standard Return Codes
See Also
DDSDomainParticipantFactory::get_default_profile
DDSDomainParticipantFactory::get_default_profile_library
virtual const char* DDSDomainParticipantFactory::get_default_profile ( )
pure virtual

<<extension>> Gets the default XML profile associated with a DDSDomainParticipantFactory.

Returns
The default profile or null if the default profile was not set.
See Also
DDSDomainParticipantFactory::set_default_profile
virtual const char* DDSDomainParticipantFactory::get_default_profile_library ( )
pure virtual

<<extension>> Gets the library where the default XML profile is contained for a DDSDomainParticipantFactory.

The default profile library is automatically set when DDSDomainParticipantFactory::set_default_profile is called.

This library can be different than the DDSDomainParticipantFactory default library (see DDSDomainParticipantFactory::get_default_library).

Returns
The default profile library or null if the default profile was not set.
See Also
DDSDomainParticipantFactory::set_default_profile
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_participant_factory_qos_from_profile ( DDS_DomainParticipantFactoryQos qos,
const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Gets the DDS_DomainParticipantFactoryQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_participant_qos_from_profile ( DDS_DomainParticipantQos qos,
const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Gets the DDS_DomainParticipantQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_publisher_qos_from_profile ( DDS_PublisherQos qos,
const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Gets the DDS_PublisherQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_subscriber_qos_from_profile ( DDS_SubscriberQos qos,
const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Gets the DDS_SubscriberQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_datawriter_qos_from_profile ( DDS_DataWriterQos qos,
const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Gets the DDS_DataWriterQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_datawriter_qos_from_profile_w_topic_name ( DDS_DataWriterQos qos,
const char *  library_name,
const char *  profile_name,
const char *  topic_name 
)
pure virtual

<<extension>> Gets the DDS_DataWriterQos values associated with the input XML QoS profile while applying topic filters to the input topic name.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).
topic_name<<in>> Topic name that will be evaluated against the topic_filter attribute in the XML QoS profile. If topic_name is null, RTI Connext will match only QoSs without explicit topic_filter expressions.

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_datareader_qos_from_profile ( DDS_DataReaderQos qos,
const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Gets the DDS_DataReaderQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_datareader_qos_from_profile_w_topic_name ( DDS_DataReaderQos qos,
const char *  library_name,
const char *  profile_name,
const char *  topic_name 
)
pure virtual

<<extension>> Gets the DDS_DataReaderQos values associated with the input XML QoS profile while applying topic filters to the input topic name.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).
topic_name<<in>> Topic name that will be evaluated against the topic_filter attribute in the XML QoS profile. If topic_name is null, RTI Connext will match only QoSs without explicit topic_filter expressions.

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_topic_qos_from_profile ( DDS_TopicQos qos,
const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Gets the DDS_TopicQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_topic_qos_from_profile_w_topic_name ( DDS_TopicQos qos,
const char *  library_name,
const char *  profile_name,
const char *  topic_name 
)
pure virtual

<<extension>> Gets the DDS_TopicQos values associated with the input XML QoS profile while applying topic filters to the input topic name.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).
topic_name<<in>> Topic name that will be evaluated against the topic_filter attribute in the XML QoS profile. If topic_name is null, RTI Connext will match only QoSs without explicit topic_filter expressions.

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_qos_profile_libraries ( struct DDS_StringSeq library_names)
pure virtual

<<extension>> Gets the names of all XML QoS profile libraries associated with the DDSDomainParticipantFactory

Parameters
library_names<<out>> DDS_StringSeq to be filled with names of XML QoS profile libraries. Cannot be NULL.
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_qos_profiles ( struct DDS_StringSeq profile_names,
const char *  library_name 
)
pure virtual

<<extension>> Gets the names of all XML QoS profiles associated with the input XML QoS profile library.

Parameters
profile_names<<out>> DDS_StringSeq to be filled with names of XML QoS profiles. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
virtual DDSDomainParticipant* DDSDomainParticipantFactory::create_participant ( DDS_DomainId_t  domainId,
const DDS_DomainParticipantQos qos,
DDSDomainParticipantListener listener,
DDS_StatusMask  mask 
)
pure virtual

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 DomainParticipant'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. See DDS_StatusMask.
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
NDDS_DISCOVERY_PEERS
DDSDomainParticipantFactory::create_participant_with_profile
DDSDomainParticipantFactory::get_default_participant_qos
DDSDomainParticipant::set_listener
virtual DDSDomainParticipant* DDSDomainParticipantFactory::create_participant_with_profile ( DDS_DomainId_t  domainId,
const char *  library_name,
const char *  profile_name,
DDSDomainParticipantListener listener,
DDS_StatusMask  mask 
)
pure virtual

<<extension>> Creates a new DDSDomainParticipant object using the DDS_DomainParticipantQos associated with the input XML QoS profile.

Precondition
The DDS_DomainParticipantQos in the input profile 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.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipantFactory::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipantFactory::set_default_profile).
listener<<in>> the DomainParticipant's listener.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
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
NDDS_DISCOVERY_PEERS
DDSDomainParticipantFactory::create_participant()
DDSDomainParticipantFactory::get_default_participant_qos()
DDSDomainParticipant::set_listener()
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.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
a_participant<<in>> DDSDomainParticipant to be deleted.
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.
virtual DDSDomainParticipant* DDSDomainParticipantFactory::lookup_participant ( DDS_DomainId_t  domainId)
pure virtual

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 DDS_ReturnCode_t DDSDomainParticipantFactory::set_qos ( const DDS_DomainParticipantFactoryQos qos)
pure virtual

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.

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 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 DDS_ReturnCode_t DDSDomainParticipantFactory::get_qos ( DDS_DomainParticipantFactoryQos qos)
pure virtual

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::load_profiles ( )
pure virtual

<<extension>> Loads the XML QoS profiles.

The XML QoS profiles are loaded implicitly after the first DDSDomainParticipant is created or explicitly, after a call to this method.

This has the same effect as DDSDomainParticipantFactory::reload_profiles().

Returns
One of the Standard Return Codes
See Also
DDS_ProfileQosPolicy
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::reload_profiles ( )
pure virtual

<<extension>> Reloads the XML QoS profiles.

The XML QoS profiles are loaded implicitly after the first DDSDomainParticipant is created or explicitly, after a call to this method.

This has the same effect as DDSDomainParticipantFactory::load_profiles().

Returns
One of the Standard Return Codes
See Also
DDS_ProfileQosPolicy
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::unload_profiles ( )
pure virtual

<<extension>> Unloads the XML QoS profiles.

The resources associated with the XML QoS profiles are freed. Any reference to the profiles after calling this method will fail with an error.

Returns
One of the Standard Return Codes
See Also
DDS_ProfileQosPolicy
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::unregister_thread ( )
pure virtual

<<extension>> Allows the user to release thread specific resources kept by the middleware.

This function should be called by the user right before exiting a thread where DDS API were used. In this way the middleware will be able to free all the resources related to this specific thread. The best approach is to call the function during the thread deletion after all the DDS related API have have been called.

Returns
One of the Standard Return Codes
virtual DDSDomainParticipant* DDSDomainParticipantFactory::create_participant_from_config ( const char *  configuration_name)
pure virtual

<<extension>> Creates a DDSDomainParticipant given its configuration name from a description provided in an XML configuration file.

This operation creates a DDSDomainParticipant registering all the necessary data types and creating all the contained entities (DDSTopic, DDSPublisher, DDSSubscriber, DDSDataWriter, DDSDataReader) from a description given in an XML configuration file.

The configuration name is the fully qualified name of the XML participant object, consisting of the name of the participant library plus the name of participant configuration.

For example the name "MyParticipantLibrary::PublicationParticipant" can be used to create the domain participant from the description in an XML file with contents shown in the snippet below:

<participant_library name="MyParticipantLibrary">
<domain_participant name="PublicationParticipant" domain_ref="MyDomainLibrary::HelloWorldDomain">
<publisher name="MyPublisher">
<data_writer name="HelloWorldWriter" topic_ref="HelloWorldTopic"/>
</publisher>
</domain_participant>
</participant_library>

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

This operation is equivalent to call DDSDomainParticipantFactory::create_participant_from_config_w_params passing DDS_PARTICIPANT_CONFIG_PARAMS_DEFAULT as parameters.

Parameters
configuration_name<<in>> Name of the participant configuration in the XML file.
Returns
The created DDSDomainParticipant or NULL on error.
See Also
DDSDomainParticipantFactory::lookup_participant_by_name
DDSDomainParticipant::lookup_topicdescription
DDSDomainParticipant::lookup_publisher_by_name
DDSDomainParticipant::lookup_subscriber_by_name
DDSDomainParticipant::lookup_datareader_by_name
DDSDomainParticipant::lookup_datawriter_by_name
DDSPublisher::lookup_datawriter_by_name
DDSSubscriber::lookup_datareader_by_name
virtual DDSDomainParticipant* DDSDomainParticipantFactory::create_participant_from_config_w_params ( const char *  configuration_name,
const DDS_DomainParticipantConfigParams_t params 
)
pure virtual

<<extension>> Creates a DDSDomainParticipant given its configuration name from a description provided in an XML configuration file and a set of parameters that allow chaging some properties of such configuration.

The operation will create a DDSDomainParticipant the same way specified in DDSDomainParticipantFactory::create_participant_from_config.

In addition, this operation allows overriding the domain ID, participant name, and entities QoS specified in the configuration.

Parameters
configuration_name<<in>> Name of the participant configuration in the XML file.
params<<in>> input parameters that allow changing some properties of the configuration referred to by configuration_name.
Returns
The created DDSDomainParticipant or NULL on error.
virtual DDSDomainParticipant* DDSDomainParticipantFactory::lookup_participant_by_name ( const char *  participant_name)
pure virtual

<<extension>> Looks up a DDSDomainParticipant by its entity name in the DDSDomainParticipantFactory.

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.
Returns
The first DDSDomainParticipant found with the specified name or NULL if it is not found.
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::register_type_support ( DDSDomainParticipantFactory_RegisterTypeFunction  register_type_fcn,
const char *  type_name 
)
pure virtual

<<extension>> Registers a DDSTypeSupport with the DDSDomainParticipantFactory to enable automatic registration if the corresponding type, should it be needed by a DDSDomainParticipant.

Types refered by the DDSTopic entities within a DDSDomainParticipant must be registered with the DDSDomainParticipant.

Type registration in a DDSDomainParticipant is performed by a call to the FooTypeSupport::register_type operation. This can be done directly from the application code or indirectly by the RTI Connext infrastructure as a result of parsing an XML configuration file that refers to that type.

The DDSDomainParticipantFactory::register_type_support operation provides the DDSDomainParticipantFactory with the information it needs to automatically call the FooTypeSupport::register_type operation and register the corresponding type if the type is needed as a result of parsing an XML configuration file.

Automatic type registration while parsing XML files can also be done by the RTI Connext infrastructure based on the type description provided in the XML files. If the DDSTypeSupport has been registered with the DDSDomainParticipantFactory this definition takes precedence over the description of the type given in the XML file.

The DDSDomainParticipantFactory::register_type_support operation receives a FooTypeSupport::register_type function as a parameter. This function is normally generated using rtiddsgen from a description of the corresponsing type in IDL, XML, or XSD.

The typical workflow when using this function is as follows: Define the data-type in IDL (or XML, or XSD) in a file. E.g. Foo.idl Run rtiddsgen in that file to generate the TypeSupport files, for the desired programming language. E.g. in C++ FooTypeSupport.h FooTypeSupport.cxx Include the proper header file (e.g. FooTypeSupport.h) in your program and call DDSDomainParticipantFactory::register_type_support passing the function that was generated by rtiddsgen. E.g. FooTypeSupport::register_type Include the TypeSupport source file in your project such that it is compiled and linked. E.g. FooTypeSupport.cxx

You may refer to the Getting Started Guide for additional details in this process.

Note that only one register function is allowed per registered type name.

Parameters
register_type_fcn<<in>> ::DDS_RegisterTypeFunction to be used for registering the type with a DDSDomainParticipant.
type_name<<in>> Name the type is registered with.
Returns
One of the Standard Return Codes
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::get_participants ( DDSDomainParticipantSeq &  participants)
pure virtual

<<extension>> Allows the application to access all the participants the DomainParticipantFactory has.

If the sequence doesn't own its buffer, and its maximum is less than the total number of participants, it will be filled up to its maximum, and fail with DDS_RETCODE_OUT_OF_RESOURCES.

MT Safety:
Safe.
Parameters
participants<<inout>> a DomainParticipantSeq object where the set or list of participants will be returned
Returns
One of the Standard Return Codes or DDS_RETCODE_OUT_OF_RESOURCES
virtual DDS_ReturnCode_t DDSDomainParticipantFactory::set_thread_factory ( DDSThreadFactory thread_factory)
pure virtual

<<extension>> Sets a DDSThreadFactory in the DDSDomainParticipantFactory that will be used to create the internal threads of the DDS middleware.

DDS threads are managed by the DDSDomainParticipant, which is responsible for creating and deleting threads throughout its lifecycle. Some threads are created when the DDSDomainParticipant gets enabled (i.e., database, event, etc.) and others when special features are enabled (i.e., asynchronous publication thread).

DDS threads have DDSDomainParticipant scope. This means every DomainParticipant creates all the necessary threads to operate and each DDSDomainParticipant will create its own independent set of threads.

Each DDSDomainParticipant creates an independent set of DDS threads and will use the DDSThreadFactory that is held by the DDSDomainParticipantFactory at the time the DomainParticipant is created. A DDSThreadFactory is immutable from a DDSDomainParticipant point of view. This means that a DDSDomainParticipant will use throughout its lifecycle the same DDSThreadFactory that was set when it was created, even if a new DDSThreadFactory is set in the DDSDomainParticipantFactory later. That is, if a new DDSThreadFactory is set, a previously created DDSDomainParticipant will not be affected.

ThreadFactory lifecycle: A DDSThreadFactory instance must be alive while there are DomainParticipants using it. A DDSThreadFactory instance can be deleted only after all DomainParticipants using it are deleted.

By default, the DDSDomainParticipantFactory has an internal DDSThreadFactory so threads are created automatically by the core product. These threads are usually created using the typical framework for the target platform (i.e., pthread for UNIX-based systems).

MT Safety:
: Safe. Creation and deletion of a DDSDomainParticipant can occur concurrently with setting a DDSThreadFactory.
Parameters
thread_factory<<in>> Instance of a DDSThreadFactory to be used for creating the DDS threads. If null is specified, the current DDSThreadFactory is removed and the internal default will be used.
Returns
One of the Standard Return Codes

RTI Connext Traditional C++ API Version 5.2.3 Copyright © Wed Apr 27 2016 Real-Time Innovations, Inc