RTI Connext Traditional C++ API Version 7.2.0
DDSDomainParticipant Class Referenceabstract

<<interface>> Container for all DDSDomainEntity objects. More...

Inheritance diagram for DDSDomainParticipant:
DDSEntity

Public Member Functions

virtual DDS_ReturnCode_t get_default_datawriter_qos (DDS_DataWriterQos &qos)=0
 <<extension>> Copy the default DDS_DataWriterQos values into the provided DDS_DataWriterQos instance. More...
 
virtual DDS_ReturnCode_t set_default_datawriter_qos (const DDS_DataWriterQos &qos)=0
 <<extension>> Set the default DataWriterQos values for this DomainParticipant. More...
 
virtual DDS_ReturnCode_t set_default_datawriter_qos_with_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Set the default DDS_DataWriterQos values for this domain participant based on the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t get_default_datareader_qos (DDS_DataReaderQos &qos)=0
 <<extension>> Copy the default DDS_DataReaderQos values into the provided DDS_DataReaderQos instance. More...
 
virtual DDS_ReturnCode_t set_default_datareader_qos (const DDS_DataReaderQos &qos)=0
 <<extension>> Set the default DDS_DataReaderQos values for this domain participant. More...
 
virtual DDS_ReturnCode_t set_default_datareader_qos_with_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Set the default DDS_DataReaderQos values for this DomainParticipant based on the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t get_default_flowcontroller_property (DDS_FlowControllerProperty_t &prop)=0
 <<extension>> Copies the default DDS_FlowControllerProperty_t values for this domain participant into the given DDS_FlowControllerProperty_t instance. More...
 
virtual DDS_ReturnCode_t set_default_flowcontroller_property (const DDS_FlowControllerProperty_t &prop)=0
 <<extension>> Set the default DDS_FlowControllerProperty_t values for this domain participant. More...
 
virtual DDS_ReturnCode_t register_contentfilter (const char *filter_name, const DDSContentFilter *contentfilter)=0
 <<extension>> Register a content filter which can be used to create a DDSContentFilteredTopic. More...
 
virtual DDSContentFilterlookup_contentfilter (const char *filter_name)=0
 <<extension>> Lookup a content filter previously registered with DDSDomainParticipant::register_contentfilter. More...
 
virtual DDS_ReturnCode_t unregister_contentfilter (const char *filter_name)=0
 <<extension>> Unregister a content filter previously registered with DDSDomainParticipant::register_contentfilter. More...
 
virtual const char * get_default_library ()=0
 <<extension>> Gets the default XML library associated with a DDSDomainParticipant. More...
 
virtual const char * get_default_profile ()=0
 <<extension>> Gets the default XML profile associated with a DDSDomainParticipant. More...
 
virtual const char * get_default_profile_library ()=0
 <<extension>> Gets the library where the default XML QoS profile is contained for a DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t set_default_library (const char *library_name)=0
 <<extension>> Sets the default XML library for a DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t set_default_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Sets the default XML profile for a DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t get_default_topic_qos (DDS_TopicQos &qos)=0
 Copies the default DDS_TopicQos values for this domain participant into the given DDS_TopicQos instance. More...
 
virtual DDS_ReturnCode_t set_default_topic_qos (const DDS_TopicQos &qos)=0
 Set the default DDS_TopicQos values for this domain participant. More...
 
virtual DDS_ReturnCode_t set_default_topic_qos_with_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Set the default DDS_TopicQos values for this domain participant based on the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t get_default_publisher_qos (DDS_PublisherQos &qos)=0
 Copy the default DDS_PublisherQos values into the provided DDS_PublisherQos instance. More...
 
virtual DDS_ReturnCode_t set_default_publisher_qos (const DDS_PublisherQos &qos)=0
 Set the default DDS_PublisherQos values for this DomainParticipant. More...
 
virtual DDS_ReturnCode_t set_default_publisher_qos_with_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Set the default DDS_PublisherQos values for this DomainParticipant based on the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t get_default_subscriber_qos (DDS_SubscriberQos &qos)=0
 Copy the default DDS_SubscriberQos values into the provided DDS_SubscriberQos instance. More...
 
virtual DDS_ReturnCode_t set_default_subscriber_qos (const DDS_SubscriberQos &qos)=0
 Set the default DDS_SubscriberQos values for this DomainParticipant. More...
 
virtual DDS_ReturnCode_t set_default_subscriber_qos_with_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Set the default DDS_SubscriberQos values for this DomainParticipant based on the input XML QoS profile. More...
 
virtual DDSPublishercreate_publisher (const DDS_PublisherQos &qos, DDSPublisherListener *listener, DDS_StatusMask mask)=0
 Creates a DDSPublisher with the desired QoS policies and attaches to it the specified DDSPublisherListener. More...
 
virtual DDSPublishercreate_publisher_with_profile (const char *library_name, const char *profile_name, DDSPublisherListener *listener, DDS_StatusMask mask)=0
 <<extension>> Creates a new DDSPublisher object using the DDS_PublisherQos associated with the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t delete_publisher (DDSPublisher *p)=0
 Deletes an existing DDSPublisher. More...
 
virtual DDSSubscribercreate_subscriber (const DDS_SubscriberQos &qos, DDSSubscriberListener *listener, DDS_StatusMask mask)=0
 Creates a DDSSubscriber with the desired QoS policies and attaches to it the specified DDSSubscriberListener. More...
 
virtual DDSSubscribercreate_subscriber_with_profile (const char *library_name, const char *profile_name, DDSSubscriberListener *listener, DDS_StatusMask mask)=0
 <<extension>> Creates a new DDSSubscriber object using the DDS_PublisherQos associated with the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t delete_subscriber (DDSSubscriber *s)=0
 Deletes an existing DDSSubscriber. More...
 
virtual DDS_ReturnCode_t get_publishers (DDSPublisherSeq &publishers)=0
 <<extension>> Allows the application to access all the publishers the participant has. More...
 
virtual DDS_ReturnCode_t get_subscribers (DDSSubscriberSeq &subscribers)=0
 <<extension>> Allows the application to access all the subscribers the participant has. More...
 
virtual DDSTopiccreate_topic (const char *topic_name, const char *type_name, const DDS_TopicQos &qos, DDSTopicListener *listener, DDS_StatusMask mask)=0
 Creates a DDSTopic with the desired QoS policies and attaches to it the specified DDSTopicListener. More...
 
virtual DDSTopiccreate_topic_with_profile (const char *topic_name, const char *type_name, const char *library_name, const char *profile_name, DDSTopicListener *listener, DDS_StatusMask mask)=0
 <<extension>> Creates a new DDSTopic object using the DDS_PublisherQos associated with the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t delete_topic (DDSTopic *topic)=0
 Deletes a DDSTopic. More...
 
virtual DDSContentFilteredTopiccreate_contentfilteredtopic (const char *name, DDSTopic *related_topic, const char *filter_expression, const DDS_StringSeq &expression_parameters)=0
 Creates a DDSContentFilteredTopic, that can be used to do content-based subscriptions. More...
 
virtual DDSContentFilteredTopiccreate_contentfilteredtopic_with_filter (const char *name, DDSTopic *related_topic, const char *filter_expression, const DDS_StringSeq &expression_parameters, const char *filter_name=DDS_SQLFILTER_NAME)=0
 <<extension>> Creates a DDSContentFilteredTopic using the specified filter to do content-based subscriptions. More...
 
virtual DDS_ReturnCode_t delete_contentfilteredtopic (DDSContentFilteredTopic *a_contentfilteredtopic)=0
 Deletes a DDSContentFilteredTopic. More...
 
virtual DDSMultiTopiccreate_multitopic (const char *name, const char *type_name, const char *subscription_expression, const DDS_StringSeq &expression_parameters)=0
 [Not supported (optional)] Creates a MultiTopic that can be used to subscribe to multiple topics and combine/filter the received data into a resulting type. More...
 
virtual DDS_ReturnCode_t delete_multitopic (DDSMultiTopic *a_multitopic)=0
 [Not supported (optional)] Deletes a DDSMultiTopic. More...
 
virtual DDSTopicfind_topic (const char *topic_name, const DDS_Duration_t &timeout)=0
 Finds an existing (or ready to exist) DDSTopic, based on its name. More...
 
virtual DDSTopicDescriptionlookup_topicdescription (const char *topic_name)=0
 Looks up an existing, locally created DDSTopicDescription, based on its name. More...
 
virtual DDSFlowControllercreate_flowcontroller (const char *name, const DDS_FlowControllerProperty_t &prop)=0
 <<extension>> Creates a DDSFlowController with the desired property. More...
 
virtual DDS_ReturnCode_t delete_flowcontroller (DDSFlowController *fc)=0
 <<extension>> Deletes an existing DDSFlowController. More...
 
virtual DDSFlowControllerlookup_flowcontroller (const char *name)=0
 <<extension>> Looks up an existing locally-created DDSFlowController, based on its name. More...
 
virtual DDSSubscriberget_builtin_subscriber ()=0
 Accesses the built-in DDSSubscriber. More...
 
virtual DDS_ReturnCode_t ignore_participant (const DDS_InstanceHandle_t &handle)=0
 Instructs RTI Connext to locally ignore a remote DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t banish_ignored_participants ()=0
 <<extension>> Prevents ignored remote DomainParticipants from receiving traffic from the local DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t ignore_topic (const DDS_InstanceHandle_t &handle)=0
 Instructs RTI Connext to locally ignore a DDSTopic. More...
 
virtual DDS_ReturnCode_t ignore_publication (const DDS_InstanceHandle_t &handle)=0
 Instructs RTI Connext to locally ignore a publication. More...
 
virtual DDS_ReturnCode_t ignore_subscription (const DDS_InstanceHandle_t &handle)=0
 Instructs RTI Connext to locally ignore a subscription. More...
 
virtual DDS_DomainId_t get_domain_id ()=0
 Get the unique domain identifier. More...
 
virtual DDS_ReturnCode_t get_current_time (DDS_Time_t &current_time)=0
 Returns the current value of the time. More...
 
virtual DDS_ReturnCode_t register_durable_subscription (const DDS_EndpointGroup_t &group, const char *topic_name)=0
 <<extension>> Registers a Durable Subscription on the specified DDSTopic on all Persistence Services. More...
 
virtual DDS_ReturnCode_t delete_durable_subscription (const DDS_EndpointGroup_t &group)=0
 <<extension>> Deletes an existing Durable Subscription on all Persistence Services. More...
 
virtual DDS_ReturnCode_t assert_liveliness ()=0
 Manually asserts the liveliness of this DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t resume_endpoint_discovery (const DDS_InstanceHandle_t &remote_participant_handle)=0
 <<extension>> Initiates endpoint discovery with the specified remote DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t delete_contained_entities ()=0
 Delete all the entities that were created by means of the "create" operations on the DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t get_discovered_participants (DDS_InstanceHandleSeq &participant_handles)=0
 Returns a list of discovered DDSDomainParticipant entities. More...
 
virtual DDS_ReturnCode_t get_discovered_participants_from_subject_name (DDS_InstanceHandleSeq &participant_handles, const char *subject_name)=0
 <<extension>> Returns a list of discovered DDSDomainParticipant entities that have the given DDS_EntityNameQosPolicy::name. More...
 
virtual DDS_ReturnCode_t get_discovered_participant_data (struct DDS_ParticipantBuiltinTopicData &participant_data, const DDS_InstanceHandle_t &participant_handle)=0
 Returns DDS_ParticipantBuiltinTopicData for the specified DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t get_discovered_participant_subject_name (char *subject_name, DDS_UnsignedLong &subject_name_size, const DDS_InstanceHandle_t &participant_handle)=0
 <<extension>> Returns DDS_EntityNameQosPolicy::name for the specified DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t get_discovered_topics (DDS_InstanceHandleSeq &topic_handles)=0
 Returns list of discovered DDSTopic objects. More...
 
virtual DDS_ReturnCode_t get_discovered_topic_data (struct DDS_TopicBuiltinTopicData &topic_data, const DDS_InstanceHandle_t &topic_handle)=0
 Returns DDS_TopicBuiltinTopicData for the specified DDSTopic. More...
 
virtual DDS_Boolean contains_entity (const DDS_InstanceHandle_t &a_handle)=0
 Completes successfully with DDS_BOOLEAN_TRUE if the referenced DDSEntity is contained by the DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t get_participant_protocol_status (struct DDS_DomainParticipantProtocolStatus &status)=0
 <<extension>> Get the domain participant protocol status for this participant. More...
 
virtual DDS_ReturnCode_t set_property (const char *property_name, const char *value, bool propagate)=0
 Set the value for a property that applies to a DomainParticipant. More...
 
virtual DDS_ReturnCode_t set_qos (const DDS_DomainParticipantQos &qos)=0
 Change the QoS of this DomainParticipant. More...
 
virtual DDS_ReturnCode_t set_qos_with_profile (const char *library_name, const char *profile_name)=0
 <<extension>> Change the QoS of this domain participant using the input XML QoS profile. More...
 
virtual DDS_ReturnCode_t get_qos (DDS_DomainParticipantQos &qos)=0
 Get the participant QoS. More...
 
virtual DDS_ReturnCode_t add_peer (const char *peer_desc_string)=0
 <<extension>> Attempt to contact one or more additional peer participants. More...
 
virtual DDS_ReturnCode_t remove_peer (const char *peer_desc_string)=0
 <<extension>> Remove one or more peer participants from the list of peers with which this DDSDomainParticipant will try to communicate. More...
 
virtual DDS_ReturnCode_t get_dns_tracker_polling_period (DDS_Duration_t &polling_period)=0
 <<extension>> Retrieves the frequency used by the DNS tracker thread to query the DNS service. More...
 
virtual DDS_ReturnCode_t set_dns_tracker_polling_period (const DDS_Duration_t &polling_period)=0
 <<extension>> Configures the frequency in which the DNS tracker queries the DNS service. More...
 
virtual DDS_ReturnCode_t set_listener (DDSDomainParticipantListener *l, DDS_StatusMask mask=DDS_STATUS_MASK_ALL)=0
 Sets the participant listener. More...
 
virtual DDSDomainParticipantListenerget_listener ()=0
 Get the participant listener. More...
 
virtual DDSPublisherget_implicit_publisher ()=0
 <<extension>> Returns the implicit DDSPublisher. If an implicit Publisher does not already exist, this creates one. More...
 
virtual DDSSubscriberget_implicit_subscriber ()=0
 <<extension>> Returns the implicit DDSSubscriber. If an implicit Subscriber does not already exist, this creates one. More...
 
virtual DDSDataWritercreate_datawriter (DDSTopic *topic, const DDS_DataWriterQos &qos, DDSDataWriterListener *listener, DDS_StatusMask mask)=0
 <<extension>> Creates a DDSDataWriter that will be attached and belong to the implicit DDSPublisher. More...
 
virtual DDSDataWritercreate_datawriter_with_profile (DDSTopic *topic, const char *library_name, const char *profile_name, DDSDataWriterListener *listener, DDS_StatusMask mask)=0
 <<extension>> Creates a DDSDataWriter using a XML QoS profile that will be attached and belong to the implicit DDSPublisher. More...
 
virtual DDS_ReturnCode_t delete_datawriter (DDSDataWriter *a_datawriter)=0
 <<extension>> Deletes a DDSDataWriter that belongs to the implicit DDSPublisher. More...
 
virtual DDSDataReadercreate_datareader (DDSTopicDescription *topic, const DDS_DataReaderQos &qos, DDSDataReaderListener *listener, DDS_StatusMask mask)=0
 <<extension>> Creates a DDSDataReader that will be attached and belong to the implicit DDSSubscriber. More...
 
virtual DDSDataReadercreate_datareader_with_profile (DDSTopicDescription *topic, const char *library_name, const char *profile_name, DDSDataReaderListener *listener, DDS_StatusMask mask)=0
 <<extension>> Creates a DDSDataReader using a XML QoS profile that will be attached and belong to the implicit DDSSubscriber. More...
 
virtual DDS_ReturnCode_t delete_datareader (DDSDataReader *a_datareader)=0
 <<extension>> Deletes a DDSDataReader that belongs to the implicit DDSSubscriber. More...
 
virtual DDSPublisherlookup_publisher_by_name (const char *publisher_name)=0
 <<extension>> Looks up a DDSPublisher by its entity name within this DDSDomainParticipant. More...
 
virtual DDSSubscriberlookup_subscriber_by_name (const char *subscriber_name)=0
 <<extension>> Retrieves a DDSSubscriber by its entity name within this DDSDomainParticipant. More...
 
virtual DDSDataWriterlookup_datawriter_by_name (const char *datawriter_full_name)=0
 <<extension>> Looks up a DDSDataWriter by its entity name within this DDSDomainParticipant. More...
 
virtual DDSDataReaderlookup_datareader_by_name (const char *datareader_full_name)=0
 <<extension>> Retrieves up a DDSDataReader by its entity name in this DDSDomainParticipant. More...
 
virtual DDS_ReturnCode_t take_discovery_snapshot ()=0
 Take a snapshot of the remote participants discovered by a local one. More...
 
virtual DDS_ReturnCode_t take_discovery_snapshot (const char *file_name)=0
 Take a snapshot of the remote participants discovered by a local one. More...
 
- Public Member Functions inherited from DDSEntity
virtual DDS_ReturnCode_t enable ()=0
 Enables the DDSEntity. More...
 
virtual DDSStatusConditionget_statuscondition ()=0
 Allows access to the DDSStatusCondition associated with the DDSEntity. More...
 
virtual DDS_StatusMask get_status_changes ()=0
 Retrieves the list of communication statuses in the DDSEntity that are triggered. More...
 
virtual DDS_InstanceHandle_t get_instance_handle ()=0
 Allows access to the DDS_InstanceHandle_t associated with the DDSEntity. More...
 

Detailed Description

<<interface>> Container for all DDSDomainEntity objects.

The DomainParticipant object plays several roles:

  • It acts as a container for all other DDSEntity objects.
  • It 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.

The following operations may be called even if the DDSDomainParticipant is not enabled. Operations NOT in this list will fail with DDS_RETCODE_NOT_ENABLED \ if called on a disabled DomainParticipant.

QoS:
DDS_DomainParticipantQos
Status:
Status Kinds
Listener:
DDSDomainParticipantListener
See also
Operations Allowed in Listener Callbacks
Examples
HelloWorld_publisher.cxx, and HelloWorld_subscriber.cxx.

Member Function Documentation

◆ get_default_datawriter_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_default_datawriter_qos ( DDS_DataWriterQos qos)
pure virtual

<<extension>> Copy the default DDS_DataWriterQos values into the provided DDS_DataWriterQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDSDomainParticipant::set_default_datawriter_qos, or DDSDomainParticipant::set_default_datawriter_qos_with_profile, or else, if the call was never made, the default values listed in DDS_DataWriterQos.

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 DataWriterQoS from a DomainPartipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_datawriter_qos.
Parameters
qos<<inout>> Qos to be filled up.
Exceptions
Oneof the Standard Return Codes

◆ set_default_datawriter_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_datawriter_qos ( const DDS_DataWriterQos qos)
pure virtual

<<extension>> Set the default DataWriterQos values for this DomainParticipant.

This set of default values will be inherited for a newly created DDSPublisher.

Precondition
The specified QoS policies 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 set the default DataWriter QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_datawriter_qos or DDSDomainParticipant::get_default_datawriter_qos or calling DDSDomainParticipant::create_datawriter with DDS_DATAWRITER_QOS_DEFAULT as the qos parameter.
Parameters
qos<<in>> Default qos to be set. The special value DDS_DATAWRITER_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 DDSDomainParticipant::set_default_datawriter_qos had never been called.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ set_default_datawriter_qos_with_profile()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_datawriter_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Set the default DDS_DataWriterQos values for this domain participant based on the input XML QoS profile.

This set of default values will be inherited for a newly created DDSPublisher.

Precondition
The DDS_DataWriterQos 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 set the default DataWriter QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_datawriter_qos or DDSDomainParticipant::get_default_datawriter_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 DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).

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

Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ get_default_datareader_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_default_datareader_qos ( DDS_DataReaderQos qos)
pure virtual

<<extension>> Copy the default DDS_DataReaderQos values into the provided DDS_DataReaderQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDSDomainParticipant::set_default_datareader_qos, or DDSDomainParticipant::set_default_datareader_qos_with_profile, or else, if the call was never made, the default values listed in DDS_DataReaderQos.

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 DataReader QoS from a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_datareader_qos.
Parameters
qos<<inout>> Qos to be filled up.
Exceptions
Oneof the Standard Return Codes

◆ set_default_datareader_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_datareader_qos ( const DDS_DataReaderQos qos)
pure virtual

<<extension>> Set the default DDS_DataReaderQos values for this domain participant.

This set of default values will be inherited for a newly created DDSSubscriber.

Precondition
The specified QoS policies 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 set the default DataReader QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_datareader_qos or DDSDomainParticipant::get_default_datareader_qos.
Parameters
qos<<in>> Default qos to be set. The special value DDS_DATAREADER_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 DDSDomainParticipant::set_default_datareader_qos had never been called.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ set_default_datareader_qos_with_profile()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_datareader_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Set the default DDS_DataReaderQos values for this DomainParticipant based on the input XML QoS profile.

This set of default values will be inherited for a newly created DDSSubscriber.

Precondition
The DDS_DataReaderQos 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 set the default DataReader QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_datareader_qos or DDSDomainParticipant::get_default_datareader_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 DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).

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

Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ get_default_flowcontroller_property()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_default_flowcontroller_property ( DDS_FlowControllerProperty_t prop)
pure virtual

<<extension>> Copies the default DDS_FlowControllerProperty_t values for this domain participant into the given DDS_FlowControllerProperty_t instance.

The retrieved property will match the set of values specified on the last successful call to DDSDomainParticipant::set_default_flowcontroller_property, or else, if the call was never made, the default values listed in DDS_FlowControllerProperty_t.

MT Safety:
UNSAFE. It is not safe to retrieve the default flow controller properties from a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_flowcontroller_property
Parameters
prop<<in>> Default property to be retrieved.
Exceptions
Oneof the Standard Return Codes
See also
DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT
DDSDomainParticipant::create_flowcontroller

◆ set_default_flowcontroller_property()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_flowcontroller_property ( const DDS_FlowControllerProperty_t prop)
pure virtual

<<extension>> Set the default DDS_FlowControllerProperty_t values for this domain participant.

This default value will be used for newly created DDSFlowController if DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT is specified as the property parameter when DDSDomainParticipant::create_flowcontroller is called.

Precondition
The specified property values 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 set the default flow controller properties for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_flowcontroller_property , DDSDomainParticipant::get_default_flowcontroller_property or calling DDSDomainParticipant::create_flowcontroller with DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT as the qos parameter.
Parameters
prop<<in>> Default property to be set. The special value DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT may be passed as property to indicate that the default property should be reset to the default values the factory would use if DDSDomainParticipant::set_default_flowcontroller_property had never been called.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT
DDSDomainParticipant::create_flowcontroller

◆ register_contentfilter()

virtual DDS_ReturnCode_t DDSDomainParticipant::register_contentfilter ( const char *  filter_name,
const DDSContentFilter contentfilter 
)
pure virtual

<<extension>> Register a content filter which can be used to create a DDSContentFilteredTopic.

DDS specifies a SQL-like content filter for use by content filtered topics. If this filter does not meet your filtering requirements, you can register a custom filter.

To use a custom filter, it must be registered in the following places:

  • In any application that uses the custom filter to create a DDSContentFilteredTopic and the corresponding DDSDataReader.
  • In each application that writes the data to the applications mentioned above.

For example, suppose Application A on the subscription side creates a Topic named X and a ContentFilteredTopic named filteredX (and a corresponding DataReader), using a previously registered content filter, myFilter. With only that, you will have filtering at the subscription side. If you also want to perform filtering in any application that publishes Topic X, then you also need to register the same definition of the ContentFilter myFilter in that application.

Each filter_name can only be used to registered a content filter once with a DDSDomainParticipant.

Parameters
filter_name<<in>> Name of the filter. The name must be unique within the DDSDomainParticipant and must not exceed 255 characters. Cannot be NULL.
contentfilter<<in>> Content filter to be registered. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes
See also
DDSDomainParticipant::unregister_contentfilter

◆ lookup_contentfilter()

virtual DDSContentFilter * DDSDomainParticipant::lookup_contentfilter ( const char *  filter_name)
pure virtual

<<extension>> Lookup a content filter previously registered with DDSDomainParticipant::register_contentfilter.

Parameters
filter_name<<in>> Name of the filter. Cannot be NULL.
Returns
NULL if the given filter_name has not been previously registered to the DDSDomainParticipant with DDSDomainParticipant::register_contentfilter. Otherwise, return the DDSContentFilter that has been previosuly registered with the given filter_name.
See also
DDSDomainParticipant::register_contentfilter

◆ unregister_contentfilter()

virtual DDS_ReturnCode_t DDSDomainParticipant::unregister_contentfilter ( const char *  filter_name)
pure virtual

<<extension>> Unregister a content filter previously registered with DDSDomainParticipant::register_contentfilter.

A filter_name can be unregistered only if it has been previously registered to the DDSDomainParticipant with DDSDomainParticipant::register_contentfilter.

The unregistration of filter is not allowed if there are any existing DDSContentFilteredTopic objects that are using the filter. If the operation is called on a filter with existing DDSContentFilteredTopic objects attached to it, this operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

If there are still existing discovered DDSDataReader s with the same filter_name and the filter's compile method of the filter have previously been called on the discovered DDSDataReader s, finalize method of the filter will be called on those discovered DDSDataReader s before the content filter is unregistered. This means filtering will now be performed on the application that is creating the DDSDataReader.

Parameters
filter_name<<in>> Name of the filter. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET
See also
DDSDomainParticipant::register_contentfilter

◆ get_default_library()

virtual const char * DDSDomainParticipant::get_default_library ( )
pure virtual

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

Returns
The default library or null if the default library was not set.
See also
DDSDomainParticipant::set_default_library

◆ get_default_profile()

virtual const char * DDSDomainParticipant::get_default_profile ( )
pure virtual

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

Returns
The default profile or null if the default profile was not set.
See also
DDSDomainParticipant::set_default_profile

◆ get_default_profile_library()

virtual const char * DDSDomainParticipant::get_default_profile_library ( )
pure virtual

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

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

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

Returns
The default profile library or null if the default profile was not set.
See also
DDSDomainParticipant::set_default_profile

◆ set_default_library()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_library ( const char *  library_name)
pure virtual

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

This method specifies the library that will be used as the default the next time a default library is needed during a call to one of this DomainParticipant's operations.

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

If the default library is not set, the DDSDomainParticipant inherits the default from the DDSDomainParticipantFactory (see DDSDomainParticipantFactory::set_default_library).

Parameters
library_name<<in>> Library name. If library_name is null any previous default is unset.
Exceptions
Oneof the Standard Return Codes
See also
DDSDomainParticipant::get_default_library

◆ set_default_profile()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

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

This method specifies the profile that will be used as the default the next time a default DomainParticipant profile is needed during a call to one of this DomainParticipant's operations. When calling a DDSDomainParticipant 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.)

If the default profile is not set, the DDSDomainParticipant inherits the default from the DDSDomainParticipantFactory (see DDSDomainParticipantFactory::set_default_profile).

This method does not set the default QoS for entities created by the DDSDomainParticipant; for this functionality, use the methods set_default_<entity>_qos_with_profile (you may pass in NULL after having called set_default_profile()).

This method does not set the default QoS for newly created DomainParticipants; for this functionality, use DDSDomainParticipantFactory::set_default_participant_qos_with_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.
Exceptions
Oneof the Standard Return Codes
See also
DDSDomainParticipant::get_default_profile
DDSDomainParticipant::get_default_profile_library

◆ get_default_topic_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_default_topic_qos ( DDS_TopicQos qos)
pure virtual

Copies the default DDS_TopicQos values for this domain participant into the given DDS_TopicQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDSDomainParticipant::set_default_topic_qos, or DDSDomainParticipant::set_default_topic_qos_with_profile or else, if the call was never made, the default values listed in DDS_TopicQos.

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 Topic QoS from a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_topic_qos
Parameters
qos<<in>> Default qos to be retrieved.
Exceptions
Oneof the Standard Return Codes
See also
DDS_TOPIC_QOS_DEFAULT
DDSDomainParticipant::create_topic

◆ set_default_topic_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_topic_qos ( const DDS_TopicQos qos)
pure virtual

Set the default DDS_TopicQos values for this domain participant.

This default value will be used for newly created DDSTopic if DDS_TOPIC_QOS_DEFAULT is specified as the qos parameter when DDSDomainParticipant::create_topic is called.

Precondition
The specified QoS policies 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 set the default topic QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_topic_qos, DDSDomainParticipant::get_default_topic_qos or calling DDSDomainParticipant::create_topic with DDS_TOPIC_QOS_DEFAULT as the qos parameter.
Parameters
qos<<in>> Default qos to be set. The special value DDS_TOPIC_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 DDSDomainParticipant::set_default_topic_qos had never been called.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_TOPIC_QOS_DEFAULT
DDSDomainParticipant::create_topic

◆ set_default_topic_qos_with_profile()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_topic_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Set the default DDS_TopicQos values for this domain participant based on the input XML QoS profile.

This default value will be used for newly created DDSTopic if DDS_TOPIC_QOS_DEFAULT is specified as the qos parameter when DDSDomainParticipant::create_topic is called.

Precondition
The DDS_TopicQos 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 set the default topic QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_topic_qos, DDSDomainParticipant::get_default_topic_qos or calling DDSDomainParticipant::create_topic with DDS_TOPIC_QOS_DEFAULT as the qos parameter.
Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).

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

Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_TOPIC_QOS_DEFAULT
DDSDomainParticipant::create_topic_with_profile

◆ get_default_publisher_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_default_publisher_qos ( DDS_PublisherQos qos)
pure virtual

Copy the default DDS_PublisherQos values into the provided DDS_PublisherQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDSDomainParticipant::set_default_publisher_qos, or DDSDomainParticipant::set_default_publisher_qos_with_profile, or else, if the call was never made, the default values listed in DDS_PublisherQos.

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

If DDS_PUBLISHER_QOS_DEFAULT is specified as the qos parameter when DDSDomainParticipant::create_topic is called, the default value of the QoS set in the factory, equivalent to the value obtained by calling DDSDomainParticipant::get_default_publisher_qos, will be used to create the DDSPublisher.

MT Safety:
UNSAFE. It is not safe to retrieve the default publisher QoS from a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_publisher_qos
Parameters
qos<<inout>> Qos to be filled up.
Exceptions
Oneof the Standard Return Codes
See also
DDS_PUBLISHER_QOS_DEFAULT
DDSDomainParticipant::create_publisher

◆ set_default_publisher_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_publisher_qos ( const DDS_PublisherQos qos)
pure virtual

Set the default DDS_PublisherQos values for this DomainParticipant.

This set of default values will be used for a newly created DDSPublisher if DDS_PUBLISHER_QOS_DEFAULT is specified as the qos parameter when DDSDomainParticipant::create_publisher is called.

Precondition
The specified QoS policies 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 set the default publisher QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_publisher_qos, DDSDomainParticipant::get_default_publisher_qos or calling DDSDomainParticipant::create_publisher with DDS_PUBLISHER_QOS_DEFAULT as the qos parameter.
Parameters
qos<<in>> Default qos to be set. The special value DDS_PUBLISHER_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 DDSDomainParticipant::set_default_publisher_qos had never been called.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_PUBLISHER_QOS_DEFAULT
DDSDomainParticipant::create_publisher

◆ set_default_publisher_qos_with_profile()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_publisher_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Set the default DDS_PublisherQos values for this DomainParticipant based on the input XML QoS profile.

This set of default values will be used for a newly created DDSPublisher if DDS_PUBLISHER_QOS_DEFAULT is specified as the qos parameter when DDSDomainParticipant::create_publisher is called.

Precondition
The DDS_PublisherQos 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 set the default publisher QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_publisher_qos, DDSDomainParticipant::get_default_publisher_qos or calling DDSDomainParticipant::create_publisher with DDS_PUBLISHER_QOS_DEFAULT as the qos parameter.
Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).

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

Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_PUBLISHER_QOS_DEFAULT
DDSDomainParticipant::create_publisher_with_profile

◆ get_default_subscriber_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_default_subscriber_qos ( DDS_SubscriberQos qos)
pure virtual

Copy the default DDS_SubscriberQos values into the provided DDS_SubscriberQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDSDomainParticipant::set_default_subscriber_qos, or DDSDomainParticipant::set_default_subscriber_qos_with_profile, or else, if the call was never made, the default values listed in DDS_SubscriberQos.

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

If DDS_SUBSCRIBER_QOS_DEFAULT is specified as the qos parameter when DDSDomainParticipant::create_subscriber is called, the default value of the QoS set in the factory, equivalent to the value obtained by calling DDSDomainParticipant::get_default_subscriber_qos, will be used to create the DDSSubscriber.

MT Safety:
UNSAFE. It is not safe to retrieve the default Subscriber QoS from a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_subscriber_qos.
Parameters
qos<<inout>> Qos to be filled up.
Exceptions
Oneof the Standard Return Codes
See also
DDS_SUBSCRIBER_QOS_DEFAULT
DDSDomainParticipant::create_subscriber

◆ set_default_subscriber_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_subscriber_qos ( const DDS_SubscriberQos qos)
pure virtual

Set the default DDS_SubscriberQos values for this DomainParticipant.

This set of default values will be used for a newly created DDSSubscriber if DDS_SUBSCRIBER_QOS_DEFAULT is specified as the qos parameter when DDSDomainParticipant::create_subscriber is called.

Precondition
The specified QoS policies 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 set the default Subscriber QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_subscriber_qos, DDSDomainParticipant::get_default_subscriber_qos or calling DDSDomainParticipant::create_subscriber with DDS_SUBSCRIBER_QOS_DEFAULT as the qos parameter.
Parameters
qos<<in>> Default qos to be set. The special value DDS_SUBSCRIBER_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 DDSDomainParticipant::set_default_subscriber_qos had never been called.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ set_default_subscriber_qos_with_profile()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_default_subscriber_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Set the default DDS_SubscriberQos values for this DomainParticipant based on the input XML QoS profile.

This set of default values will be used for a newly created DDSSubscriber if DDS_SUBSCRIBER_QOS_DEFAULT is specified as the qos parameter when DDSDomainParticipant::create_subscriber is called.

Precondition
The DDS_SubscriberQos 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 set the default Subscriber QoS for a DomainParticipant while another thread may be simultaneously calling DDSDomainParticipant::set_default_subscriber_qos, DDSDomainParticipant::get_default_subscriber_qos or calling DDSDomainParticipant::create_subscriber with DDS_SUBSCRIBER_QOS_DEFAULT as the qos parameter.
Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).

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

Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_SUBSCRIBER_QOS_DEFAULT
DDSDomainParticipant::create_subscriber_with_profile

◆ create_publisher()

virtual DDSPublisher * DDSDomainParticipant::create_publisher ( const DDS_PublisherQos qos,
DDSPublisherListener listener,
DDS_StatusMask  mask 
)
pure virtual

Creates a DDSPublisher with the desired QoS policies and attaches to it the specified DDSPublisherListener.

Precondition
The specified QoS policies must be consistent, or the operation will fail and no DDSPublisher will be created.
MT Safety:
UNSAFE. If DDS_PUBLISHER_QOS_DEFAULT is used for qos, it is not safe to create the publisher while another thread may be simultaneously calling DDSDomainParticipant::set_default_publisher_qos.
Parameters
qos<<in>> QoS to be used for creating the new DDSPublisher. The special value DDS_PUBLISHER_QOS_DEFAULT can be used to indicate that the DDSPublisher should be created with the default DDS_PublisherQos set in the DDSDomainParticipant.
listener<<in>>. Listener to be attached to the newly created DDSPublisher.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created publisher object or NULL on failure.
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_PublisherQos for rules on consistency among QoS
DDS_PUBLISHER_QOS_DEFAULT
DDSDomainParticipant::create_publisher_with_profile
DDSDomainParticipant::get_default_publisher_qos
DDSPublisher::set_listener
Examples
HelloWorld_publisher.cxx.

◆ create_publisher_with_profile()

virtual DDSPublisher * DDSDomainParticipant::create_publisher_with_profile ( const char *  library_name,
const char *  profile_name,
DDSPublisherListener listener,
DDS_StatusMask  mask 
)
pure virtual

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

Precondition
The DDS_PublisherQos in the input profile must be consistent, or the operation will fail and no DDSPublisher will be created.
Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).
listener<<in>>. Listener to be attached to the newly created DDSPublisher.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created publisher object or NULL on failure.
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_PublisherQos for rules on consistency among QoS
DDSDomainParticipant::create_publisher
DDSDomainParticipant::get_default_publisher_qos
DDSPublisher::set_listener

◆ delete_publisher()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_publisher ( DDSPublisher p)
pure virtual

Deletes an existing DDSPublisher.

Precondition
The DDSPublisher must not have any attached DDSDataWriter objects. If there are existing DDSDataWriter objects, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
DDSPublisher must have been created by this DDSDomainParticipant, or else it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the DDSPublisher will not be called after this method completes 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
p<<in>> DDSPublisher to be deleted.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

◆ create_subscriber()

virtual DDSSubscriber * DDSDomainParticipant::create_subscriber ( const DDS_SubscriberQos qos,
DDSSubscriberListener listener,
DDS_StatusMask  mask 
)
pure virtual

Creates a DDSSubscriber with the desired QoS policies and attaches to it the specified DDSSubscriberListener.

Precondition
The specified QoS policies must be consistent, or the operation will fail and no DDSSubscriber will be created.
MT Safety:
UNSAFE. If DDS_SUBSCRIBER_QOS_DEFAULT is used for qos, it is not safe to create the subscriber while another thread may be simultaneously calling DDSDomainParticipant::set_default_subscriber_qos.
Parameters
qos<<in>> QoS to be used for creating the new DDSSubscriber. The special value DDS_SUBSCRIBER_QOS_DEFAULT can be used to indicate that the DDSSubscriber should be created with the default DDS_SubscriberQos set in the DDSDomainParticipant.
listener<<in>>. Listener to be attached to the newly created DDSSubscriber.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created subscriber object or NULL on failure.
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_SubscriberQos for rules on consistency among QoS
DDS_SUBSCRIBER_QOS_DEFAULT
DDSDomainParticipant::create_subscriber_with_profile
DDSDomainParticipant::get_default_subscriber_qos
DDSSubscriber::set_listener
Examples
HelloWorld_subscriber.cxx.

◆ create_subscriber_with_profile()

virtual DDSSubscriber * DDSDomainParticipant::create_subscriber_with_profile ( const char *  library_name,
const char *  profile_name,
DDSSubscriberListener listener,
DDS_StatusMask  mask 
)
pure virtual

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

Precondition
The DDS_SubscriberQos in the input profile must be consistent, or the operation will fail and no DDSSubscriber will be created.
Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).
listener<<in>>. Listener to be attached to the newly created DDSSubscriber.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created subscriber object or NULL on failure.
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_SubscriberQos for rules on consistency among QoS
DDSDomainParticipant::create_subscriber
DDSDomainParticipant::get_default_subscriber_qos
DDSSubscriber::set_listener

◆ delete_subscriber()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_subscriber ( DDSSubscriber s)
pure virtual

Deletes an existing DDSSubscriber.

Precondition
The DDSSubscriber must not have any attached DDSDataReader objects. If there are existing DDSDataReader objects, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET
The DDSSubscriber must have been created by this DDSDomainParticipant, or else it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
A Listener installed on the DDSSubscriber will not be called after this method completes 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
s<<in>> DDSSubscriber to be deleted.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

◆ get_publishers()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_publishers ( DDSPublisherSeq publishers)
pure virtual

<<extension>> Allows the application to access all the publishers the participant has.

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

MT Safety:
Safe.
Parameters
publishers<<inout>> a PublisherSeq object where the set or list of publishers will be returned
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES

◆ get_subscribers()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_subscribers ( DDSSubscriberSeq subscribers)
pure virtual

<<extension>> Allows the application to access all the subscribers the participant has.

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

MT Safety:
Safe.
Parameters
subscribers<<inout>> a SubscriberSeq object where the set or list of subscribers will be returned
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES

◆ create_topic()

virtual DDSTopic * DDSDomainParticipant::create_topic ( const char *  topic_name,
const char *  type_name,
const DDS_TopicQos qos,
DDSTopicListener listener,
DDS_StatusMask  mask 
)
pure virtual

Creates a DDSTopic with the desired QoS policies and attaches to it the specified DDSTopicListener.

Precondition
The application is not allowed to create two DDSTopic objects with the same topic_name attached to the same DDSDomainParticipant. If the application attempts this, this method will fail and return a NULL topic.
The specified QoS policies must be consistent, or the operation will fail and no DDSTopic will be created.
Prior to creating a DDSTopic, the type must have been registered with RTI Connext. This is done using the FooTypeSupport::register_type operation on a derived class of the DDSTypeSupport interface.
MT Safety:
UNSAFE. It is not safe to create a topic while another thread is trying to lookup that topic description with DDSDomainParticipant::lookup_topicdescription.
MT Safety:
UNSAFE. If DDS_TOPIC_QOS_DEFAULT is used for qos, it is not safe to create the topic while another thread may be simultaneously calling DDSDomainParticipant::set_default_topic_qos.
Parameters
topic_name<<in>> Name for the new topic, must not exceed 255 characters. Cannot be NULL.
type_name<<in>> The type to which the new DDSTopic will be bound. Cannot be NULL.
qos<<in>> QoS to be used for creating the new DDSTopic. The special value DDS_TOPIC_QOS_DEFAULT can be used to indicate that the DDSTopic should be created with the default DDS_TopicQos set in the DDSDomainParticipant.
listener<<in>>. Listener to be attached to the newly created DDSTopic.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created topic, or NULL on failure
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_TopicQos for rules on consistency among QoS
DDS_TOPIC_QOS_DEFAULT
DDSDomainParticipant::create_topic_with_profile
DDSDomainParticipant::get_default_topic_qos
DDSTopic::set_listener
Examples
HelloWorld_publisher.cxx, and HelloWorld_subscriber.cxx.

◆ create_topic_with_profile()

virtual DDSTopic * DDSDomainParticipant::create_topic_with_profile ( const char *  topic_name,
const char *  type_name,
const char *  library_name,
const char *  profile_name,
DDSTopicListener listener,
DDS_StatusMask  mask 
)
pure virtual

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

Precondition
The application is not allowed to create two DDSTopicDescription objects with the same topic_name attached to the same DDSDomainParticipant. If the application attempts this, this method will fail and return a NULL topic.
The DDS_TopicQos in the input profile must be consistent, or the operation will fail and no DDSTopic will be created.
Prior to creating a DDSTopic, the type must have been registered with RTI Connext. This is done using the FooTypeSupport::register_type operation on a derived class of the DDSTypeSupport interface.
MT Safety:
UNSAFE. It is not safe to create a topic while another thread is trying to lookup that topic description with DDSDomainParticipant::lookup_topicdescription.
Parameters
topic_name<<in>> Name for the new topic, must not exceed 255 characters. Cannot be NULL.
type_name<<in>> The type to which the new DDSTopic will be bound. 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 DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).
listener<<in>>. Listener to be attached to the newly created DDSTopic.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created topic, or NULL on failure
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_TopicQos for rules on consistency among QoS
DDSDomainParticipant::create_topic
DDSDomainParticipant::get_default_topic_qos
DDSTopic::set_listener

◆ delete_topic()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_topic ( DDSTopic topic)
pure virtual

Deletes a DDSTopic.

Precondition
If the DDSTopic does not belong to the application's DDSDomainParticipant, this operation fails with DDS_RETCODE_PRECONDITION_NOT_MET.
Make sure no objects are using the topic. More specifically, there must be no existing DDSDataReader, DDSDataWriter, DDSContentFilteredTopic, or DDSMultiTopic objects belonging to the same DDSDomainParticipant that are using the DDSTopic. If delete_topic is called on a DDSTopic with any of these existing objects attached to it, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the DDSTopic will not be called after this method completes 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
topic<<in>> DDSTopic to be deleted.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

◆ create_contentfilteredtopic()

virtual DDSContentFilteredTopic * DDSDomainParticipant::create_contentfilteredtopic ( const char *  name,
DDSTopic related_topic,
const char *  filter_expression,
const DDS_StringSeq expression_parameters 
)
pure virtual

Creates a DDSContentFilteredTopic, that can be used to do content-based subscriptions.

The DDSContentFilteredTopic only relates to samples published under that DDSTopic, filtered according to their content. The filtering is done by means of evaluating a logical expression that involves the values of some of the data-fields in the sample. The logical expression derived from the filter_expression and expression_parameters arguments.

Queries and Filters Syntax describes the syntax of filter_expression and expression_parameters.

Precondition
The application is not allowed to create two DDSContentFilteredTopic objects with the same topic_name attached to the same DDSDomainParticipant. If the application attempts this, this method will fail and returns NULL.
If related_topic does not belong to this DDSDomainParticipant, this operation returns NULL.
This function will create a content filter using the builtin SQL filter which implements a superset of the DDS specification. This filter requires that all IDL types have been compiled with typecodes. If this precondition is not met, this operation returns NULL.
Parameters
name<<in>> Name for the new content filtered topic, must not exceed 255 characters. Cannot be NULL.
related_topic<<in>> DDSTopic to be filtered. Cannot be NULL.
filter_expression<<in>> Cannot be NULL
expression_parameters<<in>> An empty sequence must be used if the filter expression does not contain any parameters. Length of sequence cannot be greater than 100.
Returns
newly created DDSContentFilteredTopic, or NULL on failure

◆ create_contentfilteredtopic_with_filter()

virtual DDSContentFilteredTopic * DDSDomainParticipant::create_contentfilteredtopic_with_filter ( const char *  name,
DDSTopic related_topic,
const char *  filter_expression,
const DDS_StringSeq expression_parameters,
const char *  filter_name = DDS_SQLFILTER_NAME 
)
pure virtual

<<extension>> Creates a DDSContentFilteredTopic using the specified filter to do content-based subscriptions.

Parameters
name<<in>> Name for the new content filtered topic. Cannot exceed 255 characters. Cannot be NULL.
related_topic<<in>> DDSTopic to be filtered. Cannot be NULL.
filter_expression<<in>> Cannot be NULL.
expression_parameters<<in>> . An empty sequence must be used if the filter expression does not contain any parameters. Length of the sequence cannot be greater than 100.
filter_name<<in>> Name of content filter to use. Must previously have been registered with DDSDomainParticipant::register_contentfilter on the same DDSDomainParticipant. Cannot be NULL. Builtin filter names are DDS_SQLFILTER_NAME and DDS_STRINGMATCHFILTER_NAME
Returns
newly created DDSContentFilteredTopic, or NULL on failure

◆ delete_contentfilteredtopic()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_contentfilteredtopic ( DDSContentFilteredTopic a_contentfilteredtopic)
pure virtual

Deletes a DDSContentFilteredTopic.

Precondition
The deletion of a DDSContentFilteredTopic is not allowed if there are any existing DDSDataReader objects that are using the DDSContentFilteredTopic. If the operation is called on a DDSContentFilteredTopic with existing DDSDataReader objects attached to it, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
The DDSContentFilteredTopic must be created by this DDSDomainParticipant, or else this operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
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_contentfilteredtopic<<in>>
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET

◆ create_multitopic()

virtual DDSMultiTopic * DDSDomainParticipant::create_multitopic ( const char *  name,
const char *  type_name,
const char *  subscription_expression,
const DDS_StringSeq expression_parameters 
)
pure virtual

[Not supported (optional)] Creates a MultiTopic that can be used to subscribe to multiple topics and combine/filter the received data into a resulting type.

The resulting type is specified by the type_name argument. The list of topics and the logic used to combine, filter, and rearrange the information from each DDSTopic are specified using the subscription_expression and expression_parameters arguments.

Queries and Filters Syntax describes the syntax of subscription_expression and expression_parameters.

Precondition
The application is not allowed to create two DDSTopicDescription objects with the same name attached to the same DDSDomainParticipant. If the application attempts this, this method will fail and return NULL.
Prior to creating a DDSMultiTopic, the type must have been registered with RTI Connext. This is done using the FooTypeSupport::register_type operation on a derived class of the DDSTypeSupport interface. Otherwise, this method will return NULL.
Parameters
name<<in>> Name of the newly create DDSMultiTopic. Cannot be NULL.
type_name<<in>> Cannot be NULL.
subscription_expression<<in>> Cannot be NULL.
expression_parameters<<in>>
Returns
NULL

◆ delete_multitopic()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_multitopic ( DDSMultiTopic a_multitopic)
pure virtual

[Not supported (optional)] Deletes a DDSMultiTopic.

Precondition
The deletion of a DDSMultiTopic is not allowed if there are any existing DDSDataReader objects that are using the DDSMultiTopic. If the delete_multitopic operation is called on a DDSMultiTopic with existing DDSDataReader objects attached to it, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
The DDSMultiTopic must be created by this DDSDomainParticipant, or else this operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
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_multitopic<<in>>

◆ find_topic()

virtual DDSTopic * DDSDomainParticipant::find_topic ( const char *  topic_name,
const DDS_Duration_t timeout 
)
pure virtual

Finds an existing (or ready to exist) DDSTopic, based on its name.

This call can be used to block for a specified duration to wait for the DDSTopic to be created.

If the requested DDSTopic already exists, it is returned. Otherwise, find_topic() waits until another thread creates it or else returns when the specified timeout occurs.

find_topic() is useful when multiple threads are concurrently creating and looking up topics. In that case, one thread can call find_topic() and, if another thread has not yet created the topic being looked up, it can wait for some period of time for it to do so. In almost all other cases, it is more straightforward to call DDSDomainParticipant::lookup_topicdescription.

The DDSDomainParticipant must already be enabled.

Note: Each DDSTopic obtained by DDSDomainParticipant::find_topic must also be deleted by means of DDSDomainParticipant::delete_topic. If DDSTopic is obtained multiple times by means of DDSDomainParticipant::find_topic or DDSDomainParticipant::create_topic, it must also be deleted that same number of times using DDSDomainParticipant::delete_topic.

Parameters
topic_name<<in>> Name of the DDSTopic to search for. Cannot be NULL.
timeout<<in>> The time to wait if the DDSTopic does not exist already.
Returns
the topic, if it exists, or NULL

◆ lookup_topicdescription()

virtual DDSTopicDescription * DDSDomainParticipant::lookup_topicdescription ( const char *  topic_name)
pure virtual

Looks up an existing, locally created DDSTopicDescription, based on its name.

DDSTopicDescription is the base class for DDSTopic, DDSMultiTopic and DDSContentFilteredTopic. So you can narrow the DDSTopicDescription returned from this operation to a DDSTopic or DDSContentFilteredTopic as appropriate.

Unlike DDSDomainParticipant::find_topic, which logically returns a new DDSTopic object that must be independently deleted, this operation returns a reference to the original local object.

The DDSDomainParticipant does not have to be enabled when you call lookup_topicdescription().

The returned topic may be either enabled or disabled.

MT Safety:
UNSAFE. It is not safe to lookup a topic description while another thread is creating that topic.
Parameters
topic_name<<in>> Name of DDSTopicDescription to search for. This string must be no more than 255 characters; it cannot be NULL.
Returns
The topic description, if it has already been created locally, otherwise it returns NULL.

◆ create_flowcontroller()

virtual DDSFlowController * DDSDomainParticipant::create_flowcontroller ( const char *  name,
const DDS_FlowControllerProperty_t prop 
)
pure virtual

<<extension>> Creates a DDSFlowController with the desired property.

The created DDSFlowController is associated with a DDSDataWriter via DDS_PublishModeQosPolicy::flow_controller_name. A single FlowController may service multiple DataWriters instances, even if they belong to a different DDSPublisher. The property determines how the FlowController shapes the network traffic.

Precondition
The specified property must be consistent, or the operation will fail and no DDSFlowController will be created.
MT Safety:
UNSAFE. If DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT is used for property, it is not safe to create the flow controller while another thread may be simultaneously calling DDSDomainParticipant::set_default_flowcontroller_property or trying to lookup that flow controller with DDSDomainParticipant::lookup_flowcontroller.
Parameters
name<<in>> name of the DDSFlowController to create. A DDSDataWriter is associated with a DDSFlowController by name. Limited to 255 characters.
prop<<in>> property to be used for creating the new DDSFlowController. The special value DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT can be used to indicate that the DDSFlowController should be created with the default DDS_FlowControllerProperty_t set in the DDSDomainParticipant.
Returns
Newly created flow controller object or NULL on failure.
See also
DDS_FlowControllerProperty_t for rules on consistency among property
DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT
DDSDomainParticipant::get_default_flowcontroller_property

◆ delete_flowcontroller()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_flowcontroller ( DDSFlowController fc)
pure virtual

<<extension>> Deletes an existing DDSFlowController.

Precondition
The DDSFlowController must not have any attached DDSDataWriter objects. If there are any attached DDSDataWriter objects, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
The DDSFlowController must have been created by this DDSDomainParticipant, or else it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
The DDSFlowController is deleted if this method completes 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
fc<<in>> The DDSFlowController to be deleted.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

◆ lookup_flowcontroller()

virtual DDSFlowController * DDSDomainParticipant::lookup_flowcontroller ( const char *  name)
pure virtual

<<extension>> Looks up an existing locally-created DDSFlowController, based on its name.

Looks up a previously created DDSFlowController, including the built-in ones. Once a DDSFlowController has been deleted, subsequent lookups will fail.

MT Safety:
UNSAFE. It is not safe to lookup a flow controller description while another thread is creating that flow controller.
Parameters
name<<in>> Name of DDSFlowController to search for. Limited to 255 characters. Cannot be NULL.
Returns
The flow controller if it has already been created locally, or NULL otherwise.

◆ get_builtin_subscriber()

virtual DDSSubscriber * DDSDomainParticipant::get_builtin_subscriber ( )
pure virtual

Accesses the built-in DDSSubscriber.

Each DDSDomainParticipant contains several built-in DDSTopic objects as well as corresponding DDSDataReader objects to access them. All of these DDSDataReader objects belong to a single built-in DDSSubscriber.

The built-in Topics are used to communicate information about other DDSDomainParticipant, DDSTopic, DDSDataReader, and DDSDataWriter objects.

The built-in subscriber is created when this operation is called for the first time. The built-in subscriber is deleted automatically when the DDSDomainParticipant is deleted.

Returns
The built-in DDSSubscriber singleton.
See also
DDS_SubscriptionBuiltinTopicData
DDS_PublicationBuiltinTopicData
DDS_ParticipantBuiltinTopicData
DDS_TopicBuiltinTopicData

◆ ignore_participant()

virtual DDS_ReturnCode_t DDSDomainParticipant::ignore_participant ( const DDS_InstanceHandle_t handle)
pure virtual

Instructs RTI Connext to locally ignore a remote DDSDomainParticipant.

From the time of this call onwards, RTI Connext will locally behave as if the remote participant did not exist. This means it will ignore any topic, publication, or subscription that originates on that DDSDomainParticipant.

There is no way to reverse this operation.

This operation can be used in conjunction with the discovery of remote participants offered by means of the DDS_ParticipantBuiltinTopicData to provide access control.

Application data can be associated with a DDSDomainParticipant by means of the USER_DATA policy. This application data is propagated as a field in the built-in topic and can be used by an application to implement its own access control policy.

The DDSDomainParticipant to ignore is identified by the handle argument. This handle is the one that appears in the DDS_SampleInfo retrieved when reading the data-samples available for the built-in DDSDataReader to the DDSDomainParticipant topic. The built-in DDSDataReader is read with the same FooDataReader::read and FooDataReader::take operations used for any DDSDataReader.

Parameters
handle<<in>> DDS_InstanceHandle_t of the DDSDomainParticipant to be ignored.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED
See also
DDS_ParticipantBuiltinTopicData
DDS_PARTICIPANT_TOPIC_NAME
DDSDomainParticipant::get_builtin_subscriber

◆ banish_ignored_participants()

virtual DDS_ReturnCode_t DDSDomainParticipant::banish_ignored_participants ( )
pure virtual

<<extension>> Prevents ignored remote DomainParticipants from receiving traffic from the local DDSDomainParticipant.

This method complements DDSDomainParticipant::ignore_participant: ignore_participant prevents the local DDSDomainParticipant from processing traffic from the remote DomainParticipant, while this method prevents already ignored remote DomainParticipants from processing traffic from the local DomainParticipant.

Note: this method is currently only supported when enabling the RTI Security Plugins. Please refer to the RTI Security Plugins User's Manual for more information.

MT Safety:
Safe.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NOT_ENABLED
See also
DDSDomainParticipant::ignore_participant

◆ ignore_topic()

virtual DDS_ReturnCode_t DDSDomainParticipant::ignore_topic ( const DDS_InstanceHandle_t handle)
pure virtual

Instructs RTI Connext to locally ignore a DDSTopic.

This means it will locally ignore any publication, or subscription to the DDSTopic.

There is no way to reverse this operation.

This operation can be used to save local resources when the application knows that it will never publish or subscribe to data under certain topics.

The DDSTopic to ignore is identified by the handle argument. This is the handle of a DDSTopic that appears in the DDS_SampleInfo retrieved when reading data samples from the built-in DDSDataReader for the DDSTopic.

Parameters
handle<<in>> Handle of the DDSTopic to be ignored.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED
See also
DDS_TopicBuiltinTopicData
DDS_TOPIC_TOPIC_NAME
DDSDomainParticipant::get_builtin_subscriber

◆ ignore_publication()

virtual DDS_ReturnCode_t DDSDomainParticipant::ignore_publication ( const DDS_InstanceHandle_t handle)
pure virtual

Instructs RTI Connext to locally ignore a publication.

A publication is defined by the association of a topic name, user data, and partition set on the DDSPublisher (see DDS_PublicationBuiltinTopicData). After this call, any data written by that publication's DDSDataWriter will be ignored.

This operation can be used to ignore local and remote DataWriters.

The publication (DataWriter) to ignore is identified by the handle argument.

  • To ignore a remote DataWriter, the handle can be obtained from the DDS_SampleInfo retrieved when reading data samples from the built-in DDSDataReader for the publication topic.

There is no way to reverse this operation.

Parameters
handle<<in>> Handle of the DDSDataWriter to be ignored.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED
See also
DDS_PublicationBuiltinTopicData
DDS_PUBLICATION_TOPIC_NAME
DDSDomainParticipant::get_builtin_subscriber

◆ ignore_subscription()

virtual DDS_ReturnCode_t DDSDomainParticipant::ignore_subscription ( const DDS_InstanceHandle_t handle)
pure virtual

Instructs RTI Connext to locally ignore a subscription.

A subscription is defined by the association of a topic name, user data, and partition set on the DDSSubscriber (see DDS_SubscriptionBuiltinTopicData). After this call, any data received related to that subscription's DDSDataReader will be ignored.

This operation can be used to ignore local and remote DataReaders.

The subscription to ignore is identified by the handle argument.

  • To ignore a remote DataReader, the handle can be obtained from the DDS_SampleInfo retrieved when reading data samples from the built-in DDSDataReader for the subscription topic.

There is no way to reverse this operation.

Parameters
handle<<in>> Handle of the DDSDataReader to be ignored.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED
See also
DDS_SubscriptionBuiltinTopicData
DDS_SUBSCRIPTION_TOPIC_NAME
DDSDomainParticipant::get_builtin_subscriber

◆ get_domain_id()

virtual DDS_DomainId_t DDSDomainParticipant::get_domain_id ( )
pure virtual

Get the unique domain identifier.

This operation retrieves the domain id used to create the DDSDomainParticipant. The domain id identifies the DDS domain to which the DDSDomainParticipant belongs. Each DDS domain represents a separate data 'communication plane' isolated from other domains.

Returns
the unique domainId that was used to create the domain
See also
DDSDomainParticipantFactory::create_participant
DDSDomainParticipantFactory::create_participant_with_profile

◆ get_current_time()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_current_time ( DDS_Time_t current_time)
pure virtual

Returns the current value of the time.

The current value of the time that RTI Connext uses to time-stamp DDSDataWriter and to set the reception-timestamp for the data updates that it receives.

Parameters
current_time<<inout>> Current time to be filled up.
Exceptions
Oneof the Standard Return Codes

◆ register_durable_subscription()

virtual DDS_ReturnCode_t DDSDomainParticipant::register_durable_subscription ( const DDS_EndpointGroup_t group,
const char *  topic_name 
)
pure virtual

<<extension>> Registers a Durable Subscription on the specified DDSTopic on all Persistence Services.

If you need to receive all samples published on a DDSTopic, including the ones published while a DDSDataReader is inactive or before it may be created, create a Durable Subscription using this method.

In this way, the Persistence Service will ensure that all the samples on that DDSTopic are retained until they are acknowledged by at least N DataReaders belonging to the Durable Subscription where N is the quorum count.

If the same Durable Subscription is created on a different DDSTopic, the Persistence Service will implicitly delete the previous Durable Subscription and create a new one on the new DDSTopic.

Parameters
group<<in>> DDS_EndpointGroup_t The Durable Subscription name and quorum.
topic_name<<in>> The topic name for which the Durable Subscription is created.
Exceptions
Oneof the Standard Return Codes

◆ delete_durable_subscription()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_durable_subscription ( const DDS_EndpointGroup_t group)
pure virtual

<<extension>> Deletes an existing Durable Subscription on all Persistence Services.

The Persistence Service will delete the Durable Subscription and the quorum of the existing samples will be considered satisfied.

Parameters
group<<in>> DDS_EndpointGroup_t specifying the Durable Subscription name. Quorum is not required for this operation.
Exceptions
Oneof the Standard Return Codes

◆ assert_liveliness()

virtual DDS_ReturnCode_t DDSDomainParticipant::assert_liveliness ( )
pure virtual

Manually asserts the liveliness of this DDSDomainParticipant.

This is used in combination with the DDS_LivelinessQosPolicy to indicate to RTI Connext that the entity remains active.

You need to use this operation if the DDSDomainParticipant contains DDSDataWriter entities with the DDS_LivelinessQosPolicy::kind set to DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS and it only affects the liveliness of those DDSDataWriter entities. Otherwise, it has no effect.

Note: writing data via the FooDataWriter::write or FooDataWriter::write_w_timestamp operation asserts liveliness on the DDSDataWriter itself and its DDSDomainParticipant. Consequently the use of assert_liveliness() is only needed if the application is not writing data regularly.

Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_NOT_ENABLED
See also
DDS_LivelinessQosPolicy

◆ resume_endpoint_discovery()

virtual DDS_ReturnCode_t DDSDomainParticipant::resume_endpoint_discovery ( const DDS_InstanceHandle_t remote_participant_handle)
pure virtual

<<extension>> Initiates endpoint discovery with the specified remote DDSDomainParticipant.

If the operation returns DDS_RETCODE_OK, the DDSDomainParticipant will initiate endpoint discovery with the remote DDSDomainParticipant provided as a parameter.

When DDS_DiscoveryQosPolicy::enable_endpoint_discovery is set to DDS_BOOLEAN_FALSE, this operation allows the RTI Connext application to select for which remote DomainParticipants endpoint discovery is performed. By disabling endpoint discovery, the DomainParticipant will not store any state about remote endpoints and will not send local endpoint information to remote DomainParticipants.

If DDS_DiscoveryQosPolicy::enable_endpoint_discovery is set to DDS_BOOLEAN_TRUE, endpoint discovery will automatically occur for every discovered DDSDomainParticipant. In this case, invoking this operation will have no effect and will return DDS_RETCODE_OK.

When DDS_DiscoveryQosPolicy::enable_endpoint_discovery is set to DDS_BOOLEAN_FALSE, you have two options after a remote DDSDomainParticipant is discovered:

Setting DDS_DiscoveryQosPolicy::enable_endpoint_discovery to DDS_BOOLEAN_FALSE enables application-level authentication use cases, in which a DDSDomainParticipant will initiate endpoint discovery with a remote DDSDomainParticipant after successful authentication at the application level.

The remote_participant_handle paremeter is the one that appears in the DDS_SampleInfo retrieved when reading the data samples available for the built-in DDSParticipantBuiltinTopicDataDataReader.

If the specified remote DDSDomainParticipant is not in the database of discovered DomainParticipants or has been previously ignored, this operation will fail with DDS_RETCODE_ERROR.

This operation can be called multiple times on the same remote participant. If endpoint discovery has already been resumed, successive calls will have no effect and will return DDS_RETCODE_OK.

Parameters
remote_participant_handle<<in>> Handle of a discovered DDSDomainParticipant for which endpoint discovery is to be resumed.
Exceptions
Oneof the Standard Return Codes,or DDS_RETCODE_NOT_ENABLED
See also
DDS_DiscoveryQosPolicy

◆ delete_contained_entities()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_contained_entities ( )
pure virtual

Delete all the entities that were created by means of the "create" operations on the DDSDomainParticipant.

This operation deletes all contained DDSPublisher (including an implicit Publisher, if one exists), DDSSubscriber (including implicit Subscriber), DDSTopic, DDSContentFilteredTopic, and DDSMultiTopic objects.

Prior to deleting each contained entity, this operation will recursively call the corresponding delete_contained_entities() operation on each contained entity (if applicable). This pattern is applied recursively. In this manner the operation delete_contained_entities() on the DDSDomainParticipant will end up recursively deleting all the entities contained in the DDSDomainParticipant, including the DDSDataWriter, DDSDataReader, as well as the DDSQueryCondition, DDSReadCondition, and DDSTopicQuery objects belonging to the contained DDSDataReader.

The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted .

If delete_contained_entities() completes successfully, the application may delete the DDSDomainParticipant.

MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Exceptions
Oneof the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.
Examples
HelloWorld_publisher.cxx, and HelloWorld_subscriber.cxx.

◆ get_discovered_participants()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_discovered_participants ( DDS_InstanceHandleSeq participant_handles)
pure virtual

Returns a list of discovered DDSDomainParticipant entities.

This operation retrieves the list of DDSDomainParticipant entities that have been discovered in the domain and that the application has not indicated should be "ignored" by means of the DDSDomainParticipant::ignore_participant operation. When using DDS_DISCOVERYCONFIG_BUILTIN_SPDP2, this list only includes DDSDomainParticipant entities that the application has received configuration information from.

Parameters
participant_handles<<inout>> DDS_InstanceHandleSeq to be filled with handles of the discovered DDSDomainParticipant entities.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ get_discovered_participants_from_subject_name()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_discovered_participants_from_subject_name ( DDS_InstanceHandleSeq participant_handles,
const char *  subject_name 
)
pure virtual

<<extension>> Returns a list of discovered DDSDomainParticipant entities that have the given DDS_EntityNameQosPolicy::name.

This operation retrieves the same list as DDSDomainParticipant::get_discovered_participants, except this list contains only the participants that have the given DDS_EntityNameQosPolicy::name.

Note: this method has different functionality when enabling the RTI Security Plugins. Please refer to the RTI Security Plugins User's Manual for more information.

MT Safety:
Safe.
Parameters
participant_handles<<inout>> DDS_InstanceHandleSeq to be filled with handles of the discovered DDSDomainParticipant entities.
subject_name<<in>> The DDS_EntityNameQosPolicy::name by which to filter the list.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ get_discovered_participant_data()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_discovered_participant_data ( struct DDS_ParticipantBuiltinTopicData participant_data,
const DDS_InstanceHandle_t participant_handle 
)
pure virtual

Returns DDS_ParticipantBuiltinTopicData for the specified DDSDomainParticipant.

This operation retrieves information on a DDSDomainParticipant that has been discovered on the network. The participant must be in the same domain as the participant on which this operation is invoked and must not have been "ignored" by means of the DDSDomainParticipant::ignore_participant operation.

The participant_handle must correspond to such a DomainParticipant. Otherwise, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

Use the operation DDSDomainParticipant::get_discovered_participants to find the DDSDomainParticipant entities that are currently discovered.

MT Safety:
Safe.
Parameters
participant_data<<inout>> DDS_ParticipantBuiltinTopicData to be filled in with the data for the specified DDSDomainParticipant.
participant_handle<<in>> DDS_InstanceHandle_t of DDSDomainParticipant.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED
See also
DDS_ParticipantBuiltinTopicData
DDSDomainParticipant::get_discovered_participants

◆ get_discovered_participant_subject_name()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_discovered_participant_subject_name ( char *  subject_name,
DDS_UnsignedLong subject_name_size,
const DDS_InstanceHandle_t participant_handle 
)
pure virtual

<<extension>> Returns DDS_EntityNameQosPolicy::name for the specified DDSDomainParticipant.

This operation retrieves the DDS_EntityNameQosPolicy::name of a DDSDomainParticipant that has been discovered on the network. The participant must be in the same domain as the participant on which this operation is invoked and must not have been "ignored" by means of the DDSDomainParticipant::ignore_participant operation.

The participant_handle must correspond to such a DomainParticipant. If the participant_handle is DDS_HANDLE_NIL or is not a valid DDS_InstanceHandle_t for a DomainParticipant, then the operation will fail with DDS_RETCODE_BAD_PARAMETER. If the participant_handle corresponds to a DomainParticipant that has not been discovered, then the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

Use the operation DDSDomainParticipant::get_discovered_participants to find the DDSDomainParticipant entities that are currently discovered.

Note: this method has different functionality when enabling the RTI Security Plugins. Please refer to the RTI Security Plugins User's Manual for more information.

MT Safety:
Safe.
Parameters
subject_name<<out>> The char buffer that will be used to store the DDS_EntityNameQosPolicy::name of the discovered DDSDomainParticipant. If NULL, this function will return the required length of this buffer through the subject_name_size parameter.
subject_name_size<<inout>> Cannot be NULL. The size of the supplied char buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer, which includes space for the NUL terminator. If the supplied buffer is not NULL but this value is not large enough, then this function will fail with DDS_RETCODE_BAD_PARAMETER. If the DDS_EntityNameQosPolicy::name is NULL, then this value will be set to 0.
participant_handle<<in>> DDS_InstanceHandle_t of DDSDomainParticipant.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED
See also
DDS_EntityNameQosPolicy::name
DDSDomainParticipant::get_discovered_participants

◆ get_discovered_topics()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_discovered_topics ( DDS_InstanceHandleSeq topic_handles)
pure virtual

Returns list of discovered DDSTopic objects.

This operation retrieves the list of DDSTopic s that have been discovered in the domain and that the application has not indicated should be "ignored" by means of the DDSDomainParticipant::ignore_topic operation.

Parameters
topic_handles<<inout>> DDS_InstanceHandleSeq to be filled with handles of the discovered DDSTopic objects
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ get_discovered_topic_data()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_discovered_topic_data ( struct DDS_TopicBuiltinTopicData topic_data,
const DDS_InstanceHandle_t topic_handle 
)
pure virtual

Returns DDS_TopicBuiltinTopicData for the specified DDSTopic.

This operation retrieves information on a DDSTopic that has been discovered by the local Participant and must not have been "ignored" by means of the DDSDomainParticipant::ignore_topic operation.

The topic_handle must correspond to such a topic. Otherwise, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

This call is not supported for remote topics. If a remote topic_handle is used, the operation will fail with DDS_RETCODE_UNSUPPORTED.

Use the operation DDSDomainParticipant::get_discovered_topics to find the topics that are currently discovered.

Parameters
topic_data<<inout>> DDS_TopicBuiltinTopicData to be filled with the specified DDSTopic's data.
topic_handle<<in>> DDS_InstanceHandle_t of DDSTopic.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED
See also
DDS_TopicBuiltinTopicData
DDSDomainParticipant::get_discovered_topics

◆ contains_entity()

virtual DDS_Boolean DDSDomainParticipant::contains_entity ( const DDS_InstanceHandle_t a_handle)
pure virtual

Completes successfully with DDS_BOOLEAN_TRUE if the referenced DDSEntity is contained by the DDSDomainParticipant.

This operation checks whether or not the given a_handle represents an DDSEntity that was created from the DDSDomainParticipant. The containment applies recursively. That is, it applies both to entities (DDSTopicDescription, DDSPublisher, or DDSSubscriber) created directly using the DDSDomainParticipant as well as entities created using a contained DDSPublisher, or DDSSubscriber as the factory, and so forth.

The instance handle for an DDSEntity may be obtained from built-in topic data, from various statuses, or from the operation DDSEntity::get_instance_handle.

Parameters
a_handle<<in>> DDS_InstanceHandle_t of the DDSEntity to be checked.
Returns
DDS_BOOLEAN_TRUE if DDSEntity is contained by the DDSDomainParticipant, or DDS_BOOLEAN_FALSE otherwise.

◆ get_participant_protocol_status()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_participant_protocol_status ( struct DDS_DomainParticipantProtocolStatus status)
pure virtual

<<extension>> Get the domain participant protocol status for this participant.

This also resets the status so that it is no longer considered changed.

Parameters
status<<inout>> DDS_DomainParticipantProtocolStatus to be filled in.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ set_property()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_property ( const char *  property_name,
const char *  value,
bool  propagate 
)
pure virtual

Set the value for a property that applies to a DomainParticipant.

Warning
This method is not implemented in all APIs and it's intended only for testing purposes. You should use DDSDomainParticipant::set_qos instead.
Parameters
property_name<<in>>. Name of the property that you want to set.
value<<in>>. New value for the property.
propagate<<in>>. Indicates if the property will be propagated or not.
Exceptions
Oneof the Standard Return Codes
See also
DDSDataWriter::set_property
DDSDataReader::set_property
DDSDomainParticipant::set_qos

◆ set_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_qos ( const DDS_DomainParticipantQos qos)
pure virtual

Change the QoS of this DomainParticipant.

The DDS_DomainParticipantQos::user_data and DDS_DomainParticipantQos::entity_factory can be changed. The other policies are immutable.

Parameters
qos<<in>> Set of policies to be applied to DDSDomainParticipant. Policies must be consistent. Immutable policies cannot be changed after DDSDomainParticipant is enabled. The special value DDS_PARTICIPANT_QOS_DEFAULT can be used to indicate that the QoS of the DDSDomainParticipant should be changed to match the current default DDS_DomainParticipantQos set in the DDSDomainParticipantFactory.
Exceptions
Oneof the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY if an immutable policy is changed, or DDS_RETCODE_INCONSISTENT_POLICY if policies are inconsistent
See also
DDS_DomainParticipantQos for rules on consistency among QoS policies
set_qos (abstract)

◆ set_qos_with_profile()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_qos_with_profile ( const char *  library_name,
const char *  profile_name 
)
pure virtual

<<extension>> Change the QoS of this domain participant using the input XML QoS profile.

The DDS_DomainParticipantQos::user_data and DDS_DomainParticipantQos::entity_factory can be changed. The other policies are immutable.

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).
Exceptions
Oneof 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_DomainParticipantQos for rules on consistency among QoS

◆ get_qos()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_qos ( DDS_DomainParticipantQos qos)
pure virtual

Get the participant QoS.

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

Parameters
qos<<inout>> QoS to be filled up.
Exceptions
Oneof the Standard Return Codes
See also
get_qos (abstract)

◆ add_peer()

virtual DDS_ReturnCode_t DDSDomainParticipant::add_peer ( const char *  peer_desc_string)
pure virtual

<<extension>> Attempt to contact one or more additional peer participants.

Add the given peer description to the list of peers with which this DDSDomainParticipant will try to communicate.

This method may be called at any time after this DDSDomainParticipant has been created (before or after it has been enabled).

If this method is called after DDSEntity::enable, an attempt will be made to contact the new peer(s) immediately.

If this method is called before the DomainParticipant is enabled, the peer description will simply be added to the list that was populated by DDS_DiscoveryQosPolicy::initial_peers; the first attempted contact will take place after this DDSDomainParticipant is enabled.

Adding a peer description with this method does not guarantee that any peer(s) discovered as a result will exactly correspond to those described:

  • This DDSDomainParticipant will attempt to discover peer participants at the given locations but may not succeed if no such participants are available. In this case, this method will not wait for contact attempt(s) to be made and it will not report an error.

To be informed of the exact remote participants that are discovered, regardless of which peers this DDSDomainParticipant attempts to discover, use the built-in participant topic: DDS_PARTICIPANT_TOPIC_NAME.

To remove specific peer locators, you may use DDSDomainParticipant::remove_peer. If a peer is removed, the add_peer operation will add it back to the list of peers.

To stop communicating with a peer DDSDomainParticipant that has been discovered, use DDSDomainParticipant::ignore_participant.

Adding a peer description with this method has no effect on the DDS_DiscoveryQosPolicy::initial_peers that may be subsequently retrieved with DDSDomainParticipant::get_qos() (because DDS_DiscoveryQosPolicy is immutable).

Parameters
peer_desc_string<<in>> New peer descriptor to be added. The format is specified in Peer Descriptor Format.
Exceptions
Oneof the Standard Return Codes
See also
Peer Descriptor Format
DDS_DiscoveryQosPolicy::initial_peers
DDS_PARTICIPANT_TOPIC_NAME
DDSDomainParticipant::get_builtin_subscriber

◆ remove_peer()

virtual DDS_ReturnCode_t DDSDomainParticipant::remove_peer ( const char *  peer_desc_string)
pure virtual

<<extension>> Remove one or more peer participants from the list of peers with which this DDSDomainParticipant will try to communicate.

This method may be called any time after this DDSDomainParticipant has been enabled

Calling this method has the following effects:

  • If a DDSDomainParticipant was already discovered, it will be locally removed along with all its entities.
  • Any further requests coming from a DDSDomainParticipant located on any of the removed peers will be ignored.
  • All the locators contained in the peer description will be removed from the peer list. The local DDSDomainParticipant will stop sending announcement to those locators.

If remote participants located on a peer that was previously removed are discovered, they will be ignored untill the related peer is added back by using DDSDomainParticipant::add_peer.

Removing a peer description with this method has no effect on the DDS_DiscoveryQosPolicy::initial_peers that may be subsequently retrieved with DDSDomainParticipant::get_qos() (because DDS_DiscoveryQosPolicy is immutable).

Parameters
peer_desc_string<<in>> Peer descriptor to be removed. The format is specified in Peer Descriptor Format.
Exceptions
Oneof the Standard Return Codes
See also
Peer Descriptor Format
DDS_DiscoveryQosPolicy::initial_peers
DDSDomainParticipant::add_peer

◆ get_dns_tracker_polling_period()

virtual DDS_ReturnCode_t DDSDomainParticipant::get_dns_tracker_polling_period ( DDS_Duration_t polling_period)
pure virtual

<<extension>> Retrieves the frequency used by the DNS tracker thread to query the DNS service.

The DNS tracker queries the DNS for hostnames specified in the initial peers of a DomainParticipant. The frequency of these queries is defined by DDS_DiscoveryConfigQosPolicy::dns_tracker_polling_period. If the value returned is DDS_DURATION_INFINITE, the DNS tracker is disabled.

Parameters
polling_period<<out>> Duration that the API populates with the period of the DNS tracker.
Exceptions
Oneof the Standard Return Codes
See also
DDS_DiscoveryConfigQosPolicy::dns_tracker_polling_period

◆ set_dns_tracker_polling_period()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_dns_tracker_polling_period ( const DDS_Duration_t polling_period)
pure virtual

<<extension>> Configures the frequency in which the DNS tracker queries the DNS service.

This API allows you to change the frequency of the polling period for the DNS tracker. The range of accepted values, in seconds, goes from 1 second to 1 year. DDS_DURATION_INFINITE is also accepted as a valid value. If the duration is set to DDS_DURATION_INFINITE, the DNS tracker is disabled.

Modifying the DNS tracker polling period through this has no effect on the DDS_DiscoveryConfigQosPolicy::dns_tracker_polling_period when it is retrieved with DDSDomainParticipant::get_qos().

Parameters
polling_period<<in>> Duration that is set as the polling period for the DNS tracker.
Exceptions
Oneof the Standard Return Codes
See also
DDS_DiscoveryConfigQosPolicy::dns_tracker_polling_period
DDSDomainParticipant::add_peer

◆ set_listener()

virtual DDS_ReturnCode_t DDSDomainParticipant::set_listener ( DDSDomainParticipantListener l,
DDS_StatusMask  mask = DDS_STATUS_MASK_ALL 
)
pure virtual

Sets the participant listener.

Parameters
l<<in>> Listener to be installed on the entity.
mask<<in>> Changes of communication status to be invoked on the listener. See DDS_StatusMask.
MT Safety:
Unsafe. This method is not synchronized with the listener callbacks, so it is possible to set a new listener on a participant when the old listener is in a callback.

Care should therefore be taken not to delete any listener that has been set on an enabled participant unless some application-specific means are available of ensuring that the old listener cannot still be in use.

Exceptions
Oneof the Standard Return Codes
See also
set_listener (abstract)

◆ get_listener()

virtual DDSDomainParticipantListener * DDSDomainParticipant::get_listener ( )
pure virtual

Get the participant listener.

Returns
Existing listener attached to the DDSDomainParticipant.
See also
get_listener (abstract)

◆ get_implicit_publisher()

virtual DDSPublisher * DDSDomainParticipant::get_implicit_publisher ( )
pure virtual

<<extension>> Returns the implicit DDSPublisher. If an implicit Publisher does not already exist, this creates one.

There can only be one implicit Publisher per DomainParticipant.

The implicit Publisher is created with DDS_PUBLISHER_QOS_DEFAULT and no Listener.

This implicit Publisher will be deleted automatically when the following methods are called: DDSDomainParticipant::delete_contained_entities, or DDSDomainParticipant::delete_publisher with the implicit publisher as a parameter. Additionally, when a DomainParticipant is deleted, if there are no attached DataWriters that belong to the implicit Publisher, the implicit Publisher will be implicitly deleted.

Returns
The implicit publisher
See also
DDS_PUBLISHER_QOS_DEFAULT
DDSDomainParticipant::create_publisher

◆ get_implicit_subscriber()

virtual DDSSubscriber * DDSDomainParticipant::get_implicit_subscriber ( )
pure virtual

<<extension>> Returns the implicit DDSSubscriber. If an implicit Subscriber does not already exist, this creates one.

There can only be one implicit Subscriber per DomainParticipant.

The implicit Subscriber is created with DDS_SUBSCRIBER_QOS_DEFAULT and no Listener.

This implicit Subscriber will be deleted automatically when the following methods are called: DDSDomainParticipant::delete_contained_entities, or DDSDomainParticipant::delete_subscriber with the subscriber as a parameter. Additionally, when a DomainParticipant is deleted, if there are no attached DataReaders that belong to the implicit Subscriber, the implicit Subscriber will be implicitly deleted.

MT Safety:
UNSAFE. it is not safe to create the implicit subscriber while another thread may be simultaneously calling DDSDomainParticipant::set_default_subscriber_qos.
Returns
The implicit subscriber
See also
DDS_SUBSCRIBER_QOS_DEFAULT
DDSDomainParticipant::create_subscriber

◆ create_datawriter()

virtual DDSDataWriter * DDSDomainParticipant::create_datawriter ( DDSTopic topic,
const DDS_DataWriterQos qos,
DDSDataWriterListener listener,
DDS_StatusMask  mask 
)
pure virtual

<<extension>> Creates a DDSDataWriter that will be attached and belong to the implicit DDSPublisher.

Precondition
The given DDSTopic must have been created from the same DomainParticipant as the implicit Publisher. If it was created from a different DomainParticipant, this method will fail.

The DDSDataWriter created using this method will be associated with the implicit Publisher. This Publisher is automatically created (if it does not exist) using DDS_PUBLISHER_QOS_DEFAULT when the following methods are called: DDSDomainParticipant::create_datawriter, DDSDomainParticipant::create_datawriter_with_profile, or DDSDomainParticipant::get_implicit_publisher.

MT Safety:
UNSAFE. If DDS_DATAWRITER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the DataWriter while another thread may be simultaneously calling DDSDomainParticipant::set_default_datawriter_qos.
Parameters
topic<<in>> The DDSTopic that the DDSDataWriter will be associated with.
qos<<in>> QoS to be used for creating the new DDSDataWriter. The special value DDS_DATAWRITER_QOS_DEFAULT can be used to indicate that the DDSDataWriter should be created with the default DDS_DataWriterQos set in the implicit DDSPublisher. The special value DDS_DATAWRITER_QOS_USE_TOPIC_QOS can be used to indicate that the DDSDataWriter should be created with the combination of the default DDS_DataWriterQos set on the DDSPublisher and the DDS_TopicQos of the DDSTopic.
listener<<in>> The listener of the DDSDataWriter.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDSDataWriter of a derived class specific to the data type associated with the DDSTopic or NULL if an error occurred.
See also
FooDataWriter
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataWriterQos for rules on consistency among QoS
DDS_DATAWRITER_QOS_DEFAULT
DDS_DATAWRITER_QOS_USE_TOPIC_QOS
DDSDomainParticipant::create_datawriter_with_profile
DDSDomainParticipant::get_default_datawriter_qos
DDSDomainParticipant::get_implicit_publisher
DDSTopic::set_qos
DDSDataWriter::set_listener

◆ create_datawriter_with_profile()

virtual DDSDataWriter * DDSDomainParticipant::create_datawriter_with_profile ( DDSTopic topic,
const char *  library_name,
const char *  profile_name,
DDSDataWriterListener listener,
DDS_StatusMask  mask 
)
pure virtual

<<extension>> Creates a DDSDataWriter using a XML QoS profile that will be attached and belong to the implicit DDSPublisher.

Precondition
The given DDSTopic must have been created from the same DomainParticipant as the implicit Publisher. If it was created from a different DomainParticipant, this method will return NULL.

The DDSDataWriter created using this method will be associated with the implicit Publisher. This Publisher is automatically created (if it does not exist) using DDS_PUBLISHER_QOS_DEFAULT when the following methods are called: DDSDomainParticipant::create_datawriter, DDSDomainParticipant::create_datawriter_with_profile, or DDSDomainParticipant::get_implicit_publisher

Parameters
topic<<in>> The DDSTopic that the DDSDataWriter will be associated with.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).
listener<<in>> The listener of the DDSDataWriter.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDSDataWriter of a derived class specific to the data type associated with the DDSTopic or NULL if an error occurred.
See also
FooDataWriter
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataWriterQos for rules on consistency among QoS
DDSDomainParticipant::create_datawriter
DDSDomainParticipant::get_default_datawriter_qos
DDSDomainParticipant::get_implicit_publisher
DDSTopic::set_qos
DDSDataWriter::set_listener

◆ delete_datawriter()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_datawriter ( DDSDataWriter a_datawriter)
pure virtual

<<extension>> Deletes a DDSDataWriter that belongs to the implicit DDSPublisher.

The deletion of the DDSDataWriter will automatically unregister all instances.

Precondition
If the DDSDataWriter does not belong to the implicit DDSPublisher, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the DDSDataWriter will not be called after this method completes 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_datawriter<<in>> The DDSDataWriter to be deleted.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.
See also
DDSDomainParticipant::get_implicit_publisher

◆ create_datareader()

virtual DDSDataReader * DDSDomainParticipant::create_datareader ( DDSTopicDescription topic,
const DDS_DataReaderQos qos,
DDSDataReaderListener listener,
DDS_StatusMask  mask 
)
pure virtual

<<extension>> Creates a DDSDataReader that will be attached and belong to the implicit DDSSubscriber.

Precondition
The given DDSTopicDescription must have been created from the same DomainParticipant as the implicit Subscriber. If it was created from a different DomainParticipant, this method will return NULL.

The DDSDataReader created using this method will be associated with the implicit Subscriber. This Subscriber is automatically created (if it does not exist) using DDS_SUBSCRIBER_QOS_DEFAULT when the following methods are called: DDSDomainParticipant::create_datareader, DDSDomainParticipant::create_datareader_with_profile, or DDSDomainParticipant::get_implicit_subscriber.

MT Safety:
UNSAFE. If DDS_DATAREADER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datareader while another thread may be simultaneously calling DDSDomainParticipant::set_default_datareader_qos.
Parameters
topic<<in>> The DDSTopicDescription that the DDSDataReader will be associated with.
qos<<in>> The qos of the DDSDataReader. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the DDSDataReader should be created with the default DDS_DataReaderQos set in the implicit DDSSubscriber. If DDSTopicDescription is of type DDSTopic or DDSContentFilteredTopic, the special value DDS_DATAREADER_QOS_USE_TOPIC_QOS can be used to indicate that the DDSDataReader should be created with the combination of the default DDS_DataReaderQos set on the implicit DDSSubscriber and the DDS_TopicQos (in the case of a DDSContentFilteredTopic, the DDS_TopicQos of the related DDSTopic). if DDS_DATAREADER_QOS_USE_TOPIC_QOS is used, topic cannot be a DDSMultiTopic.
listener<<in>> The listener of the DDSDataReader.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDSDataReader of a derived class specific to the data-type associated with the DDSTopic or NULL if an error occurred.
See also
FooDataReader
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataReaderQos for rules on consistency among QoS
DDSDomainParticipant::create_datareader_with_profile
DDSDomainParticipant::get_default_datareader_qos
DDSDomainParticipant::get_implicit_subscriber
DDSTopic::set_qos
DDSDataReader::set_listener

◆ create_datareader_with_profile()

virtual DDSDataReader * DDSDomainParticipant::create_datareader_with_profile ( DDSTopicDescription topic,
const char *  library_name,
const char *  profile_name,
DDSDataReaderListener listener,
DDS_StatusMask  mask 
)
pure virtual

<<extension>> Creates a DDSDataReader using a XML QoS profile that will be attached and belong to the implicit DDSSubscriber.

Precondition
The given DDSTopicDescription must have been created from the same DomainParticipant as the implicit subscriber. If it was created from a different DomainParticipant, this method will return NULL.

The DDSDataReader created using this method will be associated with the implicit Subscriber. This Subscriber is automatically created (if it does not exist) using DDS_SUBSCRIBER_QOS_DEFAULT when the following methods are called: DDSDomainParticipant::create_datareader, DDSDomainParticipant::create_datareader_with_profile, or DDSDomainParticipant::get_implicit_subscriber

Parameters
topic<<in>> The DDSTopicDescription that the DDSDataReader will be associated with.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSDomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSDomainParticipant::set_default_profile).
listener<<in>> The listener of the DDSDataReader.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDSDataReader of a derived class specific to the data-type associated with the DDSTopic or NULL if an error occurred.
See also
FooDataReader
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataReaderQos for rules on consistency among QoS
DDSDomainParticipant::create_datareader
DDSDomainParticipant::get_default_datareader_qos
DDSDomainParticipant::get_implicit_subscriber
DDSTopic::set_qos
DDSDataReader::set_listener

◆ delete_datareader()

virtual DDS_ReturnCode_t DDSDomainParticipant::delete_datareader ( DDSDataReader a_datareader)
pure virtual

<<extension>> Deletes a DDSDataReader that belongs to the implicit DDSSubscriber.

Precondition
If the DDSDataReader does not belong to the implicit DDSSubscriber, or if ther are any existing DDSReadCondition or DDSQueryCondition objects that are attached to the DDSDataReader, or if there are outstanding loans on samples (as a result of a call to read(), take(), or one of the variants thereof), the operation fails with the error DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the DDSDataReader will not be called after this method completes 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_datareader<<in>> The DDSDataReader to be deleted.
Exceptions
Oneof the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.
See also
DDSDomainParticipant::get_implicit_subscriber

◆ lookup_publisher_by_name()

virtual DDSPublisher * DDSDomainParticipant::lookup_publisher_by_name ( const char *  publisher_name)
pure virtual

<<extension>> Looks up a DDSPublisher by its entity name within this DDSDomainParticipant.

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

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

Parameters
publisher_name<<in>> Entity name of the DDSPublisher.
Returns
The first DDSPublisher found with the specified name or NULL if it is not found.
See also
DDSDomainParticipant::lookup_datawriter_by_name

◆ lookup_subscriber_by_name()

virtual DDSSubscriber * DDSDomainParticipant::lookup_subscriber_by_name ( const char *  subscriber_name)
pure virtual

<<extension>> Retrieves a DDSSubscriber by its entity name within this DDSDomainParticipant.

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

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

Parameters
subscriber_name<<in>> Entity name of the DDSSubscriber.
Returns
The first DDSSubscriber found with the specified name or NULL if it is not found.
See also
DDSDomainParticipant::lookup_datareader_by_name

◆ lookup_datawriter_by_name()

virtual DDSDataWriter * DDSDomainParticipant::lookup_datawriter_by_name ( const char *  datawriter_full_name)
pure virtual

<<extension>> Looks up a DDSDataWriter by its entity name within this DDSDomainParticipant.

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

Every DDSPublisher in the system has an entity name which is also configured and stored in the EntityName policy.

This operation retrieves a DDSDataWriter within a DDSPublisher given the specified name which encodes both to the DDSDataWriter and the DDSPublisher name.

If there are several DDSDataWriter with the same name within the corresponding DDSPublisher this function returns the first matching occurrence.

The specified name might be given as a fully-qualified entity name or as a plain name.

The fully qualified entity name is a concatenation of the DDSPublisher to which the DDSDataWriter belongs and the entity name of of the DDSDataWriter itself, separated by a double colon "::". For example: MyPublisherName::MyDataWriterName

The plain name contains the DDSDataWriter name only. In this situation it is implied that the DDSDataWriter belongs to the implicit DDSPublisher so the use of a plain name is equivalent to specifying a fully qualified name with the DDSPublisher name part being "implicit". For example: the plain name "MyDataWriterName" is equivalent to specifiying the fully qualified name "implicit::MyDataWriterName"

The DDSDataWriter is only looked up within the DDSPublisher specified in the fully qualified name, or within the implicit DDSPublisher if the name was not fully qualified.

Parameters
datawriter_full_name<<in>> Entity name or fully-qualified entity name of the DDSDataWriter.
Returns
The first DDSDataWriter found with the specified name or NULL if it is not found.
See also
DDSPublisher::lookup_datawriter_by_name
DDSDomainParticipant::lookup_publisher_by_name

◆ lookup_datareader_by_name()

virtual DDSDataReader * DDSDomainParticipant::lookup_datareader_by_name ( const char *  datareader_full_name)
pure virtual

<<extension>> Retrieves up a DDSDataReader by its entity name in this DDSDomainParticipant.

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

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

This operation retrieves a DDSDataReader within a DDSSubscriber given the specified name which encodes both to the DDSDataReader and the DDSSubscriber name.

If there are several DDSDataReader with the same name within the corresponding DDSSubscriber this function returns the first matching occurrence.

The specified name might be given as a fully-qualified entity name or as a plain name.

The fully qualified entity name is a concatenation of the DDSSubscriber to which the DDSDataReader belongs and the entity name of of the DDSDataReader itself, separated by a double colon "::". For example: MySubscriberName::MyDataReaderName

The plain name contains the DDSDataReader name only. In this situation it is implied that the DDSDataReader belongs to the implicit DDSSubscriber so the use of a plain name is equivalent to specifying a fully qualified name with the DDSSubscriber name part being "implicit". For example: the plain name "MyDataReaderName" is equivalent to specifiying the fully qualified name "implicit::MyDataReaderName"

The DDSDataReader is only looked up within the DDSSubscriber specified in the fully qualified name, or within the implicit DDSSubscriber if the name was not fully qualified.

Parameters
datareader_full_name<<in>> Full entity name of the DDSDataReader.
Returns
The first DDSDataReader found with the specified name or NULL if it is not found.
See also
DDSSubscriber::lookup_datareader_by_name
DDSDomainParticipant::lookup_subscriber_by_name

◆ take_discovery_snapshot() [1/2]

virtual DDS_ReturnCode_t DDSDomainParticipant::take_discovery_snapshot ( )
pure virtual

Take a snapshot of the remote participants discovered by a local one.

The snapshot will be printed through the NDDSConfigLogger. A possible output may be the following:

Remote participants that match the local participant domain=0
name="participantTestName" role="participantTestRole" id="1"
guid_prefix="0x0101D8D1,0x20B83C0D,0x4495246E"
----------------------------------------------------------------------------
1. 0x0101542A,0x2C59B595,0xA1693BDF name="participantTestName"
role="participantTestRole"
unicastLocators="udpv4://192.168.1.170:7411"
----------------------------------------------------------------------------
Exceptions
Oneof the Standard Return Codes.

◆ take_discovery_snapshot() [2/2]

virtual DDS_ReturnCode_t DDSDomainParticipant::take_discovery_snapshot ( const char *  file_name)
pure virtual

Take a snapshot of the remote participants discovered by a local one.

The snapshot will be printed in the file specified by file_name. A possible output may be the following:

Remote participants that match the local participant domain=0
name="participantTestName" role="participantTestRole" id="1"
guid_prefix="0x0101D8D1,0x20B83C0D,0x4495246E"
----------------------------------------------------------------------------
1. 0x0101542A,0x2C59B595,0xA1693BDF name="participantTestName"
role="participantTestRole"
unicastLocators="udpv4://192.168.1.170:7411"
----------------------------------------------------------------------------
Parameters
file_name<<in>> Name of the file where snapshot should be printed.
Exceptions
Oneof the Standard Return Codes.