Session

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

Builder function

std::variant<zenoh::Session, zenoh::ErrorMessage> zenoh::open(zenoh::Config &&config, bool start_background_tasks = true)

Create a Session with the given Config

Parameters:
Returns:

a Session if the session was successfully created, an zenoh::ErrorMessage otherwise

Utility functions

void zenoh::init_logger()

Initializes logger.

User may set environment variable RUST_LOG to values debug | info | warn | error to show diagnostic output

Note

zenoh-c only

bool zenoh::scout(zenoh::ScoutingConfig &&config, zenoh::ClosureHello &&callback, ErrNo &error)

Scout for zenoh entities in the network.

Parameters:
Returns:

true if the scout operation was successful, false otherwise

bool zenoh::scout(zenoh::ScoutingConfig &&config, zenoh::ClosureHello &&callback)

Scout for zenoh entities in the network.

Parameters:
Returns:

true if the scout operation was successful, false otherwise

Session class

class Session : public zenohcxx::Owned<::z_owned_session_t>

Main zenoh session class.

Methods

inline Session rcinc()

Clone the Session instance incrementing the reference count This is possible in zenoh-c only where Session is a reference counted object.

Returns:

a new Session instance

Note

zenoh-c only

inline zenoh::Id info_zid() const

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

Returns:

the unique identifier Id

zenoh::KeyExpr declare_keyexpr(const zenoh::KeyExprView &keyexpr)

Create KeyExpr instance with numeric id registered in Session routing tables.

Parameters:

keyexpr – KeyExprView representing string key expression

Returns:

KeyExpr instance

bool undeclare_keyexpr(zenoh::KeyExpr &&keyexpr, ErrNo &error)

Remove KeyExpr instance from Session and drop KeyExpr instance.

Parameters:
Returns:

true if the KeyExpr instance was successfully removed, false otherwise

bool undeclare_keyexpr(zenoh::KeyExpr &&keyexpr)

Remove KeyExpr instance from Session and drop KeyExpr instance.

Parameters:

keyexpr – KeyExpr instance to drop

Returns:

true if the KeyExpr instance was successfully removed, false otherwise

bool get(zenoh::KeyExprView keyexpr, const char *parameters, zenoh::ClosureReply &&callback, const zenoh::GetOptions &options, ErrNo &error)

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

Parameters:
Returns:

true if the query operation was successful, false otherwise

bool get(zenoh::KeyExprView keyexpr, const char *parameters, zenoh::ClosureReply &&callback, const zenoh::GetOptions &options)

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

Parameters:

  • keyexpr – KeyExprView the key expression matching resources to query

  • parameters – the null-terminated string of query parameters

  • callback – zenoh::ClosureReply callback for process Replys

  • options – GetOptions query options

Returns:

true if the query operation was successful, false otherwise

bool get(zenoh::KeyExprView keyexpr, const char *parameters, zenoh::ClosureReply &&callback, ErrNo &error)

Query data from the matching queryables in the system.

Parameters:

  • keyexpr – KeyExprView the key expression matching resources to query

  • parameters – the null-terminated string of query parameters

  • callback – zenoh::ClosureReply callback for process Replys

  • error – zenoh::ErrNo to store the error code

Returns:

true if the query operation was successful, false otherwise

bool get(zenoh::KeyExprView keyexpr, const char *parameters, zenoh::ClosureReply &&callback)

Query data from the matching queryables in the system.

Parameters:

  • keyexpr – KeyExprView the key expression matching resources to query

  • parameters – the null-terminated string of query parameters

  • callback – zenoh::ClosureReply callback for process Replys

Returns:

true if the query operation was successful, false otherwise

bool put(zenoh::KeyExprView keyexpr, const zenoh::BytesView &payload, const zenoh::PutOptions &options, ErrNo &error)

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

Parameters:
Returns:

true if the publish operation was successful, false otherwise

bool put(zenoh::KeyExprView keyexpr, const zenoh::BytesView &payload, const zenoh::PutOptions &options)

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

Parameters:
Returns:

true if the publish operation was successful, false otherwise

bool put(zenoh::KeyExprView keyexpr, const zenoh::BytesView &payload, ErrNo &error)

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

Parameters:
Returns:

true if the publish operation was successful, false otherwise

bool put(zenoh::KeyExprView keyexpr, const zenoh::BytesView &payload)

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

Parameters:

  • keyexpr – KeyExprView the key expression to put the data

  • payload – BytesView the data to publish

Returns:

true if the publish operation was successful, false otherwise

bool delete_resource(zenoh::KeyExprView keyexpr, const zenoh::DeleteOptions &options, ErrNo &error)

Undeclare a resource. Equal to Publisher::delete_resource

Parameters:
Returns:

true if the undeclare operation was successful, false otherwise

bool delete_resource(zenoh::KeyExprView keyexpr, const zenoh::DeleteOptions &options)

Undeclare a resource. Equal to Publisher::delete_resource

Parameters:
Returns:

true if the undeclare operation was successful, false otherwise

bool delete_resource(zenoh::KeyExprView keyexpr, ErrNo &error)

Undeclare a resource. Equal to Publisher::delete_resource

Parameters:
Returns:

true if the undeclare operation was successful, false otherwise

bool delete_resource(zenoh::KeyExprView keyexpr)

Undeclare a resource.

Parameters:

keyexpr – KeyExprView the key expression to delete the resource

Returns:

true if the undeclare operation was successful, false otherwise

bool put_owned(zenoh::KeyExprView keyexpr, zenoh::Payload &&payload, const zenoh::PutOptions &options, ErrNo &error)

Publish data to the matching subscribers in the system. Equal to Publisher::put_owned

Parameters:
Returns:

true if the publish operation was successful, false otherwise

Note

zenoh-c only

bool put_owned(zenoh::KeyExprView keyexpr, zenoh::Payload &&payload, const zenoh::PutOptions &options)

Publish data to the matching subscribers in the system. Equal to Publisher::put_owned

Parameters:
Returns:

true if the publish operation was successful, false otherwise

Note

zenoh-c only

bool put_owned(zenoh::KeyExprView keyexpr, zenoh::Payload &&payload, ErrNo &error)

Publish data to the matching subscribers in the system. Equal to Publisher::put_owned

Parameters:
Returns:

true if the publish operation was successful, false otherwise

Note

zenoh-c only

bool put_owned(zenoh::KeyExprView keyexpr, zenoh::Payload &&payload)

Publish data to the matching subscribers in the system. Equal to Publisher::put_owned

Parameters:

  • keyexpr – KeyExprView the key expression to put the data

  • payload – Payload the data to publish

Returns:

true if the publish operation was successful, false otherwise

Note

zenoh-c only

std::variant<zenoh::Queryable, ErrorMessage> declare_queryable(zenoh::KeyExprView keyexpr, zenoh::ClosureQuery &&callback, const zenoh::QueryableOptions &options)

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

Parameters:
Returns:

a Queryable object if the declaration was successful, an zenoh::ErrorMessage otherwise

std::variant<zenoh::Queryable, ErrorMessage> declare_queryable(zenoh::KeyExprView keyexpr, zenoh::ClosureQuery &&callback)

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

Parameters:
Returns:

a Queryable object if the declaration was successful, an zenoh::ErrorMessage otherwise

std::variant<zenoh::Subscriber, ErrorMessage> declare_subscriber(zenoh::KeyExprView keyexpr, zenoh::ClosureSample &&callback, const zenoh::SubscriberOptions &options)

Create a Subscriber object to receive data from matching Publisher objects or from Session::put, Session::delete_resource requests.

Parameters:
Returns:

a Subscriber object if the declaration was successful, an zenoh::ErrorMessage otherwise

std::variant<zenoh::Subscriber, ErrorMessage> declare_subscriber(zenoh::KeyExprView keyexpr, zenoh::ClosureSample &&callback)

Create a Subscriber object to receive data from matching Publisher objects or from Session::put, Session::delete_resource requests.

Parameters:
Returns:

a Subscriber object if the declaration was successful, an zenoh::ErrorMessage otherwise

std::variant<zenoh::PullSubscriber, ErrorMessage> declare_pull_subscriber(zenoh::KeyExprView keyexpr, zenoh::ClosureSample &&callback, const zenoh::PullSubscriberOptions &options)

Create a PullSubscriber object to receive data from matching Publisher objects or from Session::put, Session::delete_resource requests.

Parameters:
Returns:

a PullSubscriber object if the declaration was successful, an zenoh::ErrorMessage otherwise

std::variant<zenoh::PullSubscriber, ErrorMessage> declare_pull_subscriber(zenoh::KeyExprView keyexpr, zenoh::ClosureSample &&callback)

Create a PullSubscriber object to receive data from matching Publisher objects or from Session::put, Session::delete_resource requests.

Parameters:
Returns:

a PullSubscriber object if the declaration was successful, an zenoh::ErrorMessage otherwise

std::variant<zenoh::Publisher, ErrorMessage> declare_publisher(zenoh::KeyExprView keyexpr, const zenoh::PublisherOptions &options)

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

Parameters:
Returns:

a Publisher object if the declaration was successful, an zenoh::ErrorMessage otherwise

std::variant<zenoh::Publisher, ErrorMessage> declare_publisher(zenoh::KeyExprView keyexpr)

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

Parameters:

keyexpr – KeyExprView the key expression to match the subscribers

Returns:

a Publisher object if the declaration was successful, an zenoh::ErrorMessage otherwise

bool info_routers_zid(zenoh::ClosureZid &&callback, ErrNo &error)

Fetches the Zenoh IDs of all connected routers.

Parameters:

  • callback – zenoh::ClosureZid the callback to handle the received Id objects. Callback is guaranteed to never be called concurrently, and is guaranteed to be dropped before this function exits.

  • error – zenoh::ErrNo the error code

Returns:

true if the operation was successful, false otherwise

bool info_routers_zid(zenoh::ClosureZid &&callback)

Fetches the Zenoh IDs of all connected routers.

Parameters:

callback – zenoh::ClosureZid the callback to handle the received Id objects. Callback is guaranteed to never be called concurrently, and is guaranteed to be dropped before this function exits.

Returns:

true if the operation was successful, false otherwise

bool info_peers_zid(zenoh::ClosureZid &&callback, ErrNo &error)

Fetches the Zenoh IDs of all connected peers.

Parameters:

  • callback – zenoh::ClosureZid the callback to handle the received Id objects. Callback is guaranteed to never be called concurrently, and is guaranteed to be dropped before this function exits.

  • error – zenoh::ErrNo the error code

Returns:

true if the operation was successful, false otherwise

bool info_peers_zid(zenoh::ClosureZid &&callback)

Fetches the Zenoh IDs of all connected peers.

Parameters:

callback – zenoh::ClosureZid the callback to handle the received Id objects. Callback is guaranteed to never be called concurrently, and is guaranteed to be dropped before this function exits.

Returns:

true if the operation was successful, false otherwise

bool start_read_task()

Start a separate task to read from the network and process the messages as soon as they are received.

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool start_read_task(ErrNo &error)

Start a separate task to read from the network and process the messages as soon as they are received.

Parameters:

error – zenoh::ErrNo the error code

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool stop_read_task()

Stop the read task.

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool stop_read_task(ErrNo &error)

Stop the read task.

Parameters:

error – zenoh::ErrNo the error code

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool start_lease_task()

Start a separate task to handle the session lease. This task will send KeepAlive messages when needed and will close the session when the lease is expired. When operating over a multicast transport, it also periodically sends the Join messages.

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool start_lease_task(ErrNo &error)

Start a separate task to handle the session lease. This task will send KeepAlive messages when needed and will close the session when the lease is expired. When operating over a multicast transport, it also periodically sends the Join messages.

Parameters:

error – zenoh::ErrNo the error code

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool stop_lease_task()

Stop the lease task.

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool stop_lease_task(ErrNo &error)

Stop the lease task.

Parameters:

error – zenoh::ErrNo the error code

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool read()

Triggers a single execution of reading procedure from the network and processes of any received the message.

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool read(ErrNo &error)

Triggers a single execution of reading procedure from the network and processes of any received the message.

Parameters:

error – zenoh::ErrNo the error code

Returns:

true if the operation was successful, false otherwise

Note

zenoh-pico only

bool send_keep_alive()

Triggers a single execution of keep alive procedure. It will send KeepAlive messages when needed and will close the session when the lease is expired.

Returns:

true if the leasing procedure was executed successfully, false otherwise.

bool send_keep_alive(ErrNo &error)

Triggers a single execution of keep alive procedure. It will send KeepAlive messages when needed and will close the session when the lease is expired.

Parameters:

error – zenoh::ErrNo the error code

Returns:

true if the leasing procedure was executed successfully, false otherwise.

bool send_join()

Triggers a single execution of join procedure: send the Join message.

Returns:

true if the join procedure was executed successfully, false otherwise.

bool send_join(ErrNo &error)

Triggers a single execution of join procedure: send the Join message.

Parameters:

error – zenoh::ErrNo the error code

Returns:

true if the join procedure was executed successfully, false otherwise.

zenoh::KeyExpr keyexpr_concat(const zenoh::KeyExprView &k, const std::string_view &s)

Concatenate the key expression and a string, resolving them if necessary.

Parameters:

  • k – the key expression

  • s – std::string_view representing a key expression

Returns:

Newly allocated key expression zenoh::KeyExpr

Note

zenoh-c only

zenoh::KeyExpr keyexpr_join(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b)

Join two key expressions, inserting a separator between them.

Parameters:

  • a – Key expression

  • b – Key expressio

Returns:

Newly allocated key expression zenoh::KeyExpr

Note

zenoh-c only

bool keyexpr_equals(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b, ErrNo &error)

Checks if the two key expressions are equal, resolving them if necessary.

Parameters:

  • a – Key expression

  • b – Key expression

  • error – Error code returned by ::z_keyexpr_equals (value < -1 if any of the key expressions is not valid)

Returns:

true the key expressions are equal

bool keyexpr_equals(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b)

Checks if the two key expressions are equal, resolving them if necessary.

Parameters:

  • a – Key expression

  • b – Key expression

Returns:

true the key expressions are equal

bool keyexpr_includes(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b, ErrNo &error)

Checks if the key expression “a” includes expression “b”, resolving them if necessary.

Parameters:

  • a – Key expression

  • b – Key expression

  • error – Error code returned by ::z_keyexpr_includes (value < -1 if any of the key expressions is not valid)

Returns:

true the key expression includes the other key expression

bool keyexpr_includes(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b)

Checks if the key expression “a” includes key expression “b”, resolving them if necessary.

Parameters:

  • a – Key expression

  • b – Key expression

Returns:

true the key expression includes the other key expression

bool keyexpr_intersects(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b, ErrNo &error)

Checks if the key expression intersects with another key expression, resolving them if necessaRY. “Intersects” means that exists at least one key which is contained in both of the sets defined by the key expressions.

Parameters:

  • a – Key expression

  • b – Key expression

  • error – Error code returned by ::z_keyexpr_intersects (value < -1 if any of the key expressions is not valid)

Returns:

true the key expression intersects with the other key expression

bool keyexpr_intersects(const zenoh::KeyExprView &a, const zenoh::KeyExprView &b)

Checks if the key expression intersects with another key expression, resolving them if necessaRY. “Intersects” means that exists at least one key which is contained in both of the sets defined by the key expressions.

Parameters:

  • a – Key expression

  • b – Key expression

Returns:

true the key expression intersects with the other key expression