Publish-Subscribe

Classes related to publish-subscribe pattern.

class Publisher : public zenoh::Owned<::z_owned_publisher_t>

A Zenoh publisher. Constructed by Session::declare_publisher method.

Methods

inline void put(Bytes &&payload, PutOptions &&options = PutOptions::create_default(), ZResult *err = nullptr) const

Publish a message on publisher key expression.

Parameters:

• payload – data to publish.

• options – optional parameters to pass to put operation.

• err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline void delete_resource(DeleteOptions &&options = DeleteOptions::create_default(), ZResult *err = nullptr) const

Undeclare the resource associated with the publisher key expression.

Parameters:

• options – optional parameters to pass to delete operation.

• err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline const KeyExpr &get_keyexpr() const

Get the key expression of the publisher.

inline void undeclare(ZResult *err = nullptr) &&

Undeclares publisher.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline EntityGlobalId get_id() const

Get the id of the publisher.

Returns:

id of this publisher.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

template<class C, class D>
inline MatchingListener<void> declare_matching_listener(C &&on_status_change, D &&on_drop, ZResult *err = nullptr) const

Construct matching listener, registering a callback for notifying subscribers matching with a given publisher.

Parameters:

• on_status_change – the callable that will be called every time the matching status of the publisher changes (i.e. if last subscriber disconnects or when the first subscriber connects).

• on_drop – the callable that will be called once matching listener is destroyed or undeclared.

• err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a MatchingListener object.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

template<class Channel>
inline MatchingListener<typename Channel::template HandlerType<MatchingStatus>> declare_matching_listener(Channel channel, ZResult *err = nullptr) const

Construct matching listener, delivering notification on publisher status change through a streaming handler.

Template Parameters:

Channel – the type of channel used to create stream of data (see zenoh::channels::FifoChannel or zenoh::channels::RingChannel).

Parameters:

• channel – an instance of channel.

• err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

a MatchingListener object.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

template<class C, class D>
inline void declare_background_matching_listener(C &&on_status_change, D &&on_drop, ZResult *err = nullptr) const

Declare matching listener, registering a callback for notifying subscribers matching with a given publisher. The callback will be run in the background until the corresponding publisher is destroyed.

Parameters:

• on_status_change – the callable that will be called every time the matching status of the publisher changes (i.e. if last subscriber disconnects or when the first subscriber connects).

• on_drop – the callable that will be called once publisher is destroyed or undeclared.

• err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

inline MatchingStatus get_matching_status(ZResult *err = nullptr) const

Gets publisher matching status - i.e. if there are any subscribers matching its key expression.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

struct DeleteOptions

Options to be passed to Publisher::delete_resource operation.

Fields

std::optional<Timestamp> timestamp = {}

The timestamp of this message.

Methods

static inline DeleteOptions create_default()

Create default option settings.

struct PutOptions

Options to be passed to Publisher::put operation.

Fields

std::optional<Encoding> encoding = {}

The encoding of the data to publish.

std::optional<Timestamp> timestamp = {}

The timestamp of this message.

std::optional<SourceInfo> source_info = {}

The source info of this message.

Note

Zenoh-c only.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

std::optional<Bytes> attachment = {}

The attachment to attach to the publication.

Methods

static inline PutOptions create_default()

Create default option settings.

template<class Handler>
class Subscriber : public zenoh::detail::SubscriberBase

A Zenoh subscriber. Destroying or undeclaring subscriber cancels the subscription.

Constructed by Session::declare_subscriber method.

Template Parameters:

Handler – streaming handler exposing data. If void, no handler access is provided and instead data is being processed inside the callback.

Methods

inline Handler undeclare(ZResult *err = nullptr) &&

Undeclare subscriber, and return its handler, which can still be used to process any messages received prior to undeclaration.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline const Handler &handler() const

Return the handler to subscriber data stream.

Constructors

inline Subscriber(Subscriber<void> &&s, Handler handler)

Construct stream subscriber from callback subscriber and handler.

Parameters:

• s – callback subscriber, that should expose data to the handler in its callback.

• handler – handler to access data exposed by s. Zenoh handlers implement recv and try_recv methods, for blocking and non-blocking message reception. But user is free to define his own interface.