Extensions

Extra functionality, which is not a part of core Zenoh API.

Serialization / Deserialization

Support for data serialization and deserialization.

class Serializer : public zenoh::Owned<::ze_owned_serializer_t>

A Zenoh data serializer used for incremental serialization of several values. I.e. data produced by subsequent calls to Serializer::serialize can be read by corresponding calls to Deserializer::deserialize in the same order (or alternatively by a single call to deserialize into tuple of serialized types).

Constructors

inline Serializer(): Constructs an empty serializer.

Methods

template<class T> void serialize(const T &value, ZResult *err = nullptr)

Serialize specified value and append it to the underlying Bytes.

Parameters:

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

inline Bytes finish() &&

Finalize serialization and return the underlying Bytes object.

Returns:: underlying Bytes object.

class Deserializer : public zenoh::Copyable<::ze_deserializer_t>

A Zenoh data deserializer used for incremental deserialization of several values. I.e. data produced by subsequent calls to Serializer::serialize can be read by corresponding calls to Deserializer::deserialize in the same order (or alternatively by a single call to serialize into tuple of serialized types).

Constructors

inline Deserializer(const Bytes &b)

Construct deserializer for the specified data.

Parameters:: b – data to initialize deserializer with.

Methods

template<class T> T deserialize(zenoh::ZResult *err = nullptr)

Deserialize next portion of data into specified type.

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

inline bool is_done() const

Checks if deserializer has parsed all the data.

Returns:: true if there is no more data to parse, false otherwise.

template<class T> zenoh::Bytes zenoh::ext::serialize(const T &value, ZResult *err = nullptr)

Serialize a single value into Bytes.

Parameters:

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

Returns:

‘Bytes’ containing serialized value.

template<class T> T zenoh::ext::deserialize(const zenoh::Bytes &bytes, zenoh::ZResult *err = nullptr)

Deserialize Bytes corresponding to a single serialized value.

Parameters:

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

Returns:

deserialized value.

Session Extension

Extra Zenoh entities.

class SessionExt

Zenoh Session interface extension.

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.

Constructors

inline SessionExt(const zenoh::Session &session)

Get extension interface for zenoh::Session. Its lifetime is bound that of the session.

Parameters:: session –

Methods

inline PublicationCache declare_publication_cache(const KeyExpr &key_expr, PublicationCacheOptions &&options = PublicationCacheOptions::create_default(), zenoh::ZResult *err = nullptr) const

Construct and declare a publication cache.

Parameters:

key_expr – The key expression to publish to.
options – Additional options for the publication cache.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

declared PublicationCache instance.

Warning

This API is deprecated. Please use zenoh::ext::SessionExt::declare_advanced_publisher.

inline void declare_background_publication_cache(const KeyExpr &key_expr, PublicationCacheOptions &&options = PublicationCacheOptions::create_default(), zenoh::ZResult *err = nullptr) const

Declare a background publication cache. It will function in background until the corresponding session is closed or destoryed.

Parameters:

key_expr – the key expression to publish to.
options – additional options for the publication cache.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Warning

This API is deprecated. Please use zenoh::ext::SessionExt::declare_advanced_publisher.

template<class C, class D> inline QueryingSubscriber<void> declare_querying_subscriber(const KeyExpr &key_expr, C &&on_sample, D &&on_drop, QueryingSubscriberOptions &&options = QueryingSubscriberOptions::create_default(), zenoh::ZResult *err = nullptr) const

Construct and declare a querying subscriber.

Parameters:

key_expr – the key expression to subscribe to.
on_sample – the callback that will be called for each received sample.
on_drop – the callback that will be called once subscriber is destroyed or undeclared.
options – additional options for querying subscriber.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

declared QueryingSubscriber instance.

Warning

This API is deprecated. Please use zenoh::ext::SessionExt::declare_advanced_subscriber.

template<class C, class D> inline void declare_background_querying_subscriber(const KeyExpr &key_expr, C &&on_sample, D &&on_drop, QueryingSubscriberOptions &&options = QueryingSubscriberOptions::create_default(), zenoh::ZResult *err = nullptr) const

Declare a background querying subscriber for a given key expression. Subscriber callback will be called to process the messages, until the corresponding session is closed or dropped.

Parameters:

key_expr – the key expression to subscribe to.
on_sample – the callback that will be called for each received sample.
on_drop – the callback that will be called once subscriber is destroyed or undeclared.
options – additional options for querying subscriber.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Warning

This API is deprecated. Please use zenoh::ext::SessionExt::declare_background_advanced_subscriber.

template<class Channel> inline QueryingSubscriber<typename Channel::template HandlerType<zenoh::Sample>> declare_querying_subscriber(const KeyExpr &key_expr, Channel channel, QueryingSubscriberOptions &&options = QueryingSubscriberOptions::create_default(), zenoh::ZResult *err = nullptr) const

Construct and declare a querying subscriber.

Template Parameters:

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

Parameters:

key_expr – the key expression to subscriber to.
channel – an instance of channel.
options – options to pass to querying subscriber declaration.
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 QueryingSubscriber object.

Warning

This API is deprecated. Please use zenoh::ext::SessionExt::declare_advanced_subscriber.

inline AdvancedPublisher declare_advanced_publisher(const KeyExpr &key_expr, AdvancedPublisherOptions &&options = AdvancedPublisherOptions::create_default(), zenoh::ZResult *err = nullptr) const

Create an AdvancedPublisher object to publish data to matching zenoh::Subscriberor AdvancedSubscriber objects.

Parameters:

key_expr – the key expression to match the subscribers.
options – options passed to advanced publisher declaration.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

Returns:

an AdvancedPublisher object.

template<class C, class D> inline AdvancedSubscriber<void> declare_advanced_subscriber(const KeyExpr &key_expr, C &&on_sample, D &&on_drop, AdvancedSubscriberOptions &&options = AdvancedSubscriberOptions::create_default(), zenoh::ZResult *err = nullptr) const

Create an AdvancedSubscriber object to receive data from matching Publisher objects or from Session::put and Session::delete_resource requests.

Parameters:

key_expr – the key expression to match the publishers.
on_sample – the callback that will be called for each received sample.
on_drop – the callback that will be called once subscriber is destroyed or undeclared.
options – options to pass to subscriber declaration.
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 Subscriber object.

template<class C, class D> inline void declare_background_advanced_subscriber(const KeyExpr &key_expr, C &&on_sample, D &&on_drop, AdvancedSubscriberOptions &&options = AdvancedSubscriberOptions::create_default(), zenoh::ZResult *err = nullptr) const

Declare a background advanced subscriber. It will receive data from matching Publisher objects or from Session::put and Session::delete_resource requests, until the corresponding session is closed or destroyed.

Parameters:

key_expr – the key expression to match the publishers.
on_sample – the callback that will be called for each received sample.
on_drop – the callback that will be called once subscriber is destroyed or undeclared.
options – options to pass to subscriber declaration.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

template<class Channel> inline AdvancedSubscriber<typename Channel::template HandlerType<Sample>> declare_advanced_subscriber(const KeyExpr &key_expr, Channel channel, AdvancedSubscriberOptions &&options = AdvancedSubscriberOptions::create_default(), zenoh::ZResult *err = nullptr) const

Create an AdvancedSubscriber object to receive data from matching Publisher objects or from. Session::put and Session::delete_resource requests.

Template Parameters:

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

Parameters:

key_expr – the key expression to match the publishers.
channel – an instance of channel.
options – options to pass to subscriber declaration.
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 Subscriber object.

struct AdvancedPublisherOptions

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release. Options passed to the SessionExt::declare_advanced_publisher() function.

Fields

zenoh::Session::PublisherOptions publisher_options = {}: Base publisher options.

std::optional<CacheOptions> cache: Optional settings for publisher cache.

std::optional<SampleMissDetectionOptions> sample_miss_detection = {}

Allow matching Subscribers to detect lost samples and optionally ask for retransimission.

Retransmission can only be done if cache is enabled.

bool publisher_detection = false: Allow this publisher to be detected through liveliness.

std::optional<zenoh::KeyExpr> publisher_detection_metadata = {}: An optional key expression to be added to the liveliness token key expression. It can be used to convey meta data.

Methods

static inline AdvancedPublisherOptions create_default(): Create default option settings.

struct CacheOptions

Setting for advanced publisher’s cache. The cache allows advanced subscribers to recover history and/or lost samples.

Fields

size_t max_samples = 1: Number of samples to keep for each resource.

zenoh::CongestionControl congestion_control = ::z_internal_congestion_control_default_response(): The congestion control to apply to replies.

zenoh::Priority priority = ::z_priority_default(): The priority of replies.

bool is_express = false: If set to true, this cache replies will not be batched. This usually has a positive impact on latency but negative impact on throughput.

Methods

static inline CacheOptions create_default(): Create default option settings.

struct SampleMissDetectionOptions

Settings allowing matching Subscribers to detect lost samples and optionally ask for retransimission.

Fields

std::variant<HeartbeatNone, HeartbeatPeriodic, HeartbeatSporadic> heartbeat = HeartbeatNone{}: Configure last sample miss detection through sporadic or periodic heartbeat.

std::optional<uint64_t> heartbeat_period_ms = {}

The period of publisher periodic heartbeats in ms. When this option is set and heartbeat mode is set to HeartbeatNone, the behavior is the same as HeartbeatPeriodic with the period is set to heartbeat

This option is ignored if heartbeat mode is not set to HeartbeatNone.

Do not use this option, if is temporary left for backward compatibility and will be removed soon

Warning

This API is deprecated and will be removed in future releases. Use heartbeat instead.

Methods

static inline SampleMissDetectionOptions create_default(): Create default option settings.

struct HeartbeatNone: Disable last sample miss detection through heartbeat.

struct HeartbeatPeriodic: Allow last sample miss detection through periodic heartbeat. Periodically send the last published Sample’s sequence number to allow last sample miss detection.

Fields

The period of publisher periodic heartbeats in ms.

struct HeartbeatSporadic: Allow last sample miss detection through sporadic heartbeat. Each period, the last published Sample’s sequence number is sent with z_congestion_control_t::BLOCK but only if it changed since last period.

Fields

The period of publisher sporadic heartbeats in ms.

struct AdvancedSubscriberOptions

Options passed to the SessionExt::declare_advanced_subscriber.

Warning

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

Fields

zenoh::Session::SubscriberOptions subscriber_options: Base subscriber options.

std::optional<HistoryOptions> history = {}: Optional settings for querying historical data. History can only be retransmitted by Publishers that enable caching.

std::optional<RecoveryOptions> recovery = {}: Optional settings for retransmission of detected lost Samples. Retransmission of lost samples can only be done by Publishers that enable caching and sample_miss_detection.

uint64_t query_timeout_ms = 0: Timeout to be used for history and recovery queries. Default value will be used if set to 0.

bool subscriber_detection = false: Allow this subscriber to be detected through liveliness.

std::optional<zenoh::KeyExpr> subscriber_detection_metadata = {}: An optional key expression to be added to the liveliness token key expression. It can be used to convey meta data.

Methods

static inline AdvancedSubscriberOptions create_default(): Create default option settings.

struct HistoryOptions

Settings for retrievieng historical data. History can only be retransmitted by Publishers that enable caching.

Fields

bool detect_late_publishers = false: Enable detection of late joiner publishers and query for their historical data. Late joiner detection can only be achieved for Publishers that enable publisher_detection.

size_t max_samples = 0: Number of samples to query for each resource. 0 corresponds to no limit on number of samples.

uint64_t max_age_ms = 0: Maximum age of samples to query. 0 corresponds to no limit on samples’ age.

Methods

static inline HistoryOptions create_default(): Create default option settings.

struct RecoveryOptions

Settings for recovering lost messages for Advanced Subscriber.

Fields

std::optional<std::variant<Heartbeat, PeriodicQueriesOptions>> last_sample_miss_detection = {}: Setting for detecting last sample(s) miss. Note that it does not affect intermediate sample miss detection/retrieval (which is performed automatically as long as recovery is enabled). If this option is disabled, subscriber will be unable to detect/request retransmission of missed sample until it receives a more recent one from the same publisher.

Methods

static inline RecoveryOptions create_default(): Create default option settings.

struct Heartbeat: Option tag for Heartbeat-based last sample detection.

struct PeriodicQueriesOptions

Settings for periodic queries-based last sample detection.

Fields

uint64_t period_ms = 1000

Period for queries for not yet received Samples.

These queries allow to retrieve the last Sample(s) if the last Sample(s) is/are lost. So it is useful for sporadic publications but useless for periodic publications with a period smaller or equal to this period.

Methods

static inline PeriodicQueriesOptions create_default(): Create default option settings.

struct PublicationCacheOptions

Options passed to the SessionExt::declare_publication_cache.

Warning

This API is deprecated. Please use zenoh::ext::AdvancedPublisher.

Methods

static inline PublicationCacheOptions create_default(): Create default option settings.

struct QueryingSubscriberOptions

Options passed to the SessionExt::declare_querying_subscriber.

Warning

This API is deprecated. Please use zenoh::ext::AdvancedSubscriber.

Fields

std::optional<KeyExpr> query_keyexpr = {}: The key expression to be used for queries.

zenoh::Locality allowed_origin = ::zc_locality_default(): The restriction for the matching publications that will be received by this publication cache.

zenoh::ReplyKeyExpr query_accept_replies = ::zc_reply_keyexpr_default(): The accepted replies for queries.

zenoh::QueryTarget query_target = QueryTarget::Z_QUERY_TARGET_BEST_MATCHING: The target to be used for queries.

zenoh::QueryConsolidation query_consolidation = QueryConsolidation(ConsolidationMode::Z_CONSOLIDATION_MODE_NONE): The consolidation mode to be used for queries.

uint64_t query_timeout_ms = 0: The timeout to be used for queries.

Methods

static inline QueryingSubscriberOptions create_default(): Create default option settings.

class PublicationCache : public zenoh::Owned<::ze_owned_publication_cache_t>

A Zenoh publication cache.

Used to store publications on intersecting key expressions. Can be queried later via zenoh::Session::get to retrieve this data.

Note

Zenoh-c only

Warning

This API is deprecated. Please use zenoh::ext::AdvancedPublisher.

Methods

inline const KeyExpr &get_keyexpr() const: Get the key expression of the publication cache.

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

Undeclare publication cache.

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

template<class Handler> class QueryingSubscriber : public zenoh::ext::detail::QueryingSubscriberBase

A Zenoh querying subscriber declared by SessionExt::declare_querying_subscriber.

In addition to receiving the data it is subscribed to, it also will fetch data from a Queryable at startup and peridodically (using QueryingSubscriber::get).

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

Note

Zenoh-c only.

Warning

This API is deprecated. Please use zenoh::ext::AdvancedSubscriber.

Methods

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

Undeclare querying 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 QueryingSubscriber(QueryingSubscriber<void> &&qs, Handler handler)

Construct stream querying subscriber from callback querying subscriber and handler.

Parameters:

qs – callback querying 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.

Methods

inline void get(const KeyExpr &key_expr, zenoh::Session::GetOptions &&options = zenoh::Session::GetOptions::create_default(), ZResult *err = nullptr) const

Make querying subscriber perform an additional query on a specified selector. The queried samples will be merged with the received publications and made available in the subscriber callback.

Parameters:

key_expr – the key expression matching resources to query.
options – query options.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

class AdvancedPublisher : public zenoh::Owned<::ze_owned_advanced_publisher_t>

A Zenoh advanced publisher.

In addition to publishing the data, it also maintains the storage, allowing matching subscribers to retrive missed samples.

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.

Methods

inline const KeyExpr &get_keyexpr() const: Get the key expression of the advanced publisher.

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

Undeclare advanced 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 advanced publisher.

Returns:: id of this advancedc publisher.

Warning

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

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

Publish a message on advanced 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(), zenoh::ZResult *err = nullptr) const

Undeclare the resource associated with the advanced 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.

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

Construct matching listener, registering a callback for notifying subscribers matching with a given advanced 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, zenoh::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, zenoh::ZResult *err = nullptr) const

Declare matching listener, registering a callback for notifying subscribers matching with a given advanced 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(zenoh::ZResult *err = nullptr) const

Gets advanced 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 AdvancedPublisher::delete_resource operation.

Fields

zenoh::Publisher::DeleteOptions delete_options = {}: Base delete options.

Methods

static inline DeleteOptions create_default(): Create default option settings.

struct PutOptions

Options to be passed to AdvancedPublisher::put operation.

Fields

zenoh::Publisher::PutOptions put_options = {}: Base put options.

Methods

static inline PutOptions create_default(): Create default option settings.

template<class Handler> class AdvancedSubscriber : public zenoh::ext::detail::AdvancedSubscriberBase

An owned Zenoh advanced subscriber.

In addition to receiving the data it is subscribed to, it is also able to receive notifications regarding missed samples and/or automatically recover them.

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

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.

Constructors

inline AdvancedSubscriber(AdvancedSubscriber<void> &&s, Handler handler)

Construct stream advanced subscriber from callback advanced subscriber and handler.

Parameters:

s – callback advanced 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.

Methods

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

Undeclare advanced 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 advanced subscriber data stream.

Methods

template<class C, class D> inline SampleMissListener<void> declare_sample_miss_listener(C &&on_miss_detected, D &&on_drop, zenoh::ZResult *err = nullptr) const

Construct sample miss listener, registering a callback for notifying about missed samples.

Parameters:

on_miss_detected – the callable that will be called every time when missed samples are detected.
on_drop – the callable that will be called once sample miss 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 SampleMissListener object.

Note

Zenoh-c only.

template<class C, class D> inline void declare_background_sample_miss_listener(C &&on_miss_detected, D &&on_drop, zenoh::ZResult *err = nullptr) const

Declare sample miss listener, registering a callback for notifying about detected missed samples. The callback will be run in the background until the corresponding advanced subscriber is destroyed.

Parameters:

on_miss_detected – the callable that will be called every time when missed samples are detected.
on_drop – the callable that will be called once sample miss 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.

Note

Zenoh-c only.

template<class C, class D> inline zenoh::Subscriber<void> detect_publishers(C &&on_sample, D &&on_drop, zenoh::Session::LivelinessSubscriberOptions &&options = zenoh::Session::LivelinessSubscriberOptions::create_default(), ZResult *err = nullptr) const

Declares a liveliness token listener for matching publishers detection. Only advanced publishers, enabling publisher detection can be detected.

Parameters:

on_sample – the callable that will be called each time a liveliness token status is changed.
on_drop – the callable that will be called once subscriber is destroyed or undeclared.
options – options to pass to listener declaration.
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 zenoh::Subscriber object.

template<class Channel> inline zenoh::Subscriber<typename Channel::template HandlerType<Sample>> detect_publishers(Channel channel, zenoh::Session::LivelinessSubscriberOptions &&options = zenoh::Session::LivelinessSubscriberOptions::create_default(), zenoh::ZResult *err = nullptr) const

Declares a liveliness token listener for matching publishers detection. Only advanced publishers, enabling publisher detection can be detected.

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.
options – options to pass to subscriber declaration.
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 Subscriber object.

template<class C, class D> inline void detect_publishers_background(C &&on_sample, D &&on_drop, zenoh::Session::LivelinessSubscriberOptions &&options = zenoh::Session::LivelinessSubscriberOptions::create_default(), zenoh::ZResult *err = nullptr) const

Declares a background liveliness token listener for matching publishers detection. Only advanced publishers, enabling publisher detection can be detected. The subscriber callback will be run in the background until the corresponding session is closed or destroyed.

Parameters:

on_sample – the callable that will be called each time a liveliness token status is changed.
on_drop – the callable that will be called once subscriber is destroyed or undeclared.
options – options to pass to subscriber declaration.
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.

inline const KeyExpr &get_keyexpr() const: Get the key expression of the advanced subscriber.

inline EntityGlobalId get_id() const

Get the id of the advanced subscriber.

Returns:: id of this advanced subscriber.

struct Miss

A struct that represents missed samples.

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.

Fields

zenoh::EntityGlobalId source: The source of missed samples.

uint32_t nb: The number of missed samples.

template<class Handler> class SampleMissListener : public zenoh::ext::detail::SampleMissListenerBase

A Zenoh sample miss listener listener. Missed samples can only be detected from advanced publishers, enabling sample miss detection.

A listener that sends notification when the advanced subscriber misses a sample. Dropping the corresponding subscriber, also drops the listener.

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.

Methods

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

Undeclare sample miss listener, 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 sample miss listener data stream.

Constructors

inline SampleMissListener(SampleMissListener<void> &&m, Handler handler)

Construct stream sample miss listener from callback sample miss listener and handler.

Parameters:

m – callback sample miss listener, that should expose data to the handler in its callback.
handler – handler to access data exposed by m. Zenoh handlers implement recv and try_recv methods, for blocking and non-blocking message reception. But user is free to define his own interface.