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

CSubscriber()

Constructor.

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

virtual ~CSubscriber()

Destructor.

CSubscriber(const CSubscriber&) = delete

CSubscribers are non-copyable.

CSubscriber &operator=(const CSubscriber&) = delete

CSubscribers are non-copyable.

CSubscriber(CSubscriber &&rhs) noexcept

CSubscribers are move-enabled.

CSubscriber &operator=(CSubscriber &&rhs) noexcept

CSubscribers are move-enabled.

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.

bool Destroy()

Destroys this object.

Returns

true if it succeeds, false if it fails.

bool SetQOS(const QOS::SReaderQOS &qos_)

Set subscriber quality of service attributes.

Parameters

qos_ – Quality of service policies.

Returns

True if it succeeds, false if it fails.

QOS::SReaderQOS GetQOS()

Get current subscriber quality of service attributes.

Returns

Quality of service attributes.

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.

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.

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.

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.

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.

bool AddReceiveCallback(ReceiveCallbackT callback_)

Add callback function for incoming receives.

Parameters

callback_ – The callback function to add.

Returns

True if succeeded, false if not.

bool RemReceiveCallback()

Remove callback function for incoming receives.

Returns

True if succeeded, false if not.

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.

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.

inline bool IsCreated() const

Query if this object is created.

Returns

true if created, false if not.

size_t GetPublisherCount() const

Query the number of publishers.

Returns

Number of publishers.

std::string GetTopicName() const

Gets name of the connected topic.

Returns

The topic name.

std::string GetTypeName() const

Gets type of the connected topic.

Returns

The type name.

std::string GetDescription() const

Gets description of the connected topic.

Returns

The description.

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.

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.