fastDDS之Publisher

发布定义了DataWriter和Publisher的关联。要开始发布数据实例的值，应用程序在Publisher中创建一个新的DataWriter。此DataWriter将绑定到描述正在传输的数据类型的Topic上。与此Topic匹配的远程订阅将能够从DataWriter接收数据值更新。

PublisherQos

Publisher作为一个容器，会在PublisherQos给出的公共配置下对不同的DataWriter对象进行分组。Publisher可以包含不同的主题和数据类型的DataWriter对象，属于同一Publisher的DataWriter对象之间除了PublisherQos之外没有任何其他关系，它们独立工作。PublisherQos控制着Publisher的行为，内部包含以下QosPolicy对象：

// Create a DomainParticipant in the desired domain
DomainParticipant* participant =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
    // Error
    return;
}

// Create a Publisher with default PublisherQos
Publisher* publisher =
        participant->create_publisher(PUBLISHER_QOS_DEFAULT);
if (nullptr == publisher)
{
    // Error
    return;
}

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

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

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

通过DomainParticipant对象的get_default_publisher_qos()成员函数可以获取默认的PublisherQos，常量对象PUBLISHER_QOS_DEFAULT可以作为 create_publisher() 和Publisher::set_qos()承运函数的Qos参数，代表使用当前的默认PublisherQos 。
当系统启动时，默认的PublisherQos等同于默认构造值PublisherQos()。默认的PublisherQos可以在任何时候使用DomainParticipant实例上的set_default_publisher_qos()成员函数进行修改。修改默认的PublisherQos不会影响已经存在的Publisher实例。
set_default_publisher_qos()成员函数也接受常量对象PUBLISHER_QOS_DEFAULT作为输入参数。这将把当前默认的PublisherQos重置为默认的构造值PublisherQos()。

PublisherListener

PublisherListener是一个抽象类，定义了将在响应Publisher的状态更改时触发的回调。默认情况下，这些回调函数都是空的，不做任何事情。用户应该实现该类的特化，重写应用程序上需要的回调。未被重写的回调将维持它们空的实现。
PublisherListener继承自DataWriterListener。因此，它能够对报告给DataWriter的所有事件做出反应。由于事件总是被通知给能够处理事件的最特定的实体监听器，因此只有在触发的DataWriter没有附加监听器，或者DataWriter上的StatusMask禁用了回调时，才会调用PublisherListener从DataWriterListener继承的回调。
PublisherListener不添加任何新的回调。

Publisher创建删除

Publisher隶属于一个DomainParticipant，它的创建是通过DomainParticipant实例上的create_publisher()成员函数完成。

Publisher* create_publisher(const PublisherQos& qos,PublisherListener* listener = nullptr,const StatusMask& mask = StatusMask::all())

// Create a DomainParticipant in the desired domain
DomainParticipant* participant =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
    // Error
    return;
}

// Create a Publisher with default PublisherQos and no Listener
// The value PUBLISHER_QOS_DEFAULT is used to denote the default QoS.
Publisher* publisher_with_default_qos =
        participant->create_publisher(PUBLISHER_QOS_DEFAULT);
if (nullptr == publisher_with_default_qos)
{
    // Error
    return;
}

// A custom PublisherQos can be provided to the creation method
PublisherQos custom_qos;

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

Publisher* publisher_with_custom_qos =
        participant->create_publisher(custom_qos);
if (nullptr == publisher_with_custom_qos)
{
    // Error
    return;
}

// Create a Publisher with default QoS and a custom Listener.
// CustomPublisherListener inherits from PublisherListener.
// The value PUBLISHER_QOS_DEFAULT is used to denote the default QoS.
CustomPublisherListener custom_listener;
Publisher* publisher_with_default_qos_and_custom_listener =
        participant->create_publisher(PUBLISHER_QOS_DEFAULT, &custom_listener);
if (nullptr == publisher_with_default_qos_and_custom_listener)
{
    // Error
    return;
}

在创建Publisher的DomainParticipant实例上使用delete_publisher()成员函数，可以删除Publisher。

// Create a DomainParticipant in the desired domain
DomainParticipant* participant =
        DomainParticipantFactory::get_instance()->create_participant(0, PARTICIPANT_QOS_DEFAULT);
if (nullptr == participant)
{
    // Error
    return;
}

// Create a Publisher
Publisher* publisher =
        participant->create_publisher(PUBLISHER_QOS_DEFAULT);
if (nullptr == publisher)
{
    // Error
    return;
}

// Use the Publisher to communicate
// (...)

// Delete the entities the Publisher created.
if (publisher->delete_contained_entities() != ReturnCode_t::RETCODE_OK)
{
    // Publisher failed to delete the entities it created.
    return;
}

// Delete the Publisher
if (participant->delete_publisher(publisher) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

DataWriter

DataWriter依附于一个作为其工厂的Publisher。每个DataWriter一创建就会被绑定到单个Topic。此Topic必须在创建DataWriter之前存在，并且必须绑定到DataWriter要发布的数据类型。
Publisher为特定主题创建新的DataWriter的会发布一个具有主题所描述的名称和数据类型的消息。一旦创建了DataWriter，应用程序就可以使用DataWriter上的write()成员函数通知数据值的更改。这些更改将传输到与此发布匹配的所有订阅。
DataWriterQos控制DataWriter的行为。在内部它包含以下QosPolicy对象:

已经创建的DataWriter的QoS值可以使用成员函数DataWriter::set_qos()修改。

// 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);

默认的DataWriterQos是由Publisher实例的get_default_datawriter_qos()成员函数返回的值。常量对象DATAWRITER_QOS_DEFAULT可作为create_datawriter()或DataWriter::set_qos()成员函数上的QoS参数，表示应使用当前默认的DataWriterQos。
当系统启动时，默认的DataWriterQos相当于默认构造值DataWriterQos()。默认的DataWriterQos可以在任何时候使用Publisher实例上的set_default_datawriter_qos()成员函数进行修改。修改默认的DataWriterQos不会影响已经存在的DataWriter实例。
set_default_datawriter_qos()成员函数也接受特殊值DATAWRITER_QOS_DEFAULT作为输入参数。这将把当前默认的DataWriterQos重置为默认构造值DataWriterQos()。

DataWriterListener

DataWriterListener是一个抽象类，定义了在响应DataWriter上的状态更改时将触发的回调。默认情况下，所有这些回调函数都是空的，不做任何事情。用户应该实现该类的特化，覆盖应用程序上需要的回调。未被覆盖的回调将保持它们的空实现。
DataWriterListener定义了以下回调:
1.on_publication_matched(): DataReader已经找到了主题匹配，具有公共分区和兼容的QoS的DataReader，或者停止与先前认为匹配的DataReader进行匹配。
2.on_offered_deadline_missed():在DataWriterQos上配置的截止时间内，DataWriter无法提供数据。它将在DataWriter未能提供数据的每个截止日期期间和数据实例中被调用。
3.on_offered_incompatible_qos(): DataWriter已经找到了一个与主题匹配的DataReader，并且有一个公共分区，但是请求的QoS与DataWriter上定义的QoS不兼容。
4.on_liveliness_lost(): DataWriter没有按照DataWriterQos上的活动配置执行，因此，DataReader将认为datwriter不再活动。
5.on_unacknowledgement d_sample_removed(): DataWriter删除一个没有被任何DataReader匹配确认的样本。这可能发生在受限的网络中，或者如果发布吞吐量要求太高。这个回调可以用来检测这些情况，这样发布应用程序就可以应用一些解决方案来缓解这个问题，比如降低发布速率。

DataWriter创建删除

DataWriter始终属于一个Publisher。DataWriter的创建是通过Publisher实例上的create_datawriter()成员函数完成的，该函数充当DataWriter的工厂。

DataWriter* create_datawriter(
            Topic* topic,
            const DataWriterQos& qos,
            DataWriterListener* listener = nullptr,
            const StatusMask& mask = StatusMask::all())

下面是创建的示例：

// Create a DataWriter with default DataWriterQos and no Listener
// The value DATAWRITER_QOS_DEFAULT is used to denote the default QoS.
DataWriter* data_writer_with_default_qos =
        publisher->create_datawriter(topic, DATAWRITER_QOS_DEFAULT);
if (nullptr == data_writer_with_default_qos)
{
    // Error
    return;
}

// A custom DataWriterQos can be provided to the creation method
DataWriterQos custom_qos;

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

DataWriter* data_writer_with_custom_qos =
        publisher->create_datawriter(topic, custom_qos);
if (nullptr == data_writer_with_custom_qos)
{
    // Error
    return;
}

// Create a DataWriter with default QoS and a custom Listener.
// CustomDataWriterListener inherits from DataWriterListener.
// The value DATAWRITER_QOS_DEFAULT is used to denote the default QoS.
CustomDataWriterListener custom_listener;
DataWriter* data_writer_with_default_qos_and_custom_listener =
        publisher->create_datawriter(topic, DATAWRITER_QOS_DEFAULT, &custom_listener);
if (nullptr == data_writer_with_default_qos_and_custom_listener)
{
    // Error
    return;
}

在创建DataWriter的Publisher上使用delete_datawriter()成员函数删除DataWriter

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

// Use the DataWriter to communicate
// (...)

// Delete the DataWriter
if (publisher->delete_datawriter(data_writer) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

发布数据

用户通过writer上的write()成员函数通知数据实例的值发生变化。然后，此更改将传达给与DataWriter匹配的每个DataReader。

bool write(void* data);
ReturnCode_t write( void* data,const InstanceHandle_t& handle);

以下是发送例程：

// Register the data type in the DomainParticipant.
TypeSupport custom_type_support(new CustomDataType());
custom_type_support.register_type(participant, custom_type_support.get_type_name());

// Create a Topic with the registered type.
Topic* custom_topic =
        participant->create_topic("topic_name", custom_type_support.get_type_name(), TOPIC_QOS_DEFAULT);
if (nullptr == custom_topic)
{
    // Error
    return;
}

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

// Get a data instance
void* data = custom_type_support->createData();

// Fill the data values
// (...)

// Publish the new value, deduce the instance handle
if (data_writer->write(data, eprosima::fastrtps::rtps::InstanceHandle_t()) != ReturnCode_t::RETCODE_OK)
{
    // Error
    return;
}

// The data instance can be reused to publish new values,
// but delete it at the end to avoid leaks
custom_type_support->deleteData(data);