<<interface>> Allows an application to set the value of the data to be published under a given DDSTopic. More...

Inheritance diagram for DDSDataWriter:

Public Member Functions
virtual DDS_ReturnCode_t	get_liveliness_lost_status (DDS_LivelinessLostStatus &status)
	Accesses the DDS_LIVELINESS_LOST_STATUS communication status. More...

virtual DDS_ReturnCode_t	get_offered_deadline_missed_status (DDS_OfferedDeadlineMissedStatus &status)
	Accesses the DDS_OFFERED_DEADLINE_MISSED_STATUS communication status. More...

virtual DDS_ReturnCode_t	get_offered_incompatible_qos_status (DDS_OfferedIncompatibleQosStatus &status)
	Accesses the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS communication status. More...

virtual DDS_ReturnCode_t	get_publication_matched_status (DDS_PublicationMatchedStatus &status)
	Accesses the DDS_PUBLICATION_MATCHED_STATUS communication status. More...

virtual DDS_ReturnCode_t	get_reliable_writer_cache_changed_status (DDS_ReliableWriterCacheChangedStatus &status)
	<<extension>> Get the reliable cache status for this writer. More...

virtual DDS_ReturnCode_t	get_reliable_reader_activity_changed_status (DDS_ReliableReaderActivityChangedStatus &status)
	<<extension>> Get the reliable reader activity changed status for this writer. More...

virtual DDS_ReturnCode_t	get_datawriter_cache_status (DDS_DataWriterCacheStatus &status)
	<<extension>> Get the datawriter cache status for this writer. More...

virtual DDS_ReturnCode_t	get_datawriter_protocol_status (DDS_DataWriterProtocolStatus &status)
	<<extension>> Get the datawriter protocol status for this writer. More...

virtual DDS_ReturnCode_t	get_matched_subscription_datawriter_protocol_status (DDS_DataWriterProtocolStatus &status, const DDS_InstanceHandle_t &subscription_handle)
	<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle. More...

virtual DDS_ReturnCode_t	is_matched_subscription_active (DDS_Boolean &is_active, const DDS_InstanceHandle_t &subscription_handle)
	Check if a subscription currently matched with a DataWriter is active. More...

virtual DDS_ReturnCode_t	get_service_request_accepted_status (DDS_ServiceRequestAcceptedStatus &status)
	Accesses the DDS_SERVICE_REQUEST_ACCEPTED_STATUS communication status. More...

virtual DDS_ReturnCode_t	get_matched_subscription_datawriter_protocol_status_by_locator (DDS_DataWriterProtocolStatus &status, const DDS_Locator_t &locator)
	<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator. More...

virtual DDS_ReturnCode_t	assert_liveliness ()
	This operation manually asserts the liveliness of this DDSDataWriter. More...

virtual DDS_ReturnCode_t	get_matched_subscription_locators (DDS_LocatorSeq &locators)
	<<extension>> Retrieve the list of locators for subscriptions currently "associated" with this DDSDataWriter. More...

virtual DDS_ReturnCode_t	get_matched_subscriptions (DDS_InstanceHandleSeq &subscription_handles)
	Retrieve the list of subscriptions currently "associated" with this DDSDataWriter. More...

virtual DDS_ReturnCode_t	get_matched_subscription_data (DDS_SubscriptionBuiltinTopicData &subscription_data, const DDS_InstanceHandle_t &subscription_handle)
	This operation retrieves the information on a subscription that is currently "associated" with the DDSDataWriter. More...

virtual DDS_ReturnCode_t	get_matched_subscription_participant_data (DDS_ParticipantBuiltinTopicData &participant_data, const DDS_InstanceHandle_t &subscription_handle)
	This operation retrieves the information on the discovered DDSDomainParticipant associated with the subscription that is currently matching with the DDSDataWriter. More...

virtual DDSTopic *	get_topic ()
	This operation returns the DDSTopic associated with the DDSDataWriter. More...

virtual DDSPublisher *	get_publisher ()
	This operation returns the DDSPublisher to which the DDSDataWriter belongs. More...

virtual DDS_ReturnCode_t	wait_for_acknowledgments (const DDS_Duration_t &max_wait)
	Blocks the calling thread until all data written by reliable DDSDataWriter entity is acknowledged, or until timeout expires. More...

virtual DDS_ReturnCode_t	is_sample_app_acknowledged (DDS_Boolean &is_app_ack, const struct DDS_SampleIdentity_t &identity)
	This method can be used to see if a sample has been application acknowledged. More...

virtual DDS_ReturnCode_t	wait_for_asynchronous_publishing (const DDS_Duration_t &max_wait)
	<<extension>> Blocks the calling thread until asynchronous sending is complete. More...

virtual DDS_ReturnCode_t	set_qos (const DDS_DataWriterQos &qos)
	Sets the writer QoS. More...

virtual DDS_ReturnCode_t	set_property (const char property_name, const char value, bool propagate)
	Set the value for a property that applies to a DataWriter. More...

virtual DDS_ReturnCode_t	set_qos_with_profile (const char library_name, const char profile_name)
	<<extension>> Change the QoS of this writer using the input XML QoS profile. More...

virtual DDS_ReturnCode_t	get_qos (DDS_DataWriterQos &qos)
	Gets the writer QoS. More...

virtual DDS_ReturnCode_t	set_listener (DDSDataWriterListener *l, DDS_StatusMask mask=DDS_STATUS_MASK_ALL)
	Sets the writer listener. More...

virtual DDSDataWriterListener *	get_listener ()
	Get the writer listener. More...

virtual DDS_ReturnCode_t	flush ()
	<<extension>> Flushes the batch in progress in the context of the calling thread. More...

virtual DDS_ReturnCode_t	take_discovery_snapshot ()
	Take a snapshot of the compatible and incompatible remote readers matched by a local writer. More...

virtual DDS_ReturnCode_t	take_discovery_snapshot (const char *file_name)
	Take a snapshot of the compatible and incompatible remote readers matched by a local writer. More...

virtual DDS_ReturnCode_t	enable ()
	Enables the DDSEntity. More...

virtual DDSStatusCondition *	get_statuscondition ()
	Allows access to the DDSStatusCondition associated with the DDSEntity. More...

virtual DDS_StatusMask	get_status_changes ()
	Retrieves the list of communication statuses in the DDSEntity that are triggered. More...

virtual DDS_InstanceHandle_t	get_instance_handle ()
	Allows access to the DDS_InstanceHandle_t associated with the DDSEntity. More...

virtual DDS_ReturnCode_t	enable ()=0
	Enables the DDSEntity. More...

virtual DDSStatusCondition *	get_statuscondition ()=0
	Allows access to the DDSStatusCondition associated with the DDSEntity. More...

virtual DDS_StatusMask	get_status_changes ()=0
	Retrieves the list of communication statuses in the DDSEntity that are triggered. More...

virtual DDS_InstanceHandle_t	get_instance_handle ()=0
	Allows access to the DDS_InstanceHandle_t associated with the DDSEntity. More...

Detailed Description

<<interface>> Allows an application to set the value of the data to be published under a given DDSTopic.

QoS:: DDS_DataWriterQos

Status:: DDS_LIVELINESS_LOST_STATUS, DDS_LivelinessLostStatus;
DDS_OFFERED_DEADLINE_MISSED_STATUS, DDS_OfferedDeadlineMissedStatus;
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS, DDS_OfferedIncompatibleQosStatus;
DDS_PUBLICATION_MATCHED_STATUS, DDS_PublicationMatchedStatus;
DDS_RELIABLE_READER_ACTIVITY_CHANGED_STATUS, DDS_ReliableReaderActivityChangedStatus;
DDS_RELIABLE_WRITER_CACHE_CHANGED_STATUS, DDS_ReliableWriterCacheChangedStatus.

Listener:: DDSDataWriterListener

A DDSDataWriter is attached to exactly one DDSPublisher, that acts as a factory for it.

A DDSDataWriter is bound to exactly one DDSTopic and therefore to exactly one data type. The DDSTopic must exist prior to the DDSDataWriter's creation.

DDSDataWriter is an abstract class. It must be specialized for each particular application data-type (see USER_DATA). The additional methods or functions that must be defined in the auto-generated class for a hypothetical application type Foo are specified in the example type DDSDataWriter.

The following operations may be called even if the DDSDataWriter is not enabled. Other operations will fail with DDS_RETCODE_NOT_ENABLED if called on a disabled DDSDataWriter:

Several DDSDataWriter may operate in different threads. If they share the same DDSPublisher, the middleware guarantees that its operations are thread-safe.

See also: FooDataWriter; Operations Allowed in Listener Callbacks

Examples: HelloWorldSupport.cxx, and HelloWorld_publisher.cxx.

Member Function Documentation

◆ get_liveliness_lost_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_liveliness_lost_status ( DDS_LivelinessLostStatus & status )

inlinevirtual

Accesses the DDS_LIVELINESS_LOST_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters

status <<inout>> DDS_LivelinessLostStatus to be filled in.

Exceptions

One	of the Standard Return Codes

◆ get_offered_deadline_missed_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_offered_deadline_missed_status ( DDS_OfferedDeadlineMissedStatus & status )

inlinevirtual

Accesses the DDS_OFFERED_DEADLINE_MISSED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters

status <<inout>> DDS_OfferedDeadlineMissedStatus to be filled in.

Exceptions

One	of the Standard Return Codes

◆ get_offered_incompatible_qos_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_offered_incompatible_qos_status ( DDS_OfferedIncompatibleQosStatus & status )

inlinevirtual

Accesses the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters

status <<inout>> DDS_OfferedIncompatibleQosStatus to be filled in.

Exceptions

One	of the Standard Return Codes

◆ get_publication_matched_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_publication_matched_status ( DDS_PublicationMatchedStatus & status )

inlinevirtual

Accesses the DDS_PUBLICATION_MATCHED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters

status <<inout>> DDS_PublicationMatchedStatus to be filled in.

Exceptions

One	of the Standard Return Codes

◆ get_reliable_writer_cache_changed_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_reliable_writer_cache_changed_status ( DDS_ReliableWriterCacheChangedStatus & status )

inlinevirtual

<<extension>> Get the reliable cache status for this writer.

This also resets the status so that it is no longer considered changed.

Parameters

status <<inout>> DDS_ReliableWriterCacheChangedStatus to be filled in.

Exceptions

One	of the Standard Return Codes

◆ get_reliable_reader_activity_changed_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_reliable_reader_activity_changed_status ( DDS_ReliableReaderActivityChangedStatus & status )

inlinevirtual

<<extension>> Get the reliable reader activity changed status for this writer.

This also resets the status so that it is no longer considered changed.

Parameters

status <<inout>> DDS_ReliableReaderActivityChangedStatus to be filled in.

Exceptions

One	of the Standard Return Codes

◆ get_datawriter_cache_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_datawriter_cache_status ( DDS_DataWriterCacheStatus & status )

inlinevirtual

<<extension>> Get the datawriter cache status for this writer.

This also resets the status so that it is no longer considered changed.

Parameters

status <<inout>> DDS_DataWriterCacheStatus to be filled in.

Exceptions

One	of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ get_datawriter_protocol_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_datawriter_protocol_status ( DDS_DataWriterProtocolStatus & status )

inlinevirtual

<<extension>> Get the datawriter protocol status for this writer.

This also resets the status so that it is no longer considered changed.

Parameters

status <<inout>> DDS_DataWriterProtocolStatus to be filled in.

Exceptions

One	of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ get_matched_subscription_datawriter_protocol_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_matched_subscription_datawriter_protocol_status	(	DDS_DataWriterProtocolStatus &	status,
		const DDS_InstanceHandle_t &	subscription_handle
	)

inlinevirtual

<<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.

Parameters

status	<<inout>> DDS_DataWriterProtocolStatus to be filled in.
subscription_handle	<<in>> Handle to a specific subscription associated with the DDSDataReader. Must correspond to a subscription currently associated with the DDSDataWriter.

Exceptions

One	of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ is_matched_subscription_active()

virtual DDS_ReturnCode_t DDSDataWriter::is_matched_subscription_active	(	DDS_Boolean &	is_active,
		const DDS_InstanceHandle_t &	subscription_handle
	)

inlinevirtual

Check if a subscription currently matched with a DataWriter is active.

This API is used for querying the endpoint liveliness of a matched subscription. A matched subscription will be marked as inactive when it becomes nonprogessing (e.g., not responding to a DataWriter's heartbeats, or letting its internal queue fill up without taking the available data). Note that if the participant associated with the matched subscription loses liveliness, the DDS_InstanceHandle_t will become invalid and this function will fail with DDS_RETCODE_BAD_PARAMETER.

Parameters

subscription_handle	<<in>> The DDS_InstanceHandle_t of the matched subscription. See DDSDataWriter::get_matched_subscriptions for a description of what is considered a matched subscription.
is_active	<<out>> Indicates whether or not the matched subscription is active.

Exceptions

One	of the Standard Return Codes

◆ get_service_request_accepted_status()

virtual DDS_ReturnCode_t DDSDataWriter::get_service_request_accepted_status ( DDS_ServiceRequestAcceptedStatus & status )

inlinevirtual

Accesses the DDS_SERVICE_REQUEST_ACCEPTED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters

status <<inout>> DDS_ServiceRequestAcceptedStatus to be filled in.

Exceptions

One	of the Standard Return Codes

◆ get_matched_subscription_datawriter_protocol_status_by_locator()

virtual DDS_ReturnCode_t DDSDataWriter::get_matched_subscription_datawriter_protocol_status_by_locator	(	DDS_DataWriterProtocolStatus &	status,
		const DDS_Locator_t &	locator
	)

inlinevirtual

<<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.

Parameters

status	<<inout>> DDS_DataWriterProtocolStatus to be filled in
locator	<<in>> Locator to a specific locator associated with the DDSDataReader. Must correspond to a locator of one or more subscriptions currently associated with the DDSDataWriter.

Exceptions

One	of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ assert_liveliness()

virtual DDS_ReturnCode_t DDSDataWriter::assert_liveliness ( )

inlinevirtual

This operation manually asserts the liveliness of this DDSDataWriter.

This is used in combination with the LIVELINESS policy to indicate to RTI Connext that the DDSDataWriter remains active.

You only need to use this operation if the LIVELINESS setting is either DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS or DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS. Otherwise, it has no effect.

Note: writing data via the FooDataWriter::write or FooDataWriter::write_w_timestamp operation asserts liveliness on the DDSDataWriter itself, and its DDSDomainParticipant. Consequently the use of assert_liveliness() is only needed if the application is not writing data regularly.

Exceptions

One	of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

See also: DDS_LivelinessQosPolicy

◆ get_matched_subscription_locators()

virtual DDS_ReturnCode_t DDSDataWriter::get_matched_subscription_locators ( DDS_LocatorSeq & locators )

inlinevirtual

<<extension>> Retrieve the list of locators for subscriptions currently "associated" with this DDSDataWriter.

The locators returned in the locators list are the ones that are used by the DDS implementation to communicate with the corresponding matched DDSDataReader entities.

Parameters

locators <<inout>>. Handles of all the matched subscription locators.

The sequence will be grown if the sequence has ownership and the system has the corresponding resources. Use a sequence without ownership to avoid dynamic memory allocation. If the sequence is too small to store all the matches and the system can not resize the sequence, this method will fail with DDS_RETCODE_OUT_OF_RESOURCES. .

Exceptions

One	of the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system can not resize it, or DDS_RETCODE_NOT_ENABLED

◆ get_matched_subscriptions()

virtual DDS_ReturnCode_t DDSDataWriter::get_matched_subscriptions ( DDS_InstanceHandleSeq & subscription_handles )

inlinevirtual

Retrieve the list of subscriptions currently "associated" with this DDSDataWriter.

A subscription is considered to be matching if all of the following criteria are true:

The subscription is within the same domain as this publication.
The subscription has a matching DDSTopic.
The subscription has compatible QoS.
If the applications are using partitions, the subscription shares a common partition with this publication.
The DDSDomainParticipant has not indicated that the subscription's DDSDomainParticipant should be "ignored" by means of the DDSDomainParticipant::ignore_publication API.
If the publication is using the DDS_MultiChannelQosPolicy and the subscription is using a DDSContentFilteredTopic, there is an intersection between at least one of the associated filters.
If the endpoints need to exchange key material to communicate (i.e., they are securing their communications), the writer has completed the key exchange with reader.

The handles returned in the subscription_handles list are the ones that RTI Connext uses to locally identify the corresponding matched DDSDataReader entities. These handles match the ones that appear in the DDS_SampleInfo::instance_handle field of the DDS_SampleInfo when reading the DDS_SUBSCRIPTION_TOPIC_NAME builtin topic.

This API may return the subscription handles of subscriptions that are inactive. DDSDataWriter::is_matched_subscription_active can be used to check this.

Parameters

subscription_handles <<inout>>. The handles of all the matched subscriptions.

The sequence will be grown if the sequence has ownership and the system has the corresponding resources. Use a sequence without ownership to avoid dynamic memory allocation. If the sequence is too small to store all of the matches and the system cannot resize the sequence, this method will fail with DDS_RETCODE_OUT_OF_RESOURCES.

The maximum number of matches possible is configured with DDS_DomainParticipantResourceLimitsQosPolicy. You can use a zero-maximum sequence without ownership to quickly check whether there are any matches without allocating any memory. .

Exceptions

One	of the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system cannot resize it, or DDS_RETCODE_NOT_ENABLED

◆ get_matched_subscription_data()

virtual DDS_ReturnCode_t DDSDataWriter::get_matched_subscription_data	(	DDS_SubscriptionBuiltinTopicData &	subscription_data,
		const DDS_InstanceHandle_t &	subscription_handle
	)

inlinevirtual

This operation retrieves the information on a subscription that is currently "associated" with the DDSDataWriter.

The subscription_handle must correspond to a subscription currently associated with the DDSDataWriter. Otherwise, the operation will fail and fail with DDS_RETCODE_BAD_PARAMETER. Use DDSDataWriter::get_matched_subscriptions to find the subscriptions that are currently matched with the DDSDataWriter.

The above information is also available through DDSDataReaderListener::on_data_available() (if a reader listener is installed on the DDSSubscriptionBuiltinTopicDataDataReader).

When the subscription data is updated, for example when the content filter property changes, there is a small window of time in between when the DataWriter is made aware of these changes and when they actually take effect. Taking effect in this example means that the DataWriter will perform writer-side filtering using the new filter property values (filter expression and/or parameters).

When the DataWriter is made aware of the changes they will first be seen in the DDSDataReaderListener::on_data_available() of the DDSSubscriptionBuiltinTopicDataDataReader. When these changes are applied, they will be seen in the output of this API because this API blocks until the most recent changes known to the DataWriter have taken effect. This API will only block when called outside of a listener callback, in order to not block the internal threads from making progress.

If application behavior depends on being made aware of information about a subscription only after it has taken effect on the DataWriter, the recommended pattern for usage of this API is to wait for subscription data to be received either through polling this API or by installing a listener on the DDSSubscriptionBuiltinTopicDataDataReader. When a new sample is received by the builtin DataReader, this API may be called in a separate thread and will return the expected matched subscription data once it has been applied to the DataWriter.

Because this API blocks, it is possible for this API to time out while waiting for the changes to be applied. A timeout may happen if the DataReader's subscription data is changing rapidly, preventing the DataWriter from returning valid information before newer data has been received, or if an application is performing a task in a listener callback, thereby preventing the middleware's threads from executing events in a timely manner.

Note: This operation does not retrieve the DDS_SubscriptionBuiltinTopicData::type_code. This information is available through DDSDataReaderListener::on_data_available() (if a reader listener is installed on the DDSSubscriptionBuiltinTopicDataDataReader).

Parameters

subscription_data	<<inout>>. The information to be filled in on the associated subscription. Cannot be NULL.
subscription_handle	<<in>>. Handle to a specific subscription associated with the DDSDataReader. Must correspond to a subscription currently associated with the DDSDataWriter.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, or DDS_RETCODE_TIMEOUT

◆ get_matched_subscription_participant_data()

virtual DDS_ReturnCode_t DDSDataWriter::get_matched_subscription_participant_data	(	DDS_ParticipantBuiltinTopicData &	participant_data,
		const DDS_InstanceHandle_t &	subscription_handle
	)

inlinevirtual

This operation retrieves the information on the discovered DDSDomainParticipant associated with the subscription that is currently matching with the DDSDataWriter.

The subscription_handle must correspond to a subscription currently associated with the DDSDataWriter. Otherwise, the operation will fail with DDS_RETCODE_BAD_PARAMETER. The operation may also fail with DDS_RETCODE_PRECONDITION_NOT_MET if the subscription corresponds to the same DDSDomainParticipant that the DataWriter belongs to. Use DDSDataWriter::get_matched_subscriptions to find the subscriptions that are currently matched with the DDSDataWriter.

Parameters

participant_data	<<inout>>. The information to be filled in on the associated participant Cannot be NULL.
subscription_handle	<<in>>. Handle to a specific subscription associated with the DDSDataReader. Must correspond to a subscription currently associated with the DDSDataWriter.

Exceptions

One	of the Standard Return Codes, or DDS_RETCODE_NOT_ENABLED

◆ get_topic()

virtual DDSTopic * DDSDataWriter::get_topic ( )

inlinevirtual

This operation returns the DDSTopic associated with the DDSDataWriter.

This is the same DDSTopic that was used to create the DDSDataWriter.

Returns: DDSTopic that was used to create the DDSDataWriter.

◆ get_publisher()

virtual DDSPublisher * DDSDataWriter::get_publisher ( )

inlinevirtual

This operation returns the DDSPublisher to which the DDSDataWriter belongs.

Returns: DDSPublisher to which the DDSDataWriter belongs.

◆ wait_for_acknowledgments()

virtual DDS_ReturnCode_t DDSDataWriter::wait_for_acknowledgments ( const DDS_Duration_t & max_wait )

inlinevirtual

Blocks the calling thread until all data written by reliable DDSDataWriter entity is acknowledged, or until timeout expires.

This operation blocks the calling thread until either all data written by the reliable DDSDataWriter entity is acknowledged by (a) all reliable DDSDataReader 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 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 DDSDataWriter does not have DDS_ReliabilityQosPolicy kind set to RELIABLE, this operation will succeed immediately.

Parameters

max_wait <<in>> Specifies maximum time to wait for acknowledgements DDS_Duration_t .

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_TIMEOUT

◆ is_sample_app_acknowledged()

virtual DDS_ReturnCode_t DDSDataWriter::is_sample_app_acknowledged	(	DDS_Boolean &	is_app_ack,
		const struct DDS_SampleIdentity_t &	identity
	)

inlinevirtual

This method can be used to see if a sample has been application acknowledged.

This method can be used to see if a sample has been application acknowledged by all the matching DataReaders that were alive when the sample was written.

If a DataReader does not enable application acknowledgment (by setting DDS_ReliabilityQosPolicy::acknowledgment_kind to a value other than DDS_PROTOCOL_ACKNOWLEDGMENT_MODE), the sample is considered application acknowledged for that DataReader.

Parameters

is_app_ack	<<out>> This value will be set to DDS_BOOLEAN_TRUE when the sample has been acknowledged.
identity	<<in>> Sample identity.

Exceptions

One	of the Standard Return Codes

◆ wait_for_asynchronous_publishing()

virtual DDS_ReturnCode_t DDSDataWriter::wait_for_asynchronous_publishing ( const DDS_Duration_t & max_wait )

inlinevirtual

<<extension>> Blocks the calling thread until asynchronous sending is complete.

This operation blocks the calling thread (up to max_wait) until all data written by the asynchronous DDSDataWriter is sent and acknowledged (if reliable) by all matched DDSDataReader 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 DDSDataReader is complete in addition to what DDSDataWriter::wait_for_acknowledgments provides.

If the DDSDataWriter does not have DDS_PublishModeQosPolicy kind set to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS the operation will complete immediately with DDS_RETCODE_OK.

Parameters

max_wait <<in>> Specifies maximum time to wait for acknowledgements DDS_Duration_t .

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_TIMEOUT

◆ set_qos()

virtual DDS_ReturnCode_t DDSDataWriter::set_qos ( const DDS_DataWriterQos & qos )

inlinevirtual

Sets the writer QoS.

This operation modifies the QoS of the DDSDataWriter.

The DDS_DataWriterQos::user_data, DDS_DataWriterQos::deadline, DDS_DataWriterQos::latency_budget, DDS_DataWriterQos::ownership_strength, DDS_DataWriterQos::transport_priority, DDS_DataWriterQos::lifespan and DDS_DataWriterQos::writer_data_lifecycle can be changed. The other policies are immutable.

Parameters

qos <<in>> The DDS_DataWriterQos to be set to. Policies must be consistent. Immutable policies cannot be changed after DDSDataWriter is enabled. The special value DDS_DATAWRITER_QOS_DEFAULT can be used to indicate that the QoS of the DDSDataWriter should be changed to match the current default DDS_DataWriterQos set in the DDSPublisher.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY or DDS_RETCODE_INCONSISTENT_POLICY

See also: DDS_DataWriterQos for rules on consistency among QoS; set_qos (abstract); Operations Allowed in Listener Callbacks

◆ set_property()

virtual DDS_ReturnCode_t DDSDataWriter::set_property	(	const char *	property_name,
		const char *	value,
		bool	propagate
	)

inlinevirtual

Set the value for a property that applies to a DataWriter.

Warning: This method is not implemented in all APIs and it's intended only for testing purposes. You should use DDSDataWriter::set_qos instead.

Parameters

property_name	<<in>>. Name of the property that you want to set.
value	<<in>>. New value for the property.
propagate	<<in>>. Indicates if the property will be propagated or not.

Exceptions

One	of the Standard Return Codes

See also: DDSDomainParticipant::set_property; DDSDataReader::set_property; DDSDataWriter::set_qos

◆ set_qos_with_profile()

virtual DDS_ReturnCode_t DDSDataWriter::set_qos_with_profile	(	const char *	library_name,
		const char *	profile_name
	)

inlinevirtual

<<extension>> Change the QoS of this writer using the input XML QoS profile.

This operation modifies the QoS of the DDSDataWriter.

The DDS_DataWriterQos::user_data, DDS_DataWriterQos::deadline, DDS_DataWriterQos::latency_budget, DDS_DataWriterQos::ownership_strength, DDS_DataWriterQos::transport_priority, DDS_DataWriterQos::lifespan and DDS_DataWriterQos::writer_data_lifecycle can be changed. The other policies are immutable.

Parameters

library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDSPublisher::set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSPublisher::set_default_profile).

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY or DDS_RETCODE_INCONSISTENT_POLICY

See also: DDS_DataWriterQos for rules on consistency among QoS; Operations Allowed in Listener Callbacks

◆ get_qos()

virtual DDS_ReturnCode_t DDSDataWriter::get_qos ( DDS_DataWriterQos & qos )

inlinevirtual

Gets the writer QoS.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters

qos	<<inout>> The DDS_DataWriterQos to be filled up.

Exceptions

One	of the Standard Return Codes

See also: get_qos (abstract)

◆ set_listener()

virtual DDS_ReturnCode_t DDSDataWriter::set_listener	(	DDSDataWriterListener *	l,
		DDS_StatusMask	mask = `DDS_STATUS_MASK_ALL`
	)

inlinevirtual

Sets the writer listener.

Parameters

l	<<in>> DDSDataWriterListener to set to
mask	<<in>> DDS_StatusMask associated with the DDSDataWriterListener.

Exceptions

One	of the Standard Return Codes

See also: set_listener (abstract)

◆ get_listener()

virtual DDSDataWriterListener * DDSDataWriter::get_listener ( )

inlinevirtual

Get the writer listener.

Returns: DDSDataWriterListener of the DDSDataWriter.

See also: get_listener (abstract)

◆ flush()

virtual DDS_ReturnCode_t DDSDataWriter::flush ( )

inlinevirtual

<<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 DDSDataWriter does not have DDS_PublishModeQosPolicy kind set to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS, the batch will be sent on the network immediately (in the context of the calling thread).

If the DDSDataWriter does have DDS_PublishModeQosPolicy kind set to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS, the batch will be sent in the context of the asynchronous publishing thread.

This operation may block in the same conditions as FooDataWriter::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.

MT Safety:: flush() is only thread-safe with batching if DDS_BatchQosPolicy::thread_safe_write is TRUE.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_TIMEOUT, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.

◆ take_discovery_snapshot() [1/2]

virtual DDS_ReturnCode_t DDSDataWriter::take_discovery_snapshot ( )

inlinevirtual

Take a snapshot of the compatible and incompatible remote readers matched by a local writer.

The snapshot will be printed through the NDDSConfigLogger. A possible output may be the following:

Remote readers that match the local writer domain=0 name="writerTestName" 
 
guid="0x0101D8D1,0x20B83C0D,0x4495246E:0x80000003" 
 
topic="FooTopic" type="FooType" 
 
---------------------------------------------------------------------------- 
 
Compatible readers: 
 
1. 0x0101542A,0x2C59B595,0xA1693BDF:0x80000004 name="reader1TestName" 
 
kind="unkeyed user datareader" 
 
unicastLocators="udpv4://192.168.1.170:7411" 
 
liveliness="ALIVE" 
 
Incompatible readers: 
 
1. 0x0101542A,0x2C59B595,0xA1693BDF:0x80000104 name="reader2TestName" 
 
kind="unkeyed user datareader" 
 
unicastLocators="udpv4://192.168.1.170:7411" 
 
reason="Inconsistent QoS" 
 
----------------------------------------------------------------------------

Exceptions

One	of the Standard Return Codes.

◆ take_discovery_snapshot() [2/2]

virtual DDS_ReturnCode_t DDSDataWriter::take_discovery_snapshot ( const char * file_name )

inlinevirtual

Take a snapshot of the compatible and incompatible remote readers matched by a local writer.

The snapshot will be printed in the file specified by file_name. A possible output may be the following:

Remote readers that match the local writer domain=0 name="writerTestName" 
 
guid="0x0101D8D1,0x20B83C0D,0x4495246E:0x80000003" 
 
topic="FooTopic" type="FooType" 
 
---------------------------------------------------------------------------- 
 
Compatible readers: 
 
1. 0x0101542A,0x2C59B595,0xA1693BDF:0x80000004 name="reader1TestName" 
 
kind="unkeyed user datareader" 
 
unicastLocators="udpv4://192.168.1.170:7411" 
 
liveliness="ALIVE" 
 
Incompatible readers: 
 
1. 0x0101542A,0x2C59B595,0xA1693BDF:0x80000104 name="reader2TestName" 
 
kind="unkeyed user datareader" 
 
unicastLocators="udpv4://192.168.1.170:7411" 
 
reason="Inconsistent QoS" 
 
----------------------------------------------------------------------------

Parameters

file_name <<in>> Name of the file where snapshot should be printed.

Exceptions

One	of the Standard Return Codes.

◆ enable()

virtual DDS_ReturnCode_t DDSDataWriter::enable ( )

inlinevirtual

Enables the DDSEntity.

This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the ENTITY_FACTORY QoS policy on the corresponding factory for the DDSEntity.

By default, ENTITY_FACTORY is set so that it is not necessary to explicitly call DDSEntity::enable on newly created entities.

The DDSEntity::enable operation is idempotent. Calling enable on an already enabled Entity returns OK and has no effect.

If a DDSEntity has not yet been enabled, the following kinds of operations may be invoked on it:

set or get the QoS policies (including default QoS policies) and listener
DDSEntity::get_statuscondition
'factory' operations
DDSEntity::get_status_changes and other get status operations (although the status of a disabled entity never changes)
'lookup' operations

Other operations may explicitly state that they may be called on disabled entities; those that do not will return the error DDS_RETCODE_NOT_ENABLED.

It is legal to delete an DDSEntity that has not been enabled by calling the proper operation on its factory .

Entities created from a factory Entity that is disabled are created disabled, regardless of the setting of the DDS_EntityFactoryQosPolicy.

Calling enable on an Entity whose factory Entity is not enabled will fail and return DDS_RETCODE_PRECONDITION_NOT_MET.

If DDS_EntityFactoryQosPolicy::autoenable_created_entities is TRUE, the enable operation on a factory will automatically enable all entities created from that factory (for example, enabling a DDSPublisher will enable all its contained DDSDataWriter objects)

Listeners associated with an entity are not called until the entity is enabled.

Conditions associated with a disabled entity are "inactive," that is, they have a trigger_value == FALSE.

Exceptions

One	of the Standard Return Codes, Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

Implements DDSEntity.

◆ get_statuscondition()

virtual DDSStatusCondition * DDSDataWriter::get_statuscondition ( )

inlinevirtual

Allows access to the DDSStatusCondition associated with the DDSEntity.

The returned condition can then be added to a DDSWaitSet so that the application can wait for specific status changes that affect the DDSEntity.

Returns: the status condition associated with this entity.

Implements DDSEntity.

◆ get_status_changes()

virtual DDS_StatusMask DDSDataWriter::get_status_changes ( )

inlinevirtual

Retrieves the list of communication statuses in the DDSEntity that are triggered.

That is, the list of statuses whose value has changed since the last time the application read the status using the get_*_status() method.

When the entity is first created or if the entity is not enabled, all communication statuses are in the "untriggered" state so the list returned by the get_status_changes operation will be empty.

The list of statuses returned by the get_status_changes operation refers to the status that are triggered on the Entity itself and does not include statuses that apply to contained entities.

Returns: list of communication statuses in the DDSEntity that are triggered.

See also: Status Kinds

Implements DDSEntity.

◆ get_instance_handle()

virtual DDS_InstanceHandle_t DDSDataWriter::get_instance_handle ( )

inlinevirtual

Allows access to the DDS_InstanceHandle_t associated with the DDSEntity.

This operation returns the DDS_InstanceHandle_t that represents the DDSEntity.

Returns: the instance handle associated with this entity.

Implements DDSEntity.

Public Member Functions

Detailed Description

Member Function Documentation

◆ get_liveliness_lost_status()

◆ get_offered_deadline_missed_status()

◆ get_offered_incompatible_qos_status()

◆ get_publication_matched_status()

◆ get_reliable_writer_cache_changed_status()

◆ get_reliable_reader_activity_changed_status()

◆ get_datawriter_cache_status()

◆ get_datawriter_protocol_status()

◆ get_matched_subscription_datawriter_protocol_status()

◆ is_matched_subscription_active()

◆ get_service_request_accepted_status()

◆ get_matched_subscription_datawriter_protocol_status_by_locator()

◆ assert_liveliness()

◆ get_matched_subscription_locators()

◆ get_matched_subscriptions()

◆ get_matched_subscription_data()

◆ get_matched_subscription_participant_data()

◆ get_topic()

◆ get_publisher()

◆ wait_for_acknowledgments()

◆ is_sample_app_acknowledged()

◆ wait_for_asynchronous_publishing()

◆ set_qos()

◆ set_property()

◆ set_qos_with_profile()

◆ get_qos()

◆ set_listener()

◆ get_listener()

◆ flush()

◆ take_discovery_snapshot() [1/2]

◆ take_discovery_snapshot() [2/2]

◆ enable()

◆ get_statuscondition()

◆ get_status_changes()

◆ get_instance_handle()