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 givenConfig
- Parameters:
config –
Config
to usestart_background_tasks – for zenoh-pico only. If true, start background threads which handles the network traffic. If false, the threads should be called manually with
Session::start_read_task
andSession::start_lease_task
or methodsSession::read
,Session::send_keep_alive
andSession::send_join
should be called in loop.
- Returns:
a
Session
if the session was successfully created, anzenoh::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:
config –
ScoutingConfig
to usecallback –
zenoh::ClosureHello
to process receivedHello
serror –
zenoh:ErrNo
to store the error code
- 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:
config –
ScoutingConfig
to usecallback –
zenoh::ClosureHello
to process receivedHello
s
- 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 whereSession
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 inSession
routing tables.- Parameters:
keyexpr –
KeyExprView
representing string key expression- Returns:
KeyExpr
instance
-
bool undeclare_keyexpr(zenoh::KeyExpr &&keyexpr, ErrNo &error)
Remove
KeyExpr
instance fromSession
and dropKeyExpr
instance.- Parameters:
keyexpr –
KeyExpr
instance to droperror –
zenoh::ErrNo
to store the error code
- Returns:
true if the
KeyExpr
instance was successfully removed, false otherwise
-
bool undeclare_keyexpr(zenoh::KeyExpr &&keyexpr)
Remove
KeyExpr
instance fromSession
and dropKeyExpr
instance.
-
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:
keyexpr –
KeyExprView
the key expression matching resources to queryparameters – the null-terminated string of query parameters
callback –
zenoh::ClosureReply
callback for processReply
soptions –
GetOptions
query optionserror –
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, 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 queryparameters – the null-terminated string of query parameters
callback –
zenoh::ClosureReply
callback for processReply
soptions –
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 queryparameters – the null-terminated string of query parameters
callback –
zenoh::ClosureReply
callback for processReply
serror –
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 queryparameters – the null-terminated string of query parameters
callback –
zenoh::ClosureReply
callback for processReply
s
- 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:
keyexpr –
KeyExprView
the key expression to put the datapayload –
BytesView
the data to publishoptions –
PutOptions
put optionserror –
zenoh::ErrNo
to store the error code
- 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:
keyexpr –
KeyExprView
the key expression to put the datapayload –
BytesView
the data to publishoptions –
PutOptions
put options
- 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:
keyexpr –
KeyExprView
the key expression to put the datapayload –
BytesView
the data to publisherror –
zenoh::ErrNo
to store the error code
- 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 datapayload –
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:
keyexpr –
KeyExprView
the key expression to delete the resourceoptions –
DeleteOptions
delete optionserror –
zenoh::ErrNo
to store the error code
- 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:
keyexpr –
KeyExprView
the key expression to delete the resourceoptions –
DeleteOptions
delete options
- 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:
keyexpr –
KeyExprView
the key expression to delete the resourceerror –
zenoh::ErrNo
to store the error code
- 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:
keyexpr –
KeyExprView
the key expression to put the datapayload –
Payload
the data to publishoptions –
PutOptions
put optionserror –
zenoh::ErrNo
to store the error code
- 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:
keyexpr –
KeyExprView
the key expression to put the datapayload –
Payload
the data to publishoptions –
PutOptions
put options
- 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:
keyexpr –
KeyExprView
the key expression to put the datapayload –
Payload
the data to publisherror –
zenoh::ErrNo
to store the error code
- 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 datapayload –
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 toSession::get
requests.- Parameters:
keyexpr –
KeyExprView
the key expression to match theSession::get
requestscallback –
zenoh::ClosureQuery
the callback to handleQuery
requestsoptions –
QueryableOptions
queryable options
- Returns:
a
Queryable
object if the declaration was successful, anzenoh::ErrorMessage
otherwise
-
std::variant<zenoh::Queryable, ErrorMessage> declare_queryable(zenoh::KeyExprView keyexpr, zenoh::ClosureQuery &&callback)
Create a
Queryable
object to answer toSession::get
requests.- Parameters:
keyexpr –
KeyExprView
the key expression to match theSession::get
requestscallback –
zenoh::ClosureQuery
the callback to handleQuery
requests
- Returns:
a
Queryable
object if the declaration was successful, anzenoh::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 matchingPublisher
objects or fromSession::put
,Session::delete_resource
requests.- Parameters:
keyexpr –
KeyExprView
the key expression to match the publisherscallback –
zenoh::ClosureSample
the callback to handle the receivedSample
objectsoptions –
SubscriberOptions
subscriber options
- Returns:
a
Subscriber
object if the declaration was successful, anzenoh::ErrorMessage
otherwise
-
std::variant<zenoh::Subscriber, ErrorMessage> declare_subscriber(zenoh::KeyExprView keyexpr, zenoh::ClosureSample &&callback)
Create a
Subscriber
object to receive data from matchingPublisher
objects or fromSession::put
,Session::delete_resource
requests.- Parameters:
keyexpr –
KeyExprView
the key expression to match the publisherscallback –
zenoh::ClosureSample
the callback to handle the receivedSample
objects
- Returns:
a
Subscriber
object if the declaration was successful, anzenoh::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 matchingPublisher
objects or fromSession::put
,Session::delete_resource
requests.- Parameters:
keyexpr –
KeyExprView
the key expression to match the publisherscallback –
zenoh::ClosureSample
the callback to handle the receivedSample
objectsoptions –
PullSubscriberOptions
pull subscriber options
- Returns:
a
PullSubscriber
object if the declaration was successful, anzenoh::ErrorMessage
otherwise
-
std::variant<zenoh::PullSubscriber, ErrorMessage> declare_pull_subscriber(zenoh::KeyExprView keyexpr, zenoh::ClosureSample &&callback)
Create a
PullSubscriber
object to receive data from matchingPublisher
objects or fromSession::put
,Session::delete_resource
requests.- Parameters:
keyexpr –
KeyExprView
the key expression to match the publisherscallback –
zenoh::ClosureSample
the callback to handle the receivedSample
objects
- Returns:
a
PullSubscriber
object if the declaration was successful, anzenoh::ErrorMessage
otherwise
-
std::variant<zenoh::Publisher, ErrorMessage> declare_publisher(zenoh::KeyExprView keyexpr, const zenoh::PublisherOptions &options)
Create a
Publisher
object to publish data to matchingSubscriber
andPullSubscriber
objects.- Parameters:
keyexpr –
KeyExprView
the key expression to match the subscribersoptions –
PublisherOptions
publisher options
- Returns:
a
Publisher
object if the declaration was successful, anzenoh::ErrorMessage
otherwise
-
std::variant<zenoh::Publisher, ErrorMessage> declare_publisher(zenoh::KeyExprView keyexpr)
Create a
Publisher
object to publish data to matchingSubscriber
andPullSubscriber
objects.- Parameters:
keyexpr –
KeyExprView
the key expression to match the subscribers- Returns:
a
Publisher
object if the declaration was successful, anzenoh::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 receivedId
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 receivedId
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 receivedId
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 receivedId
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
-
inline Session rcinc()