RTI Connext Modern C++ API
Version 5.2.0
|
<<reference-type>> Allows an application to publish data for a dds::topic::Topic More...
#include <dds/pub/DataWriter.hpp>
Public Member Functions | |
DataWriter (const dds::pub::Publisher &pub, const dds::topic::Topic< T > &topic) | |
Creates a DataWriter. | |
DataWriter (const dds::pub::Publisher &pub, const dds::topic::Topic< T > &topic, const dds::pub::qos::DataWriterQos &qos, dds::pub::DataWriterListener< T > *listener=NULL, const dds::core::status::StatusMask &mask=dds::core::status::StatusMask::all()) | |
Creates a DataWriter with QoS and listener. | |
void | write (const T &instance_data) |
Modifies the value of a data instance. | |
void | write (const T &instance_data, const dds::core::Time ×tamp) |
Modifies the value of a data instance and specifies the timestamp. | |
void | write (const T &instance_data, const dds::core::InstanceHandle &handle) |
Modifies the value of a data instance. | |
void | write (const T &instance_data, const dds::core::InstanceHandle &handle, const dds::core::Time &source_timestamp) |
Modifies the value of a data instance and specifies the timestamp. | |
void | write (const dds::topic::TopicInstance< T > &topic_instance) |
Write a dds::topic::TopicInstance. | |
void | write (const dds::topic::TopicInstance< T > &topic_instance, const dds::core::Time ×tamp) |
Write a topic instance with time stamp. | |
template<typename FWIterator > | |
void | write (const FWIterator &begin, const FWIterator &end) |
template<typename FWIterator > | |
void | write (const FWIterator &begin, const FWIterator &end, const dds::core::Time ×tamp) |
template<typename SamplesFWIterator , typename HandlesFWIterator > | |
void | write (const SamplesFWIterator &data_begin, const SamplesFWIterator &data_end, const HandlesFWIterator &handle_begin, const HandlesFWIterator &handle_end) |
Write a series of samples and their parallel instance handles. | |
template<typename SamplesFWIterator , typename HandlesFWIterator > | |
void | write (const SamplesFWIterator &data_begin, const SamplesFWIterator &data_end, const HandlesFWIterator &handle_begin, const HandlesFWIterator &handle_end, const dds::core::Time ×tamp) |
Write a series of samples and their parallel instance handles and a timestamp. | |
DataWriter & | operator<< (const T &data) |
Writes a sample. | |
DataWriter & | operator<< (const std::pair< T, dds::core::Time > &data) |
Writes a sample with a timestamp. | |
DataWriter & | operator<< (const std::pair< T, dds::core::InstanceHandle > &data) |
Writes a sample with an instance handle. | |
const dds::core::InstanceHandle | register_instance (const T &instance_data) |
Informs RTI Connext that the application will be modifying a particar instance. | |
const dds::core::InstanceHandle | register_instance (const T &instance_data, const dds::core::Time &source_timestamp) |
Informs RTI Connext that the application will be modifying a particular instance and specifies the timestamp. | |
DataWriter & | unregister_instance (const dds::core::InstanceHandle &handle) |
Unregister an instance. | |
DataWriter & | unregister_instance (const dds::core::InstanceHandle &handle, const dds::core::Time &source_timestamp) |
Unregister an instance with timestamp. | |
DataWriter & | dispose_instance (const dds::core::InstanceHandle &handle) |
Dispose an instance. | |
DataWriter & | dispose_instance (const dds::core::InstanceHandle &instance_handle, const dds::core::Time &source_timestamp) |
Dispose an instance with a timestamp. | |
T & | key_value (T &key_holder, const dds::core::InstanceHandle &handle) |
Retrieve the instance key that corresponds to an instance handle. | |
dds::topic::TopicInstance< T > & | key_value (dds::topic::TopicInstance< T > &key_holder, const dds::core::InstanceHandle &handle) |
Retrieve the instance key that corresponds to an instance handle. | |
dds::core::InstanceHandle | lookup_instance (const T &key_holder) |
Retrieve the instance handle that corresponds to an instance key_holder. | |
dds::pub::qos::DataWriterQos | qos () const |
Gets the DataWriterQos. | |
void | qos (const dds::pub::qos::DataWriterQos &the_qos) |
Sets the DataWriterQos. | |
DataWriter & | operator<< (const dds::pub::qos::DataWriterQos &the_qos) |
Set the DataWriterQos. | |
const DataWriter & | operator>> (dds::pub::qos::DataWriterQos &the_qos) const |
Get the DataWriterQos. | |
const dds::topic::Topic< T > & | topic () const |
Get the Topic associated with this DataWriter. | |
const dds::pub::Publisher & | publisher () const |
Get the Publisher that owns this DataWriter. | |
void | wait_for_acknowledgments (const dds::core::Duration &max_wait) |
Blocks the calling thread until all data written by reliable DataWriter entity is acknowledged, or until timeout expires. | |
void | listener (DataWriterListener< T > *l, const dds::core::status::StatusMask &mask) |
Sets the DataWriter listener. | |
DataWriterListener< T > * | listener () const |
Returns the listener currently associated with this DataWriter. | |
const dds::core::status::LivelinessLostStatus | liveliness_lost_status () |
Get the LivelinessLostStatus. | |
const dds::core::status::OfferedDeadlineMissedStatus | offered_deadline_missed_status () |
Get the OfferedDeadlineMissedStatus. | |
const dds::core::status::OfferedIncompatibleQosStatus | offered_incompatible_qos_status () |
Get the OfferedIncompatibleQosStatus. | |
const dds::core::status::PublicationMatchedStatus | publication_matched_status () |
Get the PublicationMatchedStatus. | |
void | assert_liveliness () |
Manually asserts the liveliness of this DataWriter. | |
void | unregister_instance (rti::pub::WriteParams ¶ms) |
<<extension>> | |
void | dispose_instance (rti::pub::WriteParams ¶ms) |
<<extension>> | |
void | wait_for_asynchronous_publishing (const dds::core::Duration &max_wait) |
<<extension>> | |
rti::core::status::ReliableWriterCacheChangedStatus | reliable_writer_cache_changed_status () |
<<extension>> Get the reliable cache status for this writer. | |
rti::core::status::ReliableReaderActivityChangedStatus | reliable_reader_activity_changed_status () |
<<extension>> Get the reliable reader activity changed status for this writer | |
rti::core::status::DataWriterCacheStatus | datawriter_cache_status () |
<<extension>> Get the cache status for this writer | |
rti::core::status::DataWriterProtocolStatus | datawriter_protocol_status () |
<<extension>> Get the protocol status for this writer | |
rti::core::status::DataWriterProtocolStatus | matched_subscription_datawriter_protocol_status (const dds::core::InstanceHandle &subscription_handle) |
<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle. | |
rti::core::status::DataWriterProtocolStatus | matched_subscription_datawriter_protocol_status (const rti::core::Locator &subscription_locator) |
<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator | |
void | flush () |
<<extension>> Flushes the batch in progress in the context of the calling thread. | |
void | write (const T &instance_data, rti::pub::WriteParams ¶ms) |
<<extension>> Write with advanced parameters | |
const dds::core::InstanceHandle | register_instance (const T &key, rti::pub::WriteParams ¶ms) |
<<extension>> | |
Public Member Functions inherited from dds::core::Entity | |
void | enable () |
Enables this entity (if it was created disabled) | |
const dds::core::status::StatusMask | status_changes () |
Retrieves the list of communication statuses that are triggered. | |
const dds::core::InstanceHandle | instance_handle () const |
Get the instance handle that represents this entity. | |
void | close () |
Forces the destruction of this entity. | |
void | retain () |
Disables the automatic destruction of this entity. | |
Related Functions | |
(Note that these are not member functions.) | |
void | ignore (dds::domain::DomainParticipant &participant, const dds::core::InstanceHandle &handle) |
Instructs RTI Connext to locally ignore a publication. | |
template<typename FwdIterator > | |
void | ignore (dds::domain::DomainParticipant &participant, FwdIterator begin, FwdIterator end) |
Instructs RTI Connext to locally ignore several publications. | |
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. | |
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. | |
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. | |
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. | |
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. | |
template<typename AnyDataWriterBackInsertIterator > | |
uint32_t | find_datawriters (dds::pub::Publisher publisher, AnyDataWriterBackInsertIterator begin) |
Retrieve all the dds::pub::DataWriter created from this dds::pub::Publisher. | |
template<typename AnyDataWriterForwardIterator > | |
uint32_t | find_datawriters (dds::pub::Publisher publisher, AnyDataWriterForwardIterator begin, uint32_t max_size) |
Retrieve all the dds::pub::DataWriter created from this dds::pub::Publisher. | |
template<typename WRITER > | |
WRITER | find_datawriter_by_topic_name (dds::pub::Publisher publisher, const std::string &topic_name) |
<<extension>> Retrieves a dds::pub::DataWriter with the given name within the dds::pub::Publisher | |
template<typename WRITER > | |
WRITER | find_datawriter_by_name (dds::pub::Publisher publisher, const std::string &datawriter_name) |
<<extension>> Retrieves a dds::pub::DataWriter with the given name within the dds::pub::Publisher | |
template<typename WRITER > | |
WRITER | find_datawriter_by_name (dds::domain::DomainParticipant participant, const std::string &datawriter_name) |
<<extension>> Retrieves a dds::pub::DataWriter within the dds::domain::DomainParticipant with the given name | |
Related Functions inherited from dds::core::Entity | |
template<typename TO , typename FROM > | |
TO | polymorphic_cast (FROM &from) |
Downcasts an Entity to a subclass. | |
<<reference-type>> Allows an application to publish data for a dds::topic::Topic
T | The topic-type that the DataWriter publishes |
A dds::pub::DataWriter is attached to exactly one dds::pub::Publisher, that acts as a factory for it.
A dds::pub::DataWriter is bound to exactly one dds::topic::Topic and therefore to exactly one data type. The dds::topic::Topic must exist prior to the dds::pub::DataWriter's creation.
The following operations may be called even if the dds::pub::DataWriter is not enabled. Other operations will fail with dds::core::NotEnabledError if called on a disabled dds::pub::DataWriter:
Several dds::pub::DataWriter may operate in different threads. If they share the same dds::pub::Publisher, the middleware guarantees that its operations are thread-safe.
The deletion of the dds::pub::DataWriter will automatically unregister all instances. Depending on the settings of the WRITER_DATA_LIFECYCLE QosPolicy, the deletion of the dds::pub::DataWriter may also dispose all instances.
If the DataWriter's dds::core::policy::DestinationOrder::kind is dds::core::policy::DestinationOrderKind::BY_SOURCE_TIMESTAMP, deleting the DataWriter may fail if your application has previously used the operations that receive a timestamp (dds::pub::DataWriter::write(const T&,const dds::core::Time&), dds::pub::DataWriter::register_instance(const T&, const dds::core::Time&), dds::pub::DataWriter::unregister_instance(const dds::core::InstanceHandle&,const dds::core::Time&), or dds::pub::DataWriter::dispose_instance(const dds::core::InstanceHandle&,const dds::core::Time&)) with a timestamp larger (later) than the time at which the writer is deleted. To prevent the deletion from failing in this situation, either:
The DataWriter destructor will not throw any exceptions even if the destruction fails. Calling close() will throw in case of failure One of the Standard Exceptions or dds::core::PreconditionNotMetError.
|
inline |
Creates a DataWriter.
It uses the default DataWriterQos, and sets no listener.
pub | The publisher that this DataWriter belongs to |
topic | The Topic associated with this DataWriter |
|
inline |
Creates a DataWriter with QoS and listener.
When a DataWriter is created, only those transports already registered are available to the DataWriter. See Built-in Transport Plugins for details on when a builtin transport is registered.
pub | The publisher that this DataWriter belongs to |
topic | The Topic associated with this DataWriter |
qos | QoS to be used for creating the new Datawriter. |
listener | The DataWriter listener. The caller owns the listener and is responsible for deleting it only after resetting it or after deleting the DataWriter. |
mask | Changes of communication status to be invoked on the listener |
|
inline |
Modifies the value of a data instance.
This operations does the same as write(const T&, const dds::core::InstanceHandle&) except that it deduces the identity of the instance from instance_data
(by means of the key).
instance_data | The data sample to write. |
|
inline |
Modifies the value of a data instance and specifies the timestamp.
|
inline |
Modifies the value of a data instance.
When this operation is used, RTI Connext will automatically supply the value of the source_timestamp
that is made available to dds::sub::DataReader objects by means of the source_timestamp
attribute inside the dds::sub::SampleInfo. (Refer to dds::sub::SampleInfo and DESTINATION_ORDER QoS policy for details).
As a side effect, this operation asserts liveliness on the dds::pub::DataWriter itself, the dds::pub::Publisher and the dds::domain::DomainParticipant.
Note that the special value dds::core::InstanceHandle::nil() can be used for the parameter handle
. This indicates the identity of the instance should be automatically deduced from the instance_data
(by means of the key
).
If handle
is any value other than dds::core::InstanceHandle::nil(), then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with dds::core::InvalidArgumentError.
RTI Connext will not detect the error when the handle
is any value other than dds::core::InstanceHandle::nil(), corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data
(by means of the key
). RTI Connext will treat as if the write() operation is for the instance as indicated by the handle
.
This operation may block if the RELIABILITY kind
is set to rti::core::policy::ReliabilityKind::RELIABLE and the modification would cause data to be lost or else cause one of the limits specified in the RESOURCE_LIMITS to be exceeded.
Specifically, this operation may block in the following situations (note that the list may not be exhaustive), even if its dds::core::policy::HistoryKind is dds::core::policy::HistoryKind::KEEP_LAST:
max_samples
resource limit is exhausted, RTI Connext is allowed to discard samples of some other instance, as long as at least one sample remains for such an instance. If it is still not possible to make space available to store the modification, the writer is allowed to block. This operation may also block when using rti::core::policy::ReliabilityKind::BEST_EFFORT and rti::core::policy::PublishModeKind_def::ASYNCHRONOUS. In this case, the dds::pub::DataWriter will queue samples until they are sent by the asynchronous publishing thread. The number of samples that can be stored is determined by the dds::core::policy::History. If the asynchronous thread does not send samples fast enough (e.g., when using a slow rti::pub::FlowController), the queue may fill up. In that case, subsequent write calls will block.
If this operation does block for any of the above reasons, the RELIABILITY max_blocking_time
configures the maximum time the write operation may block (waiting for space to become available). If max_blocking_time
elapses before the dds::pub::DataWriter is able to store the modification without exceeding the limits, the operation will time out (dds::core::TimeoutError).
If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance may help freeing up some resources.
This operation will fail with dds::core::PreconditionNotMetError if the timestamp is less than the timestamp used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp).
instance_data | <<in>> The data to write. |
handle | <<in>> Either the handle returned by a previous call to dds::pub::DataWriter::register_instance, or else the special value dds::core::InstanceHandle::nil(). If T has a key, handle must represent a registered instance of type T . Otherwise, this method may fail with dds::core::InvalidArgumentError. |
One | of the Standard Exceptions, dds::core::TimeoutError, dds::core::PreconditionNotMetError, dds::core::OutOfResourcesError, or dds::core::NotEnabledError. |
|
inline |
Modifies the value of a data instance and specifies the timestamp.
Explicitly provides the timestamp that will be available to the dds::sub::DataReader objects by means of the source_timestamp
attribute inside the dds::sub::SampleInfo. (Refer to dds::sub::SampleInfo and DESTINATION_ORDER QoS policy for details)
The constraints on the values of the handle
parameter and the corresponding error behavior are the same specified for the dds::pub::DataWriter::write() operation.
This operation may block and time out (dds::core::TimeoutError) under the same circumtances described for dds::pub::DataWriter::write().
If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance may help free up some resources.
This operation may fail with dds::core::InvalidArgumentError under the same circumstances described for the write operation.
instance_data | <<in>> The data to write. |
handle | <<in>> Either the handle returned by a previous call to dds::pub::DataWriter::register_instance, or else the special value dds::core::InstanceHandle::nil(). If T has a key, handle must represent a registered instance of type T . Otherwise, this method may fail with dds::core::InvalidArgumentError. |
source_timestamp | <<in>> When using dds::core::policy::DestinationOrderKind::BY_SOURCE_TIMESTAMP the timestamp value must be greater than or equal to the timestamp value used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp) However, if it is less than the timestamp of the previous operation but the difference is less than the dds::core::policy::DestinationOrder::source_timestamp_tolerance, the timestamp of the previous operation will be used as the source timestamp of this sample. Otherwise, if the difference is greater than dds::core::policy::DestinationOrder::source_timestamp_tolerance, the function will return dds::core::InvalidArgumentError. |
One | of the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError, or dds::core::NotEnabledError. |
|
inline |
Write a dds::topic::TopicInstance.
A TopicInstance encapsulates the sample and its associated instance handle.
topic_instance | The instance to write. |
|
inline |
Write a topic instance with time stamp.
topic_instance | the TopicInstance to write. |
timestamp | the timestamp for this sample. |
|
inline |
Write a series of samples or TopicInstances
FWIterator | A forward iterator. Depending on its value type this function can write data samples or TopicInstance objects. |
begin | The beginning of the range |
end | The end of the range |
|
inline |
Write a series of samples or TopicInstances with a given timestamp
FWIterator | A forward iterator. Depending on its value type this function can write data samples or TopicInstance objects. |
begin | The beginning of the range |
end | The end of the range |
timestamp | The timestamp to use for all samples in the range |
|
inline |
Write a series of samples and their parallel instance handles.
SamplesFWIterator | Sample forward iterator |
HandlesFWIterator | InstanceHandle forward iterator |
data_begin | The beginning of the data sample range |
data_end | The end of the data sample range |
handle_begin | The beginning of the InstanceHandle range |
handle_end | The end of the InstanceHandle range |
|
inline |
Write a series of samples and their parallel instance handles and a timestamp.
|
inline |
Writes a sample.
|
inline |
Writes a sample with a timestamp.
|
inline |
Writes a sample with an instance handle.
|
inline |
Informs RTI Connext that the application will be modifying a particar instance.
This operation is only useful for keyed data types. Using it for non-keyed types causes no effect and returns dds::core::InstanceHandle::nil(). The operation takes as a parameter an instance (of which only the key value is examined) and returns a handle
that can be used in successive write() or dispose_instance() operations.
The operation gives RTI Connext an opportunity to pre-configure itself to improve performance.
The use of this operation by an application is optional even for keyed types. If an instance has not been pre-registered, the application CPP2_LANGUAGE_ONLY can use the special value dds::core::InstanceHandle::nil() as the dds::core::InstanceHandle parameter to the write or dispose operation can call the write() or dipose_instance() overloads that don't receive a dds::core::InstanceHandle and RTI Connext will auto-register the instance.
For best performance, the operation should be invoked prior to calling any operation that modifies the instance, such as dds::pub::DataWriter::write(), dds::pub::DataWriter::write(const T&,const dds::core::Time&), dds::pub::DataWriter::dispose_instance() and dds::pub::DataWriter::dispose_instance(const dds::core::InstanceHandle&,const dds::core::Time&) and the handle used in conjunction with the data for those calls.
When this operation is used, RTI Connext will automatically supply the value of the source_timestamp
that is used.
This operation may fail and return dds::core::InstanceHandle::nil() if dds::core::policy::ResourceLimits::max_instances limit has been exceeded.
The operation is idempotent. If it is called for an already registered instance, it just returns the already allocated handle. This may be used to lookup and retrieve the handle allocated to a given instance.
This operation can only be called after dds::pub::DataWriter has been enabled. Otherwise, dds::core::InstanceHandle::nil() will be returned.
instance_data | <<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. |
|
inline |
Informs RTI Connext that the application will be modifying a particular instance and specifies the timestamp.
The provided source_timestamp
potentially affects the relative order in which readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details.
This operation may fail and return dds::core::InstanceHandle::nil() if dds::core::policy::ResourceLimits::max_instances limit has been exceeded.
This operation can only be called after dds::pub::DataWriter has been enabled. Otherwise, dds::core::InstanceHandle::nil() will be returned.
instance_data | <<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. |
source_timestamp | <<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. |
|
inline |
Unregister an instance.
This operation is useful only for keyed data types. Using it for non-keyed types causes no effect and reports no error. The operation takes as a parameter an instance (of which only the key value is examined) and a handle.
This operation should only be called on an instance that is currently registered. This includes instances that have been auto-registered by calling operations such as write or dispose as described in dds::pub::DataWriter::register_instance. Otherwise, this operation may fail with dds::core::InvalidArgumentError.
This only need be called just once per instance, regardless of how many times register_instance was called for that instance.
When this operation is used, RTI Connext will automatically supply the value of the source_timestamp
that is used.
This operation informs RTI Connext that the dds::pub::DataWriter is no longer going to provide any information about the instance. This operation also indicates that RTI Connext can locally remove all information regarding that instance. The application should not attempt to use the handle
previously allocated to that instance after calling dds::pub::DataWriter::unregister_instance().
The special value dds::core::InstanceHandle::nil() can be used for the parameter handle
. This indicates that the identity of the instance should be automatically deduced from the instance_data
(by means of the key
).
The parameter handle
must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with dds::core::InvalidArgumentError.
If, after a dds::pub::DataWriter::unregister_instance, the application wants to modify (dds::pub::DataWriter::write() or dds::pub::DataWriter::dispose_instance()) an instance, it has to register it again, or else use the functions that don't receive a dds::core::InstanceHandle.
This operation does not indicate that the instance is deleted (that is the purpose of dds::pub::DataWriter::dispose_instance()). The operation dds::pub::DataWriter::unregister_instance just indicates that the dds::pub::DataWriter no longer has anything to say about the instance. dds::sub::DataReader entities that are reading the instance may receive a sample with dds::sub::status::InstanceState::not_alive_no_writers() for the instance, unless there are other dds::pub::DataWriter objects writing that same instance.
dds::core::policy::WriterDataLifecycle::autodispose_unregistered_instances controls whether instances are automatically disposed when they are unregistered.
This operation can affect the ownership of the data instance (see OWNERSHIP). If the dds::pub::DataWriter was the exclusive owner of the instance, then calling unregister_instance() will relinquish that ownership.
If dds::core::policy::Reliability::kind is set to rti::core::policy::ReliabilityKind::RELIABLE and the unregistration would overflow the resource limits of this writer or of a reader, this operation may block for up to dds::core::policy::Reliability::max_blocking_time; if this writer is still unable to unregister after that period, this method will fail with dds::core::TimeoutError.
handle | <<in>> represents the instance to be unregistered. It must represent an instance that has been registered. Otherwise, this method may fail with dds::core::InvalidArgumentError. |
One | of the Standard Exceptions, dds::core::TimeoutError or dds::core::NotEnabledError |
|
inline |
Unregister an instance with timestamp.
The provided source_timestamp
potentially affects the relative order in which readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details.
The constraints on the values of the handle
parameter and the corresponding error behavior are the same specified for the dds::pub::DataWriter::unregister_instance operation.
This operation may block and may time out (dds::core::TimeoutError) under the same circumtances described for the unregister_instance operation.
handle | <<in>> represents the instance to be unregistered. It must represent an instance that has been registered. Otherwise, this method may fail with dds::core::InvalidArgumentError. |
source_timestamp | <<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. |
One | of the Standard Exceptions, dds::core::TimeoutError or dds::core::NotEnabledError. |
|
inline |
Dispose an instance.
This operation is useful only for keyed data types. Using it for non-keyed types has no effect and reports no error.
The actual deletion is postponed until there is no more use for that data in the whole system.
Applications are made aware of the deletion by means of operations on the dds::sub::DataReader objects that already knew that instance. dds::sub::DataReader objects that didn't know the instance will never see it.
This operation does not modify the value of the instance. The instance_data
parameter is passed just for the purposes of identifying the instance.
When this operation is used, RTI Connext will automatically supply the value of the source_timestamp
that is made available to dds::sub::DataReader objects by means of the source_timestamp
attribute inside the dds::sub::SampleInfo.
The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the dds::pub::DataWriter::unregister_instance operation.
The special value dds::core::InstanceHandle::nil() can be used for the parameter instance_handle
. This indicates the identity of the instance should be automatically deduced from the instance_data
(by means of the key
).
If handle
is any value other than dds::core::InstanceHandle::nil(), then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with dds::core::InvalidArgumentError.
RTI Connext will not detect the error when the handle
is any value other than dds::core::InstanceHandle::nil(), corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data
(by means of the key
). RTI Connext will treat as if the dispose() operation is for the instance as indicated by the handle
.
This operation may block and time out (dds::core::TimeoutError) under the same circumtances described for dds::pub::DataWriter::write()().
If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance may help freeing up some resources.
instance_handle | <<in>> Either the handle returned by a previous call to dds::pub::DataWriter::register_instance, or else the special value dds::core::InstanceHandle::nil(). If T has no key, instance_handle is not used. If handle is used, it must represent a registered instance of type T. Otherwise, this method fail with dds::core::InvalidArgumentError. |
One | of the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError or dds::core::NotEnabledError. |
|
inline |
Dispose an instance with a timestamp.
The constraints on the values of the handle
parameter and the corresponding error behavior are the same specified for the dds::pub::DataWriter::dispose_instance() operation.
This operation may block and time out (dds::core::TimeoutError) under the same circumtances described for dds::pub::DataWriter::write().
If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance may help freeing up some resources.
handle | <<in>> Either the handle returned by a previous call to dds::pub::DataWriter::register_instance, or else the special value dds::core::InstanceHandle::nil(). If T has a key, handle must represent a registered instance of type T . Otherwise, this method may fail with dds::core::InvalidArgumentError. |
source_timestamp | <<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the dds::sub::DataReader objects by means of the source_timestamp attribute inside the dds::sub::SampleInfo. |
One | of the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError or dds::core::NotEnabledError. |
|
inline |
Retrieve the instance key that corresponds to an instance handle.
Useful for keyed data types.
The operation will only fill the fields that form the key
inside the key_holder
instance. If T
has no key, this method has no effect and exit with no error.
For keyed data types, this operation may fail with dds::core::InvalidArgumentError if the handle
does not correspond to an existing data-object known to the dds::pub::DataWriter.
key_holder | <<inout>> a user data type specific key holder, whose key fields are filled by this operation. If T has no key, this method has no effect. |
handle | <<in>> the instance whose key is to be retrieved. If T has a key, handle must represent a registered instance of type T. Otherwise, this method will fail with dds::core::InvalidArgumentError. If T has a key and handle is dds::core::InstanceHandle::nil(), this method will fail with dds::core::InvalidArgumentError. |
One | of the Standard Exceptions or dds::core::NotEnabledError. |
key_holder
|
inline |
Retrieve the instance key that corresponds to an instance handle.
|
inline |
Retrieve the instance handle that corresponds to an instance key_holder.
Useful for keyed data types.
This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument. The instance parameter is only used for the purpose of examining the fields that define the key. This operation does not register the instance in question. If the instance has not been previously registered, or if for any other reason RTI Connext is unable to provide an instance handle, RTI Connext will return the special value HANDLE_NIL.
key_holder | <<in>> a user data type specific key holder. |
T
has no key, this method has no effect and returns dds::core::InstanceHandle::nil()
|
inline |
Gets the DataWriterQos.
|
inline |
Sets the DataWriterQos.
This operation modifies the QoS of the dds::pub::DataWriter.
The dds::core::policy::UserData, dds::core::policy::Deadline, dds::core::policy::LatencyBudget, dds::core::policy::OwnershipStrength, dds::core::policy::TransportPriority, dds::core::policy::Lifespan and dds::core::policy::WriterDataLifecycle can be changed. The other policies are immutable.
the_qos | <<in>> The dds::pub::qos::DataWriterQos to be set to. Policies must be consistent. Immutable policies cannot be changed after dds::pub::DataWriter is enabled. The special value DATAWRITER_QOS_DEFAULT can be used to indicate that the QoS of the dds::pub::DataWriter should be changed to match the current default dds::pub::qos::DataWriterQos set in the dds::pub::Publisher. |
One | of the Standard Exceptions, dds::core::ImmutablePolicyError or dds::core::InconsistentPolicyError |
|
inline |
|
inline |
Get the DataWriterQos.
the_qos | the object to populate with the qos for this DataWriter. |
|
inline |
Get the Topic associated with this DataWriter.
|
inline |
Get the Publisher that owns this DataWriter.
|
inline |
Blocks the calling thread until all data written by reliable DataWriter entity is acknowledged, or until timeout expires.
This operation blocks the calling thread until either all data written by the reliable dds::pub::DataWriter entity is acknowledged by (a) all reliable dds::sub::DataReader entities that are matched and alive and (b) by all required subscriptions, or until the duration specified by the max_wait
parameter elapses, whichever happens first. A successful completion indicates that all the samples written have been acknowledged by all reliable matched data readers and by all required subscriptions; a return value of TIMEOUT indicates that max_wait elapsed before all the data was acknowledged.
Note that if a thread is blocked in the call to wait_for_acknowledgments on a DataWriter and a different thread writes new samples on the same DataWriter, the new samples must be acknowledged before unblocking the thread waiting on wait_for_acknowledgments.
If the dds::pub::DataWriter does not have dds::core::policy::Reliability kind set to RELIABLE, this operation will complete immediately with
max_wait | <<in>> Specifies maximum time to wait for acknowledgements dds::core::Duration . |
One | of the Standard Exceptions, dds::core::NotEnabledError, dds::core::TimeoutError |
|
inline |
Sets the DataWriter listener.
l | The DataWriterListener to set |
mask | The dds::core::status::StatusMask associated with the listener |
|
inline |
Returns the listener currently associated with this DataWriter.
If there's no listener it returns NULL.
|
inline |
Get the LivelinessLostStatus.
This also resets the status so that it is no longer considered changed.
One | of the Standard Exceptions |
|
inline |
Get the OfferedDeadlineMissedStatus.
This also resets the status so that it is no longer considered changed.
One | of the Standard Exceptions |
|
inline |
Get the OfferedIncompatibleQosStatus.
This also resets the status so that it is no longer considered changed.
One | of the Standard Exceptions |
|
inline |
Get the PublicationMatchedStatus.
This also resets the status so that it is no longer considered changed.
One | of the Standard Exceptions |
|
inline |
Manually asserts the liveliness of this DataWriter.
This is used in combination with the LIVELINESS policy to indicate to RTI Connext that the dds::pub::DataWriter remains active.
You only need to use this operation if the LIVELINESS setting is either dds::core::policy::LivelinessKind::MANUAL_BY_PARTICIPANT or dds::core::policy::LivelinessKind::MANUAL_BY_TOPIC. Otherwise, it has no effect.
Note: writing data via the dds::pub::DataWriter::write() or dds::pub::DataWriter::write(const T&,const dds::core::Time&) operation asserts liveliness on the dds::pub::DataWriter itself, and its dds::domain::DomainParticipant. Consequently the use of assert_liveliness() is only needed if the application is not writing data regularly.
One | of the Standard Exceptions or dds::core::NotEnabledError |
void unregister_instance | ( | rti::pub::WriteParams & | params | ) |
void dispose_instance | ( | rti::pub::WriteParams & | params | ) |
void wait_for_asynchronous_publishing | ( | const dds::core::Duration & | max_wait | ) |
This operation blocks the calling thread (up to max_wait
) until all data written by the asynchronous dds::pub::DataWriter is sent and acknowledged (if reliable) by all matched dds::sub::DataReader entities. A successful completion indicates that all the samples written have been sent and acknowledged where applicable; a time out indicates that max_wait
elapsed before all the data was sent and/or acknowledged.
In other words, this guarantees that sending to best effort dds::sub::DataReader is complete in addition to what dds::pub::DataWriter::wait_for_acknowledgments provides.
If the dds::pub::DataWriter does not have rti::core::policy::PublishMode kind set to rti::core::policy::PublishModeKind_def::ASYNCHRONOUS the operation will complete immediately with .
max_wait | <<in>> Specifies maximum time to wait for acknowledgements dds::core::Duration . |
One | of the Standard Exceptions, dds::core::NotEnabledError, dds::core::TimeoutError |
rti::core::status::ReliableWriterCacheChangedStatus reliable_writer_cache_changed_status | ( | ) |
<<extension>> Get the reliable cache status for this writer.
This also resets the status so that it is no longer considered changed.
One | of the Standard Exceptions |
rti::core::status::ReliableReaderActivityChangedStatus reliable_reader_activity_changed_status | ( | ) |
<<extension>> Get the reliable reader activity changed status for this writer
This also resets the status so that it is no longer considered changed.
One | of the Standard Exceptions |
rti::core::status::DataWriterCacheStatus datawriter_cache_status | ( | ) |
<<extension>> Get the cache status for this writer
This also resets the status so that it is no longer considered changed.
One | of the Standard Exceptions or dds::core::NotEnabledError. |
rti::core::status::DataWriterProtocolStatus datawriter_protocol_status | ( | ) |
<<extension>> Get the protocol status for this writer
This also resets the status so that it is no longer considered changed.
One | of the Standard Exceptions or dds::core::NotEnabledError. |
rti::core::status::DataWriterProtocolStatus matched_subscription_datawriter_protocol_status | ( | const dds::core::InstanceHandle & | subscription_handle | ) |
<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle.
This also resets the status so that it is no longer considered changed.
Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.
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. |
One | of the Standard Exceptions or dds::core::NotEnabledError. |
rti::core::status::DataWriterProtocolStatus matched_subscription_datawriter_protocol_status | ( | const rti::core::Locator & | subscription_locator | ) |
<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator
This also resets the status so that it is no longer considered changed.
Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.
One | of the Standard Exceptions or dds::core::NotEnabledError. |
subscription_locator | <<in>> Locator to a specific locator associated with the DataReader. Must correspond to a locator of one or more subscriptions currently associated with the DataWriter. |
void flush | ( | ) |
<<extension>> Flushes the batch in progress in the context of the calling thread.
After being flushed, the batch is available to be sent on the network.
If the dds::pub::DataWriter does not have rti::core::policy::PublishMode kind set to rti::core::policy::PublishModeKind_def::ASYNCHRONOUS, the batch will be sent on the network immediately (in the context of the calling thread).
If the dds::pub::DataWriter does have rti::core::policy::PublishMode kind set to rti::core::policy::PublishModeKind_def::ASYNCHRONOUS, the batch will be sent in the context of the asynchronous publishing thread.
This operation may block in the same conditions as dds::pub::DataWriter::write().
If this operation does block, the RELIABILITY max_blocking_time configures the maximum time the write operation may block (waiting for space to become available). If max_blocking_time elapses before the DDS_DataWriter is able to store the modification without exceeding the limits, the operation will fail with DDS_RETCODE_TIMEOUT.
One | of the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError or dds::core::NotEnabledError. |
void write | ( | const T & | instance_data, |
rti::pub::WriteParams & | params | ||
) |
<<extension>> Write with advanced parameters
Allows provision of the sample identity, related sample identity, source timestamp, instance handle, and publication priority contained in params
.
This operation may block and time out (dds::core::TimeoutError) under the same circumstances described for dds::pub::DataWriter::write().
If there are no instance resources left, this operation may fail with dds::core::OutOfResourcesError. Calling dds::pub::DataWriter::unregister_instance(rti::pub::WriteParams&) may help free up some resources.
This operation may fail with dds::core::InvalidArgumentError under the same circumstances described for the dds::pub::DataWriter::write().
instance_data | <<in>> The data to write. |
params | <<inout>> The write parameters. Note that this is an inout parameter if you activate rti::pub::WriteParams::replace_auto; otherwise it won't be modified. |
One | of the Standard Exceptions, dds::core::TimeoutError, dds::core::OutOfResourcesError or dds::core::NotEnabledError. |
const dds::core::InstanceHandle register_instance | ( | const T & | key, |
rti::pub::WriteParams & | params | ||
) |
|
related |
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.
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. handle
can be obtained by calling dds::core::Entity::instance_handle() for the local DataWriter. There is no way to reverse this operation.
participant | The DomainParticipant where the publication will be ignored |
handle | <<in>> Handle of the dds::pub::DataWriter to be ignored. |
One | of the Standard Exceptions, dds::core::OutOfResourcesError or dds::core::NotEnabledError |
|
related |
Instructs RTI Connext to locally ignore several publications.
FwdIterator | A forward iterator whose value type is dds::core::InstanceHandle |
|
related |
Retrieve the list of subscriptions currently associated with a dds::pub::DataWriter.
Matched subscriptions include all those in the same domain that have a matching dds::topic::Topic, compatible QoS and common partition that the dds::domain::DomainParticipant has not indicated should be "ignored" by means of the dds::sub::ignore operation.
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.
The maximum number of matches possible is configured with rti::core::policy::DomainParticipantResourceLimits. .
One | of the Standard Exceptions, or dds::core::NotEnabledError |
|
related |
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.
FwdIterator | A forward iterator whose value type is dds::core::InstanceHandle |
|
related |
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.
Note: This operation does not retrieve the following information in dds::topic::SubscriptionBuiltinTopicData:
The above information is available through dds::sub::DataReaderListener::on_data_available() (if a reader listener is installed on the SubscriptionBuiltinTopicDataDataReader).
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. |
One | of the Standard Exceptions, or dds::core::NotEnabledError |
|
related |
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.
WRITER | The typed-DataWriter type to look up |
FwdIterator | The type of forward iterator passed to this function |
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 |
|
related |
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.
WRITER | The Typed DataWriter that is being looked up |
BinIterator | BinIterator The type of back-inserting iterator passed to this function |
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 |
|
related |
Retrieve all the dds::pub::DataWriter created from this dds::pub::Publisher.
AnyDataWriterBackInsertIterator | Type of the back-inserting iterator passed into this function |
publisher | The dds::pub::Publisher the DataWriters belong to |
begin | A back-inserting iterator to the position in the destination container to insert the found DataWriters into |
|
related |
Retrieve all the dds::pub::DataWriter created from this dds::pub::Publisher.
AnyDataWriterForwardIterator | A forward iterator whose value type is dds::pub::AnyDataWriter |
publisher | The dds::pub::Publisher the DataWriters belong to |
begin | A forward iterator to the position in the destination container to insert the found DataWriters in |
max_size | The maximum number of DataWriters to return |
|
related |
<<extension>> Retrieves a dds::pub::DataWriter with the given name within the dds::pub::Publisher
Every dds::pub::DataWriter in the system has an entity name which is configured and stored in the <<extension>> EntityName policy, ENTITY_NAME.
This operation retrieves the dds::pub::DataWriter within the dds::pub::Publisher whose name matches the one specified. If there are several dds::pub::DataWriter with the same name within the dds::pub::Publisher, the operation returns the first matching occurrence.
WRITER | The writer type, for example dds::pub::DataWriter<Foo> |
publisher | The dds::pub::Publisher that created the DataWriter to find |
topic_name | Entity name of the DataWriter to find |
|
related |
<<extension>> Retrieves a dds::pub::DataWriter with the given name within the dds::pub::Publisher
Every dds::pub::DataWriter in the system has an entity name which is configured and stored in the <<extension>> EntityName policy, ENTITY_NAME.
This operation retrieves the dds::pub::DataWriter within the dds::pub::Publisher whose name matches the one specified. If there are several dds::pub::DataWriter with the same name within the dds::pub::Publisher, the operation returns the first matching occurrence.
WRITER | The writer type, for example dds::pub::DataWriter<Foo> |
publisher | The dds::pub::Publisher that created the DataWriter to find |
datawriter_name | Entity name of the DataWriter to find |
|
related |
<<extension>> Retrieves a dds::pub::DataWriter within the dds::domain::DomainParticipant with the given name
Every dds::pub::DataWriter in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.
Every dds::pub::Publisher in the system has an entity name which is also configured and stored in the EntityName policy.
This operation retrieves a dds::pub::DataWriter within a dds::pub::Publisher given the specified name which encodes both to the dds::pub::DataWriter and the dds::pub::Publisher name.
If there are several dds::pub::DataWriter with the same name within the corresponding dds::pub::Publisher this function returns the first matching occurrence.
The specified name might be given as a fully-qualified entity name or as a plain name.
The fully qualified entity name is a concatenation of the dds::pub::Publisher to which the dds::pub::DataWriter belongs and the entity name of of the dds::pub::DataWriter itself, separated by a double colon "::". For example: MyPublisherName::MyDataWriterName
The plain name contains the dds::pub::DataWriter name only. In this situation it is implied that the dds::pub::DataWriter belongs to the implicit dds::pub::Publisher so the use of a plain name is equivalent to specifying a fully qualified name with the dds::pub::Publisher name part being "implicit". For example: the plain name "MyDataWriterName" is equivalent to specifiying the fully qualified name "implicit::MyDataWriterName"
The dds::pub::DataWriter is only looked up within the dds::pub::Publisher specified in the fully qualified name, or within the implicit dds::pub::Publisher if the name was not fully qualified.
WRITER | The writer type, for example dds::pub::DataWriter<Foo> |
participant | The dds::domain::DomainParticipant within which the dds::pub::DataWriter exists |
datawriter_name | EntityName of the DataWriter to find |