Skip to content
Eclipse eCAL™

class eCAL::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.

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


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


11
//---------------------------------------------------------------------------------------
12
// receive content with a callback functions
13
//---------------------------------------------------------------------------------------
14
void OnReceive(const char* topic_name_, const struct eCAL::SReceiveCallbackData* data_)
15
{
16
  size_t      size = data_->size;
17
  const void* data = data_->buf;
18
  long long   time = data_->time;
19
}
20


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


24
// idle main thread
25
while(eCAL::Ok())
26
{
27
  // sleep 100 ms
28
  std::this_thread::sleep_for(std::chrono::milliseconds(100));
29
}

Members

public ECAL_API CSubscriber()

Constructor.

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

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

public ECAL_API CSubscriber(const std::string & topic_name_)

Constructor.

Parameters

  • topic_name_ Unique topic name.

public virtual ECAL_API ~CSubscriber()

Destructor.

public ECAL_API CSubscriber(const CSubscriber &) = delete

CSubscribers are non-copyable.

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

CSubscribers are non-copyable.

public ECAL_API CSubscriber(CSubscriber && rhs) noexcept

CSubscribers are move-enabled.

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

CSubscribers are move-enabled.

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

public inline ECAL_API 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.

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

public ECAL_API bool Destroy()

Destroys this object.

Returns

true if it succeeds, false if it fails.

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

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

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

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

Sets subscriber attribute.

Parameters

  • attr_name_ Attribute name.

  • attr_value_ Attribute value.

Returns

True if it succeeds, false if it fails. @experimental

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

Removes subscriber attribute.

Parameters

  • attr_name_ Attribute name.

Returns

True if it succeeds, false if it fails. @experimental

public ECAL_API size_t Receive(std::string & buf_,long long * time_,int rcv_timeout_) 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_ Standard string for copying message content.

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

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

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

Parameters

  • buf_ Standard string for copying message content.

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

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

public ECAL_API bool RemReceiveCallback()

Remove callback function for incoming receives.

Returns

True if succeeded, false if not.

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

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

public inline ECAL_API bool IsCreated() const

Query if this object is created.

Returns

true if created, false if not.

public ECAL_API size_t GetPublisherCount() const

Query the number of publishers.

Returns

Number of publishers.

public ECAL_API std::string GetTopicName() const

Gets name of the connected topic.

Returns

The topic name.

public ECAL_API std::string GetTypeName() const

Gets type of the connected topic.

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

Returns

The type name.

public ECAL_API std::string GetDescription() const

Gets description of the connected topic.

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

Returns

The description.

public ECAL_API SDataTypeInformation GetDataTypeInformation() const

Gets description of the connected topic.

Returns

The topic information.

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

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

protected std::shared_ptr< CDataReader > m_datareader

protected bool m_created

protected bool m_initialized

protected void InitializeQOS()

protected bool ApplyTopicToDescGate(const std::string & topic_name_,const SDataTypeInformation & topic_info_)