Class CSubscriber#

Inheritance Relationships#

Derived Type#

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.

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.

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 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.

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.

Returns

The type name.

ECAL_API std::string GetDescription() const#

Gets description of the connected topic.

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.

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.