API Reference

Zenoh Types

Enums

enum z_whatami_t

Whatami values, defined as a bitmask.

enumerator Z_WHATAMI_ROUTER

Bitmask to filter Zenoh routers.

enumerator Z_WHATAMI_PEER

Bitmask to filter for Zenoh peers.

enumerator Z_WHATAMI_CLIENT

Bitmask to filter for Zenoh clients.

enum zp_keyexpr_canon_status_t

Status values for keyexpr canonization operation. Used as return value of canonization-related functions, like z_keyexpr_is_canon() or z_keyexpr_canonize().

enumerator Z_KEYEXPR_CANON_SUCCESS

The key expression is canon.

enumerator Z_KEYEXPR_CANON_LONE_DOLLAR_STAR

The key contains a $* chunk, which must be replaced by *.

enumerator Z_KEYEXPR_CANON_SINGLE_STAR_AFTER_DOUBLE_STAR

The key contains ** / *, which must be replaced by * / **.

enumerator Z_KEYEXPR_CANON_DOUBLE_STAR_AFTER_DOUBLE_STAR

The key contains ** / **, which must be replaced by **.

enumerator Z_KEYEXPR_CANON_EMPTY_CHUNK

The key contains empty chunks.

enumerator Z_KEYEXPR_CANON_STARS_IN_CHUNK

The key contains a * in a chunk without being escaped by a DSL, which is forbidden.

enumerator Z_KEYEXPR_CANON_DOLLAR_AFTER_DOLLAR_OR_STAR

The key contains $*$ or $$, which is forbidden.

enumerator Z_KEYEXPR_CANON_CONTAINS_SHARP_OR_QMARK

The key contains # or ?, which is forbidden.

enumerator Z_KEYEXPR_CANON_CONTAINS_UNBOUND_DOLLAR

The key contains a $ which is not bound to a DSL.

enum z_sample_kind_t

Sample kind values.

enumerator Z_SAMPLE_KIND_PUT

The Sample was issued by a put operation.

enumerator Z_SAMPLE_KIND_DELETE

The Sample was issued by a delete operation.

enum z_consolidation_mode_t

Consolidation mode values.

enumerator Z_CONSOLIDATION_MODE_AUTO

Let Zenoh decide the best consolidation mode depending on the query selector.

enumerator Z_CONSOLIDATION_MODE_NONE

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

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

enumerator Z_CONSOLIDATION_MODE_LATEST

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

enum z_reliability_t

Reliability values.

enumerator Z_RELIABILITY_BEST_EFFORT

Defines reliability as BEST_EFFORT

enumerator Z_RELIABILITY_RELIABLE

Defines reliability as RELIABLE

enum z_congestion_control_t

Congestion control values.

enumerator Z_CONGESTION_CONTROL_BLOCK

Defines congestion control as BLOCK. Messages are not dropped in case of congestion control.

enumerator Z_CONGESTION_CONTROL_DROP

Defines congestion control as DROP. Messages are dropped in case of congestion control.

enum z_priority_t

Priority of Zenoh messages values.

enumerator _Z_PRIORITY_CONTROL

Priority for Control messages.

enumerator Z_PRIORITY_REAL_TIME

Priority for RealTime messages.

enumerator Z_PRIORITY_INTERACTIVE_HIGH

Highest priority for Interactive messages.

enumerator Z_PRIORITY_INTERACTIVE_LOW

Lowest priority for Interactive messages.

enumerator Z_PRIORITY_DATA_HIGH

Highest priority for Data messages.

enumerator Z_PRIORITY_DATA

Default priority for Data messages.

enumerator Z_PRIORITY_DATA_LOW

Lowest priority for Data messages.

enumerator Z_PRIORITY_BACKGROUND

Priority for Background traffic messages.

enum z_query_target_t

Query target values.

enumerator Z_QUERY_TARGET_BEST_MATCHING

The nearest complete queryable if any else all matching queryables.

enumerator Z_QUERY_TARGET_ALL

All matching queryables.

enumerator Z_QUERY_TARGET_ALL_COMPLETE

A set of complete queryables.

Data Structures

typedef int z_zint_t

Represents a variable-length encoding unsigned integer.

It is equivalent to the size of a size_t.

typedef int z_id_t

Represents a Zenoh ID.

In general, valid Zenoh IDs are LSB-first 128bit unsigned and non-zero integers.

uint8_t id[16]

The array containing the 16 octets of a Zenoh ID.

typedef int z_timestamp_t
type z_subscriber_options_t

Represents the configuration used to configure a subscriber upon declaration z_declare_subscriber(). .

type z_query_consolidation_t

Represents the reply consolidation mode to apply on replies to a z_get().

z_consolidation_mode_t mode

the consolidation mode, see z_consolidation_mode_t

type z_publisher_options_t

Represents the configuration used to configure a publisher upon declaration with z_declare_publisher().

z_owned_encoding_t *encoding

Default encoding for messages put by this publisher.

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 issued by this publisher. _Bool is_express: If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth. (unstable) z_reliability_t reliability: The reliability that should be used to transmit the data.

type z_queryable_options_t

Represents the configuration used to configure a queryable upon declaration z_declare_queryable().

_Bool complete

The completeness of the queryable.

type z_query_reply_options_t

Represents the configuration used to configure a query reply sent via :c:func:`z_query_reply.

z_moved_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 when routed.

z_timestamp_t *timestamp

The API level timestamp (e.g. of the data when it was created).

_Bool is_express

If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth.

z_moved_bytes_t *attachment

An optional attachment to the response.

type z_put_options_t

Represents the configuration used to configure a put operation sent via via z_put().

z_moved_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 when routed.

z_timestamp_t *timestamp

The API level timestamp (e.g. of the data when it was created).

_Bool is_express

If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth.

z_moved_bytes_t *attachment

An optional attachment to the publication.

(unstable) z_reliability_t reliability

The reliability that should be used to transmit the data.

type z_delete_options_t

Represents the configuration used to configure a delete operation sent via z_delete().

z_congestion_control_t congestion_control

The congestion control to apply when routing this message.

z_priority_t priority

The priority of this message when router.

_Bool is_express

If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth.

z_timestamp_t *timestamp

The API level timestamp (e.g. of the data when it was created).

(unstable) z_reliability_t reliability

The reliability that should be used to transmit the data.

type z_publisher_put_options_t

Represents the configuration used to configure a put operation by a previously declared publisher, sent via z_publisher_put().

z_moved_encoding_t *encoding

The encoding of the payload.

z_timestamp_t *timestamp

The API level timestamp (e.g. of the data when it was created).

z_moved_bytes_t *attachment

An optional attachment to the publication.

type z_publisher_delete_options_t

Represents the configuration used to configure a delete operation by a previously declared publisher, sent via z_publisher_delete().

z_timestamp_t *timestamp

The API level timestamp (e.g. of the data when it was created).

type z_get_options_t

Represents the configuration used to configure a get operation sent via z_get().

z_moved_bytes_t *payload

The payload to include in the query.

z_moved_encoding_t *encoding

Payload encoding.

z_query_consolidation_t consolidation

The replies consolidation strategy to apply on replies.

z_congestion_control_t congestion_control

The congestion control to apply when routing the query.

z_priority_t priority

The priority of the query.

_Bool is_express: If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth.

z_query_target_t target: The queryables that should be targeted by this get. z_moved_bytes_t* attachment: An optional attachment to the query.

type zp_task_read_options_t

Represents the configuration used to configure a read task started via zp_start_read_task().

type zp_task_lease_options_t

Represents the configuration used to configure a lease task started via zp_start_lease_task().

type zp_read_options_t

Represents the configuration used to configure a read operation started via zp_read().

type zp_send_keep_alive_options_t

Represents the configuration used to configure a send keep alive operation started via zp_send_keep_alive().

type zp_send_join_options_t

Represents the configuration used to configure a send join operation started via zp_send_join().

typedef int z_bytes_reader_t

A reader for serialized data.

typedef int z_bytes_iterator_t

An iterator over multi-element serialized data.

type z_bytes_slice_iterator_t

An iterator over slices of serialized data.

typedef int z_bytes_writer_t

Represents a writer for serialized data.

Owned Types

TODO: owned type description

type z_owned_slice_t

Represents an array of bytes.

type z_owned_bytes_t

Represents an array of bytes container.

type z_owned_string_t

Represents a string without null-terminator.

type z_owned_keyexpr_t

Represents a key expression in Zenoh.

type z_owned_config_t

Represents a Zenoh configuration, used to configure Zenoh sessions upon opening.

type z_owned_session_t

Represents a Zenoh Session.

type z_owned_subscriber_t

Represents a Zenoh Subscriber entity.

type z_owned_publisher_t

Represents a Zenoh Publisher entity.

type z_owned_queryable_t

Represents a Zenoh Queryable entity.

type z_owned_query_t

Represents a Zenoh Query entity, received by Zenoh queryable entities.

type z_owned_encoding_t

Represents the encoding of a payload, in a MIME-like format.

type z_owned_reply_err_t

Represents a Zenoh reply error value.

type z_owned_sample_t

Represents a data sample.

type z_owned_hello_t

Represents the content of a hello message returned by a zenoh entity as a reply to a scout message.

type z_owned_reply_t

Represents the reply to a query.

type z_owned_string_array_t

Represents an array of non null-terminated string.

Loaned Types

TODO: loaned type description

type z_loaned_slice_t

Represents an array of bytes.

type z_loaned_bytes_t

Represents an array of bytes container.

type z_loaned_string_t

Represents a string without null-terminator.

type z_loaned_keyexpr_t

Represents a key expression in Zenoh.

type z_loaned_config_t

Represents a Zenoh configuration, used to configure Zenoh sessions upon opening.

type z_loaned_session_t

Represents a Zenoh Session.

type z_loaned_subscriber_t

Represents a Zenoh Subscriber entity.

type z_loaned_publisher_t

Represents a Zenoh Publisher entity.

type z_loaned_queryable_t

Represents a Zenoh Queryable entity.

type z_loaned_query_t

Represents a Zenoh Query entity, received by Zenoh queryable entities.

type z_loaned_encoding_t

Represents the encoding of a payload, in a MIME-like format.

type z_loaned_reply_err_t

Represents a Zenoh reply error.

type z_loaned_sample_t

Represents a data sample.

type z_loaned_hello_t

Represents the content of a hello message returned by a zenoh entity as a reply to a scout message.

type z_loaned_reply_t

Represents the reply to a query.

type z_loaned_string_array_t

Represents an array of non null-terminated string.

View Types

TODO: view type description

type z_view_string_t

Represents a string without null-terminator.

type z_view_slice_t

Represents an array of bytes.

type z_view_keyexpr_t

Represents a key expression in Zenoh.

type z_view_string_array_t

Represents an array of non null-terminated string.

Closures

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

  • context: a pointer to an arbitrary state.

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

  • drop: allows the callback’s state to be freed. context will be passed as its last argument.

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.

Represents a sample closure.

types.h::z_owned_closure_sample_t

Represents a loaned sample closure.

types.h::z_loaned_closure_sample_t

Represents a query closure.

types.h::z_owned_closure_query_t

Represents a loaned query closure.

types.h::z_loaned_closure_query_t

Represents a reply closure.

types.h::z_owned_closure_reply_t

Represents a loaned reply closure.

types.h::z_loaned_closure_reply_t

Represents a hello closure.

types.h::z_owned_closure_hello_t

Represents a loaned hello closure.

types.h::z_loaned_closure_hello_t

Represents a Zenoh id closure.

types.h::z_owned_closure_zid_t

Represents a loaned Zenoh id closure.

types.h::z_loaned_closure_zid_t

Zenoh Functions

Macros

z_loan(x)
z_move(x)

Defines a generic function for moving any of the z_owned_X_t types.

Parameters:

  • x – The instance to move.

Returns:

Returns the instance associated with x.

z_clone(x, y)

Defines a generic function for cloning any of the z_owned_X_t types.

Parameters:

  • x – The clone storage.

  • y – The instance to clone.

Returns:

Returns the cloned instance of x.

z_drop(x)

Defines a generic function for dropping any of the z_owned_X_t types.

Parameters:

  • x – The instance to drop.

z_closure()

Defines a variadic macro to ease the definition of callback closures.

Parameters:

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

  • dropper – allows the callback’s state to be freed. context will be passed as its last argument.

  • context – a pointer to an arbitrary state.

Returns:

Returns the new closure.

Primitives

int8_t z_view_string_from_str(z_view_string_t *str, const char *value)

Builds a z_view_string_t by wrapping a const char * string.

Parameters:

  • value – Pointer to a null terminated string.

  • str – Pointer to an uninitialized z_view_string_t.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_view_string_from_substr(z_view_string_t *str, const char *value, size_t len)

Builds a z_view_string_t by wrapping a const char * substring.

Parameters:

  • str – Pointer to an uninitialized z_view_string_t.

  • value – Pointer to a null terminated string.

  • len – Size of the string.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_view_keyexpr_from_str(z_view_keyexpr_t *keyexpr, const char *name)

Builds a z_keyexpr_t from a null-terminated string. It is a loaned key expression that aliases name. This function will fail if the string is not in canon form.

Parameters:

  • name – Pointer to string representation of the keyexpr as a null terminated string.

  • keyexpr – Pointer to an uninitialized z_view_keyexpr_t.

Returns:

0 if creation successful, negative value otherwise.

void z_view_keyexpr_from_str_unchecked(z_view_keyexpr_t *keyexpr, const char *name)

Builds a z_keyexpr_t from a null-terminated string. It is a loaned key expression that aliases name. Input key expression is not checked for correctness.

Parameters:

  • name – Pointer to string representation of the keyexpr as a null terminated string.

  • keyexpr – Pointer to an uninitialized z_view_keyexpr_t.

int8_t z_view_keyexpr_from_str_autocanonize(z_view_keyexpr_t *keyexpr, char *name)

Builds a z_view_keyexpr_t from a null-terminated string with auto canonization. It is a loaned key expression that aliases name. The string is canonized in-place before being passed to keyexpr, possibly shortening it by modifying len. May SEGFAULT if name is NULL or lies in read-only memory (as values initialized with string literals do). name must outlive the constructed key expression.

Parameters:

  • name – Pointer to string representation of the keyexpr as a null terminated string.

  • keyexpr – Pointer to an uninitialized z_view_keyexpr_t.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_keyexpr_as_view_string(const z_loaned_keyexpr_t *keyexpr, z_view_string_t *str)

Gets a null-terminated string view from a z_keyexpr_t.

Parameters:

  • keyexpr – Pointer to a loaned instance of z_keyexpr_t.

  • str – Pointer to an uninitialized z_view_string_t.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_keyexpr_is_canon(const char *start, size_t len)

Checks if a given keyexpr is valid and in canonical form.

Parameters:

  • start – Pointer to the keyexpr in its string representation as a non-null terminated string.

  • len – Number of characters in start.

Returns:

0 if passed string is a valid (and canon) key expression, or a negative value otherwise. Error codes are defined in zp_keyexpr_canon_status_t.

int8_t z_keyexpr_canonize(char *start, size_t *len)

Canonizes of a given keyexpr in string representation. The canonization is performed over the passed string, possibly shortening it by modifying len.

Parameters:

  • start – Pointer to the keyexpr in its string representation as a non-null terminated string.

  • len – Number of characters in start.

Returns:

0 if canonization successful, or a negative value otherwise. Error codes are defined in zp_keyexpr_canon_status_t.

int8_t z_keyexpr_canonize_null_terminated(char *start)

Canonizes of a given keyexpr in string representation. The canonization is performed over the passed string, possibly shortening it by setting null at the end.

Parameters:

  • start – Pointer to the keyexpr in its string representation as a null terminated string.

Returns:

0 if canonization successful, or a negative value otherwise. Error codes are defined in zp_keyexpr_canon_status_t.

_Bool z_keyexpr_includes(const z_loaned_keyexpr_t *l, const z_loaned_keyexpr_t *r)

Checks if a given keyexpr contains another keyexpr in its set.

Parameters:
Returns:

true if l includes r, i.e. the set defined by l contains every key belonging to the set

defined by r. Otherwise, returns false.

_Bool z_keyexpr_intersects(const z_loaned_keyexpr_t *l, const z_loaned_keyexpr_t *r)

Checks if a given keyexpr intersects with another keyexpr.

Parameters:
Returns:

true if keyexprs intersect, i.e. there exists at least one key which is contained in both of the

sets defined by l and r. Otherwise, returns false.

_Bool z_keyexpr_equals(const z_loaned_keyexpr_t *l, const z_loaned_keyexpr_t *r)

Checks if two keyexpr are equal.

Parameters:
Returns:

true if both l and r are equal. Otherwise, returns false.

z_keyexpr_intersection_level_t z_keyexpr_relation_to(const z_loaned_keyexpr_t *left, const z_loaned_keyexpr_t *right)

Returns the relation between left and right from left’s point of view.

Note that this is slower than z_keyexpr_intersects and keyexpr_includes, so you should favor these methods for most applications.

Parameters:
Returns:

Relation between left and right from left’s point of view.

int8_t z_keyexpr_concat(z_owned_keyexpr_t *key, const z_loaned_keyexpr_t *left, const char *right, size_t len)

Constructs key expression by concatenation of key expression in left with a string in right. Returns 0 in case of success, negative error code otherwise.

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.

Parameters:

  • keyexpr – Pointer to an uninitialized z_owned_keyexpr_t to store the keyexpr.

  • left – Pointer to z_loaned_keyexpr_t to keyexpr to concatenate to.

  • right – Pointer to the start of the substring that will be concatenated.

  • len – Length of the substring to concatenate.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_keyexpr_join(z_owned_keyexpr_t *key, const z_loaned_keyexpr_t *left, const z_loaned_keyexpr_t *right)

Constructs key expression by performing path-joining (automatically inserting ‘/’). The resulting key expression is automatically canonized.

Parameters:
Returns:

0 if creation successful, negative value otherwise.

void z_config_new(z_owned_config_t *config)

Builds a new, zenoh-allocated, empty configuration. It consists in an empty set of properties for zenoh session configuration.

Parameters:
int8_t z_config_default(z_owned_config_t *config)

Builds a new, zenoh-allocated, default configuration. It consists in a default set of properties for zenoh session configuration.

Parameters:
Returns:

0` in case of success, or a negative value otherwise.

int8_t z_config_client(z_owned_config_t *config, const char *locator)

Builds a new, zenoh-allocated, client configuration.

Parameters:

  • config – Pointer to uninitialized z_owned_config_t.

  • locator – Zenoh router locator string, if null multicast scouting will be performed.

Returns:

0` in case of success, or a negative value otherwise.

int8_t z_config_peer(z_owned_config_t *config, const char *locator)

Builds a new, zenoh-allocated, peer configuration.

Parameters:

  • config – Pointer to uninitialized z_owned_config_t.

  • locator – Multicast address for peer-to-peer communication.

Returns:

0` in case of success, or a negative value otherwise.

const char *zp_config_get(const z_loaned_config_t *config, uint8_t key)

Gets the property with the given integer key from the configuration.

Parameters:

  • config – Pointer to a z_loaned_config_t to get the property from.

  • key – Integer key of the requested property.

Returns:

The requested property value.

int8_t zp_config_insert(z_loaned_config_t *config, uint8_t key, const char *value)

Inserts or replaces the property with the given integer key in the configuration.

Parameters:

  • config – Pointer to a z_loaned_config_t to modify.

  • key – Integer key of the property to be inserted.

  • value – Property value to be inserted.

Returns:

0 if insertion successful, negative value otherwise.

int8_t z_encoding_from_str(z_owned_encoding_t *encoding, const char *s)

Builds a z_owned_encoding_t from a null terminated string.

Parameters:

  • encoding – Pointer to an uninitialized z_owned_encoding_t.

  • s – Pointer to the null terminated string to use.

Returns:

0 if creation successful,``negative value`` otherwise.

int8_t z_encoding_from_substr(z_owned_encoding_t *encoding, const char *s, size_t len)

Builds a z_owned_encoding_t from a null terminated string.

Parameters:

  • encoding – Pointer to an uninitialized z_owned_encoding_t.

  • s – Pointer to the string to use.

  • len – Number of characters from the string s to use.

Returns:

0 if creation successful,``negative value`` otherwise.

int8_t z_encoding_set_schema_from_str(z_loaned_encoding_t *encoding, const char *schema)

Sets a schema to this encoding from a null-terminated string. Zenoh does not define what a schema is and its semantics is left to the implementer. E.g. a common schema for text/plain encoding is utf-8.

Parameters:

  • encoding – Pointer to initialized z_loaned_encoding_t.

  • schema – Pointer to the null terminated string to use as a schema.

Returns:

0 in case of success,``negative value`` otherwise.

int8_t z_encoding_set_schema_from_substr(z_loaned_encoding_t *encoding, const char *schema, size_t len)

Sets a schema to this encoding from a substring. Zenoh does not define what a schema is and its semantics is left to the implementer. E.g. a common schema for text/plain encoding is utf-8.

Parameters:

  • encoding – Pointer to initialized z_loaned_encoding_t.

  • schema – Pointer to the substring start.

  • len – Number of characters to consider.

Returns:

0 if in case of success,``negative value`` otherwise.

int8_t z_encoding_to_string(const z_loaned_encoding_t *encoding, z_owned_string_t *string)

Builds a string from a z_loaned_encoding_t.

Parameters:
Returns:

0 if creation successful,``negative value`` otherwise.

const z_loaned_bytes_t *z_reply_err_payload(const z_loaned_reply_err_t *reply_err)

Gets the bytes data from a reply error payload by aliasing it.

Parameters:
Returns:

Pointer to the data as a z_loaned_bytes_t.

const z_loaned_encoding_t *z_reply_err_encoding(const z_loaned_reply_err_t *reply_err)

Gets a reply error encoding by aliasing it.

Parameters:
Returns:

Pointer to the encoding as a z_loaned_encoding_t.

int8_t z_slice_from_buf(z_owned_slice_t *slice, uint8_t *data, size_t len, void (*deleter)(void *data, void *context), void *context)

Builds a z_owned_slice_t by transferring ownership over a data to it.

Parameters:

  • slice – Pointer to an uninitialized z_owned_slice_t.

  • data – Pointer to the data to be owned by slice.

  • len –

    Number of bytes in data.

    deleter: A thread-safe delete function to free the data. Will be called once when slice is dropped. Can be

NULL, in case if data is allocated in static memory.

context: An optional context to be passed to the deleter.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_slice_copy_from_buf(z_owned_slice_t *slice, const uint8_t *data, size_t len)

Builds a z_owned_slice_t by copying a buffer into it.

Parameters:

  • slice – Pointer to an uninitialized z_owned_slice_t.

  • data – Pointer to the data that will be copied into slice.

  • len – Number of bytes to copy.

Returns:

0 if creation successful, negative value otherwise.

const uint8_t *z_slice_data(const z_loaned_slice_t *slice)

Gets date pointer of a bytes array.

Parameters:
Returns:

The data pointer.

size_t z_slice_len(const z_loaned_slice_t *slice)

Gets total number of bytes in a bytes array.

Parameters:
Returns:

The number of bytes.

void z_slice_empty(z_owned_slice_t *slice)

Builds an empty z_owned_slice_t.

Parameters:
z_slice_is_empty(const z_loaned_slice_t * slice)

Checks if slice is empty

Parameters:
Returns:

true if conainer is empty, false otherwise.

int8_t z_bytes_deserialize_into_int8(const z_loaned_bytes_t *bytes, int8_t *dst)

Decodes data into a int8_t signed integer.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized int8_t to contain the decoded int.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_int16(const z_loaned_bytes_t *bytes, int16_t *dst)

Decodes data into a int16_t signed integer.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized int16_t to contain the decoded int.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_int32(const z_loaned_bytes_t *bytes, int32_t *dst)

Decodes data into a int32_t signed integer.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized int32_t to contain the decoded int.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_int64(const z_loaned_bytes_t *bytes, int64_t *dst)

Decodes data into a int64_t signed integer.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized int64_t to contain the decoded int.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_uint8(const z_loaned_bytes_t *bytes, uint8_t *dst)

Decodes data into a uint8_t unsigned integer.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized uint8_t to contain the decoded int.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_uint16(const z_loaned_bytes_t *bytes, uint16_t *dst)

Decodes data into a uint16_t unsigned integer.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized uint16_t to contain the decoded int.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_uint32(const z_loaned_bytes_t *bytes, uint32_t *dst)

Decodes data into a uint32_t unsigned integer.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized uint32_t to contain the decoded int.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_uint64(const z_loaned_bytes_t *bytes, uint64_t *dst)

Decodes data into a uint64_t unsigned integer.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized uint64_t to contain the decoded int.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_float(const z_loaned_bytes_t *bytes, float *dst)

Decodes data into a float floating number.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized float to contain the decoded float.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_double(const z_loaned_bytes_t *bytes, double *dst)

Decodes data into a double floating number.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to decode.

  • dst – Pointer to an uninitialized double to contain the decoded float.

Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_slice(const z_loaned_bytes_t *bytes, z_owned_slice_t *dst)

Decodes data into a z_owned_slice_t

Parameters:
Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_deserialize_into_string(const z_loaned_bytes_t *bytes, z_owned_string_t *str)

Decodes data into a z_owned_string_t

Parameters:
Returns:

0 if decode successful, or a negative value otherwise.

int8_t z_bytes_serialize_from_int8(z_owned_bytes_t *bytes, int8_t val)

Encodes a signed integer into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – int8_t value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_int16(z_owned_bytes_t *bytes, int16_t val)

Encodes a signed integer into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – int16_t value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_int32(z_owned_bytes_t *bytes, int32_t val)

Encodes a signed integer into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – int32_t value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_int64(z_owned_bytes_t *bytes, int64_t val)

Encodes a signed integer into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – int64_t value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_uint8(z_owned_bytes_t *bytes, uint8_t val)

Encodes an unsigned integer into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – uint8_t value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_uint16(z_owned_bytes_t *bytes, uint16_t val)

Encodes an unsigned integer into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – uint16_t value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_uint32(z_owned_bytes_t *bytes, uint32_t val)

Encodes an unsigned integer into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – uint32_t value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_uint64(z_owned_bytes_t *bytes, uint64_t val)

Encodes an unsigned integer into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – uint64_t value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_float(z_owned_bytes_t *bytes, float val)

Encodes a floating number into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – float value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_double(z_owned_bytes_t *bytes, double val)

Encodes a floating number into a z_owned_bytes_t

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded int.

  • val – double value to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_from_slice(z_owned_bytes_t *bytes, z_moved_slice_t *slice)

Encodes a slice into a z_owned_bytes_t.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded slice.

  • slice – Pointer to the slice to encode. The slice will be consumed upon function return.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_slice(z_owned_bytes_t *bytes, const z_loaned_slice_t *slice)

Encodes a slice into a z_owned_bytes_t by copying.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded slice.

  • slice – Pointer to the slice to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_from_buf(z_owned_bytes_t *bytes, uint8_t *data, size_t len, void (*deleter)(void *data, void *context), void *context)

Encodes data into a z_owned_bytes_t.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded data.

  • data – Pointer to the data to encode. Ownership is transferred to the bytes.

  • len – Number of bytes to encode.

  • deleter – A thread-safe delete function to free the data. Will be called once when bytes is dropped. Can be

NULL, in case if data is allocated in static memory.

context: An optional context to be passed to the deleter.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_buf(z_owned_bytes_t *bytes, const uint8_t *data, size_t len)

Encodes data into a z_owned_bytes_t by copying.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded data.

  • data – Pointer to the data to encode. Ownership is transferred to the bytes.

  • len – Number of bytes to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_from_static_buf(z_owned_bytes_t *bytes, const uint8_t *data, size_t len)

Encodes statically allocated constant data into a z_owned_bytes_t by aliasing.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded data.

  • data – Pointer to the statically allocated constant data to encode.

  • len – Number of bytes to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_from_string(z_owned_bytes_t *bytes, z_moved_string_t *s)

Encodes a string into a z_owned_bytes_t.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded string.

  • s – Pointer to the string to encode. The string will be consumed upon function return.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_string(z_owned_bytes_t *bytes, const z_loaned_string_t *s)

Encodes a string into a z_owned_bytes_t by copying.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded string.

  • s – Pointer to the string to encode.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_from_str(z_owned_bytes_t *bytes, char *value, void (*deleter)(void *value, void *context), void *context)

Encodes a null-terminated string into a z_owned_bytes_t.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded string.

  • value – Pointer to the string to encode. Ownership is transferred to the bytes.

  • deleter – A thread-safe delete function to free the value. Will be called once when bytes is dropped. Can be

NULL, in case if value is allocated in static memory. context: An optional context to be passed to the deleter.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_serialize_from_str(z_owned_bytes_t *bytes, const char *value)

Encodes a null-terminated string into a z_owned_bytes_t by copying.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded string.

  • value – Pointer to the string to encode. Ownership is transferred to the bytes.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_from_static_str(z_owned_bytes_t *bytes, const char *value)

Encodes a statically allocated constant null-terminated string into a z_owned_bytes_t by aliasing.

Parameters:

  • bytes – An uninitialized z_owned_bytes_t to contain the encoded string.

  • value – Pointer to the statically allocated constant string to encode.

Returns:

0 if encode successful, negative value otherwise.

void z_bytes_empty(z_owned_bytes_t *bytes)

Parameters: bytes: Pointer to an unitialized z_lowned_bytes_t instance.

size_t z_bytes_len(const z_loaned_bytes_t *bytes)

Returns total number of bytes in the container.

Parameters:
Returns:

Number of bytes in the container.

_Bool z_bytes_is_empty(const z_loaned_bytes_t *bytes)

Checks if container is empty

Parameters:
Returns:

true if conainer is empty, false otherwise.

z_bytes_iterator_t z_bytes_get_iterator(const z_loaned_bytes_t *bytes)

Returns an iterator for multi-element serialized data.

Parameters:

  • bytes – Data to iterate over.

Returns:

The constructed z_bytes_iterator_t.

_Bool z_bytes_iterator_next(z_bytes_iterator_t *iter, z_owned_bytes_t *out)

Constructs z_owned_bytes_t object corresponding to the next element of serialized data.

Will construct null-state z_owned_bytes_t when iterator reaches the end (or in case of error).

Parameters:

  • iter – An iterator over multi-element serialized data.

  • out – An uninitialized z_owned_bytes_t that will contain next serialized element.

Returns:

false when iterator reaches the end, true otherwise.

z_bytes_slice_iterator_t z_bytes_get_slice_iterator(const z_loaned_bytes_t *bytes)

Returns an iterator on raw bytes slices contained in the z_loaned_bytes_t.

Zenoh may store data in non-contiguous regions of memory, this iterator then allows to access raw data directly without any attempt of deserializing it. Please note that no guarantee is provided on the internal memory layout. The only provided guarantee is on the bytes order that is preserved.

Parameters:

  • bytes – Data to iterate over.

Returns:

The constructed z_bytes_slice_iterator_t.

_Bool z_bytes_slice_iterator_next(z_bytes_slice_iterator_t *iter, z_view_slice_t *out)

Constructs z_view_slice_t providing view to the next slice.

Parameters:

  • iter – An iterator over slices of serialized data.

  • out – An uninitialized z_view_slice_t that will contain next slice.

Returns:

false when iterator reaches the end, true otherwise.

z_bytes_reader_t z_bytes_get_reader(const z_loaned_bytes_t *bytes)

Returns a reader for the bytes.

The bytes should outlive the reader and should not be modified, while reader is in use.

Parameters:

  • bytes – Data to read.

Returns:

The constructed z_bytes_reader_t.

size_t z_bytes_reader_read(z_bytes_reader_t *reader, uint8_t *dst, size_t len)

Reads data into specified destination.

Parameters:

  • reader – Data reader to read from.

  • dst – Buffer where the read data is written.

  • len – Maximum number of bytes to read.

Returns:

Number of bytes read. If return value is smaller than len, it means that the end of the data was reached.

int8_t z_bytes_reader_read_bounded(z_bytes_reader_t *reader, z_owned_bytes_t *dst)

Reads data into specified destination.

Parameters:

  • reader – Data reader to read from.

  • dst – An uninitialized memory location where a new piece of data will be read. Note that it does not involve a copy,

but only increases reference count.

Returns:

​0​ upon success, negative error code otherwise.

int8_t z_bytes_reader_seek(z_bytes_reader_t *reader, int64_t offset, int origin)

Sets the reader position indicator for the payload to the value pointed to by offset. The new position is exactly offset bytes measured from the beginning of the payload if origin is SEEK_SET, from the current reader position if origin is SEEK_CUR, and from the end of the payload if origin is SEEK_END.

Parameters:

  • reader – Data reader to reposition.

  • offset – New position ffset in bytes.

  • origin – Origin for the new position.

Returns:

​0​ upon success, negative error code otherwise.

int64_t z_bytes_reader_tell(z_bytes_reader_t *reader)

Gets the read position indicator.

Parameters:

  • reader – Data reader to get position of.

Returns:

Read position indicator on success or -1L if failure occurs.

z_bytes_writer_t z_bytes_get_writer(z_loaned_bytes_t *bytes)

Constructs writer for z_loaned_bytes_t.

Parameters:

  • bytes – Data container to write to.

  • writer – Uninitialized memory location where writer is to be constructed.

int8_t z_bytes_writer_write_all(z_bytes_writer_t *writer, const uint8_t *src, size_t len)

Writes len bytes from src into underlying :c:type:`z_loaned_bytes_t.

Parameters:

  • writer – A data writer.

  • src – Buffer to write from.

  • len – Number of bytes to write.

Returns:

0 if encode successful, negative value otherwise.

int8_t z_bytes_writer_append(z_bytes_writer_t *writer, z_moved_bytes_t *bytes)

Appends bytes. This allows to compose a serialized data out of multiple z_owned_bytes_t that may point to different memory regions. Said in other terms, it allows to create a linear view on different memory regions without copy.

Parameters:

  • writer – A data writer.

  • bytes – A data to append.

Returns:

0 in case of success, negative error code otherwise

int8_t z_bytes_writer_append_bounded(z_bytes_writer_t *writer, z_moved_bytes_t *bytes)

Appends bytes, with boundaries information. It would allow to read the same piece of data using z_bytes_reader_read_bounded().

Parameters:

  • writer – A data writer.

  • bytes – A data to append.

Returns:

0 in case of success, negative error code otherwise

_Bool z_timestamp_check(z_timestamp_t ts)

Checks validity of a timestamp

Parameters:

  • ts – Timestamp value to check validity of.

Returns:

true if timestamp is valid, false otherwise.

z_query_target_t z_query_target_default(void)

Builds a default query target.

Returns:

The constructed z_query_target_t.

z_query_consolidation_t z_query_consolidation_auto(void)

Builds an automatic query consolidation z_query_consolidation_t.

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

Returns:

The constructed z_query_consolidation_t.

z_query_consolidation_t z_query_consolidation_default(void)

Builds a default z_query_consolidation_t.

Returns:

The constructed z_query_consolidation_t.

z_query_consolidation_t z_query_consolidation_latest(void)

Builds a latest query consolidation z_query_consolidation_t.

This strategy optimizes bandwidth on all links in the system but will provide a very poor latency.

Returns:

The constructed z_query_consolidation_t.

z_query_consolidation_t z_query_consolidation_monotonic(void)

Builds a monotonic query consolidation z_query_consolidation_t.

This strategy offers the best latency. Replies are directly transmitted to the application when received without needing to wait for all replies. This mode does not guarantee that there will be no duplicates.

Returns:

The constructed z_query_consolidation_t.

z_query_consolidation_t z_query_consolidation_none(void)

Builds a no query consolidation z_query_consolidation_t.

This strategy is useful when querying timeseries data bases or when using quorums.

Returns:

The constructed z_query_consolidation_t.

void z_query_parameters(const z_loaned_query_t *query, z_view_string_t *parameters)

Gets a query parameters field.

Parameters:

  • query – Pointer to the z_loaned_query_t to get the parameters from.

  • parameters – Pointer to an uninitialized z_view_string_t to contain the parameters.

const z_loaned_bytes_t *z_query_payload(const z_loaned_query_t *query)

Gets a query payload by aliasing it.

Parameters:
Returns:

Pointer to the payload as a z_loaned_bytes_t.

const z_loaned_encoding_t *z_query_encoding(const z_loaned_query_t *query)

Gets a query encoding by aliasing it.

Parameters:
Returns:

Pointer to the encoding as a z_loaned_encoding_t.

const z_loaned_bytes_t *z_query_attachment(const z_loaned_query_t *query)

Gets a query attachment value by aliasing it.

Parameters:
Returns:

Pointer to the attachment as a z_loaned_bytes_t.

const z_loaned_keyexpr_t *z_query_keyexpr(const z_loaned_query_t *query)

Gets a query keyexpr by aliasing it.

Parameters:
Returns:

The keyexpr wrapped as a:c:type:z_keyexpr_t.

int8_t z_closure_sample(z_owned_closure_sample_t *closure, z_data_handler_t call, z_dropper_handler_t drop, void *context)

Builds a new sample closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.

Parameters:

  • call – Pointer to the callback function. context will be passed as its last argument.

  • drop – Pointer to the function that will free the callback state. context will be passed as its last argument.

  • context – Pointer to an arbitrary state.

Returns:

The sample closure.

int8_t z_closure_query(z_owned_closure_query_t *closure, z_queryable_handler_t call, z_dropper_handler_t drop, void *context)

Builds a new query closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.

Parameters:

  • call – Pointer to the callback function. context will be passed as its last argument.

  • drop – Pointer to the function that will free the callback state. context will be passed as its last argument.

  • context – Pointer to an arbitrary state.

Returns:

The query closure.

int8_t z_closure_reply(z_owned_closure_reply_t *closure, z_reply_handler_t call, z_dropper_handler_t drop, void *context)

Builds a new reply closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.

Parameters:

  • call – Pointer to the callback function. context will be passed as its last argument.

  • drop – Pointer to the function that will free the callback state. context will be passed as its last argument.

  • context – Pointer to an arbitrary state.

Returns:

The reply closure.

int8_t z_closure_hello(z_owned_closure_hello_t *closure, z_loaned_hello_handler_t call, z_dropper_handler_t drop, void *context)

Builds a new hello closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.

Parameters:

  • call – Pointer to the callback function. context will be passed as its last argument.

  • drop – Pointer to the function that will free the callback state. context will be passed as its last argument.

  • context – Pointer to an arbitrary state.

Returns:

The hello closure.

int8_t z_closure_zid(z_owned_closure_zid_t *closure, z_id_handler_t call, z_dropper_handler_t drop, void *context)

Builds a new zid closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.

Parameters:

  • call – Pointer to the callback function. context will be passed as its last argument.

  • drop – Pointer to the function that will free the callback state. context will be passed as its last argument.

  • context – Pointer to an arbitrary state.

Returns:

The hello closure.

const z_loaned_sample_t *z_sample_loan(const z_owned_sample_t *sample)

Loans a z_owned_sample_t.

Parameters:
Returns:

Pointer to the loaned sample as a z_loaned_sample_t.

const char *z_string_data(const z_loaned_string_t *str)

Gets data from a z_loaned_string_t.

Parameters:
Returns:

Pointer to the string data.

size_t z_string_len(const z_loaned_string_t *str)

Gets string length from a z_loaned_string_t.

Parameters:
Returns:

Length of the string.

int8_t z_string_from_str(z_owned_string_t *str, char *value, void (*deleter)(void *value, void *context), void *context)

Builds a z_owned_string_t by transferring ownership over a null-terminated string to it.

Parameters:

  • str – Pointer to an uninitialized z_owned_string_t.

  • value – Pointer to a null terminated string to be owned by str.

  • deleter – A thread-safe delete function to free the value. Will be called once when str is dropped. Can be

NULL, in case if value is allocated in static memory.

context: An optional context to be passed to the deleter.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_string_copy_from_str(z_owned_string_t *str, const char *value)

Builds a z_string_t by copying a const char * string.

Parameters:

  • str – Pointer to an uninitialized z_owned_string_t.

  • value – Pointer to a null terminated string to be copied.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_string_copy_from_substr(z_owned_string_t *str, const char *value, size_t len)

Builds a z_string_t by wrapping a substring specified by const char * and length len.

Parameters:

  • value – Pointer to a string.

  • len – String size.

  • str – Pointer to an uninitialized z_owned_string_t.

Returns:

0 if creation successful, negative value otherwise.

void z_string_empty(z_owned_string_t *str)

Builds an empty z_owned_string_t.

Parameters:
z_string_is_empty(const z_loaned_string_t * str)

Checks if string is empty

Parameters:
Returns:

true if conainer is empty, false otherwise.

const z_loaned_slice_t *z_string_as_slice(const z_loaned_string_t *str)

Returns z_loaned_slice_t for the string

Parameters:
Returns:

slice containing string data

z_id_t z_hello_zid(const z_loaned_hello_t *hello)

Returns id of Zenoh entity that transmitted hello message.

Parameters:
Returns:

Id of the Zenoh entity that transmitted hello message.

z_whatami_t z_hello_whatami(const z_loaned_hello_t *hello)

Returns type of Zenoh entity that transmitted hello message.

Parameters:
Returns:

Type of the Zenoh entity that transmitted hello message.

const z_loaned_string_array_t *z_hello_locators(const z_loaned_hello_t *hello)

Constructs an array of locators of Zenoh entity that sent hello message.

Parameters:
Returns:

z_loaned_string_array_t containing locators.

int8_t z_whatami_to_view_string(z_whatami_t whatami, z_view_string_t *str_out)

Constructs a non-owned non-null-terminated string from the kind of zenoh entity.

The string has static storage (i.e. valid until the end of the program). :param whatami: A whatami bitmask of zenoh entity kind. :param str_out: An uninitialized memory location where strring will be constructed.

Returns:

0 in case of success, negative value otherwise.

int8_t z_scout(z_moved_config_t *config, z_moved_closure_hello_t *callback, const z_scout_options_t *options)

Primitives

Scouts for other Zenoh entities like routers and/or peers.

Parameters:

  • config – Moved z_owned_config_t to configure the scouting with.

  • callback – Moved z_owned_closure_hello_t callback.

  • options – Pointer to a z_scout_options_t to configure the operation.

Returns:

0 if scouting successfully triggered, negative value otherwise.

int8_t z_open(z_owned_session_t *zs, z_moved_config_t *config)

Opens a Zenoh session.

Parameters:
Returns:

0 if open successful, negative value otherwise.

int8_t z_close(z_moved_session_t *zs)

Closes a Zenoh session.

Parameters:
Returns:

0 if close successful, negative value otherwise.

int8_t z_info_peers_zid(const z_loaned_session_t *zs, z_moved_closure_zid_t *callback)

Fetches Zenoh IDs of all connected peers.

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

Parameters:

  • zs – Pointer to z_loaned_session_t to fetch peer id from.

  • callback – Moved z_owned_closure_zid_t callback.

Returns:

0 if operation successfully triggered, negative value otherwise.

int8_t z_info_routers_zid(const z_loaned_session_t *zs, z_moved_closure_zid_t *callback)

Fetches Zenoh IDs of all connected routers.

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

Parameters:

  • zs – Pointer to a z_loaned_session_t to fetch router id from.

  • callback – Moved z_owned_closure_zid_t callback.

Returns:

0 if operation successfully triggered, negative value otherwise.

z_id_t z_info_zid(const z_loaned_session_t *zs)

Gets the local Zenoh ID associated to a given Zenoh session.

If this function returns an array of 16 zeros, this means the session is invalid.

Parameters:
Returns:

The local Zenoh ID of the session as z_id_t.

const z_loaned_keyexpr_t *z_sample_keyexpr(const z_loaned_sample_t *sample)

Gets the keyexpr from a sample by aliasing it.

Parameters:
Returns:

The keyexpr wrapped as a z_loaned_keyexpr_t.

const z_loaned_bytes_t *z_sample_payload(const z_loaned_sample_t *sample)

Gets the payload of a sample by aliasing it.

Parameters:
Returns:

The payload wrapped as a z_loaned_bytes_t.

const z_timestamp_t *z_sample_timestamp(const z_loaned_sample_t *sample)

Gets the timestamp of a sample by aliasing it.

Parameters:
Returns:

The pointer to timestamp wrapped as a z_timestamp_t. Returns NULL if no timestamp was set.

const z_loaned_encoding_t *z_sample_encoding(const z_loaned_sample_t *sample)

Gets the encoding of a sample by aliasing it.

Parameters:
Returns:

The encoding wrapped as a z_loaned_encoding_t*.

z_sample_kind_t z_sample_kind(const z_loaned_sample_t *sample)

Gets the kind of a sample by aliasing it.

Parameters:
Returns:

The sample kind wrapped as a z_sample_kind_t.

z_reliability_t z_sample_reliability(const z_loaned_sample_t *sample)
const z_loaned_bytes_t *z_sample_attachment(const z_loaned_sample_t *sample)

Gets the attachment of a sample by aliasing it.

Parameters:
Returns:

Pointer to the attachment as a z_loaned_bytes_t.

void z_put_options_default(z_put_options_t *options)

Builds a z_put_options_t with default values.

:param Pointer to an uninitialized z_put_options_t.:

void z_delete_options_default(z_delete_options_t *options)

Builds a z_delete_options_t with default values.

:param Pointer to an uninitialized z_delete_options_t.:

int8_t z_put(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, z_moved_bytes_t *payload, const z_put_options_t *options)

Puts data for a given keyexpr.

Parameters:
Returns:

0 if put operation successful, negative value otherwise.

int8_t z_delete(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, const z_delete_options_t *options)

Deletes data for a given keyexpr.

Parameters:
Returns:

0 if delete operation successful, negative value otherwise.

void z_publisher_options_default(z_publisher_options_t *options)

Builds a z_publisher_options_t with default values.

:param Pointer to an uninitialized z_delete_options_t.:

int8_t z_declare_publisher(z_owned_publisher_t *pub, const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, const z_publisher_options_t *options)

Declares a publisher for a given keyexpr.

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

Parameters:
Returns:

0 if declare successful, negative value otherwise.

int8_t z_undeclare_publisher(z_moved_publisher_t *pub)

Undeclares a publisher.

Parameters:
Returns:

0 if undeclare successful, negative value otherwise.

void z_publisher_put_options_default(z_publisher_put_options_t *options)

Builds a z_publisher_put_options_t with default values.

Parameters:
void z_publisher_delete_options_default(z_publisher_delete_options_t *options)

Builds a z_publisher_delete_options_t with default values.

Parameters:
int8_t z_publisher_put(const z_loaned_publisher_t *pub, z_moved_bytes_t *payload, const z_publisher_put_options_t *options)

Puts data for the keyexpr bound to the given publisher.

Parameters:
Returns:

0 if put operation successful, negative value otherwise.

int8_t z_publisher_delete(const z_loaned_publisher_t *pub, const z_publisher_delete_options_t *options)

Deletes data from the keyexpr bound to the given publisher.

Parameters:
Returns:

0 if delete operation successful, negative value otherwise.

void z_get_options_default(z_get_options_t *options)

Builds a z_get_options_t with default values.

Parameters:
int8_t z_get(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, const char *parameters, z_moved_closure_reply_t *callback, z_get_options_t *options)

Sends a distributed query for a given keyexpr.

Parameters:

  • zs – Pointer to a z_loaned_session_t to send the query through.

  • keyexpr – Pointer to a z_loaned_keyexpr_t to send the query for.

  • parameters – Pointer to the parameters as a null-terminated string.

  • callback – Moved z_owned_closure_reply_t callback.

  • options – Pointer to a z_get_options_t to configure the operation.

Returns:

0 if put operation successful, negative value otherwise.

_Bool z_reply_is_ok(const z_loaned_reply_t *reply)

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

Parameters:
Returns:

true if queryable answered with an OK, false otherwise.

const z_loaned_sample_t *z_reply_ok(const z_loaned_reply_t *reply)

Gets the content of an OK reply.

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

Parameters:
Returns:

The OK reply content wrapped as a z_loaned_sample_t.

const z_loaned_reply_err_t *z_reply_err(const z_loaned_reply_t *reply)

Gets the contents of an error reply.

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

Parameters:
Returns:

The error reply content wrapped as a z_loaned_reply_err_t.

void z_queryable_options_default(z_queryable_options_t *options)

Builds a z_queryable_options_t with default values.

Parameters:
int8_t z_declare_queryable(z_owned_queryable_t *queryable, const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, z_moved_closure_query_t *callback, const z_queryable_options_t *options)

Declares a queryable for a given keyexpr.

Parameters:
Returns:

0 if declare operation successful, negative value otherwise.

int8_t z_undeclare_queryable(z_moved_queryable_t *queryable)

Undeclares a queryable.

Parameters:
Returns:

0 if undeclare operation successful, negative value otherwise.

void z_query_reply_options_default(z_query_reply_options_t *options)

Builds a z_query_reply_options_t with default values.

Parameters:
int8_t z_query_reply(const z_loaned_query_t *query, const z_loaned_keyexpr_t *keyexpr, z_moved_bytes_t *payload, const z_query_reply_options_t *options)

Sends a reply to a query.

This function must be called inside of a z_owned_closure_query_t callback associated to the z_owned_queryable_t, passing the received query 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 callback returns.

Parameters:
Returns:

0 if reply operation successful, negative value otherwise.

void z_query_reply_del_options_default(z_query_reply_del_options_t *options)

Builds a z_query_reply_del_options_t with default values.

Parameters:

  • options – Pointer to an uninitialized z_query_reply_del_options_t.

int8_t z_query_reply_del(const z_loaned_query_t *query, const z_loaned_keyexpr_t *keyexpr, const z_query_reply_del_options_t *options)

Sends a reply delete to a query.

This function must be called inside of a z_owned_closure_query_t callback associated to the z_owned_queryable_t, passing the received query 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 callback returns.

Parameters:

  • query – Pointer to a z_loaned_query_t to reply.

  • keyexpr – Pointer to a z_loaned_keyexpr_t to bind the reply with.

  • options – Pointer to a z_query_reply_del_options_t to configure the reply.

Returns:

0 if reply operation successful, negative value otherwise.

void z_query_reply_err_options_default(z_query_reply_err_options_t *options)

Builds a z_query_reply_err_options_t with default values.

Parameters:

  • options – Pointer to an uninitialized z_query_reply_err_options_t.

int8_t z_query_reply_err(const z_loaned_query_t *query, z_moved_bytes_t *payload, const z_query_reply_err_options_t *options)

Sends a reply error to a query.

This function must be called inside of a z_owned_closure_query_t callback associated to the z_owned_queryable_t, passing the received query 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 callback returns.

Parameters:

  • query – Pointer to a z_loaned_query_t to reply.

  • payload – Moved reply error data payload.

  • options – Pointer to a z_query_reply_err_options_t to configure the reply error.

Returns:

0 if reply operation successful, negative value otherwise.

int8_t z_keyexpr_from_str(z_owned_keyexpr_t *keyexpr, const char *name)

Builds a new keyexpr.

Parameters:

  • keyexpr – Pointer to an uninitialized z_owned_keyexpr_t to store the keyexpr.

  • name – Pointer to the null-terminated string of the keyexpr.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_keyexpr_from_substr(z_owned_keyexpr_t *keyexpr, const char *name, size_t len)

Builds a new keyexpr from a substring.

Parameters:

  • keyexpr – Pointer to an uninitialized z_owned_keyexpr_t to store the keyexpr.

  • name – Pointer to the start of the substring for keyxpr.

  • len – Length of the substring to consider.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_keyexpr_from_str_autocanonize(z_owned_keyexpr_t *keyexpr, const char *name)

Builds a z_owned_keyexpr_t from a null-terminated string with auto canonization.

Parameters:

  • keyexpr – Pointer to an uninitialized z_owned_keyexpr_t.

  • name – Pointer to string representation of the keyexpr as a null terminated string.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_keyexpr_from_substr_autocanonize(z_owned_keyexpr_t *keyexpr, const char *name, size_t *len)

Builds a z_owned_keyexpr_t from a substring with auto canonization.

Parameters:

  • keyexpr – Pointer to an uninitialized z_owned_keyexpr_t to store the keyexpr.

  • name – Pointer to the start of the substring for keyxpr.

  • len – Length of the substring to consider. After the function return it will be equal to the canonized key

expression string length.

Returns:

0 if creation successful, negative value otherwise.

int8_t z_declare_keyexpr(z_owned_keyexpr_t *declared_keyexpr, const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr)

Declares a keyexpr, so that it is mapped on a numerical id.

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

Parameters:
Returns:

0 if declare successful, negative value otherwise.

int8_t z_undeclare_keyexpr(z_moved_keyexpr_t *keyexpr, const z_loaned_session_t *zs)

Undeclares a keyexpr.

Parameters:
Returns:

0 if undeclare successful, negative value otherwise.

void z_subscriber_options_default(z_subscriber_options_t *options)

Builds a z_subscriber_options_t with default values.

Parameters:
int8_t z_declare_subscriber(z_owned_subscriber_t *sub, const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, z_moved_closure_sample_t *callback, const z_subscriber_options_t *options)

Declares a subscriber for a given keyexpr.

Parameters:
Returns:

0 if declare successful, negative value otherwise.

int8_t z_undeclare_subscriber(z_moved_subscriber_t *sub)

Undeclares the subscriber.

Parameters:
Returns:

0 if undeclare successful, negative value otherwise.

const z_loaned_keyexpr_t *z_subscriber_keyexpr(const z_loaned_subscriber_t *subscriber)

Gets the keyexpr from a subscriber.

Parameters:
Returns:

The keyexpr wrapped as a z_loaned_keyexpr_t.

void zp_task_read_options_default(zp_task_read_options_t *options)

Multi Thread Tasks helpers

Builds a zp_task_read_options_t with default value.

Parameters:
int8_t zp_start_read_task(z_loaned_session_t *zs, const zp_task_read_options_t *options)

Starts a task to read from the network and process the received messages.

Note that the task can be implemented in form of thread, process, etc. and its implementation is platform-dependent.

Parameters:
Returns:

0 if task started successfully, negative value otherwise.

int8_t zp_stop_read_task(z_loaned_session_t *zs)

Stops the read task.

This may result in stopping a thread or a process depending on the target platform.

Parameters:
Returns:

0 if task stopped successfully, negative value otherwise.

void zp_task_lease_options_default(zp_task_lease_options_t *options)

Builds a zp_task_lease_options_t with default value.

Parameters:
int8_t zp_start_lease_task(z_loaned_session_t *zs, const zp_task_lease_options_t *options)

Starts a 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. Note that the task can be implemented in form of thread, process, etc. and its implementation is platform-dependent.

Parameters:
Returns:

0 if task started successfully, negative value otherwise.

int8_t zp_stop_lease_task(z_loaned_session_t *zs)

Stops the lease task.

This may result in stopping a thread or a process depending on the target platform.

Parameters:
Returns:

0 if task stopped successfully, negative value otherwise.

void zp_read_options_default(zp_read_options_t *options)

Single Thread helpers

Builds a zp_read_options_t with default value.

Parameters:
int8_t zp_read(const z_loaned_session_t *zs, const zp_read_options_t *options)

Executes a single read from the network and process received messages.

Parameters:
Returns:

0 if execution was successful, negative value otherwise.

void zp_send_keep_alive_options_default(zp_send_keep_alive_options_t *options)

Builds a zp_send_keep_alive_options_t with default value.

Parameters:
int8_t zp_send_keep_alive(const z_loaned_session_t *zs, const zp_send_keep_alive_options_t *options)

Executes a single send keep alive procedure.

Parameters:
Returns:

0 if execution was successful, negative value otherwise.

void zp_send_join_options_default(zp_send_join_options_t *options)

Builds a zp_send_join_options_t with default value.

Parameters:
int8_t zp_send_join(const z_loaned_session_t *zs, const zp_send_join_options_t *options)

Executes a single send join procedure.

Parameters:
Returns:

0 if execution was successful, negative value otherwise.