API Reference

Generic types

Bytes

struct z_bytes_t

A contiguous view of bytes owned by some other entity.

start being null is considered a gravestone value, and empty slices are represented using a possibly dangling pointer for start.

struct z_bytes_t z_bytes_new(const char *str)

Deprecated in favor of z_bytes_from_str: Returns a view of str using strlen (this should therefore not be used with untrusted inputs).

str == NULL will cause this to return z_bytes_null()

bool z_bytes_check(const struct z_bytes_t *b)

Returns true if b is initialized.

struct z_bytes_t z_bytes_null(void)

Returns the gravestone value for z_bytes_t

Bytes map

struct z_owned_bytes_map_t

A map of maybe-owned vector of bytes to owned vector of bytes.

In Zenoh C, this map is backed by Rust’s standard HashMap, with a DoS-resistant hasher

struct z_owned_bytes_map_t z_bytes_map_new(void)

Constructs a new map.

bool z_bytes_map_check(const struct z_owned_bytes_map_t *this_)

Returns true if the map is not in its gravestone state

struct z_owned_bytes_map_t z_bytes_map_null(void)

Constructs the gravestone value for z_owned_bytes_map_t

void z_bytes_map_drop(struct z_owned_bytes_map_t *this_)

Destroys the map, resetting this to its gravestone value.

This function is double-free safe, passing a pointer to the gravestone value will have no effect.

struct z_bytes_t z_bytes_map_get(const struct z_owned_bytes_map_t *this_, struct z_bytes_t key)

Returns the value associated with key, returning a gravestone value if: - this or key is in gravestone state. - this has no value associated to key

size_t z_bytes_map_len(struct z_owned_bytes_map_t *this_)

Returns number of key-value pairs in the map.

bool z_bytes_map_is_empty(struct z_owned_bytes_map_t *this_)

Returns true if the map is empty, false otherwise.

void z_bytes_map_insert_by_alias(const struct z_owned_bytes_map_t *this_, struct z_bytes_t key, struct z_bytes_t value)

Associates value to key in the map, aliasing them.

Note that once key is aliased, reinserting at the same key may alias the previous instance, or the new instance of key.

Calling this with NULL or the gravestone value is undefined behaviour.

void z_bytes_map_insert_by_copy(const struct z_owned_bytes_map_t *this_, struct z_bytes_t key, struct z_bytes_t value)

Associates value to key in the map, copying them to obtain ownership: key and value are not aliased past the function’s return.

Calling this with NULL or the gravestone value is undefined behaviour.

int8_t z_bytes_map_iter(const struct z_owned_bytes_map_t *this_, z_attachment_iter_body_t body, void *ctx)

Iterates over the key-value pairs in the map.

body will be called once per pair, with ctx as its last argument. If body returns a non-zero value, the iteration will stop immediately and the value will be returned. Otherwise, this will return 0 once all pairs have been visited. body is not given ownership of the key nor value, which alias the pairs in the map. It is safe to keep these aliases until existing keys are modified/removed, or the map is destroyed. Note that this map is unordered.

Calling this with NULL or the gravestone value is undefined behaviour.

struct z_owned_bytes_map_t z_bytes_map_from_attachment(struct z_attachment_t this_)

Constructs a map from the provided attachment, copying keys and values.

If this is at gravestone value, the returned value will also be at gravestone value.

struct z_owned_bytes_map_t z_bytes_map_from_attachment_aliasing(struct z_attachment_t this_)

Constructs a map from the provided attachment, aliasing the attachment’s keys and values.

If this is at gravestone value, the returned value will also be at gravestone value.

Session

Session configuration

struct z_config_t

A loaned zenoh configuration.

struct z_owned_config_t

An owned zenoh configuration.

Like most z_owned_X_t types, you may obtain an instance of z_X_t by loaning it using z_X_loan(&val). The z_loan(val) macro, available if your compiler supports C11’s _Generic, is equivalent to writing z_X_loan(&val).

Like all z_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

To check if val is still valid, you may use z_X_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

struct z_owned_scouting_config_t
struct z_owned_config_t z_config_new(void)

Return a new, zenoh-allocated, empty configuration.

Like most z_owned_X_t types, you may obtain an instance of z_X_t by loaning it using z_X_loan(&val). The z_loan(val) macro, available if your compiler supports C11’s _Generic, is equivalent to writing z_X_loan(&val).

Like all z_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

To check if val is still valid, you may use z_X_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

struct z_owned_config_t z_config_default(void)

Creates a default, zenoh-allocated, configuration.

struct z_owned_config_t z_config_client(const char *const *peers, size_t n_peers)

Constructs a default, zenoh-allocated, client mode configuration. If peer is not null, it is added to the configuration as remote peer.

struct z_owned_config_t z_config_peer(void)

Constructs a default, zenoh-allocated, peer mode configuration.

struct z_owned_config_t zc_config_from_file(const char *path)

Constructs a configuration by parsing a file at path. Currently supported format is JSON5, a superset of JSON.

struct z_owned_config_t zc_config_from_str(const char *s)

Reads a configuration from a JSON-serialized string, such as ‘{mode:”client”,connect:{endpoints:[“tcp/127.0.0.1:7447”]}}’.

Passing a null-ptr will result in a gravestone value (z_check(x) == false).

int8_t zc_config_insert_json(struct z_config_t config, const char *key, const char *value)

Inserts a JSON-serialized value at the key position of the configuration.

Returns 0 if successful, a negative value otherwise.

struct z_owned_str_t zc_config_get(struct z_config_t config, const char *key)

Gets the property with the given path key from the configuration, returning an owned, null-terminated, JSON serialized string. Use z_drop to safely deallocate this string

struct z_owned_str_t zc_config_to_string(struct z_config_t config)

Converts config into a JSON-serialized string, such as ‘{“mode”:”client”,”connect”:{“endpoints”:[“tcp/127.0.0.1:7447”]}}’.

struct z_config_t z_config_loan(const struct z_owned_config_t *s)

Returns a z_config_t loaned from s.

bool z_config_check(const struct z_owned_config_t *config)

Returns true if config is valid.

void z_config_drop(struct z_owned_config_t *config)

Frees config, invalidating it for double-drop safety.

Session management

Types

struct z_session_t

A loaned zenoh session.

struct z_owned_session_t

An owned zenoh session.

Like most z_owned_X_t types, you may obtain an instance of z_X_t by loaning it using z_X_loan(&val). The z_loan(val) macro, available if your compiler supports C11’s _Generic, is equivalent to writing z_X_loan(&val).

Like all z_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

To check if val is still valid, you may use z_X_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

struct z_owned_closure_zid_t

A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks:

void *context

a pointer to an arbitrary state.

void *call

the typical callback function. context will be passed as its last argument.

void *drop

allows the callback’s state to be freed.

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

  • call will never be called once drop has started.

  • drop will only be called once, and after every call has ended.

  • The two previous guarantees imply that call and drop are never called concurrently.

Functions

struct z_owned_session_t z_open(struct z_owned_config_t *config)

Opens a zenoh session. Should the session opening fail, z_check ing the returned value will return false.

int8_t z_close(struct z_owned_session_t *session)

Closes a zenoh session. This drops and invalidates session for double-drop safety.

Returns a negative value if an error occured while closing the session. Returns the remaining reference count of the session otherwise, saturating at i8::MAX.

struct z_session_t z_session_loan(const struct z_owned_session_t *s)

Returns a z_session_t loaned from s.

This handle doesn’t increase the refcount of the session, but does allow to do so with zc_session_rcinc.

# Safety The returned z_session_t aliases z_owned_session_t’s internal allocation, attempting to use it after all owned handles to the session (including publishers, queryables and subscribers) have been destroyed is UB (likely SEGFAULT)

bool z_session_check(const struct z_owned_session_t *session)

Returns true if session is valid.

struct z_id_t z_info_zid(struct z_session_t session)

Returns the local Zenoh ID.

Unless the session is invalid, that ID is guaranteed to be non-zero. In other words, this function returning an array of 16 zeros means you failed to pass it a valid session.

int8_t z_info_routers_zid(struct z_session_t session, struct z_owned_closure_zid_t *callback)

Fetches the Zenoh IDs of all connected routers.

callback will be called once for each ID, is guaranteed to never be called concurrently, and is guaranteed to be dropped before this function exits.

Retuns 0 on success, negative values on failure.

int8_t z_info_peers_zid(struct z_session_t session, struct z_owned_closure_zid_t *callback)

Fetches the Zenoh IDs of all connected peers.

callback will be called once for each ID, is guaranteed to never be called concurrently, and is guaranteed to be dropped before this function exits.

Retuns 0 on success, negative values on failure

void z_closure_zid_call(const struct z_owned_closure_zid_t *closure, const struct z_id_t *sample)

Calls the closure. Calling an uninitialized closure is a no-op.

void z_closure_zid_drop(struct z_owned_closure_zid_t *closure)

Drops the closure. Droping an uninitialized closure is a no-op.

Key expression

struct z_keyexpr_t
struct z_owned_keyexpr_t
struct z_keyexpr_t z_keyexpr(const char *name)

Constructs a z_keyexpr_t departing from a string. It is a loaned key expression that aliases name.

struct z_keyexpr_t z_keyexpr_autocanonize(char *name)

Constructs a z_keyexpr_t departing from a string. It is a loaned key expression that aliases name. The string is canonized in-place before being passed to keyexpr. May SEGFAULT if start is NULL or lies in read-only memory (as values initialized with string litterals do).

struct z_keyexpr_t z_keyexpr_unchecked(const char *name)

Constructs a z_keyexpr_t departing from a string without checking any of z_keyexpr_t’s assertions:

  • name MUST be valid UTF8.

  • name MUST follow the Key Expression specification, ie:

  • MUST NOT contain //, MUST NOT start nor end with /, MUST NOT contain any of the characters ?#$.

  • any instance of ** may only be lead or followed by /.

  • the key expression must have canon form.

It is a loaned key expression that aliases name.

struct z_owned_str_t z_keyexpr_to_string(struct z_keyexpr_t keyexpr)

Constructs a null-terminated string departing from a z_keyexpr_t. The user is responsible of droping the returned string using z_drop

struct z_bytes_t z_keyexpr_as_bytes(struct z_keyexpr_t keyexpr)

Returns the key expression’s internal string by aliasing it.

Currently exclusive to zenoh-c

int8_t z_keyexpr_canonize(char *start, size_t *len)

Canonizes the passed string in place, possibly shortening it by modifying len.

Returns 0 upon success, negative values upon failure. Returns a negative value if canonization failed, which indicates that the passed string was an invalid key expression for reasons other than a non-canon form.

May SEGFAULT if start is NULL or lies in read-only memory (as values initialized with string litterals do).

int8_t z_keyexpr_canonize_null_terminated(char *start)

Canonizes the passed string in place, possibly shortening it by placing a new null-terminator.

Returns 0 upon success, negative values upon failure. Returns a negative value if canonization failed, which indicates that the passed string was an invalid key expression for reasons other than a non-canon form.

May SEGFAULT if start is NULL or lies in read-only memory (as values initialized with string litterals do).

int8_t z_keyexpr_is_canon(const char *start, size_t len)

Returns 0 if the passed string is a valid (and canon) key expression. Otherwise returns error value

bool z_keyexpr_is_initialized(const struct z_keyexpr_t *keyexpr)

Returns true if keyexpr is initialized.

struct z_owned_keyexpr_t z_keyexpr_concat(struct z_keyexpr_t left, const char *right_start, size_t right_len)

Performs string concatenation and returns the result as a z_owned_keyexpr_t. In case of error, the return value will be set to its invalidated state.

You should probably prefer z_keyexpr_join as Zenoh may then take advantage of the hierachical separation it inserts.

To avoid odd behaviors, concatenating a key expression starting with * to one ending with * is forbidden by this operation, as this would extremely likely cause bugs.

struct z_owned_keyexpr_t z_keyexpr_join(struct z_keyexpr_t left, struct z_keyexpr_t right)

Performs path-joining (automatically inserting) and returns the result as a z_owned_keyexpr_t. In case of error, the return value will be set to its invalidated state.

int8_t z_keyexpr_equals(struct z_keyexpr_t left, struct z_keyexpr_t right)

Returns 0 if both left and right are equal. Otherwise, it returns a -1, or other negative value for errors.

int8_t z_keyexpr_includes(struct z_keyexpr_t left, struct z_keyexpr_t right)

Returns 0 if left includes right, i.e. the set defined by left contains every key belonging to the set defined by right. Otherwise, it returns a -1, or other negative value for errors.

int8_t z_keyexpr_intersects(struct z_keyexpr_t left, struct z_keyexpr_t right)

Returns 0 if the keyexprs intersect, i.e. there exists at least one key which is contained in both of the sets defined by left and right. Otherwise, it returns a -1, or other negative value for errors.

struct z_owned_keyexpr_t z_keyexpr_new(const char *name)

Constructs a z_keyexpr_t departing from a string, copying the passed string.

struct z_owned_keyexpr_t z_keyexpr_new_autocanonize(const char *name)

Constructs a z_keyexpr_t departing from a string, copying the passed string. The copied string is canonized.

struct z_keyexpr_t z_keyexpr_loan(const struct z_owned_keyexpr_t *keyexpr)

Returns a z_keyexpr_t loaned from z_owned_keyexpr_t.

bool z_keyexpr_check(const struct z_owned_keyexpr_t *keyexpr)

Returns true if keyexpr is valid.

void z_keyexpr_drop(struct z_owned_keyexpr_t *keyexpr)

Frees keyexpr and invalidates it for double-drop safety.

struct z_owned_keyexpr_t z_declare_keyexpr(struct z_session_t session, struct z_keyexpr_t keyexpr)

Declare a key expression. The id is returned as a z_keyexpr_t with a nullptr suffix.

This numerical id will be used on the network to save bandwidth and ease the retrieval of the concerned resource in the routing tables.

Encoding

struct z_encoding_t

The encoding of a payload, in a MIME-like format.

For wire and matching efficiency, common MIME types are represented using an integer as prefix, and a suffix may be used to either provide more detail, or in combination with the Empty prefix to write arbitrary MIME types.

z_encoding_prefix_t prefix

The integer prefix of this encoding.

z_bytes_t suffix

The suffix of this encoding. suffix MUST be a valid UTF-8 string.

struct z_owned_encoding_t

An owned payload encoding.

z_encoding_prefix_t prefix

The integer prefix of this encoding.

z_bytes_t suffix

The suffix of this encoding. suffix MUST be a valid UTF-8 string.

Like all z_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

To check if val is still valid, you may use z_X_check(&val) (or z_check(val) if your compiler supports _Generic), which will return true if val is valid.

struct z_encoding_t z_encoding_default(void)

Constructs a default z_encoding_t.

struct z_encoding_t z_encoding_loan(const struct z_owned_encoding_t *encoding)

Returns a z_encoding_t loaned from encoding.

bool z_encoding_check(const struct z_owned_encoding_t *encoding)

Returns true if encoding is valid.

void z_encoding_drop(struct z_owned_encoding_t *encoding)

Frees encoding, invalidating it for double-drop safety.

struct z_encoding_prefix_t

A z_encoding_t integer prefix.

  • Z_ENCODING_PREFIX_EMPTY

  • Z_ENCODING_PREFIX_APP_OCTET_STREAM

  • Z_ENCODING_PREFIX_APP_CUSTOM

  • Z_ENCODING_PREFIX_TEXT_PLAIN

  • Z_ENCODING_PREFIX_APP_PROPERTIES

  • Z_ENCODING_PREFIX_APP_JSON

  • Z_ENCODING_PREFIX_APP_SQL

  • Z_ENCODING_PREFIX_APP_INTEGER

  • Z_ENCODING_PREFIX_APP_FLOAT

  • Z_ENCODING_PREFIX_APP_XML

  • Z_ENCODING_PREFIX_APP_XHTML_XML

  • Z_ENCODING_PREFIX_APP_X_WWW_FORM_URLENCODED

  • Z_ENCODING_PREFIX_TEXT_JSON

  • Z_ENCODING_PREFIX_TEXT_HTML

  • Z_ENCODING_PREFIX_TEXT_XML

  • Z_ENCODING_PREFIX_TEXT_CSS

  • Z_ENCODING_PREFIX_TEXT_CSV

  • Z_ENCODING_PREFIX_TEXT_JAVASCRIPT

  • Z_ENCODING_PREFIX_IMAGE_JPEG

  • Z_ENCODING_PREFIX_IMAGE_PNG

  • Z_ENCODING_PREFIX_IMAGE_GIF

Value

struct z_value_t

A zenoh value.

z_bytes_t payload

The payload of this zenoh value.

z_encoding_t encoding

The encoding of this zenoh value payload.

Sample

struct z_sample_t

A data sample.

A sample is the value associated to a given resource at a given point in time.

z_keyexpr_t keyexpr

The resource key of this data sample.

z_bytes_t payload

The value of this data sample.

z_encoding_t encoding

The encoding of the value of this data sample.

z_sample_kind_t kind

The kind of this data sample (PUT or DELETE).

z_timestamp_t timestamp

The timestamp of this data sample.

z_attachment_t attachment

The attachment of this data sample.

Attachment

struct z_attachment_t

A iteration based map of byte slice to byte slice.

iteration_driver == NULL marks the gravestone value, as this type is often optional. Users are encouraged to use z_attachment_null and z_attachment_check to interact.

struct z_attachment_t z_attachment_null(void)

Returns the gravestone value for z_attachment_t.

struct z_bytes_t z_attachment_get(struct z_attachment_t this_, struct z_bytes_t key)

Returns the value associated with the key.

size_t z_attachment_len(struct z_attachment_t this_)

Returns number of key-value pairs for z_attachment_t.

Does so by iterating over all existing key-value pairs.

bool z_attachment_is_empty(struct z_attachment_t this_)

Returns true if z_attachment_t contains no key-value pairs, false otherwise.

bool z_attachment_check(const struct z_attachment_t *this_)

Returns the gravestone value for z_attachment_t.

int8_t z_attachment_iterate(struct z_attachment_t this_, z_attachment_iter_body_t body, void *context)

Iterate over this’s key-value pairs, breaking if body returns a non-zero value for a key-value pair, and returning the latest return value.

context is passed to body to allow stateful closures.

This function takes no ownership whatsoever.

Publication

Types

struct z_owned_publisher_t
struct z_congestion_control_t

The kind of congestion control.

  • BLOCK

  • DROP

struct z_priority_t

The priority of zenoh messages.

  • REAL_TIME

  • INTERACTIVE_HIGH

  • INTERACTIVE_LOW

  • DATA_HIGH

  • DATA

  • DATA_LOW

  • BACKGROUND

struct z_put_options_t

Options passed to the z_put() function.

z_encoding_t encoding

The encoding of the payload.

z_congestion_control_t congestion_control

The congestion control to apply when routing this message.

z_priority_t priority

The priority of this message.

z_attachment_t attachment

The attachment to this message.

struct z_put_options_t z_put_options_default(void)

Constructs the default value for z_put_options_t.

struct z_publisher_options_t

Options passed to the z_declare_publisher() function.

z_congestion_control_t congestion_control

The congestion control to apply when routing messages from this publisher.

z_priority_t priority

The priority of messages from this publisher.

struct z_publisher_options_t z_publisher_options_default(void)

Constructs the default value for z_publisher_options_t.

struct z_publisher_put_options_t

Options passed to the z_publisher_put() function.

z_encoding_t encoding

The encoding of the payload.

z_attachment_t attachment

The attachment to attach to the publication.

Functions

int8_t z_put(struct z_session_t session, struct z_keyexpr_t keyexpr, const uint8_t *payload, size_t len, const struct z_put_options_t *opts)

Put data.

The payload’s encoding can be sepcified through the options.

Parameters:

  • session – The zenoh session.

  • keyexpr – The key expression to put.

  • payload – The value to put.

  • len – The length of the value to put.

  • options – The put options.

Returns:

0 in case of success, negative values in case of failure.

struct z_owned_publisher_t z_declare_publisher(struct z_session_t session, struct z_keyexpr_t keyexpr, const struct z_publisher_options_t *options)

Declares a publisher for the given key expression.

Data can be put and deleted with this publisher with the help of the z_publisher_put() and z_publisher_delete() functions.

Parameters:

  • session – The zenoh session.

  • keyexpr – The key expression to publish.

  • options – additional options for the publisher.

Returns:

A z_owned_publisherr_t.

To check if the publisher decalration succeeded and if the publisher is still valid, you may use z_publisher_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

Like all z_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

Example

Declaring a publisher passing NULL for the options:

z_owned_publisher_t pub = z_declare_publisher(z_loan(s), z_keyexpr(expr), NULL);

is equivalent to initializing and passing the default publisher options:

z_publisher_options_t opts = z_publisher_options_default();
z_owned_publisher_t sub = z_declare_publisher(z_loan(s), z_keyexpr(expr), &opts);
int8_t z_publisher_put(struct z_publisher_t publisher, const uint8_t *payload, size_t len, const struct z_publisher_put_options_t *options)

Sends a PUT message onto the publisher’s key expression.

The payload’s encoding can be sepcified through the options.

Parameters:

  • session – The zenoh session.

  • payload – The value to put.

  • len – The length of the value to put.

  • options – The publisher put options.

Returns:

0 in case of success, negative values in case of failure.

int8_t z_publisher_delete(struct z_publisher_t publisher, const struct z_publisher_delete_options_t *_options)

Sends a DELETE message onto the publisher’s key expression.

Returns:

0 in case of success, 1 in case of failure.

int8_t z_undeclare_publisher(struct z_owned_publisher_t *publisher)

Undeclares the given z_owned_publisher_t, droping it and invalidating it for double-drop safety.

Subscription

Types

struct z_owned_subscriber_t
struct z_owned_pull_subscriber_t
struct z_owned_closure_sample_t

A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks.

void *context

a pointer to an arbitrary state.

void *call

the typical callback function. context will be passed as its last argument.

void *drop

allows the callback’s state to be freed.

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

  • call will never be called once drop has started.

  • drop will only be called once, and after every call has ended.

  • The two previous guarantees imply that call and drop are never called concurrently.

enum z_reliability_t

The subscription reliability.

  • Z_RELIABILITY_BEST_EFFORT

  • Z_RELIABILITY_RELIABLE

struct z_subscriber_options_t

Options passed to the z_declare_subscriber() or z_declare_pull_subscriber() function.

z_reliability_t reliability

The subscription reliability.

struct z_subscriber_options_t z_subscriber_options_default(void)

Constructs the default value for z_subscriber_options_t.

Functions

struct z_owned_subscriber_t z_declare_subscriber(struct z_session_t session, struct z_keyexpr_t keyexpr, struct z_owned_closure_sample_t *callback, const struct z_subscriber_options_t *opts)

Declare a subscriber for a given key expression.

Parameters:

  • session – The zenoh session.

  • keyexpr – The key expression to subscribe.

  • callback – The callback function that will be called each time a data matching the subscribed expression is received.

  • opts – The options to be passed to describe the options to be passed to the subscriber declaration.

Returns:

A z_owned_subscriber_t.

To check if the subscription succeeded and if the subscriber is still valid, you may use z_subscriber_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

Like all z_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

Example

Declaring a subscriber passing NULL for the options:

z_owned_subscriber_t sub = z_declare_subscriber(z_loan(s), z_keyexpr(expr), callback, NULL);

is equivalent to initializing and passing the default subscriber options:

z_subscriber_options_t opts = z_subscriber_options_default();
z_owned_subscriber_t sub = z_declare_subscriber(z_loan(s), z_keyexpr(expr), callback, &opts);
bool z_subscriber_check(const struct z_owned_subscriber_t *sub)

Returns true if sub is valid.

int8_t z_undeclare_subscriber(struct z_owned_subscriber_t *sub)

Undeclares the given z_owned_subscriber_t, droping it and invalidating it for double-drop safety.

struct z_owned_pull_subscriber_t z_declare_pull_subscriber(struct z_session_t session, struct z_keyexpr_t keyexpr, struct z_owned_closure_sample_t *callback, const struct z_pull_subscriber_options_t *opts)

Declares a pull subscriber for a given key expression.

Parameters:

  • session – The zenoh session.

  • keyexpr – The key expression to subscribe.

  • callback – The callback function that will be called each time a data matching the subscribed expression is received.

  • opts – additional options for the pull subscriber.

Returns:

A z_owned_subscriber_t.

To check if the subscription succeeded and if the pull subscriber is still valid, you may use z_pull_subscriber_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

Like all z_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

Example

Declaring a subscriber passing NULL for the options:

z_owned_subscriber_t sub = z_declare_pull_subscriber(z_loan(s), z_keyexpr(expr), callback, NULL);

is equivalent to initializing and passing the default subscriber options:

z_subscriber_options_t opts = z_subscriber_options_default();
z_owned_subscriber_t sub = z_declare_pull_subscriber(z_loan(s), z_keyexpr(expr), callback, &opts);
int8_t z_subscriber_pull(struct z_pull_subscriber_t sub)

Pull data for z_owned_pull_subscriber_t. The pulled data will be provided by calling the callback function provided to the z_declare_subscriber() function.

Parameters:
bool z_pull_subscriber_check(const struct z_owned_pull_subscriber_t *sub)

Returns true if sub is valid.

int8_t z_undeclare_pull_subscriber(struct z_owned_pull_subscriber_t *sub)

Undeclares the given z_owned_pull_subscriber_t, droping it and invalidating it for double-drop safety.

void z_closure_sample_call(const struct z_owned_closure_sample_t *closure, const struct z_sample_t *sample)

Calls the closure. Calling an uninitialized closure is a no-op.

void z_closure_sample_drop(struct z_owned_closure_sample_t *closure)

Drops the closure. Droping an uninitialized closure is a no-op.

Query

Types

struct z_owned_closure_reply_t

A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks:

void *context

a pointer to an arbitrary state.

void *call

the typical callback function. context will be passed as its last argument.

void *drop

allows the callback’s state to be freed.

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

  • call will never be called once drop has started.

  • drop will only be called once, and after every call has ended.

  • The two previous guarantees imply that call and drop are never called concurrently.

struct z_get_options_t

Options passed to the z_get() function.

z_query_target_t target

The Queryables that should be target of the query.

z_query_consolidation_t consolidation

The replies consolidation strategy to apply on replies to the query.

z_value_t value

An optional value to attach to the query.

z_attachment_t attachment

The attachment to attach to the query.

uint64_t timeout

The timeout for the query in milliseconds. 0 means default query timeout from zenoh configuration.

enum z_query_target_t

The Queryables that should be target of a z_get().

  • BEST_MATCHING: The nearest complete queryable if any else all matching queryables.

  • ALL_COMPLETE: All complete queryables.

  • ALL: All matching queryables.

enum z_consolidation_mode_t

Consolidation mode values.

  • Z_CONSOLIDATION_MODE_AUTO: Let Zenoh decide the best consolidation mode depending on the query selector If the selector contains time range properties, consolidation mode NONE is used. Otherwise the LATEST consolidation mode is used.

  • Z_CONSOLIDATION_MODE_NONE: No consolidation is applied. Replies may come in any order and any number.

  • Z_CONSOLIDATION_MODE_MONOTONIC: It guarantees that any reply for a given key expression will be monotonic in time w.r.t. the previous received replies for the same key expression. I.e., for the same key expression multiple replies may be received. It is guaranteed that two replies received at t1 and t2 will have timestamp ts2 > ts1. It optimizes latency.

  • Z_CONSOLIDATION_MODE_LATEST: It guarantees unicity of replies for the same key expression. It optimizes bandwidth.

type z_query_consolidation_t

The replies consolidation strategy to apply on replies to a z_get().

  • AUTO: Automatic query consolidation strategy selection.

  • MANUAL: Manual query consolidation strategy selection.

struct z_query_consolidation_t z_query_consolidation_default(void)

Creates a default z_query_consolidation_t (consolidation mode AUTO).

struct z_query_consolidation_t z_query_consolidation_auto(void)

Automatic query consolidation strategy selection.

A query consolidation strategy will automatically be selected depending the query selector. If the selector contains time range properties, no consolidation is performed. Otherwise the z_query_consolidation_latest() strategy is used.

Returns:

Returns the constructed z_query_consolidation_t.

struct z_query_consolidation_t z_query_consolidation_none(void)

Disable consolidation.

struct z_query_consolidation_t z_query_consolidation_monotonic(void)

Monotonic consolidation.

struct z_query_consolidation_t z_query_consolidation_latest(void)

Latest value consolidation.

struct z_owned_reply_t
bool z_reply_check(const struct z_owned_reply_t *reply_data)

Returns true if reply_data is valid.

void z_reply_drop(struct z_owned_reply_t *reply_data)

Frees reply_data, invalidating it for double-drop safety.

Functions

int8_t z_get(struct z_session_t session, struct z_keyexpr_t keyexpr, const char *parameters, struct z_owned_closure_reply_t *callback, const struct z_get_options_t *options)

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

Returns a negative value upon failure.

Parameters:

  • session – The zenoh session.

  • keyexpr – The key expression matching resources to query.

  • parameters – The query’s parameters, similar to a url’s query segment.

  • callback – The callback function that will be called on reception of replies for this query. Note that the reply parameter of the callback is passed by mutable reference, but will be dropped once your callback exits to help you avoid memory leaks. If you’d rather take ownership, please refer to the documentation of z_reply_null()

  • options – additional options for the get.

bool z_reply_is_ok(const struct z_owned_reply_t *reply)

Returns true if the queryable answered with an OK, which allows this value to be treated as a sample.

If this returns false, you should use z_check() before trying to use z_reply_err() if you want to process the error that may be here.

struct z_sample_t z_reply_ok(const struct z_owned_reply_t *reply)

Yields the contents of the reply by asserting it indicates a success.

You should always make sure that z_reply_is_ok() returns true before calling this function.

struct z_value_t z_reply_err(const struct z_owned_reply_t *reply)

Yields the contents of the reply by asserting it indicates a failure.

You should always make sure that z_reply_is_ok() returns false before calling this function.

struct z_owned_reply_t z_reply_null(void)

Returns an invalidated z_owned_reply_t.

This is useful when you wish to take ownership of a value from a callback to z_get():

  • copy the value of the callback’s argument’s pointee,

  • overwrite the pointee with this function’s return value,

  • you are now responsible for dropping your copy of the reply.

void z_closure_reply_call(const struct z_owned_closure_reply_t *closure, struct z_owned_reply_t *sample)

Calls the closure. Calling an uninitialized closure is a no-op.

void z_closure_reply_drop(struct z_owned_closure_reply_t *closure)

Drops the closure. Droping an uninitialized closure is a no-op.

Queryable

Types

struct z_owned_queryable_t
struct z_owned_closure_query_t

A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks:

void *context

a pointer to an arbitrary state.

void *call

the typical callback function. context will be passed as its last argument.

void *drop

allows the callback’s state to be freed.

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

  • call will never be called once drop has started.

  • drop will only be called once, and after every call has ended.

  • The two previous guarantees imply that call and drop are never called concurrently.

struct z_keyexpr_t z_query_keyexpr(const struct z_query_t *query)

Get a query’s key by aliasing it.

struct z_bytes_t z_query_parameters(const struct z_query_t *query)

Get a query’s value selector by aliasing it.

struct z_value_t z_query_value(const struct z_query_t *query)

Get a query’s payload value by aliasing it.

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

struct z_attachment_t z_query_attachment(const struct z_query_t *query)

Returns the attachment to the query by aliasing.

z_check(return_value) == false if there was no attachment to the query.

Functions

struct z_owned_queryable_t z_declare_queryable(struct z_session_t session, struct z_keyexpr_t keyexpr, struct z_owned_closure_query_t *callback, const struct z_queryable_options_t *options)

Creates a Queryable for the given key expression.

Parameters:

  • session – The zenoh session.

  • keyexpr – The key expression the Queryable will reply to.

  • callback – The callback function that will be called each time a matching query is received.

  • options – Options for the queryable.

Returns:

The created z_owned_queryable_t or null if the creation failed.

int8_t z_query_reply(const struct z_query_t *query, struct z_keyexpr_t key, const uint8_t *payload, size_t len, const struct z_query_reply_options_t *options)

Send a reply to a query.

This function must be called inside of a Queryable callback passing the query received as parameters of the callback function. This function can be called multiple times to send multiple replies to a query. The reply will be considered complete when the Queryable callback returns.

Parameters:

  • query – The query to reply to.

  • key – The key of this reply.

  • payload – The value of this reply.

  • len – The length of the value of this reply.

  • options – The options of this reply.

bool z_queryable_check(const struct z_owned_queryable_t *qable)

Returns true if qable is valid.

int8_t z_undeclare_queryable(struct z_owned_queryable_t *qable)

Undeclares a z_owned_queryable_t, droping it and invalidating it for doube-drop safety.

Parameters:
void z_closure_query_call(const struct z_owned_closure_query_t *closure, const struct z_query_t *query)

Calls the closure. Calling an uninitialized closure is a no-op.

void z_closure_query_drop(struct z_owned_closure_query_t *closure)

Drops the closure. Droping an uninitialized closure is a no-op.

Liveliness

Types

struct zc_owned_liveliness_token_t

A liveliness token that can be used to provide the network with information about connectivity to its declarer: when constructed, a PUT sample will be received by liveliness subscribers on intersecting key expressions.

A DELETE on the token’s key expression will be received by subscribers if the token is destroyed, or if connectivity between the subscriber and the token’s creator is lost.

struct zc_owned_liveliness_declaration_options_t

The options for zc_liveliness_declare_token

struct zc_liveliness_get_options_t

The options for zc_liveliness_declare_subscriber()

struct zc_owned_liveliness_declare_subscriber_options_t

The options for zc_liveliness_declare_subscriber()

Functions

struct zc_owned_liveliness_token_t zc_liveliness_declare_token(struct z_session_t session, struct z_keyexpr_t key, const struct zc_owned_liveliness_declaration_options_t *_options)

Constructs and 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.

Passing NULL as options is valid and equivalent to a pointer to the default options.

void zc_liveliness_undeclare_token(struct zc_owned_liveliness_token_t *token)

Destroys a liveliness token, notifying subscribers of its destruction.

struct zc_owned_liveliness_token_t zc_liveliness_token_null(void)

The gravestone value for liveliness tokens.

bool zc_liveliness_token_check(const struct zc_owned_liveliness_token_t *token)

Returns true unless the token is at its gravestone value.

struct z_owned_subscriber_t zc_liveliness_declare_subscriber(struct z_session_t session, struct z_keyexpr_t key, struct z_owned_closure_sample_t *callback, const struct zc_owned_liveliness_declare_subscriber_options_t *_options)

Declares a subscriber on liveliness tokens that intersect key.

Parameters:
Returns:

A z_owned_subscriber_t.

To check if the subscription succeeded and if the subscriber is still valid, you may use z_subscriber_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

int8_t zc_liveliness_get(struct z_session_t session, struct z_keyexpr_t key, struct z_owned_closure_reply_t *callback, const struct zc_liveliness_get_options_t *options)

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

Note that the same “value stealing” tricks apply as with a normal z_get()

Passing NULL as options is valid and equivalent to passing a pointer to the default options.

struct zc_liveliness_get_options_t zc_liveliness_get_options_default(void)

The gravestone value for zc_liveliness_get_options_t

Publication Cache

Types

struct ze_publication_cache_options_t

Options passed to the ze_declare_publication_cache() function.

z_keyexpr_t queryable_prefix

The prefix used for queryable

zcu_locality_t queryable_origin

The restriction for the matching queries that will be receive by this publication cache

bool queryable_complete

the complete option for the queryable

size_t history

The the history size

size_t resources_limit

The limit number of cached resources

struct ze_owned_publication_cache_t

An owned zenoh publication_cache.

Like most z_owned_X_t types, you may obtain an instance of z_X_t by loaning it using z_X_loan(&val). The z_loan(val) macro, available if your compiler supports C11’s _Generic, is equivalent to writing z_X_loan(&val).

Like all z_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

To check if val is still valid, you may use z_X_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

Functions

struct ze_owned_publication_cache_t ze_declare_publication_cache(struct z_session_t session, struct z_keyexpr_t keyexpr, const struct ze_publication_cache_options_t *options)

Declares a Publication Cache.

Parameters:
Returns:

ze_owned_publication_cache_t.

Example

Declaring a publication cache NULL for the options:

ze_owned_publication_cache_t pub_cache = ze_declare_publication_cache(z_loan(s), z_keyexpr(expr), NULL);

is equivalent to initializing and passing the default publication cache options:

ze_publication_cache_options_t opts = ze_publication_cache_options_default();
ze_owned_publication_cache_t pub_cache = ze_declare_publication_cache(z_loan(s), z_keyexpr(expr), &opts);
int8_t ze_undeclare_publication_cache(struct ze_owned_publication_cache_t *pub_cache)

Closes the given ze_owned_publication_cache_t, droping it and invalidating it for double-drop safety.

bool ze_publication_cache_check(const struct ze_owned_publication_cache_t *pub_cache)

Returns true if pub_cache is valid.

struct ze_owned_publication_cache_t ze_publication_cache_null(void)

Constructs a null safe-to-drop value of ‘ze_owned_publication_cache_t’ type

struct ze_publication_cache_options_t ze_publication_cache_options_default(void)

Constructs the default value for ze_publication_cache_options_t.

Querying Subscriber

Types

struct ze_owned_querying_subscriber_t

An owned zenoh querying subscriber. Destroying the subscriber cancels the subscription.

Like most ze_owned_X_t types, you may obtain an instance of z_X_t by loaning it using z_X_loan(&val). The z_loan(val) macro, available if your compiler supports C11’s _Generic, is equivalent to writing z_X_loan(&val).

Like all ze_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

To check if val is still valid, you may use z_X_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

struct ze_querying_subscriber_options_t

Represents the set of options that can be applied to a querying subscriber, upon its declaration via ze_declare_querying_subscriber().

z_reliability_t reliability

The subscription reliability.

zcu_locality_t allowed_origin

The restriction for the matching publications that will be receive by this subscriber.

z_keyexpr_t query_selector

The selector to be used for queries.

z_query_target_t query_target

The target to be used for queries.

z_query_consolidation_t query_consolidation

The consolidation mode to be used for queries.

zcu_reply_keyexpr_t query_accept_replies

The accepted replies for queries.

uint64_t query_timeout_ms

The timeout to be used for queries.

Functions

struct ze_owned_querying_subscriber_t ze_declare_querying_subscriber(struct z_session_t session, struct z_keyexpr_t keyexpr, struct z_owned_closure_sample_t *callback, const struct ze_querying_subscriber_options_t *options)

Declares a Querying Subscriber for a given key expression.

Parameters:
Returns:

ze_owned_subscriber_t.

To check if the subscription succeeded and if the querying subscriber is still valid, you may use ze_querying_subscriber_check(&val) or z_check(val) if your compiler supports _Generic, which will return true if val is valid.

Like all ze_owned_X_t, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider using z_move(val) instead of &val as the argument. After a move, val will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that your val is valid.

Example

Declaring a subscriber passing NULL for the options:

ze_owned_subscriber_t sub = ze_declare_querying_subscriber(z_loan(s), z_keyexpr(expr), callback, NULL);

is equivalent to initializing and passing the default subscriber options:

z_subscriber_options_t opts = z_subscriber_options_default();
ze_owned_subscriber_t sub = ze_declare_querying_subscriber(z_loan(s), z_keyexpr(expr), callback, &opts);
int8_t ze_undeclare_querying_subscriber(struct ze_owned_querying_subscriber_t *sub)

Undeclares the given ze_owned_querying_subscriber_t, droping it and invalidating it for double-drop safety.

int8_t ze_querying_subscriber_get(struct ze_querying_subscriber_t sub, struct z_keyexpr_t selector, const struct z_get_options_t *options)

Make a ze_owned_querying_subscriber_t to 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.

bool ze_querying_subscriber_check(const struct ze_owned_querying_subscriber_t *sub)

Returns true if sub is valid.

struct ze_owned_querying_subscriber_t ze_querying_subscriber_null(void)

Constructs a null safe-to-drop value of ‘ze_owned_querying_subscriber_t’ type

struct ze_querying_subscriber_options_t ze_querying_subscriber_options_default(void)

Constructs the default value for ze_querying_subscriber_options_t.