3.3.4. DataWriter

A DataWriter is attached to exactly one Publisher that acts as a factory for it. Additionally, each DataWriter is bound to a single Topic since its creation. This Topic must exist prior to the creation of the DataWriter, and must be bound to the data type that the DataWriter wants to publish.

The effect of creating a new DataWriter in a Publisher for a specific Topic is to initiate a new publication with the name and data type described by the Topic.

Once the DataWriter is created, the application can inform of changes in the data value using the write() member function on the DataWriter. These changes will be transmitted to all subscriptions matched with this publication.

3.3.4.1. DataWriterQos

DataWriterQos controls the behavior of the DataWriter. Internally it contains the following QosPolicy objects:

QosPolicy class

Accessor/Mutator

Mutable

DurabilityQosPolicy

durability()

No

DurabilityServiceQosPolicy

durability_service()

Yes

DeadlineQosPolicy

deadline()

Yes

LatencyBudgetQosPolicy

latency_budget()

Yes

LivelinessQosPolicy

liveliness()

No

ReliabilityQosPolicy

reliability()

No (*)

DestinationOrderQosPolicy

destination_order()

No

HistoryQosPolicy

history()

Yes

ResourceLimitsQosPolicy

resource_limits()

Yes

TransportPriorityQosPolicy

transport_priority()

Yes

LifespanQosPolicy

lifespan()

Yes

UserDataQosPolicy

user_data()

Yes

OwnershipQosPolicy

ownership()

No

OwnershipStrengthQosPolicy

ownership_strength()

Yes

WriterDataLifecycleQosPolicy

writer_data_lifecycle()

Yes

PublishModeQosPolicy

publish_mode()

Yes

DataRepresentationQosPolicy

representation()

Yes

PropertyPolicyQos

properties()

Yes

RTPSReliableWriterQos

reliable_writer_qos()

Yes

RTPSEndpointQos

endpoint()

Yes

WriterResourceLimitsQos

writer_resource_limits()

Yes

DataSharingQosPolicy

data_sharing()

No

The following non-consolidated property-assigned QoS apply to DataWriters:

Property name

Non-consolidated QoS

fastdds.push_mode

DataWriter operating mode QoS Policy

partitions

Endpoint Partitions

Refer to the detailed description of each QosPolicy class for more information about their usage and default values.

Note

Reliability kind (whether the publication is reliable or best effort) is not mutable. However, the max_blocking_time data member of ReliabilityQosPolicy can be modified any time.

The QoS value of a previously created DataWriter can be modified using the DataWriter::set_qos() member function.

// Create a DataWriter with default DataWriterQos
DataWriter* data_writer =
        publisher->create_datawriter(topic, DATAWRITER_QOS_DEFAULT);
if (nullptr == data_writer)
{
    // Error
    return;
}

// Get the current QoS or create a new one from scratch
DataWriterQos qos = data_writer->get_qos();

// Modify QoS attributes
// (...)

// Assign the new Qos to the object
data_writer->set_qos(qos);

3.3.4.1.1. Default DataWriterQos

The default DataWriterQos refers to the value returned by the get_default_datawriter_qos() member function on the Publisher instance. The special value DATAWRITER_QOS_DEFAULT can be used as QoS argument on create_datawriter() or DataWriter::set_qos() member functions to indicate that the current default DataWriterQos should be used.

When the system starts, the default DataWriterQos is equivalent to the default constructed value DataWriterQos(). The default DataWriterQos can be modified at any time using the set_default_datawriter_qos() member function on the Publisher instance. Modifying the default DataWriterQos will not affect already existing DataWriter instances.

// Get the current QoS or create a new one from scratch
DataWriterQos qos_type1 = publisher->get_default_datawriter_qos();

// Modify QoS attributes
// (...)

// Set as the new default DataWriterQos
if (publisher->set_default_datawriter_qos(qos_type1) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// Create a DataWriter with the new default DataWriterQos.
DataWriter* data_writer_with_qos_type1 =
        publisher->create_datawriter(topic, DATAWRITER_QOS_DEFAULT);
if (nullptr == data_writer_with_qos_type1)
{
    // Error
    return;
}

// Get the current QoS or create a new one from scratch
DataWriterQos qos_type2;

// Modify QoS attributes
// (...)

// Set as the new default DataWriterQos
if (publisher->set_default_datawriter_qos(qos_type2) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// Create a DataWriter with the new default DataWriterQos.
DataWriter* data_writer_with_qos_type2 =
        publisher->create_datawriter(topic, DATAWRITER_QOS_DEFAULT);
if (nullptr == data_writer_with_qos_type2)
{
    // Error
    return;
}

// Resetting the default DataWriterQos to the original default constructed values
if (publisher->set_default_datawriter_qos(DATAWRITER_QOS_DEFAULT)
        != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following
if (publisher->set_default_datawriter_qos(DataWriterQos())
        != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

set_default_datawriter_qos() member function also accepts the special value DATAWRITER_QOS_DEFAULT as input argument. This will reset the current default DataWriterQos to default constructed value DataWriterQos().

// Create a custom DataWriterQos
DataWriterQos custom_qos;

// Modify QoS attributes
// (...)

// Create a DataWriter with a custom DataWriterQos
DataWriter* data_writer = publisher->create_datawriter(topic, custom_qos);
if (nullptr == data_writer)
{
    // Error
    return;
}

// Set the QoS on the DataWriter to the default
if (data_writer->set_qos(DATAWRITER_QOS_DEFAULT) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// The previous instruction is equivalent to the following:
if (data_writer->set_qos(publisher->get_default_datawriter_qos())
        != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

Note

The value DATAWRITER_QOS_DEFAULT has different meaning depending on where it is used: