15.1.3.1. DataWriter¶
-
class
eprosima::fastdds::dds
::
DataWriter
: public eprosima::fastdds::dds::DomainEntity¶ Class DataWriter, contains the actual implementation of the behaviour of the DataWriter.
Public Types
-
enum
LoanInitializationKind
¶ How to initialize samples loaned with loan_sample
Values:
-
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.
-
enumerator
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.
-
enumerator
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.
-
enumerator
Public Functions
-
ReturnCode_t
enable
() override¶ This operation enables the DataWriter.
- Return
RETCODE_OK is successfully enabled. RETCODE_PRECONDITION_NOT_MET if the Publisher creating this DataWriter is not enabled.
-
bool
write
(void *data)¶ Write data to the topic.
- Return
True if correct, false otherwise
- Parameters
data
: Pointer to the data
-
bool
write
(void *data, fastrtps::rtps::WriteParams ¶ms)¶ Write data with params to the topic.
- Return
True if correct, false otherwise
- Parameters
data
: Pointer to the dataparams
: Extra write parameters.
-
ReturnCode_t
write
(void *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).
- Return
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.
- Parameters
data
: Pointer to the datahandle
: InstanceHandle_t.
-
InstanceHandle_t
register_instance
(void *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.
- Return
Handle containing the instance’s key. This handle could be used in successive
write
ordispose
operations. In case of error, HANDLE_NIL will be returned.- Parameters
[in] instance
: Sample used to get the instance’s key.
-
ReturnCode_t
unregister_instance
(void *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.
- Return
Returns the operation’s result. If the operation finishes successfully, ReturnCode_t::RETCODE_OK is returned.
- Parameters
[in] instance
: Sample used to deduce instance’s key in case ofhandle
parameter is HANDLE_NIL.[in] handle
: Instance’s key to be unregistered.
-
const fastrtps::rtps::GUID_t &
guid
() const¶ Returns the DataWriter’s GUID
- Return
Reference to the DataWriter GUID
-
InstanceHandle_t
get_instance_handle
() const¶ Returns the DataWriter’s InstanceHandle
- Return
Copy of the DataWriter InstanceHandle
-
TypeSupport
get_type
() const¶ Get data type associated to the DataWriter
- Return
Copy of the TypeSupport
-
ReturnCode_t
wait_for_acknowledgments
(const fastrtps::Duration_t &max_wait)¶ Waits the current thread until all writers have received their acknowledgments.
- Return
RETCODE_OK if the DataWriter receive the acknowledgments before the time expires and RETCODE_ERROR otherwise
- Parameters
max_wait
: Maximum blocking time for this operation
-
ReturnCode_t
get_offered_deadline_missed_status
(OfferedDeadlineMissedStatus &status)¶ Returns the offered deadline missed status.
- Return
RETCODE_OK
- Parameters
[out] status
: Deadline missed status struct
-
ReturnCode_t
get_offered_incompatible_qos_status
(OfferedIncompatibleQosStatus &status)¶ Returns the offered incompatible qos status.
- Return
RETCODE_OK
- Parameters
[out] status
: Offered incompatible qos status struct
-
ReturnCode_t
set_qos
(const DataWriterQos &qos)¶ Establishes the DataWriterQos for this DataWriter.
- Return
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.
- Parameters
qos
: DataWriterQos to be set
-
const DataWriterQos &
get_qos
() const¶ Retrieves the DataWriterQos for this DataWriter.
- Return
Reference to the current DataWriterQos
-
ReturnCode_t
get_qos
(DataWriterQos &qos) const¶ Fills the DataWriterQos with the values of this DataWriter.
- Return
RETCODE_OK
- Parameters
qos
: DataWriterQos object where the qos is returned.
-
Topic *
get_topic
() const¶ Retrieves the topic for this DataWriter.
- Return
Pointer to the associated Topic
-
const DataWriterListener *
get_listener
() const¶ Retrieves the listener for this DataWriter.
- Return
Pointer to the DataWriterListener
-
ReturnCode_t
set_listener
(DataWriterListener *listener)¶ Modifies the DataWriterListener, sets the mask to StatusMask::all()
- Return
RETCODE_OK
- Parameters
listener
: new value for the DataWriterListener
-
ReturnCode_t
set_listener
(DataWriterListener *listener, const StatusMask &mask)¶ Modifies the DataWriterListener.
- Return
RETCODE_OK
- Parameters
listener
: new value for the DataWriterListenermask
: StatusMask that holds statuses the listener responds to (default: all).
-
ReturnCode_t
dispose
(void *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.
- Return
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.
- Parameters
[in] data
: Sample used to deduce instance’s key in case ofhandle
parameter is HANDLE_NIL.[in] handle
: InstanceHandle of the data
-
ReturnCode_t
get_liveliness_lost_status
(LivelinessLostStatus &status)¶ Returns the liveliness lost status.
- Return
RETCODE_OK
- Parameters
status
: Liveliness lost status struct
-
const Publisher *
get_publisher
() const¶ Getter for the Publisher that creates this DataWriter.
- Return
Pointer to the Publisher
-
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.
- Return
RETCODE_OK if asserted, RETCODE_ERROR otherwise
-
ReturnCode_t
clear_history
(size_t *removed)¶ Clears the DataWriter history.
- Return
RETCODE_OK if the samples are removed and RETCODE_ERROR otherwise
- Parameters
removed
: size_t pointer to return the size of the data removed
-
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.
- Return
ReturnCode_t::RETCODE_ILLEGAL_OPERATION when the data type does not support loans.
- Return
ReturnCode_t::RETCODE_NOT_ENABLED if the writer has not been enabled.
- Return
ReturnCode_t::RETCODE_OUT_OF_RESOURCES if the pool has been exhausted.
- Return
ReturnCode_t::RETCODE_OK if a pointer to a sample is successfully obtained.
- Parameters
[out] sample
: Pointer to the sample on the internal pool.[in] initialization
: How to initialize the loaned sample.
-
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
-
enum