<<interface>> Allows an application to set the value of the data to be published under a given com.rti.dds.topic.Topic. More...

Inheritance diagram for DataWriter:

Public Member Functions
void	set_qos (DataWriterQos qos)
	Sets the writer QoS. More...

void	set_qos_with_profile (String library_name, 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, int mask)
	Sets the writer listener. More...

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

void	get_liveliness_lost_status (LivelinessLostStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.LIVELINESS_LOST_STATUS communication status. More...

void	get_offered_deadline_missed_status (OfferedDeadlineMissedStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_DEADLINE_MISSED_STATUS communication status. More...

void	get_offered_incompatible_qos_status (OfferedIncompatibleQosStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_INCOMPATIBLE_QOS_STATUS communication status. More...

void	get_publication_matched_status (PublicationMatchedStatus status)
	Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.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...

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

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

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

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 com.rti.dds.infrastructure.StatusKind.SERVICE_REQUEST_ACCEPTED_STATUS communication status. More...

void	get_matched_subscription_locators (LocatorSeq locators)
	<<extension>> Retrieve the list of locators for subscriptions currently "associated" with this com.rti.dds.publication.DataWriter. More...

void	get_matched_subscriptions (InstanceHandleSeq subscription_handles)
	Retrieve the list of subscriptions currently "associated" with this com.rti.dds.publication.DataWriter. More...

boolean	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 com.rti.dds.publication.DataWriter. More...

void	get_matched_subscription_participant_data (ParticipantBuiltinTopicData participant_data, InstanceHandle_t subscription_handle)
	This operation retrieves the information on the discovered com.rti.dds.domain.DomainParticipant associated with the subscription that is currently matching with the com.rti.dds.publication.DataWriter. More...

Topic	get_topic ()
	This operation returns the com.rti.dds.topic.Topic associated with the com.rti.dds.publication.DataWriter. More...

Publisher	get_publisher ()
	This operation returns the com.rti.dds.publication.Publisher to which the com.rti.dds.publication.DataWriter belongs. More...

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

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	assert_liveliness ()
	This operation manually asserts the liveliness of this com.rti.dds.publication.DataWriter. More...

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

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

InstanceHandle_t	register_instance_w_timestamp_untyped (Object instance_data, 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 (Object instance_data, InstanceHandle_t handle)
	Unregister a new instance from this writer. More...

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

void	write_untyped (Object instance_data, InstanceHandle_t handle)
	Publish a data sample. More...

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

void	dispose_untyped (Object instance_data, InstanceHandle_t handle)
	Dispose a data sample. More...

void	dispose_w_timestamp_untyped (Object instance_data, InstanceHandle_t handle, Time_t source_timestamp)
	Dispose a data sample using the given time instead of the current time. More...

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

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

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

void	take_discovery_snapshot (String file_name)
	Take a snapshot of the compatible and incompatible remote readers matched by a local writer. More...

Public Member Functions inherited from Entity
void	enable ()
	Enables the com.rti.dds.infrastructure.Entity. More...

StatusCondition	get_statuscondition ()
	Allows access to the com.rti.dds.infrastructure.StatusCondition associated with the com.rti.dds.infrastructure.Entity. More...

int	get_status_changes ()
	Retrieves the list of communication statuses in the com.rti.dds.infrastructure.Entity that are triggered. More...

InstanceHandle_t	get_instance_handle ()
	Allows access to the com.rti.dds.infrastructure.InstanceHandle_t associated with the com.rti.dds.infrastructure.Entity. More...

Detailed Description

<<interface>> Allows an application to set the value of the data to be published under a given com.rti.dds.topic.Topic.

QoS:: com.rti.dds.publication.DataWriterQos

Status:: com.rti.dds.infrastructure.StatusKind.StatusKind.LIVELINESS_LOST_STATUS, com.rti.dds.publication.LivelinessLostStatus;
com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_DEADLINE_MISSED_STATUS, com.rti.dds.publication.OfferedDeadlineMissedStatus;
com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_INCOMPATIBLE_QOS_STATUS, com.rti.dds.publication.OfferedIncompatibleQosStatus;
com.rti.dds.infrastructure.StatusKind.StatusKind.PUBLICATION_MATCHED_STATUS, com.rti.dds.publication.PublicationMatchedStatus;
com.rti.dds.infrastructure.StatusKind.StatusKind.RELIABLE_READER_ACTIVITY_CHANGED_STATUS, com.rti.dds.publication.ReliableReaderActivityChangedStatus;
com.rti.dds.infrastructure.StatusKind.StatusKind.RELIABLE_WRITER_CACHE_CHANGED_STATUS, com.rti.dds.publication.ReliableWriterCacheChangedStatus.

Listener:: com.rti.dds.publication.DataWriterListener

A com.rti.dds.publication.DataWriter is attached to exactly one com.rti.dds.publication.Publisher, that acts as a factory for it.

A com.rti.dds.publication.DataWriter is bound to exactly one com.rti.dds.topic.Topic and therefore to exactly one data type. The com.rti.dds.topic.Topic must exist prior to the com.rti.dds.publication.DataWriter's creation.

com.rti.dds.publication.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 com.rti.ndds.example.Foo are specified in the example type com.rti.dds.publication.DataWriter.

The following operations may be called even if the com.rti.dds.publication.DataWriter is not enabled. Other operations will fail with com.rti.dds.infrastructure.RETCODE_NOT_ENABLED if called on a disabled com.rti.dds.publication.DataWriter:

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

See also: com.rti.ndds.example.FooDataWriter; Operations Allowed in Listener Callbacks

Member Function Documentation

◆ set_qos()

void set_qos ( DataWriterQos qos )

Sets the writer QoS.

This operation modifies the QoS of the com.rti.dds.publication.DataWriter.

The com.rti.dds.publication.DataWriterQos.user_data, com.rti.dds.publication.DataWriterQos.deadline, com.rti.dds.publication.DataWriterQos.latency_budget, com.rti.dds.publication.DataWriterQos.ownership_strength, com.rti.dds.publication.DataWriterQos.transport_priority, com.rti.dds.publication.DataWriterQos.lifespan and com.rti.dds.publication.DataWriterQos.writer_data_lifecycle can be changed. The other policies are immutable.

Parameters

qos <<in>> The com.rti.dds.publication.DataWriterQos to be set to. Policies must be consistent. Immutable policies cannot be changed after com.rti.dds.publication.DataWriter is enabled. The special value com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT can be used to indicate that the QoS of the com.rti.dds.publication.DataWriter should be changed to match the current default com.rti.dds.publication.DataWriterQos set in the com.rti.dds.publication.Publisher. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY

See also: com.rti.dds.publication.DataWriterQos for rules on consistency among QoS; set_qos (abstract); Operations Allowed in Listener Callbacks

◆ set_qos_with_profile()

void set_qos_with_profile	(	String	library_name,
		String	profile_name
	)

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

This operation modifies the QoS of the com.rti.dds.publication.DataWriter.

The com.rti.dds.publication.DataWriterQos.user_data, com.rti.dds.publication.DataWriterQos.deadline, com.rti.dds.publication.DataWriterQos.latency_budget, com.rti.dds.publication.DataWriterQos.ownership_strength, com.rti.dds.publication.DataWriterQos.transport_priority, com.rti.dds.publication.DataWriterQos.lifespan and com.rti.dds.publication.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 com.rti.dds.publication.Publisher.set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.publication.Publisher.set_default_profile).

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY

See also: com.rti.dds.publication.DataWriterQos for rules on consistency among QoS; Operations Allowed in Listener Callbacks

◆ get_qos()

void 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 com.rti.dds.publication.DataWriterQos to be filled up. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See also: get_qos (abstract)

Referenced by Requester< TReq, TRep >.Requester().

◆ set_listener()

void set_listener	(	DataWriterListener	l,
		int	mask
	)

Sets the writer listener.

Parameters

l	<<in>> com.rti.dds.publication.DataWriterListener to set to
mask	<<in>> com.rti.dds.infrastructure.StatusMask associated with the com.rti.dds.publication.DataWriterListener.

Exceptions

One	of the Standard Return Codes

See also: set_listener (abstract)

◆ get_listener()

DataWriterListener get_listener ( )

Get the writer listener.

Returns: com.rti.dds.publication.DataWriterListener of the com.rti.dds.publication.DataWriter.

See also: get_listener (abstract)

◆ get_liveliness_lost_status()

void get_liveliness_lost_status ( LivelinessLostStatus status )

Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.LIVELINESS_LOST_STATUS communication status.

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

Parameters

status <<inout>> com.rti.dds.publication.LivelinessLostStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_offered_deadline_missed_status()

void get_offered_deadline_missed_status ( OfferedDeadlineMissedStatus status )

Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_DEADLINE_MISSED_STATUS communication status.

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

Parameters

status <<inout>> com.rti.dds.publication.OfferedDeadlineMissedStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_offered_incompatible_qos_status()

void get_offered_incompatible_qos_status ( OfferedIncompatibleQosStatus status )

Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_INCOMPATIBLE_QOS_STATUS communication status.

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

Parameters

status <<inout>> com.rti.dds.publication.OfferedIncompatibleQosStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_publication_matched_status()

void get_publication_matched_status ( PublicationMatchedStatus status )

Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.PUBLICATION_MATCHED_STATUS communication status.

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

Parameters

status <<inout>> com.rti.dds.publication.PublicationMatchedStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_reliable_writer_cache_changed_status()

void 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>> com.rti.dds.publication.ReliableWriterCacheChangedStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_reliable_reader_activity_changed_status()

void 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>> com.rti.dds.publication.ReliableReaderActivityChangedStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_datawriter_cache_status()

void get_datawriter_cache_status ( DataWriterCacheStatus status )

<<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>> com.rti.dds.publication.DataWriterCacheStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

◆ get_datawriter_protocol_status()

void get_datawriter_protocol_status ( DataWriterProtocolStatus status )

<<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>> com.rti.dds.publication.DataWriterProtocolStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

◆ get_matched_subscription_datawriter_protocol_status()

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.

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>> com.rti.dds.publication.DataWriterProtocolStatus to be filled in. Cannot be NULL.
subscription_handle	<<in>> Handle to a specific subscription associated with the com.rti.dds.subscription.DataReader. Cannot be NULL. Must correspond to a subscription currently associated with the com.rti.dds.publication.DataWriter.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

◆ get_matched_subscription_datawriter_protocol_status_by_locator()

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.

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>> com.rti.dds.publication.DataWriterProtocolStatus to be filled in Cannot be NULL.
locator	<<in>> Locator to a specific locator associated with the com.rti.dds.subscription.DataReader. Cannot be NULL. Must correspond to a locator of one or more subscriptions currently associated with the com.rti.dds.publication.DataWriter.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

◆ get_service_request_accepted_status()

void get_service_request_accepted_status ( ServiceRequestAcceptedStatus status )

Accesses the com.rti.dds.infrastructure.StatusKind.SERVICE_REQUEST_ACCEPTED_STATUS communication status.

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

Parameters

status <<inout>> com.rti.dds.publication.ServiceRequestAcceptedStatus to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

◆ get_matched_subscription_locators()

void get_matched_subscription_locators ( LocatorSeq locators )

<<extension>> Retrieve the list of locators for subscriptions currently "associated" with this com.rti.dds.publication.DataWriter.

The locators returned in the locators list are the ones that are used by the DDS implementation to communicate with the corresponding matched com.rti.dds.subscription.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 com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES. Cannot be NULL. .

Exceptions

One	of the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system can not resize it, or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED

◆ get_matched_subscriptions()

void get_matched_subscriptions ( InstanceHandleSeq subscription_handles )

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

This API may return the subscription handles of subscriptions that are inactive. com.rti.dds.publication.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 com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES.

The maximum number of matches possible is configured with com.rti.dds.infrastructure.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 com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system cannot resize it, or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED

◆ is_matched_subscription_active()

boolean 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 com.rti.dds.infrastructure.InstanceHandle_t will become invalid and this function will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.

Parameters

subscription_handle <<in>> The com.rti.dds.infrastructure.InstanceHandle_t of the matched subscription. See com.rti.dds.publication.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 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 com.rti.dds.publication.DataWriter.

The subscription_handle must correspond to a subscription currently associated with the com.rti.dds.publication.DataWriter. Otherwise, the operation will fail and fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. Use com.rti.dds.publication.DataWriter.get_matched_subscriptions to find the subscriptions that are currently matched with the com.rti.dds.publication.DataWriter.

The above information is also available through com.rti.dds.subscription.DataReaderListener::on_data_available() (if a reader listener is installed on the builtin.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 com.rti.dds.subscription.DataReaderListener::on_data_available() of the builtin.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 builtin.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 builtin.SubscriptionBuiltinTopicData.type_code. This information is available through com.rti.dds.subscription.DataReaderListener::on_data_available() (if a reader listener is installed on the builtin.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 com.rti.dds.subscription.DataReader. Must correspond to a subscription currently associated with the com.rti.dds.publication.DataWriter. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_NOT_ENABLED, or com.rti.dds.infrastructure.RETCODE_TIMEOUT

◆ get_matched_subscription_participant_data()

void get_matched_subscription_participant_data	(	ParticipantBuiltinTopicData	participant_data,
		InstanceHandle_t	subscription_handle
	)

This operation retrieves the information on the discovered com.rti.dds.domain.DomainParticipant associated with the subscription that is currently matching with the com.rti.dds.publication.DataWriter.

The subscription_handle must correspond to a subscription currently associated with the com.rti.dds.publication.DataWriter. Otherwise, the operation will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. The operation may also fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET if the subscription corresponds to the same com.rti.dds.domain.DomainParticipant that the DataWriter belongs to. Use com.rti.dds.publication.DataWriter.get_matched_subscriptions to find the subscriptions that are currently matched with the com.rti.dds.publication.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 com.rti.dds.subscription.DataReader. Must correspond to a subscription currently associated with the com.rti.dds.publication.DataWriter.

Cannot be NULL.

Exceptions

One	of the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED

◆ get_topic()

Topic get_topic ( )

This operation returns the com.rti.dds.topic.Topic associated with the com.rti.dds.publication.DataWriter.

This is the same com.rti.dds.topic.Topic that was used to create the com.rti.dds.publication.DataWriter.

Returns: com.rti.dds.topic.Topic that was used to create the com.rti.dds.publication.DataWriter.

◆ get_publisher()

Publisher get_publisher ( )

This operation returns the com.rti.dds.publication.Publisher to which the com.rti.dds.publication.DataWriter belongs.

Returns: com.rti.dds.publication.Publisher to which the com.rti.dds.publication.DataWriter belongs.

◆ wait_for_acknowledgments()

void wait_for_acknowledgments ( Duration_t max_wait )

Blocks the calling thread until all data written by reliable com.rti.dds.publication.DataWriter entity is acknowledged, or until timeout expires.

This operation blocks the calling thread until either all data written by the reliable com.rti.dds.publication.DataWriter entity is acknowledged by (a) all reliable com.rti.dds.subscription.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 com.rti.dds.publication.DataWriter does not have com.rti.dds.infrastructure.ReliabilityQosPolicy kind set to RELIABLE, this operation will complete immediately with com.rti.dds.infrastructure.RETCODE_OK

Parameters

max_wait <<in>> Specifies maximum time to wait for acknowledgements com.rti.dds.infrastructure.Duration_t .

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_NOT_ENABLED, com.rti.dds.infrastructure.RETCODE_TIMEOUT

◆ is_sample_app_acknowledged()

boolean 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 com.rti.dds.infrastructure.ReliabilityQosPolicy.acknowledgment_kind to a value other than com.rti.dds.infrastructure.ReliabilityQosPolicyAcknowledgmentModeKind.PROTOCOL_ACKNOWLEDGMENT_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 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 com.rti.dds.publication.DataWriter is sent and acknowledged (if reliable) by all matched com.rti.dds.subscription.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 com.rti.dds.subscription.DataReader is complete in addition to what com.rti.dds.publication.DataWriter.wait_for_acknowledgments provides.

If the com.rti.dds.publication.DataWriter does not have com.rti.dds.infrastructure.PublishModeQosPolicy kind set to com.rti.dds.infrastructure.PublishModeQosPolicyKind.PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS the operation will complete immediately with com.rti.dds.infrastructure.RETCODE_OK.

Parameters

max_wait <<in>> Specifies maximum time to wait for acknowledgements com.rti.dds.infrastructure.Duration_t .

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_NOT_ENABLED, com.rti.dds.infrastructure.RETCODE_TIMEOUT

◆ assert_liveliness()

void assert_liveliness ( )

This operation manually asserts the liveliness of this com.rti.dds.publication.DataWriter.

This is used in combination with the LIVELINESS policy to indicate to RTI Connext that the com.rti.dds.publication.DataWriter remains active.

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

Note: writing data via the com.rti.ndds.example.FooDataWriter.write or com.rti.ndds.example.FooDataWriter.write_w_timestamp operation asserts liveliness on the com.rti.dds.publication.DataWriter itself, and its com.rti.dds.domain.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 com.rti.dds.infrastructure.RETCODE_NOT_ENABLED

See also: com.rti.dds.infrastructure.LivelinessQosPolicy

◆ flush()

void 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 com.rti.dds.publication.DataWriter does not have com.rti.dds.infrastructure.PublishModeQosPolicy kind set to com.rti.dds.infrastructure.PublishModeQosPolicyKind.PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS, the batch will be sent on the network immediately (in the context of the calling thread).

If the com.rti.dds.publication.DataWriter does have com.rti.dds.infrastructure.PublishModeQosPolicy kind set to com.rti.dds.infrastructure.PublishModeQosPolicyKind.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 as com.rti.ndds.example.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 com.rti.dds.infrastructure.BatchQosPolicy.thread_safe_write is TRUE.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_TIMEOUT, com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

◆ register_instance_untyped()

InstanceHandle_t register_instance_untyped ( Object instance_data )

Register a new instance with this writer.

This method allows type-independent code to work with a variety of concrete com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.register_instance method instead of this one. See that method for detailed documentation.

See also: com.rti.dds.publication.DataWriter.unregister_instance_untyped; com.rti.ndds.example.FooDataWriter.register_instance

Implemented in DynamicDataWriter.

Referenced by FooDataWriter.register_instance(), KeyedBytesDataWriter.register_instance(), and KeyedStringDataWriter.register_instance().

◆ register_instance_w_timestamp_untyped()

InstanceHandle_t register_instance_w_timestamp_untyped	(	Object	instance_data,
		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 com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.register_instance_w_timestamp method instead of this one. See that method for detailed documentation.

See also: com.rti.dds.publication.DataWriter.unregister_instance_w_timestamp_untyped; com.rti.ndds.example.FooDataWriter.register_instance

Referenced by FooDataWriter.register_instance_w_timestamp(), KeyedBytesDataWriter.register_instance_w_timestamp(), and KeyedStringDataWriter.register_instance_w_timestamp().

◆ unregister_instance_untyped()

void unregister_instance_untyped	(	Object	instance_data,
		InstanceHandle_t	handle
	)

Unregister a new instance from this writer.

This method allows type-independent code to work with a variety of concrete com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.unregister_instance method instead of this one. See that method for detailed documentation.

See also: com.rti.dds.publication.DataWriter.register_instance_untyped; com.rti.ndds.example.FooDataWriter.unregister_instance

Implemented in DynamicDataWriter.

Referenced by FooDataWriter.unregister_instance(), KeyedBytesDataWriter.unregister_instance(), and KeyedStringDataWriter.unregister_instance().

◆ unregister_instance_w_timestamp_untyped()

void unregister_instance_w_timestamp_untyped	(	Object	instance_data,
		InstanceHandle_t	handle,
		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 com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.FooDataWriter.unregister_instance_w_timestamp method instead of this one. See that method for detailed documentation.

See also: com.rti.dds.publication.DataWriter.register_instance_w_timestamp_untyped; com.rti.ndds.example.FooDataWriter.FooDataWriter.unregister_instance_w_timestamp

Referenced by FooDataWriter.unregister_instance_w_timestamp(), KeyedBytesDataWriter.unregister_instance_w_timestamp(), and KeyedStringDataWriter.unregister_instance_w_timestamp().

◆ write_untyped()

void write_untyped	(	Object	instance_data,
		InstanceHandle_t	handle
	)

Publish a data sample.

This method allows type-independent code to work with a variety of concrete com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.write method instead of this one. See that method for detailed documentation.

See also: com.rti.dds.publication.DataWriter.write_w_timestamp_untyped; com.rti.ndds.example.FooDataWriter.write

Implemented in DynamicDataWriter.

Referenced by BytesDataWriter.write(), FooDataWriter.write(), KeyedBytesDataWriter.write(), KeyedStringDataWriter.write(), and StringDataWriter.write().

◆ write_w_timestamp_untyped()

void write_w_timestamp_untyped	(	Object	instance_data,
		InstanceHandle_t	handle,
		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 com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.write_w_timestamp method instead of this one. See that method for detailed documentation.

See also: com.rti.dds.publication.DataWriter.write_untyped; com.rti.ndds.example.FooDataWriter.write_w_timestamp

Referenced by BytesDataWriter.write_w_timestamp(), FooDataWriter.write_w_timestamp(), KeyedBytesDataWriter.write_w_timestamp(), KeyedStringDataWriter.write_w_timestamp(), and StringDataWriter.write_w_timestamp().

◆ dispose_untyped()

void dispose_untyped	(	Object	instance_data,
		InstanceHandle_t	handle
	)

Dispose a data sample.

This method allows type-independent code to work with a variety of concrete com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.dispose method instead of this one. See that method for detailed documentation.

See also: com.rti.dds.publication.DataWriter.dispose_w_timestamp_untyped; com.rti.ndds.example.FooDataWriter.dispose

Referenced by FooDataWriter.dispose(), KeyedBytesDataWriter.dispose(), and KeyedStringDataWriter.dispose().

◆ dispose_w_timestamp_untyped()

void dispose_w_timestamp_untyped	(	Object	instance_data,
		InstanceHandle_t	handle,
		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 com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.dispose_w_timestamp method instead of this one. See that method for detailed documentation.

See also: com.rti.dds.publication.DataWriter.dispose_untyped; com.rti.ndds.example.FooDataWriter.dispose_w_timestamp

Implemented in DynamicDataWriter.

Referenced by FooDataWriter.dispose_w_timestamp(), KeyedBytesDataWriter.dispose_w_timestamp(), and KeyedStringDataWriter.dispose_w_timestamp().

◆ get_key_value_untyped()

void get_key_value_untyped	(	Object	key_holder,
		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 com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.get_key_value method instead of this one. See that method for detailed documentation.

See also: com.rti.ndds.example.FooDataWriter.get_key_value

Referenced by FooDataWriter.get_key_value(), KeyedBytesDataWriter.get_key_value(), and KeyedStringDataWriter.get_key_value().

◆ lookup_instance_untyped()

InstanceHandle_t lookup_instance_untyped ( Object key_value )

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 com.rti.ndds.example.FooDataWriter classes in a consistent way.

Statically type-safe code should use the appropriate com.rti.ndds.example.FooDataWriter.lookup_instance method instead of this one. See that method for detailed documentation.

See also: com.rti.ndds.example.FooDataWriter.lookup_instance

Referenced by FooDataWriter.lookup_instance(), KeyedBytesDataWriter.lookup_instance(), and KeyedStringDataWriter.lookup_instance().

◆ take_discovery_snapshot() [1/2]

void take_discovery_snapshot ( )

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

The snapshot will be printed through the com.rti.ndds.config.Logger. 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]

void take_discovery_snapshot ( String file_name )

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.

Public Member Functions

Detailed Description

Member Function Documentation

◆ set_qos()

◆ set_qos_with_profile()

◆ get_qos()

◆ set_listener()

◆ get_listener()

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

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

◆ assert_liveliness()

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

◆ take_discovery_snapshot() [1/2]

◆ take_discovery_snapshot() [2/2]