Query-Reply

Classes related to query-reply pattern.

class Querier : public zenoh::Owned<::z_owned_querier_t>

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release. A Zenoh Querier. Constructed by Session::declare_querier method. Queriers allow to send queries to a queryable.

Methods

template<class C, class D>
inline void get(const std::string &parameters, C &&on_reply, D &&on_drop, GetOptions &&options = GetOptions::create_default(), ZResult *err = nullptr) const

Query data from the matching queryables in the system. Replies are provided through a callback function.

Parameters:

  • parameters – the parameters string in URL format.

  • options – Options to pass to get 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 Channel>
inline Channel::template HandlerType<Reply> get(const std::string &parameters, Channel channel, GetOptions &&options = GetOptions::create_default(), ZResult *err = nullptr) const

Query data from the matching queryables in the system. Replies are provided through a channel.

Template Parameters:

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

Parameters:

  • parameters – the parameters string in URL format.

  • channel – channel instance.

  • options – Options to pass to get operation.

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

Returns:

reply handler.

inline const KeyExpr &get_keyexpr() const

Get the key expression of the querier.

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

Undeclares querier.

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

Returns:

id of this querier.

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 queryables matching with a given querier’s key expression and target.

Parameters:

  • on_status_change – the callable that will be called every time the matching status of the querier changes (i.e. if last querier disconnects or when the first querier 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 querier 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 queryables matching with a given querier. The callback will be run in the background until the corresponding querier is destroyed.

Parameters:

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

  • on_drop – the callable that will be called once querier 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 querier matching status - i.e. if there are any queryables 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 GetOptions

Options passed to the Querier::get operation.

Fields

std::optional<Bytes> payload = {}

An optional payload of the query.

std::optional<Encoding> encoding = {}

An optional encoding of the query payload and/or attachment.

std::optional<SourceInfo> source_info = {}

The source info for the query.

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 = {}

An optional attachment to the query.

Methods

static inline GetOptions create_default()

Create default option settings.

template<class Handler>
class Queryable : public zenoh::detail::QueryableBase

A Zenoh queryable. Destroying or undeclaring queryable cancels its callback function.

Constructed by Session::declare_queryable 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 const Handler &handler() const

Return handler to queryable data stream.

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

Undeclare queryable, and return its handler, which can still be used to examine any queries received prior to undeclaration, replying to such queries is undefined behaviour.

Parameters:

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

Constructors

inline Queryable(Queryable<void> &&q, Handler handler)

Construct stream queryable from callback queryable and handler.

Parameters:

  • q – Callback queryable, that should expose data to the handler in its callback.

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

class Query : public zenoh::Owned<::z_owned_query_t>

The query to be answered by a Queryable.

Methods

inline const KeyExpr &get_keyexpr() const

Get the key expression of the query.

Returns:

KeyExpr of the query.

inline std::string_view get_parameters() const

Get query parameters. See Selector for more information.

Returns:

parameters string.

inline std::optional<std::reference_wrapper<const Bytes>> get_payload() const

Get the payload of the query.

Returns:

payload of the query.

inline std::optional<std::reference_wrapper<Bytes>> get_payload()

Get the payload of the query.

Returns:

payload of the query.

inline std::optional<std::reference_wrapper<const Encoding>> get_encoding() const

Get the encoding of the query.

Returns:

encoding of the query.

inline std::optional<std::reference_wrapper<const Bytes>> get_attachment() const

Get the attachment of the query.

Returns:

attachment of the query.

inline std::optional<std::reference_wrapper<Bytes>> get_attachment()

Get the mutable attachment of the query.

Returns:

attachment of the query.

inline void reply(const KeyExpr &key_expr, Bytes &&payload, ReplyOptions &&options = ReplyOptions::create_default(), ZResult *err = nullptr) const

Send reply to a query.

Parameters:

  • options – options to pass to reply 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 reply_err(Bytes &&payload, ReplyErrOptions &&options = ReplyErrOptions::create_default(), ZResult *err = nullptr) const

Send error reply to a query.

Parameters:

  • options – options to pass to reply error 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 reply_del(const KeyExpr &key_expr, ReplyDelOptions &&options = ReplyDelOptions::create_default(), ZResult *err = nullptr) const

Send a delete reply to a query.

Parameters:

  • key_expr – the key of this delete reply.

  • options – the options to pass to reply del 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 Query clone() const

Construct a shallow copy of this Query. This can be used, to send query replies outside of Queryable callback.

The query responses will be sent only when the last clone is destroyed.

struct ReplyDelOptions

Options passed to the Query::reply_del operation.

struct ReplyErrOptions

Options passed to the Query::reply_err operation.

Methods

static inline ReplyErrOptions create_default()

Create default option settings.

struct ReplyOptions

Options passed to the Query::reply operation.

Methods

static inline ReplyOptions create_default()

Create default option settings.

class QueryConsolidation : public zenoh::Copyable<::z_query_consolidation_t>

Replies consolidation mode to apply on replies of get operation.

Constructors

inline QueryConsolidation()

Create a new default QueryConsolidation value.

inline QueryConsolidation(ConsolidationMode v)

Create a new QueryConsolidation value with the given consolidation mode.

Parameters:

v – zenoh::ConsolidationMode value.

Operators

inline bool operator==(const QueryConsolidation &other) const

Equality relation.

Parameters:

other – a value to compare with.

Returns:

true if the two values are equal (have the same consolidation mode).

inline bool operator!=(const QueryConsolidation &other) const

Inequality relation.

Parameters:

other – a value to compare with.

Returns:

true if the two values are not equal (have different consolidation mode)

class Reply : public zenoh::Owned<::z_owned_reply_t>

A reply from queryable to Session::get operation.

Methods

inline bool is_ok() const

Check if the reply is OK (and contains a sample).

Returns:

true if the reply is OK, false if contains a error.

inline const Sample &get_ok() const

Get the reply sample. Will throw a ZException if Reply::is_ok returns false.

Returns:

reply sample.

inline const ReplyError &get_err() const

Get the reply error. Will throw a ZException if Reply::is_ok returns true.

Returns:

reply error.

inline std::optional<Id> get_replier_id() const

Get the id of the Zenoh instance that issued this reply.

Returns:

Zenoh instance id, or an empty optional if the id was not set.

Warning

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

inline Reply clone() const

Construct a shallow copy of this Reply.

The reply will be sent only when the last clone is destroyed.

class ReplyError : public zenoh::Owned<::z_owned_reply_err_t>

Reply error data.

Methods

inline const Bytes &get_payload() const

The payload of this error.

Returns:

error payload.

inline Bytes &get_payload()

The payload of this error.

Returns:

error payload.

inline const Encoding &get_encoding() const

The encoding of this error.

Returns:

error encoding.