14.1.4.9. Subscriber

class eprosima::fastdds::dds::Subscriber : public eprosima::fastdds::dds::DomainEntity

Class Subscriber, contains the public API that allows the user to control the reception of messages. This class should not be instantiated directly. DomainRTPSParticipant class should be used to correctly create this element.

Public Functions

~Subscriber()

Destructor.

ReturnCode_t enable() override

This operation enables the Subscriber.

Return

RETCODE_OK is successfully enabled. RETCODE_PRECONDITION_NOT_MET if the participant creating this Subscriber is not enabled.

const SubscriberQos &get_qos() const

Allows accessing the Subscriber Qos.

Return

SubscriberQos reference

ReturnCode_t get_qos(SubscriberQos &qos) const

Retrieves the Subscriber Qos.

Return

RETCODE_OK

Parameters

ReturnCode_t set_qos(const SubscriberQos &qos)

Allows modifying the Subscriber Qos. The given Qos must be supported by the SubscriberQos.

Return

RETCODE_IMMUTABLE_POLICY if any of the Qos cannot be changed, RETCODE_INCONSISTENT_POLICY if the Qos is not self consistent and RETCODE_OK if the qos is changed correctly.

Parameters

const SubscriberListener *get_listener() const

Retrieves the attached SubscriberListener.

Return

Pointer to the SubscriberListener

ReturnCode_t set_listener(SubscriberListener *listener)

Modifies the SubscriberListener, sets the mask to StatusMask::all()

Return

RETCODE_OK

Parameters

ReturnCode_t set_listener(SubscriberListener *listener, const StatusMask &mask)

Modifies the SubscriberListener.

Return

RETCODE_OK

Parameters

DataReader *create_datareader(TopicDescription *topic, const DataReaderQos &reader_qos, DataReaderListener *listener = nullptr, const StatusMask &mask = StatusMask::all())

This operation creates a DataReader. The returned DataReader will be attached and belong to the Subscriber.

Return

Pointer to the created DataReader. nullptr if failed.

Parameters
  • topic: Topic the DataReader will be listening.

  • reader_qos: QoS of the DataReader.

  • listener: Pointer to the listener (default: nullptr)

  • mask: StatusMask that holds statuses the listener responds to (default: all).

DataReader *create_datareader_with_profile(TopicDescription *topic, const std::string &profile_name, DataReaderListener *listener = nullptr, const StatusMask &mask = StatusMask::all())

This operation creates a DataReader. The returned DataReader will be attached and belongs to the Subscriber.

Return

Pointer to the created DataReader. nullptr if failed.

Parameters
  • topic: Topic the DataReader will be listening.

  • profile_name: DataReader profile name.

  • listener: Pointer to the listener (default: nullptr)

  • mask: StatusMask that holds statuses the listener responds to (default: all).

ReturnCode_t delete_datareader(DataReader *reader)

This operation deletes a DataReader that belongs to the Subscriber.

The delete_datareader operation must be called on the same Subscriber object used to create the DataReader. If delete_datareader is called on a different Subscriber, the operation will have no effect and it will return an error.

Return

RETCODE_PRECONDITION_NOT_MET if the datareader does not belong to this subscriber, RETCODE_OK if it is correctly deleted and RETCODE_ERROR otherwise.

Parameters

DataReader *lookup_datareader(const std::string &topic_name) const

This operation retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topic_name. If no such DataReader exists, the operation will return nullptr.

If multiple DataReaders attached to the Subscriber satisfy this condition, then the operation will return one of them. It is not specified which one.

Return

Pointer to a previously created DataReader created on a Topic with that topic_name

Parameters
  • topic_name: Name of the topic associated to the DataReader

ReturnCode_t get_datareaders(std::vector<DataReader*> &readers) const

This operation allows the application to access the DataReader objects.

Return

RETCODE_OK

Parameters
  • readers: Vector of DataReader where the list of existing readers is returned

bool has_datareaders() const

This operation checks if the subscriber has DataReaders

Return

true if the subscriber has one or several DataReaders, false in other case

ReturnCode_t notify_datareaders() const

This operation invokes the operation on_data_available on the DataReaderListener objects attached to contained DataReader entities.

This operation is typically invoked from the on_data_on_readers operation in the SubscriberListener. That way the SubscriberListener can delegate to the DataReaderListener objects the handling of the data.

Return

RETCODE_OK

ReturnCode_t set_default_datareader_qos(const DataReaderQos &qos)

This operation sets a default value of the DataReader QoS policies which will be used for newly created DataReader entities in the case where the QoS policies are defaulted in the create_datareader operation.

This operation will check that the resulting policies are self consistent; if they are not, the operation will have no effect and return false.

The special value DATAREADER_QOS_DEFAULT may be passed to this operation to indicate that the default QoS should be reset back to the initial values the factory would use, that is the values that would be used if the set_default_datareader_qos operation had never been called.

Return

RETCODE_INCONSISTENT_POLICY if the Qos is not self consistent and RETCODE_OK if the qos is changed correctly.

Parameters

const DataReaderQos &get_default_datareader_qos() const

This operation returns the default value of the DataReader QoS, that is, the QoS policies which will be used for newly created DataReader entities in the case where the QoS policies are defaulted in the create_datareader operation.

The values retrieved get_default_datareader_qos will match the set of values specified on the last successful call to get_default_datareader_qos, or else, if the call was never made, the default values.

Return

Current default DataReaderQos.

DataReaderQos &get_default_datareader_qos()

This operation returns the default value of the DataReader QoS, that is, the QoS policies which will be used for newly created DataReader entities in the case where the QoS policies are defaulted in the create_datareader operation.

The values retrieved get_default_datareader_qos will match the set of values specified on the last successful call to get_default_datareader_qos, or else, if the call was never made, the default values.

Return

Current default DataReaderQos.

ReturnCode_t get_default_datareader_qos(DataReaderQos &qos) const

This operation retrieves the default value of the DataReader QoS, that is, the QoS policies which will be used for newly created DataReader entities in the case where the QoS policies are defaulted in the create_datareader operation.

The values retrieved get_default_datareader_qos will match the set of values specified on the last successful call to get_default_datareader_qos, or else, if the call was never made, the default values.

Return

RETCODE_OK

Parameters

const DomainParticipant *get_participant() const

This operation returns the DomainParticipant to which the Subscriber belongs.

Return

DomainParticipant Pointer

const fastrtps::rtps::InstanceHandle_t &get_instance_handle() const

Returns the Subscriber’s handle.

Return

InstanceHandle of this Subscriber.