31. DataWriters

To create a DataWriter, you need a DomainParticipant and a Topic.

You need a DataWriter for each Topic that you want to publish. Once you have a DataWriter, you can use it to perform the operations listed in Table 31.1 DataWriter Operations. The most important operation is write(), described in 31.8 Writing Data. For more details on all operations, see the API Reference HTML documentation.

DataWriters are created by using operations on a DomainParticipant or a Publisher, as described in 31.1 Creating DataWriters. If you use the DomainParticipant’s operations, the DataWriter will belong to an implicit Publisher that is automatically created by the middleware. If you use a Publisher’s operations, the DataWriter will belong to that Publisher. So either way, the DataWriter belongs to a Publisher.

Note: Some operations cannot be used within a listener callback, see 15.8.8.1 Restricted Operations in Listener Callbacks.

Table 31.1 DataWriter Operations

Working with ...

Operation

Description

Reference

DataWriters

assert_liveliness

Manually asserts the liveliness of the DataWriter.

31.17 Asserting Liveliness

enable

Enables the DataWriter.

15.2 Enabling DDS Entities

equals

Compares two DataWriter’s QoS structures for equality.

31.15.2 Comparing QoS Values

get_qos

Gets the QoS.

31.15 Setting DataWriter QosPolicies

lookup_instance

Gets a handle, given an instance. (Useful for keyed data types only.)

31.14.5 Looking up an Instance Handle

set_qos

Modifies the QoS.

31.15 Setting DataWriter QosPolicies

set_qos_with_profile

Modifies the QoS based on a QoS profile.

31.15 Setting DataWriter QosPolicies

get_listener

Gets the currently installed Listener.

31.4 Setting Up DataWriterListeners

set_listener

Replaces the Listener.

FooDataWriter

(See 31.7 Using a Type-Specific DataWriter (FooDataWriter))

dispose

States that the instance no longer exists. (Useful for keyed data types only.)

31.14.3 Disposing Instances

dispose_w_timestamp

Same as dispose, but allows the application to override the automatic source_timestamp. (Useful for keyed data types only.)

flush

Makes the batch available to be sent on the network.

31.9 Flushing Batches of DDS Data Samples

get_key_value

Maps an instance_handle to the corresponding key.

31.14.6 Getting the Key Value for an Instance

narrow

A type-safe way to cast a pointer. This takes a DDSDataWriter pointer and ‘narrows’ it to a ‘FooDataWriter’ where ‘Foo’ is the related data type.

31.7 Using a Type-Specific DataWriter (FooDataWriter)

register_instance

States the intent of the DataWriter to write values of the data-instance that matches a specified key. Improves the performance of subsequent writes to the instance. (Useful for keyed data types only.)

31.14.2 Registering Instances and 31.14.4 Unregistering Instances

register_instance_w_
timestamp

Like register_instance, but allows the application to override the automatic source_timestamp. (Useful for keyed data types only.)

unregister_instance

Reverses register_instance. Relinquishes the ownership of the instance. (Useful for keyed data types only.)

unregister_instance_w_
timestamp

Like unregister_instance, but allows the application to override the automatic source_timestamp. (Useful for keyed data types only.)

write

Writes a new value for a data-instance.

31.8 Writing Data

write_w_timestamp

Same as write, but allows the application to override the automatic source_timestamp.

FooDataWriter

(See 31.7 Using a Type-Specific DataWriter (FooDataWriter))

write_w_params

Same as write, but allows the application to specify parameters such as source timestamp and instance handle.

31.8 Writing Data

dispose_w_params

Same as dispose, but allows the application to specify parameters such as source timestamp and instance handle..

31.14.3 Disposing Instances

register_w_params

Same as register, but allows the application to specify parameters such as source timestamp, instance handle.

31.14.2 Registering Instances and 31.14.4 Unregistering Instances

unregister_w_params

Same as unregister, but allows the application to specify parameters such as source timestamp, and instance handle.

Matched Subscriptions

 

get_matched_
subscriptions

Gets a list of subscriptions that have a matching Topic and compatible QoS. These are the subscriptions currently associated with the DataWriter.

31.16.1 Finding Matching Subscriptions

get_matched_
subscription_data

Gets information on a subscription with a matching Topic and compatible QoS.

get_matched_
subscription_locators

Gets a list of locators for subscriptions that have a matching Topic and compatible QoS. These are the subscriptions currently associated with the DataWriter.

get_matched_
subscription_
participant_data

Gets information about the DomainParticipant of a matching subscription.

31.16.2 Finding the Matching Subscription’s ParticipantBuiltinTopicData

is_matched_subscription_active

Enables you to query whether the matched DataReader (identified using the instance handle returned by get_matched_subscriptions) is active. get_matched_subscriptions returns all matching DataReaders, including those that are not active. This operation enables you to see which matching DataReaders are active.

31.16.1 Finding Matching Subscriptions

Status

get_status_changes

Gets a list of statuses that have changed since the last time the application read the status or the listeners were called.

15.4 Getting Status and Status Changes

get_liveliness_lost_status

Gets LIVELINESS_LOST status.

31.6 Statuses for DataWriters

get_offered_deadline_
missed_status

Gets OFFERED_DEADLINE_MISSED status.

get_offered_
incompatible_qos_status

Gets OFFERED_INCOMPATIBLE_QOS status.

get_publication_match_
status

Gets PUBLICATION_MATCHED_QOS status.

Status
cont'd

get_reliable_writer_
cache_changed_status

Gets RELIABLE_WRITER_CACHE_CHANGED
status

get_reliable_reader_
activity_changed_status

Gets RELIABLE_READER_ACTIVITY_CHANGED status

get_datawriter_cache_
status

Gets DATA_WRITER_CACHE_status

get_datawriter_protocol_status

Gets DATA_WRITER_PROTOCOL status

get_matched_
subscription_datawriter_protocol_status

Gets DATA_WRITER_PROTOCOL status for this DataWriter, per matched subscription identified by the subscription_handle.

31.6 Statuses for DataWriters

get_matched_
subscription_datawriter_protocol_status_
by_locator

Gets DATA_WRITER_PROTOCOL status for this DataWriter, per matched subscription as identified by a locator.

Other

get_publisher

Gets the Publisher to which the DataWriter belongs.

31.16.3 Finding Related DDS Entities

get_topic

Get the Topic associated with the DataWriter.

wait_for_
acknowledgements

Blocks the calling thread until either all data written by the DataWriter is acknowledged by all matched Reliable DataReaders, or until the a specified timeout duration, max_wait, elapses.

31.11 Waiting for Acknowledgments in a DataWriter