Class CSubscriber

• Defined in File ecal_subscriber.h

Inheritance Relationships

Derived Type

• public eCAL::CMsgSubscriber< T > (Template Class CMsgSubscriber)

Class Documentation

class CSubscriber

eCAL subscriber class.

The CSubscriber

class is used to receive topics from matching eCAL publishers.

For receiving the topic payload the subscriber class provides a callback interface and overloaded receive methods.

// create subscriber, topic name "A"
eCAL::CSubscriber sub("A");

//---------------------------------------------------------------------------------------
// receive content with 100 ms timeout as standard string and read receive time stamp
//---------------------------------------------------------------------------------------
std::string rcv_s;
long long time = 0;
size_t rcv_len = sub.Receive(rcv_s, &time, 100);

//---------------------------------------------------------------------------------------
// receive content with a callback functions
//---------------------------------------------------------------------------------------
void OnReceive(const char* topic_name_, const struct eCAL::SReceiveCallbackData* data_)
{
  size_t      size = data_->size;
  const void* data = data_->buf;
  long long   time = data_->time;
}

// add callback
sub.AddReceiveCallback(std::bind(OnReceive, std::placeholders::_1, std::placeholders::_2));

// idle main thread
while(eCAL::Ok())
{
  // sleep 100 ms
  std::this_thread::sleep_for(std::chrono::milliseconds(100));
}

Subclassed by eCAL::CMsgSubscriber< T >

Public Functions

ECAL_API CSubscriber()

Constructor.

ECAL_API CSubscriber(const std::string &topic_name_, const std::string &topic_type_, const std::string &topic_desc_ = "")

Constructor.

Deprecated:

Please use the constructor CSubscriber(const std::string& topic_name_, const SDataTypeInformation& topic_info_) instead. This function will be removed in future eCAL versions..

Parameters:

• topic_name_ – Unique topic name.

• topic_type_ – Type name (optional for type checking).

• topic_desc_ – Type description (optional for description checking).

ECAL_API CSubscriber(const std::string &topic_name_, const SDataTypeInformation &topic_info_)

Constructor.

Parameters:

• topic_name_ – Unique topic name.

• topic_info_ – Topic information (encoding, type, descriptor)

ECAL_API CSubscriber(const std::string &topic_name_)

Constructor.

Parameters:

topic_name_ – Unique topic name.

ECAL_API virtual ~CSubscriber()

Destructor.

ECAL_API CSubscriber(const CSubscriber&) = delete

CSubscribers are non-copyable.

ECAL_API CSubscriber &operator=(const CSubscriber&) = delete

CSubscribers are non-copyable.

ECAL_API CSubscriber(CSubscriber &&rhs) noexcept

CSubscribers are move-enabled.

ECAL_API CSubscriber &operator=(CSubscriber &&rhs) noexcept

CSubscribers are move-enabled.

ECAL_API bool Create(const std::string &topic_name_, const std::string &topic_type_, const std::string &topic_desc_ = "")

Creates this object.

Deprecated:

Please use the create method bool Create(const std::string& topic_name_, const STopicInformation& topic_info_) instead. This function will be removed in future eCAL versions.

Parameters:

• topic_name_ – Unique topic name.

• topic_type_ – Type name (optional for type checking).

• topic_desc_ – Type description (optional for description checking).

Returns:

true if it succeeds, false if it fails.

ECAL_API inline bool Create(const std::string &topic_name_)

Creates this object.

Parameters:

topic_name_ – Unique topic name.

Returns:

True if it succeeds, false if it fails.

ECAL_API bool Create(const std::string &topic_name_, const SDataTypeInformation &topic_info_)

Creates this object.

Parameters:

• topic_name_ – Unique topic name.

• topic_info_ – Topic information (encoding, type, descriptor)

Returns:

True if it succeeds, false if it fails.

ECAL_API bool Destroy()

Destroys this object.

Returns:

true if it succeeds, false if it fails.

ECAL_API bool SetQOS(const QOS::SReaderQOS &qos_)

Set subscriber quality of service attributes.

Deprecated:

Will be removed in future eCAL versions.

Parameters:

qos_ – Quality of service policies.

Returns:

True if it succeeds, false if it fails.

ECAL_API QOS::SReaderQOS GetQOS()

Get current subscriber quality of service attributes.

Deprecated:

Will be removed in future eCAL versions.

Returns:

Quality of service attributes.

ECAL_API bool SetID(const std::set<long long> &id_set_)

Set a set of id’s to prefiltering topics (see CPublisher::SetID).

Parameters:

id_set_ – Set of id’s.

Returns:

True if it succeeds, false if it fails.

ECAL_API bool SetAttribute(const std::string &attr_name_, const std::string &attr_value_)

Sets subscriber attribute.

This feature is marked as experimental:

Parameters:

• attr_name_ – Attribute name.

• attr_value_ – Attribute value.

Returns:

True if it succeeds, false if it fails.

ECAL_API bool ClearAttribute(const std::string &attr_name_)

Removes subscriber attribute.

This feature is marked as experimental:

Parameters:

attr_name_ – Attribute name.

Returns:

True if it succeeds, false if it fails.

ECAL_API size_t Receive(std::string &buf_, long long *time_ = nullptr, int rcv_timeout_ = 0) const

Receive a message from the publisher.

Deprecated:

Please use the method bool ReceiveBuffer(std::string& buf_, long long* time_ = nullptr, int rcv_timeout_ = 0) instead. This function will be removed in future eCAL versions.

Parameters:

• buf_ – [out] Standard string for copying message content.

• time_ – [out] Time from publisher in us (default = nullptr).

• rcv_timeout_ – Maximum time before receive operation returns (in milliseconds, -1 means infinite).

Returns:

Length of received buffer.

ECAL_API bool ReceiveBuffer(std::string &buf_, long long *time_ = nullptr, int rcv_timeout_ = 0) const

Receive a message from the publisher (able to process zero length buffer).

Parameters:

• buf_ – [out] Standard string for copying message content.

• time_ – [out] Time from publisher in us (default = nullptr).

• rcv_timeout_ – Maximum time before receive operation returns (in milliseconds, -1 means infinite).

Returns:

True if it succeeds, false if it fails.

ECAL_API bool AddReceiveCallback(ReceiveCallbackT callback_)

Add callback function for incoming receives.

Parameters:

callback_ – The callback function to add.

Returns:

True if succeeded, false if not.

ECAL_API bool RemReceiveCallback()

Remove callback function for incoming receives.

Returns:

True if succeeded, false if not.

ECAL_API bool AddEventCallback(eCAL_Subscriber_Event type_, SubEventCallbackT callback_)

Add callback function for subscriber events.

Parameters:

• type_ – The event type to react on.

• callback_ – The callback function to add.

Returns:

True if succeeded, false if not.

ECAL_API bool RemEventCallback(eCAL_Subscriber_Event type_)

Remove callback function for subscriber events.

Parameters:

type_ – The event type to remove.

Returns:

True if succeeded, false if not.

ECAL_API inline bool IsCreated() const

Query if this object is created.

Returns:

true if created, false if not.

ECAL_API size_t GetPublisherCount() const

Query the number of publishers.

Returns:

Number of publishers.

ECAL_API std::string GetTopicName() const

Gets name of the connected topic.

Returns:

The topic name.

ECAL_API std::string GetTypeName() const

Gets type of the connected topic.

Deprecated:

Please use the method SDataTypeInformation GetDataTypeInformation() instead. You can extract the typename from the SDataTypeInformation variable. This function will be removed in future eCAL versions.

Returns:

The type name.

ECAL_API std::string GetDescription() const

Gets description of the connected topic.

Deprecated:

Please use the method SDataTypeInformation GetDataTypeInformation() instead. You can extract the descriptor from the SDataTypeInformation variable. This function will be removed in future eCAL versions.

Returns:

The description.

ECAL_API SDataTypeInformation GetDataTypeInformation() const

Gets description of the connected topic.

Returns:

The topic information.

ECAL_API bool SetTimeout(int timeout_)

Set the timeout parameter for triggering the timeout callback.

Deprecated:

Will be removed in future eCAL versions.

Parameters:

timeout_ – The timeout in milliseconds.

Returns:

True if succeeded, false if not.

ECAL_API std::string Dump(const std::string &indent_ = "") const

Dump the whole class state into a string.

Parameters:

indent_ – Indentation used for dump.

Returns:

The dump sting.