Session Management

The zenoh::Session is the main zenoh object. The instance of the session reprsents a single zenoh node in the network.

Session

class Session : public zenoh::Owned<::z_owned_session_t>

A Zenoh session.

Constructors

inline Session(Config &&config, SessionOptions &&options = SessionOptions::create_default(), ZResult *err = nullptr)

Create a new Session.

Parameters:

config – Zenoh session Config.
options – options to pass to session creation 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 Session(Config &&config, const ShmClientStorage &shm_storage, SessionOptions &&options = SessionOptions::create_default(), ZResult *err = nullptr)

Create a new Session with custom SHM client set.

Parameters:

config – Zenoh session Config.
shm_storage – storage with custom SHM clients.
options – options to pass to session creation 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 std::variant<SharedShmProvider, ShmProviderNotReadyState> obtain_shm_provider(bool blocking = false) const

Each session’s runtime may create its own provider to manage internal optimizations. This method exposes that provider so it can also be accessed at the application level.

Note that the provider may not be immediately available or may be disabled via configuration. Provider initialization is concurrent and triggered by access events (both transport-internal and through this API).

To use this provider, both shared_memory and transport_optimization config sections must be enabled.

Returns:: SharedShmProvider if initialized from Session’s provider if it exists and ShmProviderNotReadyState with provider state description otherwise.

Warning

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

static inline Session open(Config &&config, SessionOptions &&options = SessionOptions::create_default(), ZResult *err = nullptr)

A factory method equivalent to a Session constructor.

Parameters:

config – Zenoh session Config.
options – options to pass to session creation 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:

Session object. In case of failure it will be return in invalid state.

static inline Session open(Config &&config, const ShmClientStorage &shm_storage, SessionOptions &&options = SessionOptions::create_default(), ZResult *err = nullptr)

A factory method equivalent to a Session constructor for custom SHM clients list.

Parameters:

config – Zenoh session Config.
shm_storage – storage with custom SHM clients.
options – options to pass to session creation 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:

Session object. In case of failure it will be return in invalid state.

Methods

inline Id get_zid() const

Get the unique identifier of the zenoh node associated to this Session.

Returns:: the unique identifier Id.

inline KeyExpr declare_keyexpr(const KeyExpr &key_expr, ZResult *err = nullptr) const

Create KeyExpr instance with numeric id registered in Session routing tables (to reduce bandwith usage).

Parameters:

key_expr – KeyExpr to declare.
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 KeyExpr instance.

inline void undeclare_keyexpr(KeyExpr &&key_expr, ZResult *err = nullptr) const

Remove KeyExpr instance from Session routing table and drop KeyExpr instance.

Parameters:

err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.
key_expr – KeyExpr instance to undeclare, that was previously returned by Session::declare_keyexpr.

template<class C, class D> inline void get(const KeyExpr &key_expr, 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:

key_expr – KeyExpr the key expression matching resources to query.
parameters – the parameters string in URL format.
on_reply – callable that will be called once for each received reply.
on_drop – callable that will be called once all replies are received.
options – GetOptions 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.

template<class Channel> inline Channel::template HandlerType<Reply> get(const KeyExpr &key_expr, 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:

key_expr – the key expression matching resources to query.
parameters – the parameters string in URL format.
channel – channel instance.
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.

Returns:

reply handler.

template<class C, class D> inline Queryable<void> declare_queryable(const KeyExpr &key_expr, C &&on_query, D &&on_drop, QueryableOptions &&options = QueryableOptions::create_default(), ZResult *err = nullptr) const

Create a Queryable object to answer to Session::get requests.

Parameters:

key_expr – the key expression to match the Session::get requests.
on_query – the callable to handle Query requests. Will be called once for each query.
on_drop – the drop callable. Will be called once, when Queryable is destroyed or undeclared.
options – options passed to queryable 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 Queryable object.

template<class C, class D> inline void declare_background_queryable(const KeyExpr &key_expr, C &&on_query, D &&on_drop, QueryableOptions &&options = QueryableOptions::create_default(), ZResult *err = nullptr) const

Declare a background queryable. It will answer to Session::get requests, until the corresponding session is closed or destroyed.

Parameters:

key_expr – the key expression to match the Session::get requests.
on_query – the callable to handle Query requests. Will be called once for each query.
on_drop – the drop callable. Will be called once, when Queryable is destroyed or undeclared.
options – options passed to queryable 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 Queryable<typename Channel::template HandlerType<Query>> declare_queryable(const KeyExpr &key_expr, Channel channel, QueryableOptions &&options = QueryableOptions::create_default(), ZResult *err = nullptr) const

Create a Queryable object to answer to Session::get 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 Session::get requests.
channel – an instance of channel.
options – options passed to queryable 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 Queryable object.

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

Create a Subscriber 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_subscriber(const KeyExpr &key_expr, C &&on_sample, D &&on_drop, SubscriberOptions &&options = SubscriberOptions::create_default(), ZResult *err = nullptr) const

Declare a a background 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 Subscriber<typename Channel::template HandlerType<Sample>> declare_subscriber(const KeyExpr &key_expr, Channel channel, SubscriberOptions &&options = SubscriberOptions::create_default(), ZResult *err = nullptr) const

Create a Subscriber 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.

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

Undeclare a resource. Equivalent to Publisher::delete_resource.

Parameters:

key_expr – the key expression to delete the resource.
options – options 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 void put(const KeyExpr &key_expr, Bytes &&payload, PutOptions &&options = PutOptions::create_default(), ZResult *err = nullptr) const

Publish data to the matching subscribers in the system. Equivalent to Publisher::put.

Parameters:

key_expr – the key expression to put the data.
payload – the data to publish.
options – options 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 Publisher declare_publisher(const KeyExpr &key_expr, PublisherOptions &&options = PublisherOptions::create_default(), ZResult *err = nullptr) const

Create a Publisher object to publish data to matching Subscriber objects.

Parameters:

key_expr – the key expression to match the subscribers.
options – options passed to 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:

a Publisher object.

inline Querier declare_querier(const KeyExpr &key_expr, QuerierOptions &&options = QuerierOptions::create_default(), ZResult *err = nullptr) const

Create a Querier object to send queries to matching Queryable objects.

Parameters:

key_expr – the key expression to match the queryables.
options – options passed to querier 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 Querier object.

inline std::vector<Id> get_routers_z_id(ZResult *err = nullptr) const

Fetches the Zenoh IDs of all connected routers.

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:: a vector of all connected router Id.

inline std::vector<Id> get_peers_z_id(ZResult *err = nullptr) const

Fetches the Zenoh IDs of all connected peers.

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:: a vector of all connected peer Id.

inline std::vector<Transport> get_transports(ZResult *err = nullptr) const

Fetches all transports of this session.

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:: a vector of all transports.

Warning

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

inline std::vector<Link> get_links(std::optional<Transport> transport = {}, ZResult *err = nullptr) const

Fetches all links of this session.

Parameters:

transport – if provided, only links for this transport will be returned.
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 vector of all links.

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 TransportEventsListener<void> declare_transport_events_listener(C &&on_event, D &&on_drop, TransportEventsListenerOptions &&options = TransportEventsListenerOptions::create_default(), ZResult *err = nullptr) const

Declare a transport events listener.

Parameters:

on_event – the callable that will be called each time a transport event occurs.
on_drop – the callable that will be called once listener 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 TransportEventsListener object.

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_transport_events_listener(C &&on_event, D &&on_drop, TransportEventsListenerOptions &&options = TransportEventsListenerOptions::create_default(), ZResult *err = nullptr) const

Declare a background transport events listener. The listener callback will be run in the background until the corresponding session is closed or destroyed.

Parameters:

on_event – the callable that will be called each time a transport event occurs.
on_drop – the callable that will be called once listener 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.

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 TransportEventsListener<typename Channel::template HandlerType<TransportEvent>> declare_transport_events_listener(Channel channel, TransportEventsListenerOptions &&options = TransportEventsListenerOptions::create_default(), ZResult *err = nullptr) const

Declare a transport events listener with a channel.

Template Parameters:

Channel – the type of channel used to create stream of data.

Parameters:

channel – an instance of channel.
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 TransportEventsListener object.

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 LinkEventsListener<void> declare_link_events_listener(C &&on_event, D &&on_drop, LinkEventsListenerOptions &&options = LinkEventsListenerOptions::create_default(), ZResult *err = nullptr) const

Declare a link events listener.

Parameters:

on_event – the callable that will be called each time a link event occurs.
on_drop – the callable that will be called once listener 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 LinkEventsListener object.

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_link_events_listener(C &&on_event, D &&on_drop, LinkEventsListenerOptions &&options = LinkEventsListenerOptions::create_default(), ZResult *err = nullptr) const

Declare a background link events listener. The listener callback will be run in the background until the corresponding session is closed or destroyed.

Parameters:

on_event – the callable that will be called each time a link event occurs.
on_drop – the callable that will be called once listener 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.

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 LinkEventsListener<typename Channel::template HandlerType<LinkEvent>> declare_link_events_listener(Channel channel, LinkEventsListenerOptions &&options = LinkEventsListenerOptions::create_default(), ZResult *err = nullptr) const

Declare a link events listener with a channel.

Template Parameters:

Channel – the type of channel used to create stream of data.

Parameters:

channel – an instance of channel.
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 LinkEventsListener object.

Warning

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

inline void spin_once() const: Spins zenoh executor once, executing a single pending task (such as read, lease, keep alive, accept, connect, etc…) from the task queue.

Note

Zenoh-pico with Z_FEATURE_MULTI_THREAD disabled only.

inline void start_admin_space(ZResult *err = nullptr) const

Starts the admin space for a session.

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-pico with Z_FEATURE_ADMIN_SPACE enabled only.

inline void stop_admin_space(ZResult *err = nullptr) const

Stops the admin space for a session.

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-pico with Z_FEATURE_ADMIN_SPACE enabled only.

inline LivelinessToken liveliness_declare_token(const KeyExpr &key_expr, LivelinessDeclarationOptions &&options = LivelinessDeclarationOptions::create_default(), ZResult *err = nullptr)

Declares a liveliness token on the network.

Liveliness token subscribers on an intersecting key expression will receive a PUT sample when connectivity is achieved, and a DELETE sample if it’s lost.

Parameters:

key_expr – a keyexpr to declare a liveliess token for.
options – liveliness token declaration properties.
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 LivelinessToken.

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

Declares a subscriber on liveliness tokens that intersect key_expr.

Parameters:

key_expr – the key expression to subscribe to.
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.

Returns:

a Subscriber object.

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

Declares a background subscriber on liveliness tokens that intersect key_expr. The subscriber callback will be run in the background until the corresponding session is closed or destroyed.

Parameters:

key_expr – the key expression to subscribe to.
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.

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

Declare a subscriber on liveliness tokens that intersect key_expr.

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 subscribe to.
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 liveliness_get(const KeyExpr &key_expr, C &&on_reply, D &&on_drop, LivelinessGetOptions &&options = LivelinessGetOptions::create_default(), ZResult *err = nullptr) const

Query liveliness tokens currently on the network with a key expression intersecting with key_expr.

Parameters:

key_expr – the key expression to query liveliness tokens for.
on_reply – the callable that will be called for each received reply.
on_drop – the callable that will be called once all replies are received.
options – additional options for the liveliness 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> liveliness_get(const KeyExpr &key_expr, Channel channel, LivelinessGetOptions &&options = LivelinessGetOptions::create_default(), ZResult *err = nullptr) const

Query liveliness tokens currently on the network with a key expression intersecting with key_expr.

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 query liveliness tokens for.
channel – channel instance.
options – additional options for the liveliness 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 Timestamp new_timestamp(ZResult *err = nullptr)

Create Timestamp from session id.

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(): Get session global ID.

inline void close(SessionCloseOptions &&options = SessionCloseOptions::create_default(), ZResult *err = nullptr)

Close the session and undeclare all not yet undeclared Subscriber and Queryable callbacks. After this, all calls to corresponding session (or session entity) methods will fail. It still possible though to process any already received messages using Subscriber or Queryable handlers (but not reply to them).

Parameters:

options – options to pass to close 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 bool is_closed() const

Check if session is closed.

Returns:: true if session is closed, false otherwise.

template<class Ext = zenoh::ext::SessionExt> inline Ext ext() const

Get access to extension functionality.

Template Parameters:: Ext – Session interface extension.
Returns:: Session interface extension providing access to non-core Zenoh functionality.

Warning

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

inline BatchGuard start_batching(ZResult *err = nullptr) const

Activate the batching mechanism.

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:: A RAII-style batch guard.

Note

Zenoh-pico only.

class BatchGuard

A RAII-style batch guard. Until it goes out of scope, any message that would have been sent on the network by subsequent api calls will be instead stored until the batch is full, or BatchGuard::flush is called.

When the guard goes out of scope, all the messages remaining in the batch are automatically flushed.

Note

Zenoh-pico only.

Methods

inline void flush(ZResult *err = nullptr) const

Send the currently batched messages on the network.

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

struct DeleteOptions

Options to be passed to delete_resource operation.

Fields

Priority priority = Z_PRIORITY_DEFAULT: The priority of the delete message.

CongestionControl congestion_control = ::z_internal_congestion_control_default_push(): The congestion control to apply when routing delete message.

bool is_express = false: Whether Zenoh will NOT wait to batch delete message with others to reduce the bandwith.

Reliability reliability = z_reliability_default(): The delete operation reliability.

Warning

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

std::optional<Timestamp> timestamp = {}: the timestamp of this message.

Methods

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

struct GetOptions

Options passed to the Session::get operation.

Fields

QueryTarget target = QueryTarget::Z_QUERY_TARGET_BEST_MATCHING: The Queryables that should be target of the query.

QueryConsolidation consolidation = QueryConsolidation(): The replies consolidation strategy to apply on replies to the query.

Priority priority = Z_PRIORITY_DEFAULT: The priority of the get message.

CongestionControl congestion_control = ::z_internal_congestion_control_default_request(): The congestion control to apply when routing get message.

bool is_express = false: Whether Zenoh will NOT wait to batch get message with others to reduce the bandwith.

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.

ReplyKeyExpr accept_replies = ::z_reply_keyexpr_default(): The accepted replies for the query.

Locality allowed_destination = ::z_locality_default(): Allowed destination.

std::optional<Bytes> attachment = {}: An optional attachment to the query.

uint64_t timeout_ms = 0: The timeout for the query in milliseconds. 0 means default query timeout from zenoh configuration.

std::optional<CancellationToken> cancellation_token = {}: Cancellation token to interrupt the query.

Warning

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

Methods

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

struct LinkEventsListenerOptions

Options to pass to Session::declare_link_events_listener.

Warning

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

Fields

bool history = false: If true, listener will receive events for links that were already established before its declaration.

std::optional<Transport> transport = {}: An optional transport to filter link events for.

Methods

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

struct LivelinessDeclarationOptions

Options to pass to Session::liveliness_declare_token.

Methods

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

struct LivelinessGetOptions

Options to pass to Session::liveliness_get.

Fields

uint64_t timeout_ms = 10000: The timeout for the query in milliseconds.

std::optional<CancellationToken> cancellation_token = {}: Cancellation token to interrupt the query.

Warning

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

Methods

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

struct LivelinessSubscriberOptions

Options to pass to Session::liveliness_declare_subscriber.

Fields

bool history = false: If true, subscriber will receive the state change notifications for liveliness tokens that were declared before its declaration.

Methods

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

struct PublisherOptions

Options to be passed when declaring a Publisher.

Fields

CongestionControl congestion_control = ::z_internal_congestion_control_default_push(): The congestion control to apply when routing messages from this publisher.

Priority priority = Z_PRIORITY_DEFAULT: The priority of messages from this publisher.

bool is_express = false: If true, Zenoh will not wait to batch this message with others to reduce the bandwith.

Reliability reliability = z_reliability_default(): The publisher reliability.

Warning

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

Locality allowed_destination = ::z_locality_default(): Allowed destination.

std::optional<Encoding> encoding = {}: Default encoding to use for Publisher::put.

Methods

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

struct PutOptions

Options passed to the Session::put operation.

Fields

Priority priority = Z_PRIORITY_DEFAULT: The priority of this message.

CongestionControl congestion_control = ::z_internal_congestion_control_default_push(): The congestion control to apply when routing this message.

bool is_express = false: Whether Zenoh will NOT wait to batch this message with others to reduce the bandwith.

Locality allowed_destination = ::z_locality_default(): Allowed destination.

std::optional<Timestamp> timestamp = {}: the timestamp of this message.

std::optional<Encoding> encoding = {}: An optional encoding of the message payload and/or attachment.

Reliability reliability = z_reliability_default(): The put operation reliability.

Warning

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

std::optional<SourceInfo> source_info = {}: The source info of this message.

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

Methods

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

struct QuerierOptions

Options to be passed when declaring a Querier.

Fields

QueryTarget target = QueryTarget::Z_QUERY_TARGET_BEST_MATCHING: The Queryables that should be target of the querier queries.

QueryConsolidation consolidation = QueryConsolidation(): The replies consolidation strategy to apply on replies to the querier queries.

Priority priority = Z_PRIORITY_DEFAULT: The priority of the querier queries.

CongestionControl congestion_control = ::z_internal_congestion_control_default_request(): The congestion control to apply when routing querier queries.

bool is_express = false: Whether Zenoh will NOT wait to batch querier queries with other messages to reduce the bandwith.

ReplyKeyExpr accept_replies = ::z_reply_keyexpr_default(): The accepted replies for the querier queries.

Locality allowed_destination = ::z_locality_default(): Allowed destination for querier queries.

uint64_t timeout_ms = 0: The timeout for the querier queries in milliseconds. 0 means default query timeout from zenoh configuration.

Methods

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

struct QueryableOptions

Options to be passed when declaring a Queryable

Fields

bool complete = false: The completeness of the Queryable.

Locality allowed_origin = ::z_locality_default(): Restrict the matching requests that will be received by this Queryable to the ones that have the compatible allowed_destination.

Methods

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

struct SessionCloseOptions: Options to be passed when closing a Session.

struct SessionOptions

Options to be passed when opening a Session.

Fields

z_task_attr_t *executor_task_attributes = nullptr: The attributes to pass to zenoh session executor thread running read, lease, keep alive, join, connect and other tasks in the background.

Note

Zenoh-pico with Z_FEATURE_MULTI_THREAD enabled only.

bool auto_start_admin_space = false: Auto-start admin space after session creation.

Note

Zenoh-pico with Z_FEATURE_ADMIN_SPACE enabled only.

Methods

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

struct SubscriberOptions

Options to be passed when declaring a Subscriber.

Fields

Locality allowed_origin = ::z_locality_default(): Restrict the matching publications that will be received by this Subscribers to the ones that have the compatible allowed_destination.

Methods

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

struct TransportEventsListenerOptions

Options to pass to Session::declare_transport_events_listener.

Warning

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

Fields

bool history = false: If true, listener will receive events for transports that were already established before its declaration.

Methods

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