| Fast DDS Version 3.3.0 Fast DDS

Loading...
Searching...
No Matches
DataWriter Class Reference
eProsima Fast DDS API Reference » DDS Public API

Class DataWriter, contains the actual implementation of the behaviour of the DataWriter. More...

`#include <DataWriter.hpp>`

Inheritance diagram for DataWriter:
[legend]

## Public Types

enum class | LoanInitializationKind { NO_LOAN_INITIALIZATION , ZERO_LOAN_INITIALIZATION , CONSTRUCTED_LOAN_INITIALIZATION }
| How to initialize samples loaned with loan_sample. More...

## Public Member Functions

virtual | ~DataWriter ()
FASTDDS_EXPORTED_API ReturnCode_t | enable () override
| This operation enables the DataWriter.
FASTDDS_EXPORTED_API ReturnCode_t | write (const void *const data)
| Write data to the topic.
FASTDDS_EXPORTED_API ReturnCode_t | write (const void *const data, fastdds::rtps::WriteParams &params)
| Write data with params to the topic.
FASTDDS_EXPORTED_API ReturnCode_t | write (const void *const data, const InstanceHandle_t &handle)
| Write data with handle.
FASTDDS_EXPORTED_API ReturnCode_t | write_w_timestamp (const void *const data, const InstanceHandle_t &handle, const fastdds::dds::Time_t &timestamp)
| This operation performs the same function as write except that it also provides the value for the source_timestamp that is made available to DataReader objects by means of the source_timestamp attribute "source_timestamp" inside the SampleInfo.
FASTDDS_EXPORTED_API InstanceHandle_t | register_instance (const void *const instance)
| Informs that the application will be modifying a particular instance.
FASTDDS_EXPORTED_API InstanceHandle_t | register_instance_w_timestamp (const void *const instance, const fastdds::dds::Time_t &timestamp)
| This operation performs the same function as register_instance and can be used instead of register_instance in the cases where the application desires to specify the value for the source_timestamp.
FASTDDS_EXPORTED_API ReturnCode_t | unregister_instance (const void *const instance, const InstanceHandle_t &handle)
| This operation reverses the action of register_instance.
FASTDDS_EXPORTED_API ReturnCode_t | unregister_instance_w_timestamp (const void *const instance, const InstanceHandle_t &handle, const fastdds::dds::Time_t &timestamp)
| This operation performs the same function as unregister_instance and can be used instead of unregister_instance in the cases where the application desires to specify the value for the source_timestamp.
FASTDDS_EXPORTED_API ReturnCode_t | get_key_value (void *key_holder, const InstanceHandle_t &handle)
| This operation can be used to retrieve the instance key that corresponds to an instance_handle.
FASTDDS_EXPORTED_API InstanceHandle_t | lookup_instance (const void *const instance) const
| NOT YET IMPLEMENTED.
FASTDDS_EXPORTED_API const fastdds::rtps::GUID_t & | guid () const
| Returns the DataWriter's GUID.
FASTDDS_EXPORTED_API InstanceHandle_t | get_instance_handle () const
| Returns the DataWriter's InstanceHandle.
FASTDDS_EXPORTED_API TypeSupport | get_type () const
| Get data type associated to the DataWriter.
FASTDDS_EXPORTED_API ReturnCode_t | wait_for_acknowledgments (const fastdds::dds::Duration_t &max_wait)
| Waits the current thread until all writers have received their acknowledgments.
FASTDDS_EXPORTED_API ReturnCode_t | get_offered_deadline_missed_status (OfferedDeadlineMissedStatus &status)
| Returns the offered deadline missed status.
FASTDDS_EXPORTED_API ReturnCode_t | get_offered_incompatible_qos_status (OfferedIncompatibleQosStatus &status)
| Returns the offered incompatible qos status.
FASTDDS_EXPORTED_API ReturnCode_t | get_publication_matched_status (PublicationMatchedStatus &status) const
| Returns the publication matched status.
FASTDDS_EXPORTED_API ReturnCode_t | set_qos (const DataWriterQos &qos)
| Establishes the DataWriterQos for this DataWriter.
FASTDDS_EXPORTED_API const DataWriterQos & | get_qos () const
| Retrieves the DataWriterQos for this DataWriter.
FASTDDS_EXPORTED_API ReturnCode_t | get_qos (DataWriterQos &qos) const
| Fills the DataWriterQos with the values of this DataWriter.
FASTDDS_EXPORTED_API Topic * | get_topic () const
| Retrieves the topic for this DataWriter.
FASTDDS_EXPORTED_API const DataWriterListener * | get_listener () const
| Retrieves the listener for this DataWriter.
FASTDDS_EXPORTED_API ReturnCode_t | set_listener (DataWriterListener *listener)
| Modifies the DataWriterListener, sets the mask to StatusMask::all().
FASTDDS_EXPORTED_API ReturnCode_t | set_listener (DataWriterListener *listener, const StatusMask &mask)
| Modifies the DataWriterListener.
FASTDDS_EXPORTED_API ReturnCode_t | dispose (const void *const data, const InstanceHandle_t &handle)
| This operation requests the middleware to delete the data (the actual deletion is postponed until there is no more use for that data in the whole system).
FASTDDS_EXPORTED_API ReturnCode_t | dispose_w_timestamp (const void *const instance, const InstanceHandle_t &handle, const fastdds::dds::Time_t &timestamp)
| This operation performs the same functions as dispose except that the application provides the value for the source_timestamp that is made available to DataReader objects by means of the source_timestamp attribute inside the SampleInfo.
FASTDDS_EXPORTED_API ReturnCode_t | get_liveliness_lost_status (LivelinessLostStatus &status)
| Returns the liveliness lost status.
FASTDDS_EXPORTED_API const Publisher * | get_publisher () const
| Getter for the Publisher that creates this DataWriter.
FASTDDS_EXPORTED_API ReturnCode_t | assert_liveliness ()
| This operation manually asserts the liveliness of the DataWriter.
FASTDDS_EXPORTED_API ReturnCode_t | get_matched_subscription_data (SubscriptionBuiltinTopicData &subscription_data, const InstanceHandle_t &subscription_handle) const
| Retrieves in a subscription associated with the DataWriter.
FASTDDS_EXPORTED_API ReturnCode_t | get_matched_subscriptions (std::vector< InstanceHandle_t > &subscription_handles) const
| Fills the given vector with the InstanceHandle_t of matched DataReaders.
FASTDDS_EXPORTED_API ReturnCode_t | clear_history (size_t *removed)
| Clears the DataWriter history.
FASTDDS_EXPORTED_API ReturnCode_t | loan_sample (void *&sample, LoanInitializationKind initialization=LoanInitializationKind::NO_LOAN_INITIALIZATION)
| Get a pointer to the internal pool where the user could directly write.
FASTDDS_EXPORTED_API ReturnCode_t | discard_loan (void *&sample)
| Discards a loaned sample pointer.
FASTDDS_EXPORTED_API ReturnCode_t | get_sending_locators (rtps::LocatorList &locators) const
| Get the list of locators from which this DataWriter may send data.
FASTDDS_EXPORTED_API ReturnCode_t | wait_for_acknowledgments (const void *const instance, const InstanceHandle_t &handle, const fastdds::dds::Duration_t &max_wait)
| Block the current thread until the writer has received the acknowledgment corresponding to the given instance.
FASTDDS_EXPORTED_API ReturnCode_t | get_publication_builtin_topic_data (PublicationBuiltinTopicData &publication_data) const
| Retrieve the publication data discovery information.
FASTDDS_EXPORTED_API ReturnCode_t | set_sample_prefilter (std::shared_ptr< IContentFilter > prefilter)
| Set a sample prefilter to be used.
FASTDDS_EXPORTED_API ReturnCode_t | set_related_datareader (const DataReader *related_reader)
| This operation sets the key of the DataReader that is related to this DataWriter.
Public Member Functions inherited from DomainEntity
| DomainEntity (const StatusMask &mask=StatusMask::all())
| Constructor.
Public Member Functions inherited from Entity
FASTDDS_EXPORTED_API | Entity (const StatusMask &mask=StatusMask::all())
| Constructor.
void | close ()
| This operation disables the Entity before closing it.
FASTDDS_EXPORTED_API const StatusMask & | get_status_mask () const
| Retrieves the set of relevant statuses for the Entity.
FASTDDS_EXPORTED_API const StatusMask & | get_status_changes () const
| Retrieves the set of triggered statuses in the Entity.
const InstanceHandle_t & | get_instance_handle () const
| Retrieves the instance handler that represents the Entity.
FASTDDS_EXPORTED_API bool | is_enabled () const
| Checks if the Entity is enabled.
FASTDDS_EXPORTED_API bool | operator== (const Entity &other) const
FASTDDS_EXPORTED_API StatusCondition & | get_statuscondition ()
| Allows access to the StatusCondition associated with the Entity.
FASTDDS_EXPORTED_API const StatusCondition & | get_statuscondition () const
| Allows access to the StatusCondition associated with the Entity.

## Protected Member Functions

| DataWriter (DataWriterImpl *impl, const StatusMask &mask=StatusMask::all())
| Create a data writer, assigning its pointer to the associated implementation.
| DataWriter (Publisher *pub, Topic *topic, const DataWriterQos &qos=DATAWRITER_QOS_DEFAULT, DataWriterListener *listener=nullptr, const StatusMask &mask=StatusMask::all())
Protected Member Functions inherited from Entity
FASTDDS_EXPORTED_API void | set_instance_handle (const InstanceHandle_t &handle)
| Setter for the Instance Handle.

## Protected Attributes

DataWriterImpl * | impl_
Protected Attributes inherited from Entity
StatusMask | status_mask_
| StatusMask with relevant statuses set to 1.
StatusCondition | status_condition_
| Condition associated to the Entity.
InstanceHandle_t | instance_handle_
| InstanceHandle associated to the Entity.
bool | enable_
| Boolean that states if the Entity is enabled or disabled.

## Friends

class | PublisherImpl
class | DataWriterImpl

## Detailed Description

Class DataWriter, contains the actual implementation of the behaviour of the DataWriter.

## Member Enumeration Documentation

## ◆ LoanInitializationKind

enum class LoanInitializationKind

strong

How to initialize samples loaned with loan_sample.

Enumerator
NO_LOAN_INITIALIZATION | Do not perform initialization of sample. This is the default initialization scheme of loaned samples. It is the fastest scheme, but implies the user should take care of writing every field on the data type before calling write on the loaned sample.
ZERO_LOAN_INITIALIZATION | Initialize all memory with zero-valued bytes. The contents of the loaned sample will be zero-initialized upon return of loan_sample.
CONSTRUCTED_LOAN_INITIALIZATION | Use in-place constructor initialization. This will call the constructor of the data type over the memory space being returned by loan_sample.

## Constructor & Destructor Documentation

## ◆ DataWriter() [1/2]

DataWriter | ( | DataWriterImpl * | impl,
|  | const StatusMask & | mask = StatusMask::all() )

protected

Create a data writer, assigning its pointer to the associated implementation.

Don't use directly, create DataWriter using create_datawriter from Publisher.

## ◆ DataWriter() [2/2]

DataWriter | ( | Publisher * | pub,
|  | Topic * | topic,
|  | const DataWriterQos & | qos = DATAWRITER_QOS_DEFAULT,
|  | DataWriterListener * | listener = nullptr,
|  | const StatusMask & | mask = StatusMask::all() )

protected

## ◆ ~DataWriter()

virtual ~DataWriter | ( |  | ) |

virtual

## Member Function Documentation

## ◆ assert_liveliness()

FASTDDS_EXPORTED_API ReturnCode_t assert_liveliness | ( |  | ) |

This operation manually asserts the liveliness of the DataWriter.

This is used in combination with the LivelinessQosPolicy to indicate to the Service that the entity remains active. This operation need only be used if the LIVELINESS setting is either MANUAL_BY_PARTICIPANT or MANUAL_BY_TOPIC. Otherwise, it has no effect.

Note
  Writing data via the write operation on a DataWriter asserts liveliness on the DataWriter itself and its DomainParticipant. Consequently the use of assert_liveliness is only needed if the application is not writing data regularly.

Returns
  RETCODE_OK if asserted, RETCODE_ERROR otherwise

## ◆ clear_history()

FASTDDS_EXPORTED_API ReturnCode_t clear_history | ( | size_t * | removed | ) |

Clears the DataWriter history.

Parameters

  removed | size_t pointer to return the size of the data removed

Returns
  RETCODE_OK if the samples are removed and RETCODE_ERROR otherwise

## ◆ discard_loan()

FASTDDS_EXPORTED_API ReturnCode_t discard_loan | ( | void *& | sample | ) |

Discards a loaned sample pointer.

See the description on loan_sample for how and when to call this method.

Parameters

  [in,out] | sample | Pointer to the previously loaned sample.

Returns
  RETCODE_ILLEGAL_OPERATION when the data type does not support loans.
  RETCODE_NOT_ENABLED if the writer has not been enabled.
  RETCODE_BAD_PARAMETER if the pointer does not correspond to a loaned sample.
  RETCODE_OK if the loan is successfully discarded.

## ◆ dispose()

FASTDDS_EXPORTED_API ReturnCode_t dispose | ( | const void *const | data,
|  | const InstanceHandle_t & | handle )

This operation requests the middleware to delete the data (the actual deletion is postponed until there is no more use for that data in the whole system).

In general, applications are made aware of the deletion by means of operations on the DataReader objects that already knew that instance. This operation does not modify the value of the instance. The instance parameter is passed just for the purposes of identifying the instance. When this operation is used, the Service will automatically supply the value of the source_timestamp that is made available to DataReader objects by means of the source_timestamp attribute inside the SampleInfo. The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the unregister_instance operation.

Parameters

  [in] | data | Sample used to deduce instance's key in case of handle parameter is HANDLE_NIL.
  [in] | handle | InstanceHandle of the data

Returns
  RETCODE_PRECONDITION_NOT_MET if the handle introduced does not match with the one associated to the data, RETCODE_OK if the data is correctly sent and RETCODE_ERROR otherwise.

## ◆ dispose_w_timestamp()

FASTDDS_EXPORTED_API ReturnCode_t dispose_w_timestamp | ( | const void *const | instance,
|  | const InstanceHandle_t & | handle,
|  | const fastdds::dds::Time_t & | timestamp )

This operation performs the same functions as dispose except that the application provides the value for the source_timestamp that is made available to DataReader objects by means of the source_timestamp attribute inside the SampleInfo.

The constraints on the values of the `handle` parameter and the corresponding error behavior are the same specified for the dispose operation.

This operation may return RETCODE_PRECONDITION_NOT_MET and RETCODE_BAD_PARAMETER under the same circumstances described for the dispose operation.

This operation may return RETCODE_TIMEOUT and RETCODE_OUT_OF_RESOURCES under the same circumstances described for the write operation.

Parameters

  instance | Sample used to deduce instance's key in case of handle parameter is HANDLE_NIL.
  handle | Instance's key to be disposed.
  timestamp | Time_t used to set the source_timestamp.

Returns
  FASTDDS_EXPORTED_API

## ◆ enable()

FASTDDS_EXPORTED_API ReturnCode_t enable | ( |  | ) |

override virtual

This operation enables the DataWriter.

Returns
  RETCODE_OK is successfully enabled. RETCODE_PRECONDITION_NOT_MET if the Publisher creating this DataWriter is not enabled.

Reimplemented from Entity.

## ◆ get_instance_handle()

FASTDDS_EXPORTED_API InstanceHandle_t get_instance_handle | ( |  | ) | const

Returns the DataWriter's InstanceHandle.

Returns
  Copy of the DataWriter InstanceHandle

## ◆ get_key_value()

FASTDDS_EXPORTED_API ReturnCode_t get_key_value | ( | void * | key_holder,
|  | const InstanceHandle_t & | handle )

This operation can be used to retrieve the instance key that corresponds to an instance_handle.

The operation will only fill the fields that form the key inside the key_holder instance.

This operation may return BAD_PARAMETER if the InstanceHandle_t handle does not correspond to an existing data-object known to the DataWriter. If the implementation is not able to check invalid handles then the result in this situation is unspecified.

Parameters

  [in,out] | key_holder | Sample where the key fields will be returned.
  [in] | handle | Handle to the instance to retrieve the key values from.

Returns
  Any of the standard return codes.

## ◆ get_listener()

FASTDDS_EXPORTED_API const DataWriterListener * get_listener | ( |  | ) | const

Retrieves the listener for this DataWriter.

Returns
  Pointer to the DataWriterListener

## ◆ get_liveliness_lost_status()

FASTDDS_EXPORTED_API ReturnCode_t get_liveliness_lost_status | ( | LivelinessLostStatus & | status | ) |

Returns the liveliness lost status.

Parameters

  status | Liveliness lost status struct

Returns
  RETCODE_OK

## ◆ get_matched_subscription_data()

FASTDDS_EXPORTED_API ReturnCode_t get_matched_subscription_data | ( | SubscriptionBuiltinTopicData & | subscription_data,
|  | const InstanceHandle_t & | subscription_handle ) const

Retrieves in a subscription associated with the DataWriter.

Parameters

  [out] | subscription_data | subscription data struct
  | subscription_handle | InstanceHandle_t of the subscription

Returns
  RETCODE_OK

Warning
  Not supported yet. Currently returns RETCODE_UNSUPPORTED

## ◆ get_matched_subscriptions()

FASTDDS_EXPORTED_API ReturnCode_t get_matched_subscriptions | ( | std::vector< InstanceHandle_t > & | subscription_handles | ) | const

Fills the given vector with the InstanceHandle_t of matched DataReaders.

Parameters

  [out] | subscription_handles | Vector where the InstanceHandle_t are returned

Returns
  RETCODE_OK

Warning
  Not supported yet. Currently returns RETCODE_UNSUPPORTED

## ◆ get_offered_deadline_missed_status()

FASTDDS_EXPORTED_API ReturnCode_t get_offered_deadline_missed_status | ( | OfferedDeadlineMissedStatus & | status | ) |

Returns the offered deadline missed status.

Parameters

  [out] | status | Deadline missed status struct

Returns
  RETCODE_OK

## ◆ get_offered_incompatible_qos_status()

FASTDDS_EXPORTED_API ReturnCode_t get_offered_incompatible_qos_status | ( | OfferedIncompatibleQosStatus & | status | ) |

Returns the offered incompatible qos status.

Parameters

  [out] | status | Offered incompatible qos status struct

Returns
  RETCODE_OK

## ◆ get_publication_builtin_topic_data()

FASTDDS_EXPORTED_API ReturnCode_t get_publication_builtin_topic_data | ( | PublicationBuiltinTopicData & | publication_data | ) | const

Retrieve the publication data discovery information.

Parameters

  [out] | publication_data | The publication data discovery information.

Returns
  NOT_ENABLED if the writer has not been enabled.
  OK if the publication data is returned.

## ◆ get_publication_matched_status()

FASTDDS_EXPORTED_API ReturnCode_t get_publication_matched_status | ( | PublicationMatchedStatus & | status | ) | const

Returns the publication matched status.

Parameters

  [out] | status | publication matched status struct

Returns
  RETCODE_OK

## ◆ get_publisher()

FASTDDS_EXPORTED_API const Publisher * get_publisher | ( |  | ) | const

Getter for the Publisher that creates this DataWriter.

Returns
  Pointer to the Publisher

## ◆ get_qos() [1/2]

FASTDDS_EXPORTED_API const DataWriterQos & get_qos | ( |  | ) | const

Retrieves the DataWriterQos for this DataWriter.

Returns
  Reference to the current DataWriterQos

## ◆ get_qos() [2/2]

FASTDDS_EXPORTED_API ReturnCode_t get_qos | ( | DataWriterQos & | qos | ) | const

Fills the DataWriterQos with the values of this DataWriter.

Parameters

  qos | DataWriterQos object where the qos is returned.

Returns
  RETCODE_OK

## ◆ get_sending_locators()

FASTDDS_EXPORTED_API ReturnCode_t get_sending_locators | ( | rtps::LocatorList & | locators | ) | const

Get the list of locators from which this DataWriter may send data.

Parameters

  [out] | locators | LocatorList where the list of locators will be stored.

Returns
  NOT_ENABLED if the reader has not been enabled.
  OK if a list of locators is returned.

## ◆ get_topic()

FASTDDS_EXPORTED_API Topic * get_topic | ( |  | ) | const

Retrieves the topic for this DataWriter.

Returns
  Pointer to the associated Topic

## ◆ get_type()

FASTDDS_EXPORTED_API TypeSupport get_type | ( |  | ) | const

Get data type associated to the DataWriter.

Returns
  Copy of the TypeSupport

## ◆ guid()

FASTDDS_EXPORTED_API const fastdds::rtps::GUID_t & guid | ( |  | ) | const

Returns the DataWriter's GUID.

Returns
  Reference to the DataWriter GUID

## ◆ loan_sample()

FASTDDS_EXPORTED_API ReturnCode_t loan_sample | ( | void *& | sample,
|  | LoanInitializationKind | initialization = LoanInitializationKind::NO_LOAN_INITIALIZATION )

Get a pointer to the internal pool where the user could directly write.

This method can only be used on a DataWriter for a plain data type. It will provide the user with a pointer to an internal buffer where the data type can be prepared for sending.

When using NO_LOAN_INITIALIZATION on the initialization parameter, which is the default, no assumptions should be made on the contents where the pointer points to, as it may be an old pointer being reused. See LoanInitializationKind for more details.

Once the sample has been prepared, it can then be published by calling write. After a successful call to write, the middleware takes ownership of the loaned pointer again, and the user should not access that memory again.

If, for whatever reason, the sample is not published, the loan can be returned by calling discard_loan.

Parameters

  [out] | sample | Pointer to the sample on the internal pool.
  [in] | initialization | How to initialize the loaned sample.

Returns
  RETCODE_ILLEGAL_OPERATION when the data type does not support loans.
  RETCODE_NOT_ENABLED if the writer has not been enabled.
  RETCODE_OUT_OF_RESOURCES if the pool has been exhausted.
  RETCODE_OK if a pointer to a sample is successfully obtained.

## ◆ lookup_instance()

FASTDDS_EXPORTED_API InstanceHandle_t lookup_instance | ( | const void *const | instance | ) | const

NOT YET IMPLEMENTED.

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.

Parameters

  [in] | instance | Data pointer to the sample

Returns
  handle of the given instance

## ◆ register_instance()

FASTDDS_EXPORTED_API InstanceHandle_t register_instance | ( | const void *const | instance | ) |

Informs that the application will be modifying a particular instance.

It gives an opportunity to the middleware to pre-configure itself to improve performance.

Parameters

  [in] | instance | Sample used to get the instance's key.

Returns
  Handle containing the instance's key. This handle could be used in successive write or dispose operations. In case of error, HANDLE_NIL will be returned.

## ◆ register_instance_w_timestamp()

FASTDDS_EXPORTED_API InstanceHandle_t register_instance_w_timestamp | ( | const void *const | instance,
|  | const fastdds::dds::Time_t & | timestamp )

This operation performs the same function as register_instance and can be used instead of register_instance in the cases where the application desires to specify the value for the source_timestamp.

The source_timestamp potentially affects the relative order in which readers observe events from multiple writers. See the QoS policy DESTINATION_ORDER.

This operation may block and return RETCODE_TIMEOUT under the same circumstances described for the write operation.

This operation may return RETCODE_OUT_OF_RESOURCES under the same circumstances described for the write operation.

Parameters

  instance | Sample used to get the instance's key.
  timestamp | Time_t used to set the source_timestamp.

Returns
  Handle containing the instance's key.

## ◆ set_listener() [1/2]

FASTDDS_EXPORTED_API ReturnCode_t set_listener | ( | DataWriterListener * | listener | ) |

Modifies the DataWriterListener, sets the mask to StatusMask::all().

Parameters

  listener | new value for the DataWriterListener

Returns
  RETCODE_OK

## ◆ set_listener() [2/2]

FASTDDS_EXPORTED_API ReturnCode_t set_listener | ( | DataWriterListener * | listener,
|  | const StatusMask & | mask )

Modifies the DataWriterListener.

Parameters

  listener | new value for the DataWriterListener
  mask | StatusMask that holds statuses the listener responds to (default: all).

Returns
  RETCODE_OK

## ◆ set_qos()

FASTDDS_EXPORTED_API ReturnCode_t set_qos | ( | const DataWriterQos & | qos | ) |

Establishes the DataWriterQos for this DataWriter.

Parameters

  qos | DataWriterQos to be set

Returns
  RETCODE_IMMUTABLE_POLICY if any of the Qos cannot be changed, RETCODE_INCONSISTENT_POLICY if the Qos is not self consistent and RETCODE_OK if the qos is changed correctly.

## ◆ set_related_datareader()

FASTDDS_EXPORTED_API ReturnCode_t set_related_datareader | ( | const DataReader * | related_reader | ) |

This operation sets the key of the DataReader that is related to this DataWriter.

This is used to establish a relationship between a DataReader and a DataWriter in the context of RPC over DDS.

Warning
  This operation is only valid if the entity is not enabled.

Parameters

  [in] | related_reader | Pointer to the DataReader to set as related.

Returns
  RETCODE_OK if the key is set successfully.
  RETCODE_ILLEGAL_OPERATION if this entity is enabled.
  RETCODE_PRECONDITION_NOT_MET if the entity does not belong to the same participant.
  RETCODE_BAD_PARAMETER if the provided GUID is unknown or the pointer is not valid.

## ◆ set_sample_prefilter()

FASTDDS_EXPORTED_API ReturnCode_t set_sample_prefilter | ( | std::shared_ptr< IContentFilter > | prefilter | ) |

Set a sample prefilter to be used.

This filter is always evaluated before sending the sample to any DataReader and prior to any content filtering. Passing a nullptr disables prefiltering.

Parameters

  prefilter | The prefilter to be set.

Returns
  RETCODE_OK if the prefilter is set correctly.

Note
  Prefiltering is currently incompatible with DataSharing.

## ◆ unregister_instance()

FASTDDS_EXPORTED_API ReturnCode_t unregister_instance | ( | const void *const | instance,
|  | const InstanceHandle_t & | handle )

This operation reverses the action of register_instance.

It should only be called on an instance that is currently registered. Informs the middleware that the DataWriter is not intending to modify any more of that data instance. Also indicates that the middleware can locally remove all information regarding that instance.

Parameters

  [in] | instance | Sample used to deduce instance's key in case of handle parameter is HANDLE_NIL.
  [in] | handle | Instance's key to be unregistered.

Returns
  Returns the operation's result. If the operation finishes successfully, RETCODE_OK is returned.

## ◆ unregister_instance_w_timestamp()

FASTDDS_EXPORTED_API ReturnCode_t unregister_instance_w_timestamp | ( | const void *const | instance,
|  | const InstanceHandle_t & | handle,
|  | const fastdds::dds::Time_t & | timestamp )

This operation performs the same function as unregister_instance and can be used instead of unregister_instance in the cases where the application desires to specify the value for the source_timestamp.

The source_timestamp potentially affects the relative order in which readers observe events from multiple writers. See the QoS policy DESTINATION_ORDER.

The constraints on the values of the `handle` parameter and the corresponding error behavior are the same specified for the unregister_instance operation.

This operation may block and return RETCODE_TIMEOUT under the same circumstances described for the write operation

Parameters

  instance | Sample used to deduce instance's key in case of handle parameter is HANDLE_NIL.
  handle | Instance's key to be unregistered.
  timestamp | Time_t used to set the source_timestamp.

Returns
  Handle containing the instance's key.

## ◆ wait_for_acknowledgments() [1/2]

FASTDDS_EXPORTED_API ReturnCode_t wait_for_acknowledgments | ( | const fastdds::dds::Duration_t & | max_wait | ) |

Waits the current thread until all writers have received their acknowledgments.

Parameters

  max_wait | Maximum blocking time for this operation

Returns
  RETCODE_OK if the DataWriter receive the acknowledgments before the time expires and RETCODE_ERROR otherwise

## ◆ wait_for_acknowledgments() [2/2]

FASTDDS_EXPORTED_API ReturnCode_t wait_for_acknowledgments | ( | const void *const | instance,
|  | const InstanceHandle_t & | handle,
|  | const fastdds::dds::Duration_t & | max_wait )

Block the current thread until the writer has received the acknowledgment corresponding to the given instance.

Operations performed on the same instance while the current thread is waiting will not be taken into consideration, i.e. this method may return RETCODE_OK with those operations unacknowledged.

Parameters

  instance | Sample used to deduce instance's key in case of handle parameter is HANDLE_NIL.
  handle | Instance handle of the data.
  max_wait | Maximum blocking time for this operation.

Returns
  RETCODE_NOT_ENABLED if the writer has not been enabled.
  RETCODE_BAD_PARAMETER if instance is not a valid pointer.
  RETCODE_PRECONDITION_NOT_MET if the topic does not have a key, the key is unknown to the writer, or the key is not consistent with handle.
  RETCODE_OK if the DataWriter received the acknowledgments before the time expired.
  RETCODE_TIMEOUT otherwise.

## ◆ write() [1/3]

FASTDDS_EXPORTED_API ReturnCode_t write | ( | const void *const | data | ) |

Write data to the topic.

Parameters

  data | Pointer to the data

Returns
  RETCODE_OK if the data is correctly sent or a ReturnCode related to the specific error otherwise.

## ◆ write() [2/3]

FASTDDS_EXPORTED_API ReturnCode_t write | ( | const void *const | data,
|  | const InstanceHandle_t & | handle )

Write data with handle.

The special value HANDLE_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).

Parameters

  data | Pointer to the data
  handle | InstanceHandle_t.

Returns
  RETCODE_PRECONDITION_NOT_MET if the handle introduced does not match with the one associated to the data, RETCODE_OK if the data is correctly sent and RETCODE_ERROR otherwise.

## ◆ write() [3/3]

FASTDDS_EXPORTED_API ReturnCode_t write | ( | const void *const | data,
|  | fastdds::rtps::WriteParams & | params )

Write data with params to the topic.

Parameters

  data | Pointer to the data
  params | Extra write parameters.

Returns
  RETCODE_OK if the data is correctly sent or a ReturnCode related to the specific error otherwise.

## ◆ write_w_timestamp()

FASTDDS_EXPORTED_API ReturnCode_t write_w_timestamp | ( | const void *const | data,
|  | const InstanceHandle_t & | handle,
|  | const fastdds::dds::Time_t & | timestamp )

This operation performs the same function as write except that it also provides the value for the source_timestamp that is made available to DataReader objects by means of the source_timestamp attribute "source_timestamp" inside the SampleInfo.

The constraints on the values of the `handle` parameter and the corresponding error behavior are the same specified for the write operation. This operation may block and return RETCODE_TIMEOUT under the same circumstances described for the write operation. This operation may return RETCODE_OUT_OF_RESOURCES, RETCODE_PRECONDITION_NOT_MET or RETCODE_BAD_PARAMETER under the same circumstances described for the write operation.

Parameters

  data | Pointer to the data
  handle | InstanceHandle_t
  timestamp | Time_t used to set the source_timestamp.

Returns
  Any of the standard return codes.

## Friends And Related Symbol Documentation

## ◆ DataWriterImpl

friend class DataWriterImpl

friend

## ◆ PublisherImpl

friend class PublisherImpl

friend

## Member Data Documentation

## ◆ impl_

DataWriterImpl* impl_

protected

The documentation for this class was generated from the following file:

- include/fastdds/dds/publisher/DataWriter.hpp