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

#include <managed_publication.h>

Inheritance diagram for DDS::DataWriter:

Public Member Functions
void	get_liveliness_lost_status (LivelinessLostStatus% status)
	Accesses the LIVELINESS_LOST_STATUS communication status. More...

void	get_offered_deadline_missed_status (OfferedDeadlineMissedStatus% status)
	Accesses the OFFERED_DEADLINE_MISSED_STATUS communication status. More...

void	get_offered_incompatible_qos_status (OfferedIncompatibleQosStatus^ status)
	Accesses the OFFERED_INCOMPATIBLE_QOS_STATUS communication status. More...

void	get_publication_matched_status (PublicationMatchedStatus% status)
	Accesses the PUBLICATION_MATCHED_STATUS communication status. More...

void	get_reliable_writer_cache_changed_status (ReliableWriterCacheChangedStatus% status)
	<<extension>> Get the reliable cache status for this writer. More...

void	get_reliable_reader_activity_changed_status (ReliableReaderActivityChangedStatus% status)
	<<extension>> Get the reliable reader activity changed status for this writer. More...

virtual void	get_datawriter_cache_status (DataWriterCacheStatus% status)
	<<extension>> Get the datawriter cache status for this writer. More...

virtual void	get_datawriter_protocol_status (DataWriterProtocolStatus% status)
	<<extension>> Get the datawriter protocol status for this writer. More...

virtual void	get_matched_subscription_datawriter_protocol_status (DataWriterProtocolStatus% status, InstanceHandle_t% subscription_handle)
	<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle. More...

virtual void	get_matched_subscription_datawriter_protocol_status_by_locator (DataWriterProtocolStatus% status, Locator_t^ locator)
	<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator. More...

void	get_service_request_accepted_status (ServiceRequestAcceptedStatus% status)
	Accesses the SERVICE_REQUEST_ACCEPTED_STATUS communication status. More...

void	assert_liveliness ()
	This operation manually asserts the liveliness of this DDS::DataWriter. More...

virtual void	get_matched_subscription_locators (LocatorSeq^ locators)
	<<extension>> Retrieve the list of locators for subscriptions currently "associated" with this DDS::DataWriter. More...

void	get_matched_subscriptions (InstanceHandleSeq^ subscription_handles)
	Retrieve the list of subscriptions currently "associated" with this DDS::DataWriter. More...

bool	is_matched_subscription_active (InstanceHandle_t% subscription_handle)
	Check if a subscription currently matched with a DataWriter is active. More...

void	get_matched_subscription_data (SubscriptionBuiltinTopicData^ subscription_data, InstanceHandle_t% subscription_handle)
	This operation retrieves the information on a subscription that is currently "associated" with the DDS::DataWriter. More...

void	get_matched_subscription_participant_data (ParticipantBuiltinTopicData^ participant_data, InstanceHandle_t% subscription_handle)
	This operation retrieves the information on the discovered DDS::DomainParticipant associated with the subscription that is currently matching with the DDS::DataWriter. More...

Topic ^	get_topic ()
	This operation returns the DDS::Topic associated with the DDS::DataWriter. More...

Publisher ^	get_publisher ()
	This operation returns the DDS::Publisher to which the DDS::DataWriter belongs. More...

void	wait_for_acknowledgments (Duration_t max_wait)
	Blocks the calling thread until all data written by reliable DDS::DataWriter entity is acknowledged, or until timeout expires. More...

System::Boolean	is_sample_app_acknowledged (SampleIdentity_t% identity)
	This method can be used to see if a sample has been application acknowledged. More...

void	wait_for_asynchronous_publishing (Duration_t max_wait)
	<<extension>> Blocks the calling thread until asynchronous sending is complete. More...

void	set_qos (DataWriterQos^ qos)
	Sets the writer QoS. More...

void	set_qos_with_profile (System::String^ library_name, System::String^ profile_name)
	<<extension>> Change the QoS of this writer using the input XML QoS profile. More...

void	get_qos (DataWriterQos^ qos)
	Gets the writer QoS. More...

void	set_listener (DataWriterListener^ l, StatusMask mask)
	Sets the writer listener. More...

DataWriterListener ^	get_listener ()
	Get the writer listener. More...

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

InstanceHandle_t	register_instance_untyped (System::Object^ instance_data)
	Register a new instance with this writer. More...

InstanceHandle_t	register_instance_w_timestamp_untyped (System::Object^ instance_data, DDS::Time_t% source_timestamp)
	Register a new instance with this writer using the given time instead of the current time. More...

void	unregister_instance_untyped (System::Object^ instance_data, DDS::InstanceHandle_t% handle)
	Unregister a new instance from this writer. More...

void	unregister_instance_w_timestamp_untyped (System::Object^ instance_data, DDS::InstanceHandle_t% handle, DDS::Time_t% source_timestamp)
	Unregister a new instance from this writer using the given time instead of the current time. More...

void	write_untyped (System::Object^ instance_data, DDS::InstanceHandle_t% handle)
	Publish a data sample. More...

void	write_w_timestamp_untyped (System::Object^ instance_data, DDS::InstanceHandle_t% handle, DDS::Time_t% source_timestamp)
	Publish a data sample using the given time instead of the current time. More...

void	dispose_untyped (System::Object^ instance_data, DDS::InstanceHandle_t% instance_handle)
	Dispose a data sample. More...

void	dispose_w_timestamp_untyped (System::Object^ instance_data, DDS::InstanceHandle_t% instance_handle, DDS::Time_t% source_timestamp)
	Dispose a data sample using the given time instead of the current time. More...

void	get_key_value_untyped (System::Object^ key_holder, DDS::InstanceHandle_t% handle)
	Fill in the key fields of the given data sample. More...

InstanceHandle_t	lookup_instance_untyped (System::Object^ key_holder)
	Given a sample with the given key field values, return the handle corresponding to its instance. More...

virtual void	enable () override
	Enables the DDS::Entity. More...

virtual StatusCondition ^	get_statuscondition () override
	Allows access to the DDS::StatusCondition associated with the DDS::Entity. More...

virtual StatusMask	get_status_changes () override
	Retrieves the list of communication statuses in the DDS::Entity that are triggered. More...

virtual InstanceHandle_t	get_instance_handle () override
	Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity. More...

Detailed Description

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

QoS:: DDS::DataWriterQos

Status:: LIVELINESS_LOST_STATUS, DDS::LivelinessLostStatus;
OFFERED_DEADLINE_MISSED_STATUS, DDS::OfferedDeadlineMissedStatus;
OFFERED_INCOMPATIBLE_QOS_STATUS, DDS::OfferedIncompatibleQosStatus;
PUBLICATION_MATCHED_STATUS, DDS::PublicationMatchedStatus;
RELIABLE_READER_ACTIVITY_CHANGED_STATUS, DDS::ReliableReaderActivityChangedStatus;
RELIABLE_WRITER_CACHE_CHANGED_STATUS, DDS::ReliableWriterCacheChangedStatus.

Listener:: DDS::DataWriterListener

A DDS::DataWriter is attached to exactly one DDS::Publisher, that acts as a factory for it.

A DDS::DataWriter is bound to exactly one DDS::Topic and therefore to exactly one data type. The DDS::Topic must exist prior to the DDS::DataWriter's creation.

DDS::DataWriter 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 DDS::DataWriter.

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

Several DDS::DataWriter may operate in different threads. If they share the same DDS::Publisher, the middleware guarantees that its operations are thread-safe.

See also: DDS::TypedDataWriter; Operations Allowed in Listener Callbacks

Examples:: HelloWorld_publisher.cpp, and HelloWorldSupport.cpp.

Member Function Documentation

◆ get_liveliness_lost_status()

void DDS::DataWriter::get_liveliness_lost_status ( LivelinessLostStatus% status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_offered_deadline_missed_status()

void DDS::DataWriter::get_offered_deadline_missed_status ( OfferedDeadlineMissedStatus% status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_offered_incompatible_qos_status()

void DDS::DataWriter::get_offered_incompatible_qos_status ( OfferedIncompatibleQosStatus^ status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_publication_matched_status()

void DDS::DataWriter::get_publication_matched_status ( PublicationMatchedStatus% status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_reliable_writer_cache_changed_status()

void DDS::DataWriter::get_reliable_writer_cache_changed_status ( ReliableWriterCacheChangedStatus% status )

<<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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_reliable_reader_activity_changed_status()

void DDS::DataWriter::get_reliable_reader_activity_changed_status ( ReliableReaderActivityChangedStatus% status )

<<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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_datawriter_cache_status()

virtual void DDS::DataWriter::get_datawriter_cache_status ( DataWriterCacheStatus% status )

virtual

<<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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled.

◆ get_datawriter_protocol_status()

virtual void DDS::DataWriter::get_datawriter_protocol_status ( DataWriterProtocolStatus% status )

virtual

<<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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled.

◆ get_matched_subscription_datawriter_protocol_status()

virtual void DDS::DataWriter::get_matched_subscription_datawriter_protocol_status	(	DataWriterProtocolStatus%	status,
		InstanceHandle_t%	subscription_handle
	)

virtual

<<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. Cannot be NULL.
subscription_handle	<<in>> Handle to a specific subscription associated with the DDS::DataReader. Cannot be NULL.Must correspond to a subscription currently associated with the DDS::DataWriter.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled.

◆ get_matched_subscription_datawriter_protocol_status_by_locator()

virtual void DDS::DataWriter::get_matched_subscription_datawriter_protocol_status_by_locator	(	DataWriterProtocolStatus%	status,
		Locator_t^	locator
	)

virtual

<<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 Cannot be NULL.
locator	<<in>> Locator to a specific locator associated with the DDS::DataReader. Cannot be NULL.Must correspond to a locator of one or more subscriptions currently associated with the DDS::DataWriter.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled.

◆ get_service_request_accepted_status()

void DDS::DataWriter::get_service_request_accepted_status ( ServiceRequestAcceptedStatus% status )

Accesses the 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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ assert_liveliness()

void DDS::DataWriter::assert_liveliness ( )

This operation manually asserts the liveliness of this DDS::DataWriter.

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

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

Note: writing data via the DDS::TypedDataWriter::write or DDS::TypedDataWriter::write_w_timestamp operation asserts liveliness on the DDS::DataWriter itself, and its DDS::DomainParticipant. 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_NotEnabled

See also: DDS::LivelinessQosPolicy

◆ get_matched_subscription_locators()

virtual void DDS::DataWriter::get_matched_subscription_locators ( LocatorSeq^ locators )

virtual

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

The locators returned in the locators list are the ones that are used by the DDS implementation to communicate with the corresponding matched DDS::DataReader 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_OutOfResources. Cannot be NULL..

Exceptions

One	of the Standard Return Codes, or DDS::Retcode_OutOfResources if the sequence is too small and the system can not resize it, or DDS::Retcode_NotEnabled

◆ get_matched_subscriptions()

void DDS::DataWriter::get_matched_subscriptions ( InstanceHandleSeq^ subscription_handles )

Retrieve the list of subscriptions currently "associated" with this DDS::DataWriter.

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 DDS::Topic.
The subscription has compatible QoS.
If the applications are using partitions, the subscription shares a common partition with this publication.
The DDS::DomainParticipant has not indicated that the subscription's DDS::DomainParticipant should be "ignored" by means of the DDS::DomainParticipant::ignore_publication API.
If the publication is using the DDS::MultiChannelQosPolicy and the subscription is using a DDS::ContentFilteredTopic, 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 DDS::DataReader entities. These handles match the ones that appear in the DDS::SampleInfo::instance_handle field of the DDS::SampleInfo when reading the DDS::SubscriptionBuiltinTopicDataTypeSupport::SUBSCRIPTION_TOPIC_NAME builtin topic.

This API may return the subscription handles of subscriptions that are inactive. DDS::DataWriter::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_OutOfResources.

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. Cannot be NULL..

Exceptions

One	of the Standard Return Codes, or DDS::Retcode_OutOfResources if the sequence is too small and the system cannot resize it, or DDS::Retcode_NotEnabled

◆ is_matched_subscription_active()

bool DDS::DataWriter::is_matched_subscription_active ( InstanceHandle_t% subscription_handle )

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

Parameters

subscription_handle <<in>> The DDS::InstanceHandle_t of the matched subscription. See DDS::DataWriter::get_matched_subscriptions for a description of what is considered a matched subscription.

Returns: A boolean indicating whether or not the matched subscription is active.

◆ get_matched_subscription_data()

void DDS::DataWriter::get_matched_subscription_data	(	SubscriptionBuiltinTopicData^	subscription_data,
		InstanceHandle_t%	subscription_handle
	)

This operation retrieves the information on a subscription that is currently "associated" with the DDS::DataWriter.

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

The above information is also available through DDS::DataReaderListener::on_data_available() (if a reader listener is installed on the DDS::SubscriptionBuiltinTopicDataDataReader).

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 DDS::DataReaderListener::on_data_available() of the DDS::SubscriptionBuiltinTopicDataDataReader. 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 DDS::SubscriptionBuiltinTopicDataDataReader. 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 DDS::DataReaderListener::on_data_available() (if a reader listener is installed on the DDS::SubscriptionBuiltinTopicDataDataReader).

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 DDS::DataReader. Must correspond to a subscription currently associated with the DDS::DataWriter. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS::Retcode_NotEnabled, or DDS::Retcode_Timeout

Referenced by RTI.Connext.Queuing.QueueProducer< TRep >::CreateWriteSample().

◆ get_matched_subscription_participant_data()

void DDS::DataWriter::get_matched_subscription_participant_data	(	ParticipantBuiltinTopicData^	participant_data,
		InstanceHandle_t%	subscription_handle
	)

This operation retrieves the information on the discovered DDS::DomainParticipant associated with the subscription that is currently matching with the DDS::DataWriter.

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

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 DDS::DataReader. Must correspond to a subscription currently associated with the DDS::DataWriter. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, or DDS::Retcode_NotEnabled

◆ get_topic()

Topic ^ DDS::DataWriter::get_topic ( )

This operation returns the DDS::Topic associated with the DDS::DataWriter.

This is the same DDS::Topic that was used to create the DDS::DataWriter.

Returns: DDS::Topic that was used to create the DDS::DataWriter.

◆ get_publisher()

Publisher ^ DDS::DataWriter::get_publisher ( )

This operation returns the DDS::Publisher to which the DDS::DataWriter belongs.

Returns: DDS::Publisher to which the DDS::DataWriter belongs.

◆ wait_for_acknowledgments()

void DDS::DataWriter::wait_for_acknowledgments ( Duration_t max_wait )

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

This operation blocks the calling thread until either all data written by the reliable DDS::DataWriter entity is acknowledged by (a) all reliable DDS::DataReader 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 DDS::DataWriter does not have DDS::ReliabilityQosPolicy kind set to RELIABLE, this operation will complete immediately with DDS::ReturnCode_t::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_NotEnabled, DDS::Retcode_Timeout

◆ is_sample_app_acknowledged()

System::Boolean DDS::DataWriter::is_sample_app_acknowledged ( SampleIdentity_t% identity )

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::acknowledgement_mode to a value other than DDS::ReliabilityQosPolicyAcknowledgmentModeKind::PROTOCOL_ACKNOWLEDGEMENT_MODE), the sample is considered application acknowledged for that DataReader.

Parameters

identity <<in>> Sample identity.

Returns: true when the sample has been application acknowledged. Otherwise, false.

Exceptions

One	of the Standard Return Codes

◆ wait_for_asynchronous_publishing()

void DDS::DataWriter::wait_for_asynchronous_publishing ( Duration_t max_wait )

<<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 DDS::DataWriter is sent and acknowledged (if reliable) by all matched DDS::DataReader 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 DDS::DataReader is complete in addition to what DDS::DataWriter::wait_for_acknowledgments provides.

If the DDS::DataWriter does not have DDS::PublishModeQosPolicy kind set to ASYNCHRONOUS_PUBLISH_MODE_QOS the operation will complete immediately with DDS::ReturnCode_t::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_NotEnabled, DDS::Retcode_Timeout

◆ set_qos()

void DDS::DataWriter::set_qos ( DataWriterQos^ qos )

Sets the writer QoS.

This operation modifies the QoS of the DDS::DataWriter.

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 DDS::DataWriter is enabled. The special value DDS::Publisher::DATAWRITER_QOS_DEFAULT can be used to indicate that the QoS of the DDS::DataWriter should be changed to match the current default DDS::DataWriterQos set in the DDS::Publisher. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, DDS::Retcode_ImmutablePolicy or DDS::Retcode_InconsistentPolicy

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

◆ set_qos_with_profile()

void DDS::DataWriter::set_qos_with_profile	(	System::String^	library_name,
		System::String^	profile_name
	)

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

This operation modifies the QoS of the DDS::DataWriter.

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 DDS::Publisher::set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS::Publisher::set_default_profile).

Exceptions

One	of the Standard Return Codes, DDS::Retcode_ImmutablePolicy or DDS::Retcode_InconsistentPolicy

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

◆ get_qos()

void DDS::DataWriter::get_qos ( DataWriterQos^ qos )

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. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See also: get_qos (abstract)

◆ set_listener()

void DDS::DataWriter::set_listener	(	DataWriterListener^	l,
		StatusMask	mask
	)

Sets the writer listener.

Parameters

l	<<in>> DDS::DataWriterListener to set to
mask	<<in>> DDS::StatusMask associated with the DDS::DataWriterListener.

Exceptions

One	of the Standard Return Codes

See also: set_listener (abstract)

◆ get_listener()

DataWriterListener ^ DDS::DataWriter::get_listener ( )

Get the writer listener.

Returns: DDS::DataWriterListener of the DDS::DataWriter.

See also: get_listener (abstract)

◆ flush()

void DDS::DataWriter::flush ( )

<<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 DDS::DataWriter does not have DDS::PublishModeQosPolicy kind set to ASYNCHRONOUS_PUBLISH_MODE_QOS, the batch will be sent on the network immediately (in the context of the calling thread).

If the DDS::DataWriter does have DDS::PublishModeQosPolicy kind set to 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 DDS::TypedDataWriter::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_OutOfResources or DDS::Retcode_NotEnabled.

◆ register_instance_untyped()

InstanceHandle_t DDS::DataWriter::register_instance_untyped ( System::Object^ instance_data )

Register a new instance with this writer.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::register_instance method instead of this one. See that method for detailed documentation.

See also: DDS::DataWriter::unregister_instance_untyped; DDS::TypedDataWriter::register_instance

◆ register_instance_w_timestamp_untyped()

InstanceHandle_t DDS::DataWriter::register_instance_w_timestamp_untyped	(	System::Object^	instance_data,
		DDS::Time_t%	source_timestamp
	)

Register a new instance with this writer using the given time instead of the current time.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::register_instance_w_timestamp method instead of this one. See that method for detailed documentation.

See also: DDS::DataWriter::unregister_instance_w_timestamp_untyped; DDS::TypedDataWriter::register_instance

◆ unregister_instance_untyped()

void DDS::DataWriter::unregister_instance_untyped	(	System::Object^	instance_data,
		DDS::InstanceHandle_t%	handle
	)

Unregister a new instance from this writer.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::unregister_instance method instead of this one. See that method for detailed documentation.

See also: DDS::DataWriter::register_instance_untyped; DDS::TypedDataWriter::unregister_instance

◆ unregister_instance_w_timestamp_untyped()

void DDS::DataWriter::unregister_instance_w_timestamp_untyped	(	System::Object^	instance_data,
		DDS::InstanceHandle_t%	handle,
		DDS::Time_t%	source_timestamp
	)

Unregister a new instance from this writer using the given time instead of the current time.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::unregister_instance_w_timestamp method instead of this one. See that method for detailed documentation.

See also: DDS::DataWriter::register_instance_w_timestamp_untyped; DDS::TypedDataWriter::unregister_instance_w_timestamp

◆ write_untyped()

void DDS::DataWriter::write_untyped	(	System::Object^	instance_data,
		DDS::InstanceHandle_t%	handle
	)

Publish a data sample.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::write method instead of this one. See that method for detailed documentation.

See also: DDS::DataWriter::write_w_timestamp_untyped; DDS::TypedDataWriter::write

◆ write_w_timestamp_untyped()

void DDS::DataWriter::write_w_timestamp_untyped	(	System::Object^	instance_data,
		DDS::InstanceHandle_t%	handle,
		DDS::Time_t%	source_timestamp
	)

Publish a data sample using the given time instead of the current time.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::write_w_timestamp method instead of this one. See that method for detailed documentation.

See also: DDS::DataWriter::write_untyped; DDS::TypedDataWriter::write_w_timestamp

◆ dispose_untyped()

void DDS::DataWriter::dispose_untyped	(	System::Object^	instance_data,
		DDS::InstanceHandle_t%	instance_handle
	)

Dispose a data sample.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::dispose method instead of this one. See that method for detailed documentation.

See also: DDS::DataWriter::dispose_w_timestamp_untyped; DDS::TypedDataWriter::dispose

◆ dispose_w_timestamp_untyped()

void DDS::DataWriter::dispose_w_timestamp_untyped	(	System::Object^	instance_data,
		DDS::InstanceHandle_t%	instance_handle,
		DDS::Time_t%	source_timestamp
	)

Dispose a data sample using the given time instead of the current time.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::dispose_w_timestamp method instead of this one. See that method for detailed documentation.

See also: DDS::DataWriter::dispose_untyped; DDS::TypedDataWriter::dispose_w_timestamp

◆ get_key_value_untyped()

void DDS::DataWriter::get_key_value_untyped	(	System::Object^	key_holder,
		DDS::InstanceHandle_t%	handle
	)

Fill in the key fields of the given data sample.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::get_key_value method instead of this one. See that method for detailed documentation.

See also: DDS::TypedDataWriter::get_key_value

◆ lookup_instance_untyped()

InstanceHandle_t DDS::DataWriter::lookup_instance_untyped ( System::Object^ key_holder )

Given a sample with the given key field values, return the handle corresponding to its instance.

This method allows type-independent code to work with a variety of concrete DDS::TypedDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate DDS::TypedDataWriter::lookup_instance method instead of this one. See that method for detailed documentation.

See also: DDS::TypedDataWriter::lookup_instance

◆ enable()

virtual void DDS::DataWriter::enable ( )

overridevirtual

Enables the DDS::Entity.

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 DDS::Entity.

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

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

If a DDS::Entity 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
DDS::Entity::get_statuscondition
'factory' operations
DDS::Entity::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_NotEnabled.

It is legal to delete an DDS::Entity 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_PreconditionNotMet.

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 DDS::Publisher will enable all its contained DDS::DataWriter 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_PreconditionNotMet.

Implements DDS::Entity.

◆ get_statuscondition()

virtual StatusCondition ^ DDS::DataWriter::get_statuscondition ( )

overridevirtual

Allows access to the DDS::StatusCondition associated with the DDS::Entity.

The returned condition can then be added to a DDS::WaitSet so that the application can wait for specific status changes that affect the DDS::Entity.

Returns: the status condition associated with this entity.

Implements DDS::Entity.

◆ get_status_changes()

virtual StatusMask DDS::DataWriter::get_status_changes ( )

overridevirtual

Retrieves the list of communication statuses in the DDS::Entity 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 DDS::Entity that are triggered.

See also: Status Kinds

Implements DDS::Entity.

◆ get_instance_handle()

virtual InstanceHandle_t DDS::DataWriter::get_instance_handle ( )

overridevirtual

Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity.

This operation returns the DDS::InstanceHandle_t that represents the DDS::Entity.

Returns: the instance handle associated with this entity.

Implements DDS::Entity.

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()

◆ get_matched_subscription_datawriter_protocol_status_by_locator()

◆ get_service_request_accepted_status()

◆ assert_liveliness()

◆ get_matched_subscription_locators()

◆ get_matched_subscriptions()

◆ is_matched_subscription_active()

◆ 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_qos_with_profile()

◆ get_qos()

◆ set_listener()

◆ get_listener()

◆ flush()

◆ register_instance_untyped()

◆ register_instance_w_timestamp_untyped()

◆ unregister_instance_untyped()

◆ unregister_instance_w_timestamp_untyped()

◆ write_untyped()

◆ write_w_timestamp_untyped()

◆ dispose_untyped()

◆ dispose_w_timestamp_untyped()

◆ get_key_value_untyped()

◆ lookup_instance_untyped()

◆ enable()

◆ get_statuscondition()

◆ get_status_changes()

◆ get_instance_handle()