DDSDomainParticipant Class Reference

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

#include <dds_cpp_domain.hxx>

Inheritance diagram for DDSDomainParticipant:

List of all members.

Public Member Functions
virtual DDSEntity *	as_entity ()=0
	<<cert>> Access a DDSDomainParticipant's supertype instance.
virtual DDSPublisher *	create_publisher (const DDS_PublisherQos &qos, DDSPublisherListener *listener, DDS_StatusMask mask)=0
	<<cert>> Creates a DDSPublisher with the desired QoS policies and attaches to it the specified DDSPublisherListener.
virtual DDS_ReturnCode_t	delete_publisher (DDSPublisher *p)=0
	Deletes an existing DDSPublisher.
virtual DDSSubscriber *	create_subscriber (const DDS_SubscriberQos &qos, DDSSubscriberListener *listener, DDS_StatusMask mask)=0
	<<cert>> Creates a DDSSubscriber with the desired QoS policies and attaches to it the specified DDSSubscriberListener.
virtual DDS_ReturnCode_t	delete_subscriber (DDSSubscriber *s)=0
	Deletes an existing DDSSubscriber.
virtual DDSTopic *	create_topic (const char *topic_name, const char *type_name, const DDS_TopicQos &qos, DDSTopicListener *listener, DDS_StatusMask mask)=0
	<<cert>> Creates a DDSTopic with the desired QoS policies
virtual DDS_ReturnCode_t	delete_topic (DDSTopic *topic)=0
	Deletes a DDSTopic.
virtual DDSTopic *	find_topic (const char *topic_name, const DDS_Duration_t &timeout)=0
	Finds an existing (or ready to exist) DDSTopic, based on its name.
virtual DDS_ReturnCode_t	get_qos (DDS_DomainParticipantQos &qos)=0
	Get the participant QoS.
virtual DDS_ReturnCode_t	set_qos (const DDS_DomainParticipantQos &qos)=0
	Change the QoS of this domain participant.
virtual DDS_ReturnCode_t	get_default_publisher_qos (DDS_PublisherQos &qos)=0
	Copy the default DDS_PublisherQos values into the provided DDS_PublisherQos instance.
virtual DDS_ReturnCode_t	set_default_publisher_qos (const DDS_PublisherQos &qos)=0
	Set the default DDS_PublisherQos values for this domain participant.
virtual DDS_ReturnCode_t	get_default_subscriber_qos (DDS_SubscriberQos &qos)=0
	Copy the default DDS_SubscriberQos values into the provided DDS_SubscriberQos instance.
virtual DDS_ReturnCode_t	set_default_subscriber_qos (const DDS_SubscriberQos &qos)=0
	Set the default DDS_SubscriberQos values for this domain participant.
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.
virtual DDS_ReturnCode_t	set_default_topic_qos (const DDS_TopicQos &qos)=0
	Set the default DDS_TopicQos values for this domain participant.
virtual DDSTopicDescription *	lookup_topicdescription (const char *topic_name)=0
	<<cert>> Lookup an existing locally-created DDSTopicDescription, based on its name.
virtual DDSPublisher *	lookup_publisher_by_name (const char *publisher_name)=0
	<<cert>> Retrieves a DDSPublisher by its entity name within this DDSDomainParticipant
virtual DDSSubscriber *	lookup_subscriber_by_name (const char *subscriber_name)=0
	<<cert>> Retrieves a DDSSubscriber by its entity name within this DDSDomainParticipant
virtual DDSDataWriter *	lookup_datawriter_by_name (const char *datawriter_full_name)=0
	<<cert>> Retrieves a DDSDataWriter by its entity name within this DDSDomainParticipant
virtual DDSDataReader *	lookup_datareader_by_name (const char *datareader_full_name)=0
	<<cert>> Retrieves a DDSDataReader by its entity name within this DDSDomainParticipant
virtual DDS_ReturnCode_t	assert_liveliness ()=0
	Manually asserts the liveliness of this DDSDomainParticipant.
virtual DDS_ReturnCode_t	delete_contained_entities ()=0
	Delete all the entities that were created by means of the "create" operations on the DDSDomainParticipant.
virtual DDS_ReturnCode_t	register_type (const char *type_name, DDS_TypePluginI *plugin)=0
	<<eXtension>> <<cert>> Allows an application to communicate to RTI Connext DDS Micro the existence of a data type.
virtual DDS_TypePluginI *	unregister_type (const char *type_name)=0
	Allows an application to unregister a data type from RTI Connext DDS Micro. After calling unregister_type, no further communication using that type is possible.
virtual DDS_ReturnCode_t	set_listener (const DDSDomainParticipantListener *listener, DDS_StatusMask mask)=0
	Sets the participant listener.
virtual DDSDomainParticipantListener *	get_listener ()=0
	Get the participant listener.
virtual DDS_ReturnCode_t	get_discovered_participants (DDS_InstanceHandleSeq &participant_handles)=0
	Returns a sequence containing DDS_InstanceHandle_t for all the remote DDSDomainParticipant that have been discovered by the DDSDomainParticipant.
virtual DDS_ReturnCode_t	get_discovered_participant_data (DDS_ParticipantBuiltinTopicData &participant_data, const DDS_InstanceHandle_t &participant_handle)=0
	Returns information about a remote DDSDomainParticipant that has been discovered by the DDSDomainParticipant.
virtual DDS_ReturnCode_t	get_current_time (DDS_Time_t &current_time)=0
	<<cert>> Returns the current value of the time.
virtual DDS_ReturnCode_t	add_peer (const char *peer)=0
	<<eXtension>> <<cert>> Attempt to contact one or more additional peer participants.
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.
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.
virtual DDSFlowController *	create_flowcontroller (const char *name, const DDS_FlowControllerProperty_t &prop)=0
	<<eXtension>> Creates a DDSFlowController with the desired property.
virtual DDS_ReturnCode_t	delete_flowcontroller (DDSFlowController *fc)=0
	<<eXtension>> Deletes an existing DDSFlowController.
virtual DDSFlowController *	lookup_flowcontroller (const char *name)=0
	<<eXtension>> Looks up an existing locally-created DDSFlowController, based on its name.
Public Member Functions inherited from DDSEntity
DDS_ReturnCode_t	enable ()
	<<cert>> Enables the DDSEntity.
DDSStatusCondition *	get_statuscondition ()
	<<cert>> Return the DDSStatusCondition associated with a particular DDSEntity.
DDS_StatusMask	get_status_changes ()
	<<cert>> Retrieves the list of communication statuses in the DDSEntity that are triggered.
DDS_InstanceHandle_t	get_instance_handle ()
	<<cert>> Allows access to the DDS_InstanceHandle_t associated with the DDSEntity.

---

Detailed Description

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

The DomainParticipant object plays several roles:

- It acts as a container for all other DDSEntity objects.

- It acts as factory for the DDSPublisher, DDSSubscriber, DDSTopic and 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. Other operations will fail with the value DDS_RETCODE_NOT_ENABLED if called on a disabled DomainParticipant:

• Operations defined at the base-class level namely, set_qos(), get_qos(), set_listener(), get_listener(), and enable().
• Factory operations: create_topic(), create_publisher(), create_subscriber(), delete_topic(), delete_publisher(), delete_subscriber(), delete_contained_entities().

QoS:

DDS_DomainParticipantQos

Status:

Status Kinds

Listener:

DDSDomainParticipantListener

---

Member Function Documentation

virtual DDSEntity* DDSDomainParticipant::as_entity ( )

pure virtual

<<cert>> Access a DDSDomainParticipant's supertype instance.

Returns:

DDSDomainParticipant's supertype DDSEntity instance

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

pure virtual

<<cert>> 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.

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.

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

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.

Parameters:

p	<<in>> DDSPublisher to be deleted.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

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

pure virtual

<<cert>> 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 publisher 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.

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

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.

Parameters:

s	<<in>> DDSSubscriber to be deleted.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

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

pure virtual

<<cert>> Creates a DDSTopic with the desired QoS policies

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 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 DDS Micro. This is done using the DDSDomainParticipant::register_type operation on a derived class of the DDS_TypePluginI 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 create the publisher 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.

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

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, or DDSDataWriter, 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.

Parameters:

topic

<<in>> DDSTopic to be deleted.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

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.

If a DDSTopic of the same name already exists, it gives access to it, otherwise it waits until either another mechanism creates it, or else completes when the specified timeout occurs.

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 doesn't exist already.

Returns:

the topic, if it exists, or NULL

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.

Returns:

One of the Standard Return Codes

See also:

get_qos (abstract)

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

pure virtual

Change the QoS of this domain participant.

The 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.

Returns:

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

See also:

DDS_DomainParticipantQos for rules on consistency among QoS

set_qos (abstract)

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 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 QoS value from a domain participant while another thread may be simultaneously calling DDSDomainParticipant::set_default_publisher_qos

Parameters:

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

Returns:

One of the Standard Return Codes

See also:

DDS_PUBLISHER_QOS_DEFAULT

DDSDomainParticipant::create_publisher

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

pure virtual

Set the default DDS_PublisherQos values for this domain participant.

This default value will be used for 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 retrieve the default QoS value from a domain participant while another thread may be simultaneously calling 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.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

See also:

DDS_PUBLISHER_QOS_DEFAULT

DDSDomainParticipant::create_publisher

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 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 QoS value from a domain participant while another thread may be simultaneously calling DDSDomainParticipant::set_default_subscriber_qos

Parameters:

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

Returns:

One of the Standard Return Codes

See also:

DDS_SUBSCRIBER_QOS_DEFAULT

DDSDomainParticipant::create_subscriber

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

pure virtual

Set the default DDS_SubscriberQos values for this domain participant.

This default value will be used for 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 retrieve the default QoS value from a domain participant while another thread may be simultaneously calling 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.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

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 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 QoS value from a domain participant while another thread may be simultaneously calling 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 retrieved.

Returns:

One of the Standard Return Codes

See also:

DDS_TOPIC_QOS_DEFAULT

DDSDomainParticipant::create_topic

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 retrieve the default QoS value from a domain participant while another thread may be simultaneously calling 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 have used if DDSDomainParticipant::set_default_topic_qos had never been called.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

See also:

DDS_TOPIC_QOS_DEFAULT

DDSDomainParticipant::create_topic

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

pure virtual

<<cert>> Lookup an existing locally-created DDSTopicDescription, based on its name.

The returned topic can either be enabled or disabled.

The operation DDSDomainParticipant::lookup_topicdescription searches among the locally created topics and returns a pointer to a DDSTopicDescription. It is possible to delete the DDSTopicDescription returned by DDSDomainParticipant::lookup_topicdescription, provided it has no readers or writers, but then it is really deleted and subsequent lookups will fail.

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. Cannot be NULL.

Returns:

the topic description if it has already been created locally, or NULL otherwise.

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

pure virtual

<<cert>> Retrieves a DDSPublisher by its entity name within this DDSDomainParticipant

This returned DDSPublisher is either enabled or disabled.

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. Cannot be NULL.

Returns:

The first DDSPublisher found with the specified name or NULL if it is not found.

MT Safety:

UNSAFE. It is not safe to lookup a DDSPublisher in one thread while another thread is simultaneously creating or destroying that DDSPublisher.

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

pure virtual

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

This returned DDSSubscriber is either enabled or disabled.

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. Cannot be NULL.

Returns:

The first DDSSubscriber found with the specified name or NULL if it is not found.

MT Safety:

UNSAFE. It is not safe to lookup a DDSSubscriber in one thread while another thread is simultaneously creating or destroying that DDSSubscriber.

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

pure virtual

<<cert>> Retrieves a DDSDataWriter by its entity name within this DDSDomainParticipant

This returned DDSDataWriter is either enabled or disabled.

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

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

Parameters:

datawriter_full_name

<<in>> Entity name of the DDSDataWriter. Cannot be NULL.

Returns:

The first DDSDataWriter found with the specified name or NULL if it is not found.

MT Safety:

UNSAFE. It is not safe to lookup a DDSDataWriter in one thread while another thread is simultaneously creating or destroying that DDSDataWriter.

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

pure virtual

<<cert>> Retrieves a DDSDataReader by its entity name within this DDSDomainParticipant

This returned DDSDataReader is either enabled or disabled.

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

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

Parameters:

datareader_full_name

<<in>> Entity name of the DDSDataReader. Cannot be NULL.

Returns:

The first DDSDataReader found with the specified name or NULL if it is not found.

MT Safety:

UNSAFE. It is not safe to lookup a DDSDataReader in one thread while another thread is simultaneously creating or destroying that DDSDataReader.

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 DDS Micro that the entity remains active.

You need to use this operation if the DDSDomainParticipant cointains 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.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_NOT_ENABLED

See also:

DDS_LivelinessQosPolicy

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, DDSSubscriber, and DDSTopic.

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 deleting all the entities recursively contained in the DDSDomainParticipant, that is also the DDSDataWriter, and 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 knowing that it has no contained entities.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

virtual DDS_ReturnCode_t DDSDomainParticipant::register_type ( const char *  type_name, DDS_TypePluginI *  plugin  )

pure virtual

<<eXtension>> <<cert>> Allows an application to communicate to RTI Connext DDS Micro the existence of a data type.

The generated implementation of the operation embeds all the knowledge that has to be communicated to the middleware in order to make it able to manage the contents of data of that type. This includes in particular the key definition that will allow RTI Connext DDS Micro to distinguish different instances of the same type.

The same DDS_TypePluginI can be registered multiple times with a DDSDomainParticipant using the same or different values for the type_name. If register_type is called multiple times on the same DDS_TypePluginI with the same DDSDomainParticipant and type_name, the second (and subsequent) registrations are ignored by the operation fails with DDS_RETCODE_OK.

Precondition:

Cannot use the same type_name to register two different DDS_TypePluginI with the same DDSDomainParticipant, or else the operation will fail and DDS_RETCODE_PRECONDITION_NOT_MET will be returned.

Parameters:

type_name	<<in>> the type name under with the data type Foo is registered with the participant; this type name is used when creating a new DDSTopic. (See DDSDomainParticipant::create_topic.) The name may not be NULL or longer than 255 characters.
plugin	<<in>> the Foo type plugin to register the data type with. Cannot be NULL.

Returns:

One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_OUT_OF_RESOURCES.

See also:

DDSDomainParticipant::create_topic

virtual DDS_TypePluginI* DDSDomainParticipant::unregister_type ( const char *  type_name )

pure virtual

Allows an application to unregister a data type from RTI Connext DDS Micro. After calling unregister_type, no further communication using that type is possible.

The generated implementation of the operation removes all the information about a type from RTI Connext DDS Micro. No further communication using that type is possible.

Precondition:

A type with type_name is registered with the participant and all DDSTopic objects referencing the type have been destroyed. If the type is not registered with the participant, or if any DDSTopic is associated with the type, the operation will fail with DDS_RETCODE_ERROR.

Postcondition:

All information about the type is removed from RTI Connext DDS Micro. No further communication using this type is possible.

Parameters:

type_name

<<in>> the type name under with the data type Foo is registered with the participant. The name should match a name that has been previously used to register a type with the participant. Cannot be NULL.

Returns:

One of the Standard Return Codes, DDS_RETCODE_BAD_PARAMETER or DDS_RETCODE_ERROR

See also:

DDSDomainParticipant::register_type

virtual DDS_ReturnCode_t DDSDomainParticipant::set_listener ( const DDSDomainParticipantListener *  listener, DDS_StatusMask  mask  )

pure virtual

Sets the participant listener.

Parameters:

listener	<<in>> Listener to be installed on entity.
mask	<<in>> Changes of communication status to be invoked on the listener.

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.

Returns:

One of the Standard Return Codes

See also:

set_listener (abstract)

virtual DDSDomainParticipantListener* DDSDomainParticipant::get_listener ( )

pure virtual

Get the participant listener.

Returns:

Existing listener attached to the DDSDomainParticipant.

virtual DDS_ReturnCode_t DDSDomainParticipant::get_discovered_participants ( DDS_InstanceHandleSeq &  participant_handles )

pure virtual

Returns a sequence containing DDS_InstanceHandle_t for all the remote DDSDomainParticipant that have been discovered by the DDSDomainParticipant.

Parameters:

participant_handles

<<out>> sequence of DDS_InstanceHandle_t where the result will be stored.

Returns:

One of the Standard Return Codes

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

pure virtual

Returns information about a remote DDSDomainParticipant that has been discovered by the DDSDomainParticipant.

Parameters:

participant_data	<<out>> information about the remote DDSDomainParticipant.
participant_handle	<<in>> DDS_InstanceHandle_t identifying the remote DDSDomainParticipant.

Returns:

One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSDomainParticipant::get_current_time ( DDS_Time_t &  current_time )

pure virtual

<<cert>> Returns the current value of the time.

The current value of the time that RTI Connext DDS Micro 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.

Returns:

One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSDomainParticipant::add_peer ( const char *  peer )

pure virtual

<<eXtension>> <<cert>> 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 it is called after DDSEntity::enable, an attempt will be made to contact the new peer(s) immediately. If it is called before, 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. Such a situation will not result in an error result from this method, which will not wait for contact attempt(s) to be made.
• If remote participants such as are described by the given peer description are discovered, the distributed application is configured with asymmetric peer lists, and DDS_DiscoveryQosPolicy::accept_unknown_peers is set to DDS_BOOLEAN_TRUE this DDSDomainParticipant may actually discover more peers than are described in the given peer description.

Adding a peer description with this method has no effect on the DDS_DiscoveryQosPolicy::initial_peers.

Parameters:

peer	<<in>> New peer descriptor to be added.

Returns:

One of the Standard Return Codes

See also:

DDS_DiscoveryQosPolicy::initial_peers

::DDS_PARTICIPANT_TOPIC_NAME

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.

Returns:

One of the Standard Return Codes

See also:

DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT

DDSDomainParticipant::create_flowcontroller

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.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

See also:

DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT

DDSDomainParticipant::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.

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

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.

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.

Returns:

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

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.