<<extension>> <<value-type>> Advanced parameters for writing with a DataWriter More...

#include "rti/pub/WriteParams.hpp"

Public Member Functions
	WriteParams ()
	Creates a WriteParams object with default values.

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

bool	replace_automatic_values () const
	Indicates if the replacement of automatic values has been activated or not.

WriteParams &	replace_automatic_values (bool value)
	Allows retrieving the actual value of those fields that were automatic.

rti::core::SampleIdentity	identity () const
	Gets the sample identity.

WriteParams &	identity (const rti::core::SampleIdentity &value)
	Sets a explicit sample identity for writing.

rti::core::SampleIdentity	related_sample_identity () const
	Gets the related sample identity.

WriteParams &	related_sample_identity (const rti::core::SampleIdentity &value)
	Sets a related sample identity for a sample.

dds::core::Time	source_timestamp () const
	Gets the timestamp.

WriteParams &	source_timestamp (const dds::core::Time &value)
	Sets the source timestamp for writing.

rti::core::Cookie	cookie () const
	Gets the cookie.

WriteParams &	cookie (const rti::core::Cookie &value)
	Sets a cookie for writing.

dds::core::InstanceHandle	handle () const
	Gets the instance handle.

WriteParams &	handle (const dds::core::InstanceHandle &value)
	Sets the instance handle for writing.

int32_t	priority () const
	Gets the priority.

WriteParams &	priority (int32_t value)
	Sets the priority for writing.

rti::core::SampleFlag	flag () const
	Gets the sample flag.

WriteParams &	flag (const rti::core::SampleFlag &value)
	Sets the sample flags for writing.

rti::core::Guid	source_guid () const
	Gets the source GUID.

WriteParams &	source_guid (const rti::core::Guid &value)
	Sets the source GUID for writing.

rti::core::Guid	related_source_guid () const
	Gets the related source guid.

WriteParams &	related_source_guid (const rti::core::Guid &value)
	Sets the related source guid for writing.

rti::core::Guid	related_reader_guid () const
	Gets the related reader GUID.

WriteParams &	related_reader_guid (const rti::core::Guid &value)
	Sets the related reader guid for writing.

Detailed Description

<<extension>> <<value-type>> Advanced parameters for writing with a DataWriter

See Also: dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&)

Constructor & Destructor Documentation

rti::pub::WriteParams::WriteParams ( )

inline

Creates a WriteParams object with default values.

The default instance is such that it makes dds::pub::DataWriter(const T&, WriteParams&) behave identically to dds::pub::DataWriter(const T&).

Member Function Documentation

void rti::pub::WriteParams::reset ( )

Resets all the fields to their default values.

See Also: replace_auto()

bool rti::pub::WriteParams::replace_automatic_values ( ) const

Indicates if the replacement of automatic values has been activated or not.

WriteParams& rti::pub::WriteParams::replace_automatic_values ( bool value )

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, rti::core::SampleIdentity::automatic()) receive their actual value after dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&) is called.

To reset those fields to their automatic value after calling dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&), use rti::pub::WriteParams::reset

Parameters

value Whether to replace automatic values or not

[default] false

rti::core::SampleIdentity rti::pub::WriteParams::identity ( ) const

Gets the sample identity.

WriteParams& rti::pub::WriteParams::identity ( const rti::core::SampleIdentity & value )

Sets a explicit sample identity for writing.

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 Virtual Writer GUID is the virtual GUID associated with the writer writing the sample. This virtual GUID is configured using rti::core::policy::DataWriterProtocol::virtual_guid.

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::sub::SampleInfo::original_publication_virtual_guid and dds::sub::SampleInfo::original_publication_virtual_sequence_number in the dds::sub::SampleInfo.

[default] rti::core::SampleIdentity::automatic().

rti::core::SampleIdentity rti::pub::WriteParams::related_sample_identity ( ) const

Gets the related sample identity.

WriteParams& rti::pub::WriteParams::related_sample_identity ( const rti::core::SampleIdentity & value )

Sets a related sample identity for a sample.

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::sub::SampleInfo (see dds::sub::SampleInfo::get_related_sample_identity).

The default value is rti::core::SampleIdentity::unknown(), and is not propagated.

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

[default] rti::core::SampleIdentity::unknown()

dds::core::Time rti::pub::WriteParams::source_timestamp ( ) const

Gets the timestamp.

WriteParams& rti::pub::WriteParams::source_timestamp ( const dds::core::Time & value )

Sets the source timestamp for writing.

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

[default] dds::core::Time::invalid().

rti::core::Cookie rti::pub::WriteParams::cookie ( ) const

Gets the cookie.

WriteParams& rti::pub::WriteParams::cookie ( const rti::core::Cookie & value )

Sets a cookie for writing.

Used in the callback dds::pub::DataWriterListener::on_application_acknowledgment to associate acknowledgments to samples.

The maximum size of the cookie is configurable using the field rti::core::policy::DataWriterResourceLimits::cookie_max_length.

[default] Empty sequence (zero-length).

dds::core::InstanceHandle rti::pub::WriteParams::handle ( ) const

Gets the instance handle.

Either the handle returned by a previous call to dds::pub::DataWriter::register_instance, or else the special value dds::core::InstanceHandle::nil().

[default] dds::core::InstanceHandle::nil()

WriteParams& rti::pub::WriteParams::handle ( const dds::core::InstanceHandle & value )

Sets the instance handle for writing.

Instance handle

Either the handle returned by a previous call to dds::pub::DataWriter::register_instance, or else the special value dds::core::InstanceHandle::nil().

[default] dds::core::InstanceHandle::nil()

int32_t rti::pub::WriteParams::priority ( ) const

Gets the priority.

WriteParams& rti::pub::WriteParams::priority ( int32_t value )

Sets the priority for writing.

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 (rti::core::policy::PublishModeKind_def::ASYNCHRONOUS) with rti::pub::FlowControllerProperty::scheduling_policy set to FlowControllerSchedulingPolicy_def::HIGHEST_PRIORITY_FIRST.

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 PUBLICATION_PRIORITY_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 PUBLICATION_PRIORITY_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 rti::pub::WriteParams of dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&).

For dispose and unregister samples, use the rti::pub::WriteParams of dds::pub::DataWriter::dispose_instance(rti::pub::WriteParams&) and dds::pub::DataWriter::unregister_instance(rti::pub::WriteParams&).

[default] 0 (lowest priority)

See Also: rti::core::ChannelSettings::priority

rti::core::SampleFlag rti::pub::WriteParams::flag ( ) const

Gets the sample flag.

WriteParams& rti::pub::WriteParams::flag ( const rti::core::SampleFlag & value )

Sets the sample flags for writing.

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 (SampleFlagBits::REDELIVERED_SAMPLE) is reserved for marking samples as redelivered when using RTI Queuing Service.

The second bit (SampleFlagBits::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 Connext Repliers sending multiple responses for a request.

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

[default] 0 (no flags are set)

rti::core::Guid rti::pub::WriteParams::source_guid ( ) const

Gets the source GUID.

WriteParams& rti::pub::WriteParams::source_guid ( const rti::core::Guid & value )

Sets the source GUID for writing.

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

The default value is rti::core::Guid::automatic(), 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] rti::core::Guid::automatic() (the source_guid is automatically set to the dds::pub::DataWriter virtual GUID).

See Also: rti::pub::WriteParams::related_source_guid

rti::core::Guid rti::pub::WriteParams::related_source_guid ( ) const

Gets the related source guid.

WriteParams& rti::pub::WriteParams::related_source_guid ( const rti::core::Guid & value )

Sets the related source guid for writing.

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

The default value is rti::core::Guid::unknown(), and is not propagated.

[default] rti::core::Guid::unknown()

See Also: rti::pub::WriteParams::source_guid

rti::core::Guid rti::pub::WriteParams::related_reader_guid ( ) const

Gets the related reader GUID.

WriteParams& rti::pub::WriteParams::related_reader_guid ( const rti::core::Guid & value )

Sets the related reader guid for writing.

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

The default value is rti::core::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::pub::DataWriter::write(const T&,rti::pub::WriteParams&) 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] rti::core::Guid::unknown()

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation