Writes (publishes) objects of type DDS::DynamicData. More...

#include <managed_dynamicdata.h>

Inheritance diagram for DDS::DynamicDataWriter:

Public Member Functions
InstanceHandle_t	register_instance (DynamicData^ instance_data)
	Informs RTI Connext that the application will be modifying a particular instance. More...

InstanceHandle_t	register_instance_w_timestamp (DynamicData^ instance_data, DDS::Time_t% source_timestamp)
	Performs the same functions as register_instance except that the application provides the value for the `source_timestamp`. More...

void	unregister_instance (DynamicData^ instance_data, DDS::InstanceHandle_t% handle)
	Reverses the action of DDS::TypedDataWriter::register_instance. More...

void	unregister_instance_w_timestamp (DynamicData^ instance_data, DDS::InstanceHandle_t% handle, DDS::Time_t% source_timestamp)
	Performs the same function as DDS::TypedDataWriter::unregister_instance except that it also provides the value for the `source_timestamp`. More...

void	write (DynamicData^ instance_data, DDS::InstanceHandle_t% handle)
	Modifies the value of a data instance. More...

void	write_w_timestamp (DynamicData^ instance_data, DDS::InstanceHandle_t% handle, DDS::Time_t% source_timestamp)
	Performs the same function as DDS::TypedDataWriter::write except that it also provides the value for the `source_timestamp`. More...

void	dispose (DynamicData^ instance_data, DDS::InstanceHandle_t% instance_handle)
	Requests the middleware to delete the instance. More...

void	dispose_w_timestamp (DynamicData^ instance_data, DDS::InstanceHandle_t% instance_handle, DDS::Time_t% source_timestamp)
	Performs the same functions as dispose except that the application provides the value for the `source_timestamp` that is made available to DDS::DataReader objects by means of the `source_timestamp` attribute inside the DDS::SampleInfo. More...

void	get_key_value (DynamicData^ key_holder, DDS::InstanceHandle_t% handle)
	Retrieve the instance `key` that corresponds to an instance `handle`. More...

InstanceHandle_t	lookup_instance (DynamicData^ key_holder)
	Retrieve the instance `handle` that corresponds to an instance `key_holder`. More...

Public Member Functions inherited from DDS::TypedDataWriter< DynamicData^>
InstanceHandle_t	register_instance (DynamicData^ instance_data)
	Informs RTI Connext that the application will be modifying a particular instance. More...

InstanceHandle_t	register_instance_w_timestamp (DynamicData^ instance_data, DDS::Time_t% source_timestamp)
	Performs the same functions as register_instance except that the application provides the value for the `source_timestamp`. More...

InstanceHandle_t	register_instance_w_params (DynamicData^ instance_data, DDS::WriteParams_t^ params)
	Performs the same function as DDS::TypedDataWriter::register_instance and DDS::TypedDataWriter::register_instance_w_timestamp except that it also provides the values contained in `params`. More...

void	unregister_instance (DynamicData^ instance_data, DDS::InstanceHandle_t% handle)
	Reverses the action of DDS::TypedDataWriter::register_instance. More...

void	unregister_instance_w_timestamp (DynamicData^ instance_data, DDS::InstanceHandle_t% handle, DDS::Time_t% source_timestamp)
	Performs the same function as DDS::TypedDataWriter::unregister_instance except that it also provides the value for the `source_timestamp`. More...

void	unregister_instance_w_params (DynamicData^ instance_data, DDS::WriteParams_t^ params)
	Performs the same function as DDS::TypedDataWriter::unregister_instance and DDS::TypedDataWriter::unregister_instance_w_timestamp except that it also provides the values contained in `params`. More...

void	write (DynamicData^ instance_data, DDS::InstanceHandle_t% handle)
	Modifies the value of a data instance. More...

void	write_w_timestamp (DynamicData^ instance_data, DDS::InstanceHandle_t% handle, DDS::Time_t% source_timestamp)
	Performs the same function as DDS::TypedDataWriter::write except that it also provides the value for the `source_timestamp`. More...

void	write_w_params (DynamicData^ instance_data, DDS::WriteParams_t^ params)
	Performs the same function as DDS::TypedDataWriter::write and DDS::TypedDataWriter::write_w_timestamp except that it also provides the values contained in `params`. More...

void	dispose (DynamicData^ instance_data, DDS::InstanceHandle_t% instance_handle)
	Requests the middleware to delete the instance. More...

void	dispose_w_timestamp (DynamicData^ instance_data, DDS::InstanceHandle_t% instance_handle, DDS::Time_t% source_timestamp)
	Performs the same functions as dispose except that the application provides the value for the `source_timestamp` that is made available to DDS::DataReader objects by means of the `source_timestamp` attribute inside the DDS::SampleInfo. More...

void	dispose_w_params (DynamicData^ instance_data, DDS::WriteParams_t^ params)
	Performs the same function as DDS::TypedDataWriter::dispose and DDS::TypedDataWriter::dispose_w_timestamp except that it also provides the values contained in `params`. More...

void	get_key_value (DynamicData^ key_holder, DDS::InstanceHandle_t% handle)
	Retrieve the instance `key` that corresponds to an instance `handle`. More...

InstanceHandle_t	lookup_instance (DynamicData^ key_holder)
	Retrieve the instance `handle` that corresponds to an instance `key_holder`. More...

Public Member Functions inherited from DDS::DataWriter
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

Writes (publishes) objects of type DDS::DynamicData.

Instantiates DDS::DataWriter < DDS::DynamicData > .

See also: DDS::DataWriter; DDS::TypedDataWriter; DDS::DynamicData

Member Function Documentation

◆ register_instance()

InstanceHandle_t DDS::DynamicDataWriter::register_instance ( DynamicData^ instance_data )

Informs RTI Connext that the application will be modifying a particular instance.

This operation is only useful for keyed data types. Using it for non-keyed types causes no effect and returns DDS::InstanceHandle_t::HANDLE_NIL. The operation takes as a parameter an instance (of which only the key value is examined) and returns a handle that can be used in successive write() or dispose() operations.

The operation gives RTI Connext an opportunity to pre-configure itself to improve performance.

The use of this operation by an application is optional even for keyed types. If an instance has not been pre-registered, the application can use the special value DDS::InstanceHandle_t::HANDLE_NIL as the DDS::InstanceHandle_t parameter to the write or dispose operation and RTI Connext will auto-register the instance.

For best performance, the operation should be invoked prior to calling any operation that modifies the instance, such as DDS::TypedDataWriter::write, DDS::TypedDataWriter::write_w_timestamp, DDS::TypedDataWriter::dispose and DDS::TypedDataWriter::dispose_w_timestamp and the handle used in conjunction with the data for those calls.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is used.

This operation may fail and return DDS::InstanceHandle_t::HANDLE_NIL if DDS::ResourceLimitsQosPolicy::max_instances limit has been exceeded.

The operation is idempotent. If it is called for an already registered instance, it just returns the already allocated handle. This may be used to lookup and retrieve the handle allocated to a given instance.

This operation can only be called after DDS::DataWriter has been enabled. Otherwise, DDS::InstanceHandle_t::HANDLE_NIL will be returned.

Parameters

instance_data <<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. Cannot be NULL.

Returns: For keyed data type, a handle that can be used in the calls that take a DDS::InstanceHandle_t, such as write, dispose, unregister_instance, or return DDS::InstanceHandle_t::HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always returns DDS::InstanceHandle_t::HANDLE_NIL.

See also: DDS::TypedDataWriter::unregister_instance, DDS::TypedDataWriter::get_key_value, Relationship between registration, liveliness and ownership

◆ register_instance_w_timestamp()

InstanceHandle_t DDS::DynamicDataWriter::register_instance_w_timestamp	(	DynamicData^	instance_data,
		DDS::Time_t%	source_timestamp
	)

Performs the same functions as register_instance except that the application provides the value for the source_timestamp.

The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details.

This operation may fail and return DDS::InstanceHandle_t::HANDLE_NIL if DDS::ResourceLimitsQosPolicy::max_instances limit has been exceeded.

This operation can only be called after DDS::DataWriter has been enabled. Otherwise, DDS::InstanceHandle_t::HANDLE_NIL will be returned.

Parameters

instance_data	<<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. Cannot be NULL.
source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. Cannot be NULL.

Returns: For keyed data type, return a handle that can be used in the calls that take a DDS::InstanceHandle_t, such as write, dispose, unregister_instance, or return DDS::InstanceHandle_t::HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always return DDS::InstanceHandle_t::HANDLE_NIL.

See also: DDS::TypedDataWriter::unregister_instance, DDS::TypedDataWriter::get_key_value

◆ unregister_instance()

void DDS::DynamicDataWriter::unregister_instance	(	DynamicData^	instance_data,
		DDS::InstanceHandle_t%	handle
	)

Reverses the action of DDS::TypedDataWriter::register_instance.

This operation is useful only for keyed data types. Using it for non-keyed types causes no effect and reports no error. The operation takes as a parameter an instance (of which only the key value is examined) and a handle.

This operation should only be called on an instance that is currently registered. This includes instances that have been auto-registered by calling operations such as write or dispose as described in DDS::TypedDataWriter::register_instance. Otherwise, this operation may fail with DDS::Retcode_BadParameter.

This only need be called just once per instance, regardless of how many times register_instance was called for that instance.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is used.

This operation informs RTI Connext that the DDS::DataWriter is no longer going to provide any information about the instance. This operation also indicates that RTI Connext can locally remove all information regarding that instance. The application should not attempt to use the handle previously allocated to that instance after calling this function.

The special value DDS::InstanceHandle_t::HANDLE_NIL can be used for the parameter handle. This indicates that the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If handle is any value other than DDS::InstanceHandle_t::HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS::Retcode_BadParameter.

RTI Connext will not detect the error when the handle is any value other than DDS::InstanceHandle_t::HANDLE_NIL, corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data (by means of the key). RTI Connext will treat as if the unregister_instance() operation is for the instance as indicated by the handle.

If, after a DDS::TypedDataWriter::unregister_instance, the application wants to modify (DDS::TypedDataWriter::write or DDS::TypedDataWriter::dispose) an instance, it has to register it again, or else use the special handle value DDS::InstanceHandle_t::HANDLE_NIL.

This operation does not indicate that the instance is deleted (that is the purpose of DDS::TypedDataWriter::dispose). The operation DDS::TypedDataWriter::unregister_instance just indicates that the DDS::DataWriter no longer has anything to say about the instance. DDS::DataReader entities that are reading the instance may receive a sample with DDS::InstanceStateKind::NOT_ALIVE_NO_WRITERS_INSTANCE_STATE for the instance, unless there are other DDS::DataWriter objects writing that same instance.

DDS::WriterDataLifecycleQosPolicy::autodispose_unregistered_instances controls whether instances are automatically disposed when they are unregistered.

This operation can affect the ownership of the data instance (see OWNERSHIP). If the DDS::DataWriter was the exclusive owner of the instance, then calling unregister_instance() will relinquish that ownership.

If DDS::ReliabilityQosPolicy::kind is set to DDS::ReliabilityQosPolicyKind::RELIABLE_RELIABILITY_QOS and the unregistration would overflow the resource limits of this writer or of a reader, this operation may block for up to DDS::ReliabilityQosPolicy::max_blocking_time; if this writer is still unable to unregister after that period, this method will fail with DDS::Retcode_Timeout.

Parameters

instance_data <<in>> The instance that should be unregistered. If Foo has a key and instance_handle is DDS::InstanceHandle_t::HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If instance_data is used, it must represent an instance that has been registerd. Otherwise, this method may fail with DDS::Retcode_BadParameter . If Foo has a key, instance_data can be NULL only if handle is not DDS::InstanceHandle_t::HANDLE_NIL. Otherwise, this method will fail with DDS::Retcode_BadParameter.

handle <<in>> represents the instance to be unregistered. If Foo has a key and handle is DDS::InstanceHandle_t::HANDLE_NIL, handle is not used and instance is deduced from instance_data. If Foo has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with DDS::Retcode_BadParameter. This method will fail with DDS::Retcode_BadParameter if handle is NULL. If Foo has a key, handle cannot be DDS::InstanceHandle_t::HANDLE_NIL if instance_data is NULL. Otherwise, this method will report the error DDS::Retcode_BadParameter.

Exceptions

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

See also: DDS::TypedDataWriter::register_instance; DDS::TypedDataWriter::unregister_instance_w_timestamp; DDS::TypedDataWriter::get_key_value; Relationship between registration, liveliness and ownership

◆ unregister_instance_w_timestamp()

void DDS::DynamicDataWriter::unregister_instance_w_timestamp	(	DynamicData^	instance_data,
		DDS::InstanceHandle_t%	handle,
		DDS::Time_t%	source_timestamp
	)

Performs the same function as DDS::TypedDataWriter::unregister_instance except that it also provides the value for the source_timestamp.

The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the DDS::TypedDataWriter::unregister_instance operation.

This operation may block and may time out (DDS::Retcode_Timeout) under the same circumtances described for the unregister_instance operation.

Parameters

instance_data	<<in>> The instance that should be unregistered. If Foo has a key and `instance_handle` is DDS::InstanceHandle_t::HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, `instance_data` is not used. If `instance_data` is used, it must represent an instance that has been registerd. Otherwise, this method may fail with DDS::Retcode_BadParameter. If Foo has a key, `instance_data` can be NULL only if `handle` is not DDS::InstanceHandle_t::HANDLE_NIL. Otherwise, this method will fail with DDS::Retcode_BadParameter.
handle	<<in>> represents the `instance` to be unregistered. If Foo has a key and `handle` is DDS::InstanceHandle_t::HANDLE_NIL, `handle` is not used and `instance` is deduced from `instance_data`. If Foo has no key, `handle` is not used. If `handle` is used, it must represent an instance that has been registered. Otherwise, this method may fail with DDS::Retcode_BadParameter. This method will fail with DDS::Retcode_BadParameter if `handle` is NULL. If Foo has a key, `handle` cannot be DDS::InstanceHandle_t::HANDLE_NIL if `instance_data` is NULL. Otherwise, this method will report the error DDS::Retcode_BadParameter.
source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. Cannot be NULL.

Exceptions

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

See also: DDS::TypedDataWriter::register_instance; DDS::TypedDataWriter::unregister_instance; DDS::TypedDataWriter::get_key_value

◆ write()

void DDS::DynamicDataWriter::write	(	DynamicData^	instance_data,
		DDS::InstanceHandle_t%	handle
	)

Modifies the value of a data instance.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is made available to DDS::DataReader objects by means of the source_timestamp attribute inside the DDS::SampleInfo. (Refer to DDS::SampleInfo and DESTINATION_ORDER QoS policy for details).

As a side effect, this operation asserts liveliness on the DDS::DataWriter itself, the DDS::Publisher and the DDS::DomainParticipant.

Note that the special value DDS::InstanceHandle_t::HANDLE_NIL can be used for the parameter handle. This indicates the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If handle is any value other than DDS::InstanceHandle_t::HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS::Retcode_BadParameter.

RTI Connext will not detect the error when the handle is any value other than DDS::InstanceHandle_t::HANDLE_NIL, corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data (by means of the key). RTI Connext will treat as if the write() operation is for the instance as indicated by the handle.

This operation may block if the RELIABILITY kind is set to DDS::ReliabilityQosPolicyKind::RELIABLE_RELIABILITY_QOS and the modification would cause data to be lost or else cause one of the limits specified in the RESOURCE_LIMITS to be exceeded.

Here is how the write operation behaves when KEEP_LAST_HISTORY_QOS and DDS::ReliabilityQosPolicyKind::RELIABLE_RELIABILITY_QOS are used:

The send window size is determined by the DDS::RtpsReliableWriterProtocol_t::max_send_window_size and DDS::RtpsReliableWriterProtocol_t::min_send_window_size fields in the DDS::DataWriterProtocolQosPolicy. If a send window is specified (max_send_window_size is not UNLIMITED) and the window is full, the write operation will block until one of the samples in the send window is protocol-acknowledged (ACKed) (1) or until the DDS::ReliabilityQosPolicy::max_blocking_time expires.
Then, the DDS::DataWriter will try to add the new sample to the writer history.
If the instance associated with the sample is present in the writer history and there are depth (in the HISTORY) samples in the instance, the DataWriter will replace the oldest sample of that instance independently of that sample's acknowledged status, and the write operation will return DDS::ReturnCode_t::RETCODE_OK. Otherwise, no sample will be replaced and the write operation will continue.
If the instance associated with the sample is not present in the writer history and DDS::ResourceLimitsQosPolicy::max_instances is exceeded, the DataWriter will try to replace an existing instance (and its samples) according to the value of DDS::DataWriterResourceLimitsQosPolicy::instance_replacement (see DDS::DataWriterResourceLimitsInstanceReplacementKind).
- If no instance can be replaced, the write operation returns DDS::Retcode_OutOfResources.
If DDS::ResourceLimitsQosPolicy::max_samples is exceeded, the DataWriter will try to drop a sample from a different instance as follows:
- The DataWriter will try first to remove a fully ACKed (2) sample from a different instance 'I' as long as that sample is not the last remaining sample for the instance 'I'. To find this sample, the DataWriter starts iterating from the oldest sample in the writer history to the newest sample.
- If no such sample is found, the DataWriter will replace the oldest sample in the writer history.
The sample is added to the writer history, and the write operation returns DDS::ReturnCode_t::RETCODE_OK.

Here is how the write operation behaves when KEEP_ALL_HISTORY_QOS and DDS::ReliabilityQosPolicyKind::RELIABLE_RELIABILITY_QOS are used:

The send window size is determined by the DDS::RtpsReliableWriterProtocol_t::max_send_window_size and DDS::RtpsReliableWriterProtocol_t::min_send_window_size fields in the DATA_WRITER_PROTOCOL. If a send window is specified (max_send_window_size is not UNLIMITED) and the window is full, the write operation will block until one of the samples in the send window is protocol-acknowledged (ACKed) (1) or until the DDS::ReliabilityQosPolicy::max_blocking_time expires.
- If the max_blocking_time expires, the write operation returns DDS::Retcode_Timeout.
When a sample is protocol-ACKed (1) before max_blocking_time expires, the DataWriter will try to add the sample to the writer history as follows:
- If the instance associated with the sample is not present in the writer history and max_instances is exceeded, the DataWriter will try to replace an existing instance (and its samples) according to the value of DDS::DataWriterResourceLimitsQosPolicy::instance_replacement (see DDS::DataWriterResourceLimitsInstanceReplacementKind).
  - If no instance can be replaced, the write operation returns DDS::Retcode_OutOfResources.
- If DDS::ResourceLimitsQosPolicy::max_samples is exceeded, the DataWriter will go through the samples in the order in which they were added, and it will replace the first sample that is fully ACKed (2).
  - If no fully ACKed sample is found, the DataWriter will block (3) until a sample is fully ACKed and can be replaced or DDS::ReliabilityQosPolicy::max_blocking_time expires. If the max_blocking_time expires, the write operation will return DDS::Retcode_Timeout.
- If DDS::ResourceLimitsQosPolicy::max_samples_per_instance is exceeded, the DataWriter will go through the samples of the instance in the order in which they were added, and it will replace the first sample that is fully ACKed.
  - If no fully ACKed sample is found, the DataWriter will block (3) until a sample is fully ACKed and can be replaced or the max_blocking_time expires. If the max_blocking_time expires, the write operation will return DDS::Retcode_Timeout.
- The sample is added to the writer history, and the write operation returns DDS::ReturnCode_t::RETCODE_OK.

If there are no instance resources left, this operation may fail with DDS::Retcode_OutOfResources. Calling DDS::TypedDataWriter::unregister_instance may help freeing up some resources.

This operation will fail with DDS::Retcode_PreconditionNotMet if the timestamp is less than the timestamp used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp).

See DDS::ReliabilityQosPolicyAcknowledgmentModeKind for more information on the following notes:

(1) A sample in the writer history is considered "protocol ACKed" when the sample has been individually ACKed at the RTPS protocol level by each one of the DataReaders that matched the DataWriter at the moment the sample was added to the writer queue.

Late joiners do not change the protocol ACK state of a sample. If a sample is marked as protocol ACKed because it has been acknowledged by all the matching DataReaders and a DataReader joins later on, the historical sample is still considered protocol ACKed even if it has not been received by the late joiner.
If a sample 'S1' is protocol ACKed and a TopicQuery is received, triggering the publication of 'S1', the sample is still considered protocol ACKed. If a sample 'S1' is not ACKed and a TopicQuery is received triggering the publication of 'S1', the DataWriter will require that both the matching DataReaders on the live RTPS channel and the DataReader on the TopicQuery channel individually protocol ACK the sample in order to consider the sample protocol ACKed.

(2) A sample in the writer history is considered "fully ACKed" when all of the following conditions are met:

The sample is protocol-ACKed.
The sample has been "application-level ACKed" by all the DataReaders matching the DataWriter that have their DDS::ReliabilityQosPolicy::acknowledgement_mode set to DDS::ReliabilityQosPolicyAcknowledgmentModeKind::APPLICATION_EXPLICIT_ACKNOWLEDGEMENT_MODE or DDS::ReliabilityQosPolicyAcknowledgmentModeKind::APPLICATION_AUTO_ACKNOWLEDGEMENT_MODE. Once the sample is application-level ACKed, it cannot change its status to not ACked after new DataReaders are matched. (Application-level ACK occurs when the application acknowledges receipt of a sample.)
If required subscriptions are enabled (see DDS::AvailabilityQosPolicy), the sample must also be ACKed by all the required subscriptions configured on the DataWriter.

(3) It is possible within a single call to the write operation for a DataWriter to block both when the send window is full and then again when DDS::ResourceLimitsQosPolicy::max_samples or DDS::ResourceLimitsQosPolicy::max_samples_per_instance is exceeded. This can happen because blocking on the send window only considers protocol-ACKed samples, while blocking based on resource limits considers fully-ACKed samples. In any case, the total max blocking time of a single call to the write operation will not exceed DDS::ReliabilityQosPolicy::max_blocking_time.

Parameters

instance_data <<in>> The data to write.

This method will fail with DDS::Retcode_BadParameter if instance_data is NULL.

Parameters

handle <<in>> Either the handle returned by a previous call to DDS::TypedDataWriter::register_instance, or else the special value DDS::InstanceHandle_t::HANDLE_NIL. If Foo has a key and handle is not DDS::InstanceHandle_t::HANDLE_NIL, handle must represent a registered instance of type Foo. Otherwise, this method may fail with DDS::Retcode_BadParameter.

Exceptions

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

MT Safety:: It is UNSAFE to modify instance_data before the operation has finished. The operation is otherwise SAFE.

See also: DDS::DataReader; DDS::TypedDataWriter::write_w_timestamp; DESTINATION_ORDER

Referenced by RTI.Connext.Queuing.QueueConsumer< TRep >::SendAvailability().

◆ write_w_timestamp()

void DDS::DynamicDataWriter::write_w_timestamp	(	DynamicData^	instance_data,
		DDS::InstanceHandle_t%	handle,
		DDS::Time_t%	source_timestamp
	)

Performs the same function as DDS::TypedDataWriter::write except that it also provides the value for the source_timestamp.

Explicitly provides the timestamp that will be available to the DDS::DataReader objects by means of the source_timestamp attribute inside the DDS::SampleInfo. (Refer to DDS::SampleInfo and DESTINATION_ORDER QoS policy for details)

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the DDS::TypedDataWriter::write operation.

This operation may block and time out (DDS::Retcode_Timeout) under the same circumtances described for DDS::TypedDataWriter::write.

If there are no instance resources left, this operation may fail with DDS::Retcode_OutOfResources. Calling DDS::TypedDataWriter::unregister_instance may help free up some resources.

This operation may fail with DDS::Retcode_BadParameter under the same circumstances described for the write operation.

Parameters

instance_data	<<in>> The data to write. This method will fail with DDS::Retcode_BadParameter if `instance_data` is NULL.
handle	<<in>> Either the handle returned by a previous call to DDS::TypedDataWriter::register_instance, or else the special value DDS::InstanceHandle_t::HANDLE_NIL. If Foo has a key and `handle` is not DDS::InstanceHandle_t::HANDLE_NIL, `handle` must represent a registered instance of type Foo. Otherwise, this method may fail with DDS::Retcode_BadParameter. This method will fail with DDS::Retcode_BadParameter if `handle` is NULL.
source_timestamp	<<in>> When using BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS the timestamp value must be greater than or equal to the timestamp value used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp) However, if it is less than the timestamp of the previous operation but the difference is less than the DDS::DestinationOrderQosPolicy::source_timestamp_tolerance, the timestamp of the previous operation will be used as the source timestamp of this sample. Otherwise, if the difference is greater than DDS::DestinationOrderQosPolicy::source_timestamp_tolerance, the function will return DDS::Retcode_BadParameter.

Cannot be NULL.

Exceptions

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

See also: DDS::TypedDataWriter::write; DDS::DataReader; DESTINATION_ORDER

◆ dispose()

void DDS::DynamicDataWriter::dispose	(	DynamicData^	instance_data,
		DDS::InstanceHandle_t%	instance_handle
	)

Requests the middleware to delete the instance.

This operation is useful only for keyed data types. Using it for non-keyed types has no effect and reports no error.

When an instance is disposed, the DDS::DataWriter communicates this state change to DDS::DataReader objects by propagating a dispose sample. When the instance changes to a disposed state, you can see the state change on the DataReader by looking at DDS::SampleInfo::instance_state. Disposed instances have the value DDS::InstanceStateKind::NOT_ALIVE_DISPOSED_INSTANCE_STATE.

The resources allocated to dispose instances on the DataWriter are not removed by default. The removal of the resources allocated to a dispose instance on the DataWriter queue can be controlled by using the QoS DDS::WriterDataLifecycleQosPolicy::autopurge_disposed_instances_delay.

Likewise, on the DataReader, the removal of the resources associated with an instance in the dispose state can be controlled by using the QoS DDS::ReaderDataLifecycleQosPolicy::autopurge_disposed_instances_delay.

This operation does not modify the value of the instance. The instance_data parameter is passed just for the purposes of identifying the instance.

When this operation is used, RTI Connext will automatically supply the value of the source_timestamp that is made available to DDS::DataReader objects by means of the source_timestamp attribute inside the DDS::SampleInfo.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the DDS::TypedDataWriter::unregister_instance operation.

The special value DDS::InstanceHandle_t::HANDLE_NIL can be used for the parameter instance_handle. This indicates the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If instance_handle is any value other than DDS::InstanceHandle_t::HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS::Retcode_BadParameter.

RTI Connext will not detect the error when the instance_handle is any value other than DDS::InstanceHandle_t::HANDLE_NIL, and the instance_handle corresponds to an instance that has been registered but does not correspond to the instance deduced from the instance_data (by means of the key). In this case, the instance that will be disposed is the instance corresponding to the instance_handle, not to the instance_data.

This operation may block and time out (DDS::Retcode_Timeout) under the same circumstances described for DDS::TypedDataWriter::write.

If there are no instance resources left, this operation may fail with DDS::Retcode_OutOfResources. Calling DDS::TypedDataWriter::unregister_instance may help free up some resources.

Parameters

instance_data <<in>> The data to dispose. If Foo has a key and instance_handle is DDS::InstanceHandle_t::HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If Foo has a key, instance_data can be NULL only if instance_handle is not DDS::InstanceHandle_t::HANDLE_NIL. Otherwise, this method will fail with DDS::Retcode_BadParameter.

instance_handle <<in>> Either the handle returned by a previous call to DDS::TypedDataWriter::register_instance, or else the special value DDS::InstanceHandle_t::HANDLE_NIL. If Foo has a key and instance_handle is DDS::InstanceHandle_t::HANDLE_NIL, instance_handle is not used and it is deduced from instance_data. If Foo has no key, instance_handle is not used. If instance_handle is used, it must represent an instance of type Foo that has been written or registered with this writer. Otherwise, this method fail with DDS::Retcode_BadParameter. This method will fail with DDS::Retcode_BadParameter if instance_handle is NULL. If Foo has a key, instance_handle cannot be DDS::InstanceHandle_t::HANDLE_NIL if instance_data is NULL. Otherwise, this method will fail with DDS::Retcode_BadParameter.

Exceptions

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

See also: DDS::TypedDataWriter::dispose_w_timestamp; Relationship between registration, liveliness and ownership

◆ dispose_w_timestamp()

void DDS::DynamicDataWriter::dispose_w_timestamp	(	DynamicData^	instance_data,
		DDS::InstanceHandle_t%	instance_handle,
		DDS::Time_t%	source_timestamp
	)

Performs the same functions as dispose except that the application provides the value for the source_timestamp that is made available to DDS::DataReader objects by means of the source_timestamp attribute inside the DDS::SampleInfo.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the DDS::TypedDataWriter::dispose operation.

This operation may block and time out (DDS::Retcode_Timeout) under the same circumtances described for DDS::TypedDataWriter::write.

If there are no instance resources left, this operation may fail with DDS::Retcode_OutOfResources. Calling DDS::TypedDataWriter::unregister_instance may help freeing up some resources.

Parameters

instance_data	<<in>> The data to dispose. If Foo has a key and `instance_handle` is DDS::InstanceHandle_t::HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, `instance_data` is not used. If Foo has a key, `instance_data` can be NULL only if `instance_handle` is not DDS::InstanceHandle_t::HANDLE_NIL. Otherwise, this method will fail with DDS::Retcode_BadParameter.
instance_handle	<<in>> Either the handle returned by a previous call to DDS::TypedDataWriter::register_instance, or else the special value DDS::InstanceHandle_t::HANDLE_NIL. If Foo has a key and `handle` is not DDS::InstanceHandle_t::HANDLE_NIL, `handle` must represent a registered instance of type Foo. Otherwise, this method may fail with DDS::Retcode_BadParameter. This method will fail with DDS::Retcode_BadParameter if `handle` is NULL.
source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the DDS::DataReader objects by means of the `source_timestamp` attribute inside the DDS::SampleInfo. Cannot be NULL.

Exceptions

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

See also: DDS::TypedDataWriter::dispose

◆ get_key_value()

void DDS::DynamicDataWriter::get_key_value	(	DynamicData^	key_holder,
		DDS::InstanceHandle_t%	handle
	)

Retrieve the instance key that corresponds to an instance handle.

Useful for keyed data types.

The operation will only fill the fields that form the key inside the key_holder instance. If the type has no keys, this method has no effect and exits with no error.

For keyed data types, this operation may fail with DDS::Retcode_BadParameter if the handle does not correspond to an existing data-object known to the DDS::DataWriter.

Parameters

key_holder <<inout>> a user data type specific key holder, whose key fields are filled by this operation. If Foo has no key, this method has no effect.

This method will fail with DDS::Retcode_BadParameter if key_holder is NULL.

Parameters

handle <<in>> the instance whose key is to be retrieved. If Foo has a key, handle must represent a registered instance of type Foo. Otherwise, this method will fail with DDS::Retcode_BadParameter. If Foo has a key and handle is DDS::InstanceHandle_t::HANDLE_NIL, this method will fail with DDS::Retcode_BadParameter. This method will fail with DDS::Retcode_BadParameter if handle is NULL.

Exceptions

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

See also: DDS::TypedDataReader::get_key_value

◆ lookup_instance()

InstanceHandle_t DDS::DynamicDataWriter::lookup_instance ( DynamicData^ key_holder )

Retrieve the instance handle that corresponds to an instance key_holder.

Useful for keyed data types.

This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument. The instance parameter is only used for the purpose of examining the fields that define the key. This operation does not register the instance in question. If the instance has not been previously registered, or if for any other reason RTI Connext is unable to provide an instance handle, RTI Connext will return the special value HANDLE_NIL.

Parameters

key_holder <<in>> a user data type specific key holder.

Returns: the instance handle associated with this instance. If Foo has no key, this method has no effect and returns DDS::InstanceHandle_t::HANDLE_NIL

Public Member Functions

Detailed Description

Member Function Documentation

◆ register_instance()

◆ register_instance_w_timestamp()

◆ unregister_instance()

◆ unregister_instance_w_timestamp()

◆ write()

◆ write_w_timestamp()

◆ dispose()

◆ dispose_w_timestamp()

◆ get_key_value()

◆ lookup_instance()