RTI Connext .NET API (legacy)  Version 6.1.2
DDS::WriteParams_t Class Reference

<<extension>> Input parameters for writing with DDS::TypedDataWriter::write_w_params, DDS::TypedDataWriter::dispose_w_params, DDS::TypedDataWriter::register_instance_w_params, DDS::TypedDataWriter::unregister_instance_w_params More...

#include <managed_infrastructure.h>

Public Member Functions

void reset ()
 Resets all the fields to their default values. More...
 

Public Attributes

SampleIdentity_t identity
 Identity of the sample. More...
 
SampleIdentity_t related_sample_identity
 The identity of another sample related to this one. More...
 
Time_t source_timestamp
 Source timestamp upon write. More...
 
InstanceHandle_t handle
 Instance handle. More...
 
System::Int32 priority
 Publication priority. More...
 
System::Int32 flag
 Flags associated with the sample. More...
 
GUID_t source_guid
 Identifies the application logical data source associated with the sample being written. More...
 
GUID_t related_source_guid
 Identifies the application logical data source that is related to the sample being written. More...
 
GUID_t related_reader_guid
 Identifies a DataReader that is logically related to the sample that is being written. More...
 

Properties

System::Boolean replace_auto [get, set]
 Allows retrieving the actual value of those fields that were automatic. More...
 

Detailed Description

Member Function Documentation

◆ reset()

void DDS::WriteParams_t::reset ( )
inline

Resets all the fields to their default values.

This operation is useful to reset all the fields to their automatic value when DDS::WriteParams_t::replace_auto is enabled and the same params instance is used in multiple calls to DDS::TypedDataWriter::write_w_params

Member Data Documentation

◆ identity

SampleIdentity_t DDS::WriteParams_t::identity

Identity of the sample.

Identifies the sample being written. The identity consists of a pair (Virtual Writer GUID, Virtual Sequence Number).

Use the default value to let RTI Connext determine the sample identity as follows:

  • The sequence number is increased by one with respect to the previous value.

The virtual sequence numbers for a virtual writer must be strictly monotonically increasing. If the user tries to write a sample with a sequence number smaller or equal to the last sequence number, the write operation will fail.

A DataReader can access the identity of a received sample by using the fields DDS::SampleInfo::original_publication_virtual_guid and DDS::SampleInfo::original_publication_virtual_sequence_number in the DDS::SampleInfo.

[default] DDS::SampleIdentity_t::AUTO_SAMPLE_IDENTITY.

Referenced by RTI.Connext.Queuing.QueueProducer< TRep >::CreateWriteSample(), RTI.Connext.RequestReply.Requester< TReq, TRep >::SendRequest(), and RTI.Connext.Queuing.QueueProducer< TRep >::SendSample().

◆ related_sample_identity

SampleIdentity_t DDS::WriteParams_t::related_sample_identity

The identity of another sample related to this one.

Identifies another sample that is logically related to the one that is written.

When this field is set, the related sample identity is propagated and subscribing applications can retrieve it from the DDS::SampleInfo

The default value is DDS::SampleIdentity_t::UNKNOWN_SAMPLE_IDENTITY, and is not propagated.

A DataReader can access the related identity of a received sample by using the fields DDS::SampleInfo::related_original_publication_virtual_guid and DDS::SampleInfo::related_original_publication_virtual_sequence_number in the DDS::SampleInfo.

[default] DDS::SampleIdentity_t::UNKNOWN_SAMPLE_IDENTITY

Referenced by RTI.Connext.RequestReply.Replier< TReq, TRep >::CreateRequestSample().

◆ source_timestamp

Time_t DDS::WriteParams_t::source_timestamp

Source timestamp upon write.

Specifies the source timestamp that will be available to the DDS::DataReader objects by means of the source_timestamp attribute within the DDS::SampleInfo.

[default] DDS::Time_t::TIME_INVALID.

◆ handle

InstanceHandle_t DDS::WriteParams_t::handle

Instance handle.

Either the handle returned by a previous call to DDS::TypedDataWriter::register_instance, or else the special value DDS::InstanceHandle_t::HANDLE_NIL.

[default] DDS::InstanceHandle_t::HANDLE_NIL

◆ priority

System::Int32 DDS::WriteParams_t::priority

Publication priority.

A positive integer value designating the relative priority of the sample, used to determine the transmission order of pending writes.

Use of publication priorities requires an asynchronous publisher (ASYNCHRONOUS_PUBLISH_MODE_QOS) with DDS::FlowControllerProperty_t::scheduling_policy set to DDS_HPF_FLOW_CONTROLLER_SCHED_POLICY.

Larger numbers have higher priority.

For multi-channel DataWriters, the publication priority of a sample may be used as a filter criteria for determining channel membership.

If the publication priority of the parent DataWriter, or for multi-channel DataWriters, if the publication priority of the parent channel, is set to DDS::PublicationPriority::AUTOMATIC, then the DataWriter or channel will be assigned the priority of the largest publication priority of all samples in the DataWriter or channel.

If the publication priority of the parent DataWriter, and for multi-channel DataWriters, if the publication priority of the parent channel, are set to DDS::PublicationPriority::UNDEFINED, then the DataWriter or channel will be assigned the lowest priority, regardless of the value of the publication priorities of samples written to the DataWriter or channel.

The publication priority of each sample can be set in the DDS::WriteParams_t of DDS::TypedDataWriter::write_w_params.

For dispose and unregister samples, use the DDS::WriteParams_t of DDS::TypedDataWriter::dispose_w_params and DDS::TypedDataWriter::unregister_instance_w_params.

[default] 0 (lowest priority)

See also
DDS::ChannelSettings_t::priority

◆ flag

System::Int32 DDS::WriteParams_t::flag

Flags associated with the sample.

The flags are represented as a 32-bit integer, of which only the 16 least-significant bits are used.

RTI reserves least-significant bits [0-7] for middleware-specific usage.

The application can use least-significant bits [8-15].

The first bit (REDELIVERED_SAMPLE) is reserved for marking samples as redelivered when using RTI Queuing Service.

The second bit (INTERMEDIATE_REPLY_SEQUENCE_SAMPLE) is used to indicate that a response sample is not the last response sample for a given request. This bit is usually set by a Replier sending multiple responses for a request.

An application can inspect the flags associated with a received sample by checking the field DDS::SampleInfo::flag.

[default] 0 (no flags are set)

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

◆ source_guid

GUID_t DDS::WriteParams_t::source_guid

Identifies the application logical data source associated with the sample being written.

When this field is set, the source_guid is propagated and subscribing applications can retrieve it from the DDS::SampleInfo (see DDS::SampleInfo::source_guid).

The default value is DDS::GUID_t::GUID_AUTO, and is not propagated.

The main use case for source_guid and related_source_guid is a request/reply scenario in which a reply has to be sent only to the Requester that issue the related request.

In this case, the Requester's DataWriter will send a request setting the source_guid to an unique value. This value must be the same value even after Requester restart.

The Replier's DataReader will get the request's source_guid from the SampleInfo and it will send it as the related_source_guid of the reply using the Replier's DataWriter.

The Requester's DataReader will install a CFT on the related_source_guid using a filter expression. For example:

@related_source_guid.value = &hex(00000000000000000000000000000001)

This way the reply will be send only to the right Requester.

The source_guid and related_source_guid fields are used by RTI Queuing Service in a request/reply scenario.

[default] DDS::GUID_t::GUID_AUTO (the source_guid is automatically set to the DDS::DataWriter virtual GUID).

See also
DDS::WriteParams_t::related_source_guid

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

◆ related_source_guid

GUID_t DDS::WriteParams_t::related_source_guid

Identifies the application logical data source that is related to the sample being written.

When this field is set, the related_source_guid is propagated and subscribing applications can retrieve it from the DDS::SampleInfo (see DDS::SampleInfo::related_source_guid).

The default value is DDS::GUID_t::GUID_UNKNOWN, and is not propagated.

[default] DDS::GUID_t::GUID_UNKNOWN

See also
DDS::WriteParams_t::source_guid

◆ related_reader_guid

GUID_t DDS::WriteParams_t::related_reader_guid

Identifies a DataReader that is logically related to the sample that is being written.

When this field is set, the related_reader_guid is propagated and subscribing applications can retrieve it from the DDS::SampleInfo (see DDS::SampleInfo::related_subscription_guid).

The default value is DDS::GUID_t::GUID_UNKNOWN, and is not propagated.

The main use case for this field is point-to-point sample distribution using CFT. DataReaders install a CFT on the related_reader_guid using a unique GUID. For example, the filter for DataReader 'n' can be:

@related_reader_guid.value = &hex(00000000000000000000000000000001)

Then, a DataWriter that wants to send the sample to DataReader 'n' will use the DDS::TypedDataWriter::write_w_params method and set related_reader_guid to the value used by DataReader 'n' in its filter expression.

This field is currently used by RTI Queuing Service to distribute a sample to only one of the Consumer's DataReaders attached to a SharedReaderQueue.

[default] DDS::GUID_t::GUID_UNKNOWN

Property Documentation

◆ replace_auto

System:: Boolean DDS::WriteParams_t::replace_auto
getset

Allows retrieving the actual value of those fields that were automatic.

When this field is set, the fields that were configured with an automatic value (for example, DDS::SampleIdentity_t::AUTO_SAMPLE_IDENTITY) receive their actual value after DDS::TypedDataWriter::write_w_params is called.

To reset those fields to their automatic value after calling DDS::TypedDataWriter::write_w_params, use DDS::WriteParams_t::reset

Referenced by RTI.Connext.Queuing.QueueProducer< TRep >::CreateWriteSample(), and RTI.Connext.RequestReply.Requester< TReq, TRep >::SendRequest().