DDS::DataWriter Class Reference
[Data Writers]

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

List of all members.

Public Member Functions

void get_liveliness_lost_status (LivelinessLostStatus% status)

Accesses the DDS::StatusKind::LIVELINESS_LOST_STATUS communication status.

void get_offered_deadline_missed_status (OfferedDeadlineMissedStatus% status)

Accesses the DDS::StatusKind::OFFERED_DEADLINE_MISSED_STATUS communication status.

void get_offered_incompatible_qos_status (OfferedIncompatibleQosStatus^ status)

Accesses the DDS::StatusKind::OFFERED_INCOMPATIBLE_QOS_STATUS communication status.

void get_publication_matched_status (PublicationMatchedStatus% status)

Accesses the DDS::StatusKind::PUBLICATION_MATCHED_STATUS communication status.

void get_reliable_writer_cache_changed_status (ReliableWriterCacheChangedStatus% status)

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

void get_reliable_reader_activity_changed_status (ReliableReaderActivityChangedStatus% status)

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

virtual void get_datawriter_cache_status (DataWriterCacheStatus% status)

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

virtual void get_datawriter_protocol_status (DataWriterProtocolStatus% status)

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

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.

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.

void assert_liveliness ()

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

virtual void get_matched_subscription_locators (LocatorSeq^ locators)

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

void get_matched_subscriptions (InstanceHandleSeq^ subscription_handles)

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

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.

Topic^ get_topic ()

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

Publisher^ get_publisher ()

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

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.

void wait_for_asynchronous_publishing (Duration_t max_wait)

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

void set_qos (DataWriterQos^ qos)

Sets the writer QoS.

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.

void get_qos (DataWriterQos^ qos)

Gets the writer QoS.

void set_listener (DataWriterListener^ l, StatusMask mask)

Sets the writer listener.

DataWriterListener^ get_listener ()

Get the writer listener.

void flush ()

<<eXtension>> Flushes the batch in progress in the context of the calling thread.

InstanceHandle_t register_instance_untyped (System::Object^ instance_data)

Register a new instance with this writer.

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.

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

Unregister a new instance from this writer.

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.

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

Publish a data sample.

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.

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

Dispose a data sample.

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.

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

Fill in the key fields of the given data sample.

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.

virtual void enable () override

Enables the DDS::Entity.

virtual StatusCondition^ get_statuscondition () override

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

virtual StatusMask get_status_changes () override

Retrieves the list of communication statuses in the DDS::Entity that are triggered.

virtual InstanceHandle_t get_instance_handle () override

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

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:: DDS::StatusKind::LIVELINESS_LOST_STATUS, DDS::LivelinessLostStatus;
DDS::StatusKind::OFFERED_DEADLINE_MISSED_STATUS, DDS::OfferedDeadlineMissedStatus;
DDS::StatusKind::OFFERED_INCOMPATIBLE_QOS_STATUS, DDS::OfferedIncompatibleQosStatus;
DDS::StatusKind::PUBLICATION_MATCHED_STATUS, DDS::PublicationMatchedStatus;
DDS::StatusKind::RELIABLE_READER_ACTIVITY_CHANGED_STATUS, DDS::ReliableReaderActivityChangedStatus;
DDS::StatusKind::RELIABLE_WRITER_CACHE_CHANGED_STATUS, DDS::ReliableWriterCacheChangedStatus<BR>

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

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

Accesses the DDS::StatusKind::LIVELINESS_LOST_STATUS communication status.

Parameters:

status

<<inout>> DDS::LivelinessLostStatus to be filled in. Cannot be NULL.

Exceptions:

One

of the Standard Return Codes

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

Accesses the DDS::StatusKind::OFFERED_DEADLINE_MISSED_STATUS communication status.

Parameters:

status

<<inout>> DDS::OfferedDeadlineMissedStatus to be filled in. Cannot be NULL.

Exceptions:

One

of the Standard Return Codes

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

Accesses the DDS::StatusKind::OFFERED_INCOMPATIBLE_QOS_STATUS communication status.

Parameters:

status

<<inout>> DDS::OfferedIncompatibleQosStatus to be filled in. Cannot be NULL.

Exceptions:

One

of the Standard Return Codes

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

Accesses the DDS::StatusKind::PUBLICATION_MATCHED_STATUS communication status.

Parameters:

status

<<inout>> DDS::PublicationMatchedStatus to be filled in. Cannot be NULL.

Exceptions:

One

of the Standard Return Codes

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

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

Parameters:

status

<<inout>> DDS::ReliableWriterCacheChangedStatus to be filled in. Cannot be NULL.

Exceptions:

One

of the Standard Return Codes

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

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

Parameters:

status

<<inout>> DDS::ReliableReaderActivityChangedStatus to be filled in. Cannot be NULL.

Exceptions:

One

of the Standard Return Codes

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

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

Parameters:

status

<<inout>> DDS::DataWriterCacheStatus to be filled in. Cannot be NULL.

Exceptions:

One

of the Standard Return Codes or DDS::Retcode_NotEnabled.

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

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

Parameters:

status

<<inout>> DDS::DataWriterProtocolStatus to be filled in. Cannot be NULL.

Exceptions:

One

of the Standard Return Codes or DDS::Retcode_NotEnabled.

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.

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.

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.

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.

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 Data Distribution Service that the DDS::DataWriter remains active.

You only need to use this operation if the LIVELINESS setting is either DDS::LivelinessQosPolicyKind::MANUAL_BY_PARTICIPANT_LIVELINESS_QOS or DDS::LivelinessQosPolicyKind::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

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.

Matched subscription locators include locators for all those subscriptions in the same domain that have a matching DDS::Topic, compatible QoS and common partition that the DDS::DomainParticipant has not indicated should be "ignored" by means of the DDS::DomainParticipant::ignore_subscription operation.

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

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

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

Matched subscriptions include all those in the same domain that have a matching DDS::Topic, compatible QoS and common partition that the DDS::DomainParticipant has not indicated should be "ignored" by means of the DDS::DomainParticipant::ignore_subscription operation.

The handles returned in the subscription_handles list are the ones that are used by the DDS implementation 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.

Parameters:

subscription_handles

<<inout>>. 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 the matches and the system can not 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 can not resize it, or DDS::Retcode_NotEnabled

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.

Note: This operation does not retrieve the following information in DDS::SubscriptionBuiltinTopicData:

DDS::SubscriptionBuiltinTopicData::type_code
DDS::SubscriptionBuiltinTopicData::property
DDS::SubscriptionBuiltinTopicData::content_filter_property

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

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.

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.

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 all matched reliable DDS::DataReader entities, or else 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; a time out indicates that max_wait elapsed before all the data was acknowledged.

If the DDS::DataWriter does not have DDS::ReliabilityQosPolicy kind set to RELIABLE the operation will complete immediately with 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

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 DDS::PublishModeQosPolicyKind::ASYNCHRONOUS_PUBLISH_MODE_QOS the operation will complete immediately with DDS::Exception::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

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

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

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)

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)

DataWriterListener ^ DDS::DataWriter::get_listener ( )

Get the writer listener.

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

See also:: get_listener (abstract)

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 DDS::PublishModeQosPolicyKind::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 DDS::PublishModeQosPolicyKind::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 than 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.

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

Register a new instance with this writer.