RTI Connext Modern C++ API  Version 6.1.2
dds::pub Namespace Reference

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)

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

There is no way to reverse this operation.

Parameters
participantThe DomainParticipant where the publication will be ignored
handle<<in>> Handle of the dds::pub::DataWriter to be ignored.
Exceptions
Oneof 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
FwdIteratorA 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
Oneof 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
FwdIteratorA 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
writerThe 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
Oneof 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
WriterThe 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)
FwdIteratorThe type of forward iterator passed to this function
Parameters
publisherThe dds::pub::Publisher the DataWriter belongs to
topic_nameName of the dds::topic::Topic associated with the DataWriter that is to be looked up.
beginA forward iterator to the position in the destination container to insert the found DataWriter in
max_sizeOnly 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
WriterThe 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)
BinIteratorBinIterator The type of back-inserting iterator passed to this function
Parameters
publisherThe dds::pub::Publisher the DataWriter belongs to
topic_nameName of the dds::topic::Topic associated with the DataWriter that is to be looked up.
beginA 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)