Contains the type and functions to support publishing topics. More...

Namespaces
	qos
	Contains PublisherQos and DataWriterQos.

Classes
class	AnyDataWriter
	<<reference-type>> This class provides an non-template holder for representing a DataWriter of any type More...

class	AnyDataWriterListener
	The listener to notify status changes for a dds::pub::DataWriter of a generic type. More...

class	CoherentSet
	<<value-type>> A publishing application can request that a set of DDS data-sample changes be propagated in such a way that they are interpreted at the receivers' side as a cohesive set of modifications. More...

class	DataWriter
	<<reference-type>> Allows an application to publish data for a dds::topic::Topic More...

class	DataWriterListener
	The Listener to notify status changes for a dds::pub::DataWriter. More...

class	NoOpDataWriterListener
	A convenience implementation of DataWriterListener where all methods are overridden to do nothing. More...

class	NoOpPublisherListener
	A convenience implementation of PublisherListener where all methods are overridden to do nothing. More...

class	Publisher
	<<reference-type>> A publisher is the object responsible for the actual dissemination of publications. More...

class	PublisherListener
	The listener to notify status changes for a dds::pub::Publisher. More...

class	SuspendedPublication
	<<value-type>> Indicates that the application is about to make multiple modifications using several dds::pub::DataWriter's belonging to the same dds::pub::Publisher More...

Functions
template<typename T >
DataWriter< T >	get (const AnyDataWriter &any_writer)
	Same as AnyDataWriter::get() More...

void	ignore (dds::domain::DomainParticipant &participant, const dds::core::InstanceHandle &handle)
	Instructs RTI Connext to locally ignore a publication. More...

template<typename FwdIterator >
void	ignore (dds::domain::DomainParticipant &participant, FwdIterator begin, FwdIterator end)
	Instructs RTI Connext to locally ignore several publications. More...

template<typename T >
dds::core::InstanceHandleSeq	matched_subscriptions (const dds::pub::DataWriter< T > &writer)
	Retrieve the list of subscriptions currently associated with a dds::pub::DataWriter. More...

template<typename T , typename FwdIterator >
FwdIterator	matched_subscriptions (const dds::pub::DataWriter< T > &writer, FwdIterator begin, FwdIterator end)
	Retrieve the list of subscriptions currently associated with a dds::pub::DataWriter. More...

template<typename T >
const dds::topic::SubscriptionBuiltinTopicData	matched_subscription_data (const dds::pub::DataWriter< T > &writer, const dds::core::InstanceHandle &subscription_handle)
	Retrieves information on a subscription that is currently associated with a dds::pub::DataWriter. More...

template<typename WRITER , typename FwdIterator >
uint32_t	find (const dds::pub::Publisher &publisher, const std::string &topic_name, FwdIterator begin, uint32_t max_size)
	Retrieves the dds::pub::DataWriter for a specific topic name. More...

template<typename WRITER , typename BinIterator >
uint32_t	find (const dds::pub::Publisher &publisher, const std::string &topic_name, BinIterator begin)
	Retrieves the dds::pub::DataWriter for a specific topic name. More...

Detailed Description

Contains the type and functions to support publishing topics.

Function Documentation

◆ get()

template<typename T >

DataWriter< T > get ( const AnyDataWriter & any_writer )

Same as AnyDataWriter::get()

◆ ignore() [1/2]

void ignore	(	dds::domain::DomainParticipant &	participant,
		const dds::core::InstanceHandle &	handle
	)

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 dds::pub::Publisher (see dds::topic::PublicationBuiltinTopicData). After this call, any data written by that publication's dds::pub::DataWriter 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::sub::SampleInfo retrieved when reading data samples from the built-in dds::sub::DataReader for the publication topic.

To ignore a local DataWriter, the handle can be obtained by calling dds::core::Entity::instance_handle() for the local DataWriter.

There is no way to reverse this operation.

Parameters

participant	The DomainParticipant where the publication will be ignored
handle	<<in>> Handle of the dds::pub::DataWriter to be ignored.

Exceptions

One	of the Standard Exceptions, dds::core::OutOfResourcesError or dds::core::NotEnabledError

See also: dds::topic::PublicationBuiltinTopicData; dds::topic::publication_topic_name(); dds::sub::builtin_subscriber

Referenced by ignore().

◆ ignore() [2/2]

template<typename FwdIterator >

void ignore	(	dds::domain::DomainParticipant &	participant,
		FwdIterator	begin,
		FwdIterator	end
	)

Instructs RTI Connext to locally ignore several publications.

Template Parameters

FwdIterator A forward iterator whose value type is dds::core::InstanceHandle

See also: ignore(dds::domain::DomainParticipant&, const dds::core::InstanceHandle&);

References ignore().

◆ matched_subscriptions() [1/2]

template<typename T >

dds::core::InstanceHandleSeq matched_subscriptions ( const dds::pub::DataWriter< T > & writer )

Retrieve the list of subscriptions currently associated with a dds::pub::DataWriter.

A subscription is considered to be matching if all of the following criteria are true:

The subscription is within the same domain as this publication.
The subscription has a matching dds::topic::Topic.
The subscription has compatible QoS.
If the applications are using partitions, the subscription shares a common partition with this publication.
The dds::domain::DomainParticipant has not indicated that the subscription's dds::domain::DomainParticipant should be "ignored" by means of the dds::pub::ignore API.
If the publication is using the rti::core::policy::MultiChannel and the subscription is using a dds::topic::ContentFilteredTopic, there is an intersection between at least one of the associated filters.
If the endpoints need to exchange key material to communicate (i.e., they are securing their communications), the writer has completed the key exchange with reader.

The handles returned list are the ones that RTI Connext uses to locally identify the corresponding matched dds::sub::DataReader entities. These handles match the ones that appear in the dds::sub::SampleInfo::instance_handle field of the dds::sub::SampleInfo when reading the dds::topic::subscription_topic_name() builtin topic.

This API may return the subscription handles of subscriptions that are inactive. dds::pub::DataWriter::is_matched_subscription_active can be used to check this.

The maximum number of matches possible is configured with rti::core::policy::DomainParticipantResourceLimits. .

Exceptions

One	of the Standard Exceptions, or dds::core::NotEnabledError

Referenced by matched_subscriptions().

◆ matched_subscriptions() [2/2]

template<typename T , typename FwdIterator >

FwdIterator matched_subscriptions	(	const dds::pub::DataWriter< T > &	writer,
		FwdIterator	begin,
		FwdIterator	end
	)

Retrieve the list of subscriptions currently associated with a dds::pub::DataWriter.

This operation is similar to matched_subscriptions(const dds::pub::DataWriter<T>&) but it copies the instance handles into an iterator range.

Template Parameters

FwdIterator A forward iterator whose value type is dds::core::InstanceHandle

References matched_subscriptions().

◆ matched_subscription_data()

template<typename T >

const dds::topic::SubscriptionBuiltinTopicData matched_subscription_data	(	const dds::pub::DataWriter< T > &	writer,
		const dds::core::InstanceHandle &	subscription_handle
	)

Retrieves information on a subscription that is currently associated with a dds::pub::DataWriter.

The subscription_handle must correspond to a subscription currently associated with the dds::pub::DataWriter. Otherwise, the operation will fail and fail with dds::core::InvalidArgumentError. Use dds::pub::matched_subscriptions() to find the subscriptions that are currently matched with the dds::pub::DataWriter.

The above information is also available through dds::sub::DataReaderListener::on_data_available() (if a reader listener is installed on the dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData>).

When the subscription data is updated, for example when the content filter property changes, there is a small window of time in between when the DataWriter is made aware of these changes and when they actually take effect. Taking effect in this example means that the DataWriter will perform writer-side filtering using the new filter property values (filter expression and/or parameters).

When the DataWriter is made aware of the changes they will first be seen in the dds::sub::DataReaderListener::on_data_available() of the dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData>. When these changes are applied, they will be seen in the output of this API because this API blocks until the most recent changes known to the DataWriter have taken effect. This API will only block when called outside of a listener callback, in order to not block the internal threads from making progress.

If application behavior depends on being made aware of information about a subscription only after it has taken effect on the DataWriter, the recommended pattern for usage of this API is to wait for subscription data to be received either through polling this API or by installing a listener on the dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData>. When a new sample is received by the builtin DataReader, this API may be called in a separate thread and will return the expected matched subscription data once it has been applied to the DataWriter.

Because this API blocks, it is possible for this API to time out while waiting for the changes to be applied. A timeout may happen if the DataReader's subscription data is changing rapidly, preventing the DataWriter from returning valid information before newer data has been received, or if an application is performing a task in a listener callback, thereby preventing the middleware's threads from executing events in a timely manner.

Note: This operation does not retrieve the dds::topic::SubscriptionBuiltinTopicData::type. This information is available through dds::sub::DataReaderListener::on_data_available() (if a reader listener is installed on the dds::sub::DataReader<dds::topic::SubscriptionBuiltinTopicData>).

Parameters

writer	The DataWriter to which the subscription is associated
subscription_handle	<<in>>. Handle to a specific subscription associated with the dds::sub::DataReader. Must correspond to a subscription currently associated with the dds::pub::DataWriter.

Exceptions

One	of the Standard Exceptions, dds::core::NotEnabledError, or dds::core::TimeoutError

◆ find() [1/2]

template<typename WRITER , typename FwdIterator >

uint32_t find	(	const dds::pub::Publisher &	publisher,
		const std::string &	topic_name,
		FwdIterator	begin,
		uint32_t	max_size
	)

Retrieves the dds::pub::DataWriter for a specific topic name.

This returned dds::pub::DataWriter is either enabled or disabled.

If more than one dds::pub::DataWriter is attached to the dds::pub::Publisher with the same topic_name, then this operation may return any one of them.

MT Safety:: UNSAFE. It is not safe to lookup a dds::pub::DataWriter in one thread while another thread is simultaneously creating or destroying that dds::pub::DataWriter. This function retrieves a previously-created DataWriter belonging to the dds::pub::Publisher that is attached to a dds::topic::Topic with a matching topic name. If no such DataWriter exists, the operation will return an empty container. The use of this operation on the built-in Publisher allows access to the built-in DataWriter entities for the built-in topics

Template Parameters

Writer	The type of the writer. It can be dds::pub::AnyDataWriter, or an instantiation of dds::pub::DataWriter<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)
FwdIterator	The type of forward iterator passed to this function

Parameters

publisher	The dds::pub::Publisher the DataWriter belongs to
topic_name	Name of the dds::topic::Topic associated with the DataWriter that is to be looked up.
begin	A forward iterator to the position in the destination container to insert the found DataWriter in
max_size	Only 1 DataWriter will be returned from this function

Returns: The number of DataWriters that were found (either 0 or 1)

◆ find() [2/2]

template<typename WRITER , typename BinIterator >

uint32_t find	(	const dds::pub::Publisher &	publisher,
		const std::string &	topic_name,
		BinIterator	begin
	)

Retrieves the dds::pub::DataWriter for a specific topic name.

This returned dds::pub::DataWriter is either enabled or disabled.

If more than one dds::pub::DataWriter is attached to the dds::pub::Publisher with the same topic_name, then this operation may return any one of them.

MT Safety:: UNSAFE. It is not safe to lookup a dds::pub::DataWriter in one thread while another thread is simultaneously creating or destroying that dds::pub::DataWriter. This function retrieves a previously created DataWriter belonging to the dds::pub::Publisher that is attached to a dds::topic::Topic with a matching topic name. If no such DataWriter exists, the operation will return an empty container. The use of this operation on the built-in Publisher allows access to the built-in DataWriter entities for the built-in topics

Template Parameters

Writer	The type of the writer. It can be dds::pub::AnyDataWriter, or an instantiation of dds::pub::DataWriter<T> (if T is not the correct type, this function throws dds::core::InvalidDowncastError)
BinIterator	BinIterator The type of back-inserting iterator passed to this function

Parameters

publisher	The dds::pub::Publisher the DataWriter belongs to
topic_name	Name of the dds::topic::Topic associated with the DataWriter that is to be looked up.
begin	A back-inserting iterator to the position in the destination container to insert the found DataWriter into

Returns: The number of DataWriters that were found (either 0 or 1)

Namespaces

Classes

Functions

Detailed Description

Function Documentation

◆ get()

◆ ignore() [1/2]

◆ ignore() [2/2]

◆ matched_subscriptions() [1/2]

◆ matched_subscriptions() [2/2]

◆ matched_subscription_data()

◆ find() [1/2]

◆ find() [2/2]