The DomainParticipant is used to configure, create and destroy Publisher, Subscriber and Topic objects. More...

Inheritance diagram for DDS::DomainParticipant:

Public Member Functions
ReturnCode_t	get_qos (DomainParticipantQos &qos)
	Provides access to the DomainParticipantQoS settings of the DomainParticipant.

ReturnCode_t	set_qos (const DomainParticipantQos &qos)
	Sets the DomainParticipantQoS values. More...

StatusMask	get_status_changes ()
	This returns the list of triggered communication statuses in the DomainParticipant. More...

ReturnCode_t	set_listener (DomainParticipantListener *a_listener, StatusMask mask)
	This operation installs a DomainParticipantListener on the DomainParticipant. More...

DomainParticipantListener *	get_listener ()
	This operation returns the currently installed DomainParticipantListener. More...

class Publisher *	create_publisher (const PublisherQos &qos, PublisherListener *a_listener, StatusMask mask)
	This operation creates a Publisher with the specified PublisherQoS settings and PublisherListener. More...

ReturnCode_t	delete_publisher (class Publisher *p)
	This operation deletes an existing Publisher. More...

class Subscriber *	create_subscriber (const SubscriberQos &qos, SubscriberListener *a_listener, StatusMask mask)
	This operation creates a Subscriber with the specified SubscriberQos and SubscriberListener. More...

ReturnCode_t	delete_subscriber (class Subscriber *s)
	This operation deletes an existing Subscriber. More...

class Topic *	create_topic (const char topic_name, const char type_name, const TopicQos &qos, TopicListener *a_listener, StatusMask mask)
	This operation creates a Topic with the specified TopicQos settings and TopicListener. More...

ReturnCode_t	delete_topic (class Topic *a_topic)
	This operation deletes a Topic. More...

class Topic *	find_topic (const char *topic_name, const Duration_t &timeout)
	This operation returns a Topic identified by the provided topic_name. More...

class TopicDescription *	lookup_topicdescription (const char *name)
	This operation returns an existing, locally-created TopicDescription, named name. More...

class Subscriber *	get_builtin_subscriber ()
	Returns the built-in Subscriber. More...

ReturnCode_t	ignore_participant (InstanceHandle_t &handle)
	Instructs the DomainParticipant dp to ignore the external DomainParticipant identified by handle. More...

ReturnCode_t	ignore_topic (InstanceHandle_t &handle)
	This operation instructs the DomainParticipant dp to ignore a Topic identified by handle. More...

ReturnCode_t	ignore_publication (InstanceHandle_t &handle)
	This operation instructs the DomainParticipant dp to ignore a Publication identified by handle. More...

ReturnCode_t	ignore_subscription (InstanceHandle_t &handle)
	This operation instructs the DomainParticipant dp to ignore a Subscription identified by handle. More...

DomainId_t	get_domain_id ()
	This operation retrieves the domain_id to which the DomainParticipant belongs.

ReturnCode_t	delete_contained_entities ()
	This operation deletes all the objects created by means of the create operations on DomainParticipant dp. More...

ReturnCode_t	assert_liveliness ()
	This operation manually asserts the liveliness of the DomainParticipant dp. More...

ReturnCode_t	set_default_publisher_qos (const PublisherQos &qos)
	Sets the default PublisherQos held in the DomainParticipant. More...

ReturnCode_t	get_default_publisher_qos (PublisherQos &qos)
	Provides access to the default PublisherQos settings held in the factory. More...

ReturnCode_t	set_default_subscriber_qos (const SubscriberQos &qos)
	Sets the default SubscriberQos held in the DomainParticipant. More...

ReturnCode_t	get_default_subscriber_qos (SubscriberQos &qos)
	Provides access to the default SubscriberQos settings held in the factory. More...

ReturnCode_t	set_default_topic_qos (const TopicQos &qos)
	Sets the default TopicQos held in the DomainParticipant. More...

ReturnCode_t	get_default_topic_qos (TopicQos &qos)
	Provides access to the default TopicQos settings held in the factory. More...

ReturnCode_t	get_discovered_participants (InstanceHandleSeq *participant_handles)
	This operation returns the list of handles identifying the DomainParticipant objects that have been discovered. More...

ReturnCode_t	get_discovered_participant_data (ParticipantBuiltinTopicData *participant_data, InstanceHandle_t &participant_handle)
	This operation returns data that describes a particular discovered participant identified by participant_handle. More...

ReturnCode_t	get_discovered_topics (InstanceHandleSeq *topic_handles)
	This operation returns the list of handles identifying the Topic objects that have been discovered. More...

class ContentFilteredTopic *	create_contentfilteredtopic (const char name, class Topic related_topic, const char *filter_expression, const StringSeq &filter_parameters)
	This operation creates a ContentFilteredTopic. More...

ReturnCode_t	delete_contentfilteredtopic (class ContentFilteredTopic *a_cft)
	This operation deletes a previously allocated ContentFilteredTopic. More...

class MultiTopic *	create_multitopic (const char name, const char type_name, const char *subscription_expression, const StringSeq &expression_params)

ReturnCode_t	delete_multitopic (class MultiTopic *a_multitopic)

ReturnCode_t	get_discovered_topic_data (TopicBuiltinTopicData *topic_data, InstanceHandle_t &topic_handle)
	This operation returns data that describes a particular discovered topic identified by topic_handle. More...

bool	contains_entity (InstanceHandle_t a_handle)
	This operation checks whether or not the given handle a_handle represents an object that was created by the DomainParticipant d. More...

ReturnCode_t	get_current_time (Time_t *current_time)
	This operation returns the current value of the time used by the service.

ReturnCode_t	do_work (const Duration_t &time_slice)
	Transfer control to the DomainParticipant so it can do background processing. More...

ReturnCode_t	builtin_wait_for_acknowledgments (const Duration_t &max_wait)
	Ensure that local discovery information has been received by all known peers.

ReturnCode_t	get_guid (GUID_t *guid)
	Access the GUID which uniquely identifies this participant.

ReturnCode_t	enable ()
	Enables the DomainParticipant. More...

InstanceHandle_t	get_instance_handle ()
	This operation returns the InstanceHandle_t that identifies the DomainParticipant.

ReturnCode_t	register_type (TypeSupport ts, const char type_name)
	Registers a TypeSupport with the Participant. More...

int	check_version (const char major, const char minor, const char *patch)
	Tests the provided version information against the version of the running CoreDX DDS library. More...

void	print_stats ()
	Prints simple summary debug stats to stdout for each Reader and Writer.

Public Member Functions inherited from DDS::Entity
virtual StatusCondition *	get_statuscondition ()
	Gets the StatusCondition associated with this Entity. NOTE: The entity maintains ownership of the statuscondition, and it remains valid only as long as the Entity is valid. Destroying the Entity also destroys the status condition.

Detailed Description

The DomainParticipant is used to configure, create and destroy Publisher, Subscriber and Topic objects.

The DomainParticipant is a container for the objects that it creates. The objects operate within the domain identified by the domain_id provided when the DomainParticipant was created. Objects within different domains do not communicate or interfere with each other.

Member Function Documentation

ReturnCode_t DDS::DomainParticipant::assert_liveliness ( )

This operation manually asserts the liveliness of the DomainParticipant dp.

This operation indicates that the DomainParticipant is still alive. It is effective only if the DomainParticipant contains on ore more DataWriter objects with LIVELINES QoS set to MANUAL_BY_PARTICIPANT. In this case, the operation will assert the liveliness of those particular DataWriter objects.

Note: Writing data via the DataWriter write operation automatically asserts the liveliness of the DataWriter and its containing DomainParticipant. Therefore, the use of DomainParticipant::assert_liveliness() is needed only if the application is not writing data frequently enough to keep the DataWriter considered 'alive'.

int DDS::DomainParticipant::check_version	(	const char *	major,
		const char *	minor,
		const char *	patch
	)

Tests the provided version information against the version of the running CoreDX DDS library.

If the provided major and minor numbers match those of the running library, then the routine returns 0. If the provided numbers are larger than those of the running library, then the routine returns a positive number (indicating that the provided version is greater than the library version). Finaly, if the provied version is less than the library version, a negative number is returned. Currently, the 'patch' value is ignored.

bool DDS::DomainParticipant::contains_entity ( InstanceHandle_t a_handle )

This operation checks whether or not the given handle a_handle represents an object that was created by the DomainParticipant d.

This applies recursively to all objects created by the DomainParticipant.

The routine will return true (non-zero) if the handle is found, zero otherwise.

class ContentFilteredTopic* DDS::DomainParticipant::create_contentfilteredtopic	(	const char *	name,
		class Topic *	related_topic,
		const char *	filter_expression,
		const StringSeq &	filter_parameters
	)

This operation creates a ContentFilteredTopic.

The ContentFilteredTopic is associated with another un-filtered topic related_topic. It applies a filter to the data of the related topic. If a data sample passes the filter, it will be made available to a DataReader associated with the ContentFilteredTopic.

The filter_expression is an SQL like condition expression, and filter_parameters provide optional parameters that are referenced by the filter_expression. The syntax of the filter expression is similar to the WHERE clause in SQL. For example "x<4" is a valid filter expression. It would test that data member 'x' is less than value '4'. If the filter expression evaluates to TRUE, then the data sample will be available, otherwise the data sample would be 'filtered' (excluded).

CoreDX DDS supports the 'LIKE' operator (and NOT LIKE) for regular expression string matching. The pattern string in a LIKE clause can contain '' to match zero or more characters, '_' to match a single character, or '[<characters>]' to match a range of characters.

CoreDX DDS also includes support for the 'IN' operator. This provides a very powerful mechanism for testing that a value appears in a set of values. For example "symbol IN ('ge', 'msft', 'ibm')" will select all samples that have a symbol value of 'ge', 'msft', or 'ibm'. This could also be written as a series of equality tests combined with the OR operator; however, the IN operator is much more efficient. A filter that matches on several hundred or even thousands of values can be implemented very efficiently using the 'IN' operator.

The filter_expression can refer to parameters. The syntax for paramters is the percent sign '' followed by a number. The number is the index of the paramter in the filter_paramters sequence. Parameters are counted starting at zero. So, "%0" refers to the first parameter, and "%4" refers to the fifth paramter. Using this syntax, the expression "x<%0" would test the value of 'x' against the first parameter in the sequence.

class MultiTopic* DDS::DomainParticipant::create_multitopic	(	const char *	name,
		const char *	type_name,
		const char *	subscription_expression,
		const StringSeq &	expression_params
	)

Not Yet Supported:: This operation is not implemented yet.

class Publisher* DDS::DomainParticipant::create_publisher	(	const PublisherQos &	qos,
		PublisherListener *	a_listener,
		StatusMask	mask
	)

This operation creates a Publisher with the specified PublisherQoS settings and PublisherListener.

The value PUBLISHER_QOS_DEFAULT may be provided for the qos argument. This will indicate that the the default publisher QoS settings held in the DomainParticipant should be used.

This operation may fail and return NULL if the QoS settings are internally inconsistent.

class Subscriber* DDS::DomainParticipant::create_subscriber	(	const SubscriberQos &	qos,
		SubscriberListener *	a_listener,
		StatusMask	mask
	)

This operation creates a Subscriber with the specified SubscriberQos and SubscriberListener.

The value SUBSCRIBER_QOS_DEFAULT may be provided for the qos argument. This will indicate that the the default subscriber QoS settings held in the DomainParticipant should be used.

This operation may fail and return NULL if the QoS settings are internally inconsistent.

class Topic* DDS::DomainParticipant::create_topic	(	const char *	topic_name,
		const char *	type_name,
		const TopicQos &	qos,
		TopicListener *	a_listener,
		StatusMask	mask
	)

This operation creates a Topic with the specified TopicQos settings and TopicListener.

The value TOPIC_QOS_DEFAULT may be provided for the qos argument. This will indicate that the the default topic QoS settings held in the DomainParticipant should be used.

The topic is created with a reference to the data type indicated by the type_name argument. The data type must have been registered with the DomainParticipant (by a call to register_type() on the appropriate TypeSupport object) prior to calling create_topic().

This operation may fail and return NULL if the QoS settings are internally inconsistent.

The topic returned from this operation (if not NULL) must be deleted by calling DomainParticipant::delete_topic().

ReturnCode_t DDS::DomainParticipant::delete_contained_entities ( )

This operation deletes all the objects created by means of the create operations on DomainParticipant dp.

This routine will recursively call the corresponding delete_contained_entities() operation on each of the contained objects (Publishers, Subscribers, Topics, ContentFilteredTopics, and MultiTopics). If successful, this operation will recursively delete all objects contained with this DomainParticipant. After successful execution, the application may delete the DomainParticipant by calling DomainParticipantFactory_delete_participant().

If any of the objects cannot be deleted, this routine will return RETCODE_PRECONDITION_NOT_MET.

ReturnCode_t DDS::DomainParticipant::delete_contentfilteredtopic ( class ContentFilteredTopic * a_cft )

This operation deletes a previously allocated ContentFilteredTopic.

This operation will fail if there are any DataReader, DataWriter, ContentFilteredTopic, or MultiTopic objects that reference the specified Topic. In this case, the operation will return RETCODE_PRECONDITION_NOT_MET.

The Topic must be owned by DomainPartipant dp; otherwise RETCODE_PRECONDITION_NOT_MET will be returned.

ReturnCode_t DDS::DomainParticipant::delete_multitopic ( class MultiTopic * a_multitopic )

Not Yet Supported:: This operation is not implemented yet.

ReturnCode_t DDS::DomainParticipant::delete_publisher ( class Publisher * p )

This operation deletes an existing Publisher.

A Publisher cannot be deleted if it contains any DataWriter objects. In this case, delete_publisher will return RETCODE_PRECONDITION_NOT_MET.

If the DomainParticipant dp does not contain the provided Publisher p, the operation will return RETCODE_PRECONDITION_NOT_MET.

ReturnCode_t DDS::DomainParticipant::delete_subscriber ( class Subscriber * s )

This operation deletes an existing Subscriber.

A Subscriber cannot be deleted if it contains any DataReader objects. In this case, delete_subscriber will return RETCODE_PRECONDITION_NOT_MET.

If the DomainParticipant dp does not contain the provided Subscriber s, the operation will return RETCODE_PRECONDITION_NOT_MET.

ReturnCode_t DDS::DomainParticipant::delete_topic ( class Topic * a_topic )

This operation deletes a Topic.

This operation will fail if there are any DataReader, DataWriter, ContentFilteredTopic, or MultiTopic objects that reference the specified Topic. In this case, the operation will return RETCODE_PRECONDITION_NOT_MET.

The Topic must be owned by DomainPartipant dp; otherwise RETCODE_PRECONDITION_NOT_MET will be returned.

ReturnCode_t DDS::DomainParticipant::do_work ( const Duration_t & time_slice )

Transfer control to the DomainParticipant so it can do background processing.

This function is to be called only if the DomainParticipant is configured to use NO threads via the thread_model QoS policy. The participant will continue to execute background processing until at least 'time_slice' time passes. This routine will attempt to use no more than 'time_slice' time, but this is not a guarantee.

Note: If the DomainParticipant has threads (default case), then the Participant takes care of scheduling background work on its own, and this routine is not necessary and should not be called.

ReturnCode_t DDS::DomainParticipant::enable ( )

virtual

Enables the DomainParticipant.

A DomainParticipant is created either enabled or not based on the DomainParticipantFactoryQoS setting entity_factory. When a DomainPartcipant is not enabled, only the following sub-set of all DomainParticipant operations are legal:

operations to get and set QoS policies,
factory operations (create, delete),
get_statuscondition(),
get_status_changes(),
lookup operations

Any other DomainParticipant operation will return the NOT_ENABLED error. DomainParticipant::enable() may be called on an already enabled DomainParticipant [it will have no effect].

Reimplemented from DDS::Entity.

class Topic* DDS::DomainParticipant::find_topic	(	const char *	topic_name,
		const Duration_t &	timeout
	)

This operation returns a Topic identified by the provided topic_name.

If a topic with name topic_name is known to exist, the function returns this matching topic immediately. Otherwise, the operation will block for up to the timeout duration. If a topic with name topic_name is discovered or otherwise created, the operation will cease to wait, and will return the matching topic.

If a matching topic is not known by the time the timout has expired, the operation will return NULL.

Like DomainParticipant::create_topic(), the topic returned from this operation (if not NULL) must be deleted by calling DomainParticipant::delete_topic().

class Subscriber* DDS::DomainParticipant::get_builtin_subscriber ( )

Returns the built-in Subscriber.

Each DomainParticipant contains several built-in Topic objects as well as corresponding DataReader objects to access them. These built-in DataReader objects belong to the single built-in Subscriber that is accessed through this operation.

The built-in Topics are used to communicate information about other DomainParticipant, Topic, DataReader, and DataWriter objects.

An application should not explicitly delete the Subscriber returned by this operation - it is managed internally.

ReturnCode_t DDS::DomainParticipant::get_default_publisher_qos ( PublisherQos & qos )

Provides access to the default PublisherQos settings held in the factory.

The provided qos argument is populated with the default qos settings.

ReturnCode_t DDS::DomainParticipant::get_default_subscriber_qos ( SubscriberQos & qos )

Provides access to the default SubscriberQos settings held in the factory.

The provided qos argument is populated with the default qos settings.

ReturnCode_t DDS::DomainParticipant::get_default_topic_qos ( TopicQos & qos )

Provides access to the default TopicQos settings held in the factory.

The provided qos argument is populated with the default qos settings.

ReturnCode_t DDS::DomainParticipant::get_discovered_participant_data	(	ParticipantBuiltinTopicData *	participant_data,
		InstanceHandle_t &	participant_handle
	)

This operation returns data that describes a particular discovered participant identified by participant_handle.

An appropriate handle can be obtained through a call to DomainParticipant::get_discovered_participants().

If participant_handle does not identify a known DomainParticipant, this routine will return RETCODE_PRECONDITION_NOT_MET.

ReturnCode_t DDS::DomainParticipant::get_discovered_participants ( InstanceHandleSeq * participant_handles )

This operation returns the list of handles identifying the DomainParticipant objects that have been discovered.

The returned list will include only participants which are in the same domain as participant d, and which are not explicitly ignored as a result of a call to DomainParticipant::ignore_participant().

This routine allocates memory to populate the participant_handles sequence. The application is responsible for freeing this memory.

ReturnCode_t DDS::DomainParticipant::get_discovered_topic_data	(	TopicBuiltinTopicData *	topic_data,
		InstanceHandle_t &	topic_handle
	)

This operation returns data that describes a particular discovered topic identified by topic_handle.

An appropriate handle can be obtained through a call to DomainParticipant::get_discovered_topics().

If topic_handle does not identify a known Topic, this routine will return RETCODE_PRECONDITION_NOT_MET.

ReturnCode_t DDS::DomainParticipant::get_discovered_topics ( InstanceHandleSeq * topic_handles )

This operation returns the list of handles identifying the Topic objects that have been discovered.

The returned list will include only topics which are in the same domain as participant d, and which are not explicitly ignored as a result of a call to DomainParticipant::ignore_topic().

This routine allocates memory to populate the topic_handles sequence. The application is responsible for freeing this memory.

DomainParticipantListener* DDS::DomainParticipant::get_listener ( )

This operation returns the currently installed DomainParticipantListener.

Note: Because the infrastructure makes a copy of the listener provided in DomainParticipant::set_listener(), the returned structure pointer will not match the pointer originally provided. However, the function pointers within the structure will match. Also, the application should not free the data referenced by the returned pointer.

StatusMask DDS::DomainParticipant::get_status_changes ( )

virtual

This returns the list of triggered communication statuses in the DomainParticipant.

If the DomainParticipant is not enabled, all statuses will be untriggered. The list returned by get_status_changes may be empty. The list of statuses returned by get_status_changes operation contains statuses that are triggered on the DomainParticipant itself and does not include statuses from contained objects.

Implements DDS::Entity.

ReturnCode_t DDS::DomainParticipant::ignore_participant ( InstanceHandle_t & handle )

Instructs the DomainParticipant dp to ignore the external DomainParticipant identified by handle.

This will cause the infrastructure to behave as if the external participant handle did not exist. The handle can be discovered by accessing the built-in topic DCPSParticipant via the appropriate built-in DataReader.

There is no mechanism to reverse this operation.

ReturnCode_t DDS::DomainParticipant::ignore_publication ( InstanceHandle_t & handle )

This operation instructs the DomainParticipant dp to ignore a Publication identified by handle.

The handle can be discovered by accessing the built-in topic DCPSPublication via the appropriate built-in DataReader.

There is no mechanism to reverse this operation.

Not Yet Supported:: This operation is not implemented yet.

ReturnCode_t DDS::DomainParticipant::ignore_subscription ( InstanceHandle_t & handle )

This operation instructs the DomainParticipant dp to ignore a Subscription identified by handle.

The handle can be discovered by accessing the built-in topic DCPSSubscription via the appropriate built-in DataReader.

There is no mechanism to reverse this operation.

Not Yet Supported:: This operation is not implemented yet.

ReturnCode_t DDS::DomainParticipant::ignore_topic ( InstanceHandle_t & handle )

This operation instructs the DomainParticipant dp to ignore a Topic identified by handle.

This can be used to save resources if a participant will never participate on certain Topics. The handle can be discovered by accessing the built-in topic DCPSTopic via the appropriate built-in DataReader.

There is no mechanism to reverse this operation.

Not Yet Supported:: This operation is not implemented yet.

class TopicDescription* DDS::DomainParticipant::lookup_topicdescription ( const char * name )

This operation returns an existing, locally-created TopicDescription, named name.

If a TopicDescription named name does not exist, then this routine will return NULL.

ReturnCode_t DDS::DomainParticipant::register_type	(	TypeSupport *	ts,
		const char *	type_name
	)

Registers a TypeSupport with the Participant.

Associates a TypeSupport object with the provided 'type_name'. This TypeSupport will be used to handle data that has a matching type_name. If a TypeSupport has already been registered for the provied type_name, then an error is returned and the previously registered TypeSupport is maintained.

ReturnCode_t DDS::DomainParticipant::set_default_publisher_qos ( const PublisherQos & qos )

Sets the default PublisherQos held in the DomainParticipant.

This default qos will be used during subsequent calls to DomainParticipant::create_publisher() if the special PUBLISHER_QOS_DEFAULT value is provided for qos.
This routine may fail if the provided qos argument is not internally consistent. In this case, INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant.

ReturnCode_t DDS::DomainParticipant::set_default_subscriber_qos ( const SubscriberQos & qos )

Sets the default SubscriberQos held in the DomainParticipant.

This default qos will be used during subsequent calls to DomainParticipant::create_subscriber() if the special SUBSCRIBER_QOS_DEFAULT value is provided for qos.
This routine may fail if the provided qos argument is not internally consistent. In this case, INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant.

ReturnCode_t DDS::DomainParticipant::set_default_topic_qos ( const TopicQos & qos )

Sets the default TopicQos held in the DomainParticipant.

This default qos will be used during subsequent calls to DomainParticipant::create_topic() [and related] if the special TOPIC_QOS_DEFAULT value is provided for qos.
This routine may fail if the provided qos argument is not internally consistent. In this case, INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant.

ReturnCode_t DDS::DomainParticipant::set_listener	(	DomainParticipantListener *	a_listener,
		StatusMask	mask
	)

This operation installs a DomainParticipantListener on the DomainParticipant.

Only one listener may be attached to a DomainParticipant at a time. A call to set_listener() will replace any current listener with a_listener.

a_listener can be NULL, which indicates a listener that does nothing.

The infrastructure will make an internal copy of the listener structure so that it need not be persisted by the application.

ReturnCode_t DDS::DomainParticipant::set_qos ( const DomainParticipantQos & qos )

Sets the DomainParticipantQoS values.

These QoS values affect the behavior of the DomainParticipant.

Public Member Functions

Detailed Description

Member Function Documentation