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.	31.4 Setting Up DataWriterListeners
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.)	31.14.3 Disposing Instances
	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.	31.8 Writing Data
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.	31.6 Statuses for DataWriters
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.	31.16.3 Finding Related DDS Entities
	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