API Reference

Containers

Slice

Represents an array of bytes.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_slice_t

type z_view_slice_t

type z_loaned_slice_t

type z_moved_slice_t

Functions

void z_slice_empty(z_owned_slice_t *slice)

Builds an empty z_owned_slice_t.

Parameters:

slice – Pointer to an uninitialized z_owned_slice_t.

z_result_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 is successful, negative value otherwise.

z_result_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 the case where data is allocated in static memory.
context – An optional context to be passed to the deleter.

Returns:

0 if creation is successful, negative value otherwise.

const uint8_t *z_slice_data(const z_loaned_slice_t *slice)

Gets date pointer of a bytes array.

Parameters:

slice – Pointer to a z_loaned_slice_t to get data from.

Returns:

The data pointer.

size_t z_slice_len(const z_loaned_slice_t *slice)

Gets the total number of bytes in a bytes array.

Parameters:

slice – Pointer to a z_loaned_slice_t to get length from.

Returns:

The number of bytes.

bool z_slice_is_empty(const z_loaned_slice_t *slice)

Checks if slice is empty

Parameters:

slice – Pointer to a z_loaned_slice_t to check.

Returns:

true if the container is empty, false otherwise.

z_result_t z_view_slice_from_buf(z_view_slice_t *slice, const uint8_t *data, size_t len)

Builds a z_view_slice_t.

Parameters:

slice – Pointer to an uninitialized z_view_slice_t.
data – Pointer to the data to be pointed by slice.
len – Number of bytes in data.

Returns:

0 if creation is successful, negative value otherwise.

void z_view_slice_empty(z_view_slice_t *slice): See z_slice_empty()

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_slice_drop(z_moved_slice_t *slice)

void z_slice_clone(z_owned_slice_t *dst, const z_loaned_slice_t *slice)

const z_loaned_slice_t *z_view_slice_loan(const z_view_slice_t *slice)

z_loaned_slice_t *z_view_slice_loan_mut(z_view_slice_t *slice)

const z_loaned_slice_t *z_slice_loan(const z_owned_slice_t *slice)

z_loaned_slice_t *z_slice_loan_mut(z_owned_slice_t *slice)

z_result_t z_slice_take_from_loaned(z_owned_slice_t *dst, z_loaned_slice_t *src)

String

Represents a string without null-terminator.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_string_t

type z_view_string_t

type z_loaned_string_t

type z_moved_string_t

Functions

void z_string_empty(z_owned_string_t *str)

Builds an empty z_owned_string_t.

Parameters:

str – Pointer to an uninitialized z_owned_string_t.

z_result_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 is successful, negative value otherwise.

z_result_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:

str – Pointer to an uninitialized z_owned_string_t.
value – Pointer to a string.
len – String size.

Returns:

0 if creation is successful, negative value otherwise.

z_result_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 the case where value is allocated in static memory.
context – An optional context to be passed to the deleter.

Returns:

0 if creation is successful, negative value otherwise.

const char *z_string_data(const z_loaned_string_t *str)

Gets data from a z_loaned_string_t.

Parameters:

str – Pointer to a z_loaned_string_t to get data from.

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:

str – Pointer to a z_loaned_string_t to get length from.

Returns:

Length of the string.

bool z_string_is_empty(const z_loaned_string_t *str)

Checks if string is empty

Parameters:

str – Pointer to a z_loaned_string_t to check.

Returns:

true if the string 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:

str – Pointer to a z_loaned_string_t to get a slice.

Returns:

slice containing string data

z_result_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:

str – Pointer to an uninitialized z_view_string_t.
value – Pointer to a null terminated string.

Returns:

0 if creation successful, negative value otherwise.

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

void z_view_string_empty(z_view_string_t *string): See z_string_empty()

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_string_drop(z_moved_string_t *string)

void z_string_clone(z_owned_string_t *dst, const z_loaned_string_t *string)

const z_loaned_string_t *z_view_string_loan(const z_view_string_t *string)

z_loaned_string_t *z_view_string_loan_mut(z_view_string_t *string)

const z_loaned_string_t *z_string_loan(const z_owned_string_t *string)

z_loaned_string_t *z_string_loan_mut(z_owned_string_t *string)

z_result_t z_string_take_from_loaned(z_owned_string_t *dst, z_loaned_string_t *src)

String Array

Represents an array of non null-terminated strings.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_string_array_t

type z_loaned_string_array_t

type z_moved_string_array_t

Functions

void z_string_array_new(z_owned_string_array_t *a)

Constructs a new empty string array.

Parameters:

a – Pointer to an uninitialized z_owned_string_array_t to store the array of strings.

size_t z_string_array_push_by_alias(z_loaned_string_array_t *a, const z_loaned_string_t *value)

Appends specified value to the end of the string array by alias.

Parameters:

a – Pointer to z_loaned_string_array_t.
value – Pointer to the string to be added.

Returns:

The new length of the array.

size_t z_string_array_push_by_copy(z_loaned_string_array_t *a, const z_loaned_string_t *value)

Appends specified value to the end of the string array by copying.

Parameters:

a – Pointer to z_loaned_string_array_t.
value – Pointer to the string to be added.

Returns:

The new length of the array.

const z_loaned_string_t *z_string_array_get(const z_loaned_string_array_t *a, size_t k)

Returns the value at the position of index in the string array.

Parameters:

a – Pointer to z_loaned_string_array_t.
k – index value.

Returns:

NULL if the index is out of bounds.

size_t z_string_array_len(const z_loaned_string_array_t *a): Returns the number of elements in the array.

bool z_string_array_is_empty(const z_loaned_string_array_t *a): Returns true if the array is empty, false otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_string_array_drop(z_moved_string_array_t *string_array)

void z_string_array_clone(z_owned_string_array_t *dst, const z_loaned_string_array_t *string_array)

const z_loaned_string_array_t *z_string_array_loan(const z_owned_string_array_t *string_array)

z_loaned_string_array_t *z_string_array_loan_mut(z_owned_string_array_t *string_array)

z_result_t z_string_array_take_from_loaned(z_owned_string_array_t *dst, z_loaned_string_array_t *src)

Common

Key expression

Represents a key expression in Zenoh.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_keyexpr_t

type z_view_keyexpr_t

type z_loaned_keyexpr_t

type z_moved_keyexpr_t

enum z_keyexpr_intersection_level_t

Intersection level of two key expressions.

enumerator Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT: The two key expressions do not intersect.

enumerator Z_KEYEXPR_INTERSECTION_LEVEL_INTERSECTS: The two key expressions intersect, i.e. there exists at least one key expression that is included by both.

enumerator Z_KEYEXPR_INTERSECTION_LEVEL_INCLUDES: The first key expression is the superset of the second one.

enumerator Z_KEYEXPR_INTERSECTION_LEVEL_EQUALS: The two key expressions are equal.

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.

Functions

z_result_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 is successful, negative value otherwise.

z_result_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:

keyexpr – Pointer to an uninitialized z_view_keyexpr_t.
name – Pointer to string representation of the keyexpr as a null terminated string.

Returns:

0 if creation successful, negative value otherwise.

z_result_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 is successful, negative value otherwise.

z_result_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:

keyexpr – Pointer to an uninitialized z_view_keyexpr_t.
name – Pointer to string representation of the keyexpr as a null terminated string.

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:

keyexpr – Pointer to an uninitialized z_view_keyexpr_t.
name – Pointer to string representation of the keyexpr as a null terminated string.

z_result_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 is successful, negative value otherwise.

z_result_t z_view_keyexpr_from_substr(z_view_keyexpr_t *keyexpr, const char *name, size_t len)

Builds a z_keyexpr_t by aliasing a substring. It is a loaned key expression that aliases name. This function will fail if the string is not in canon form.

Parameters:

keyexpr – Pointer to an uninitialized z_view_keyexpr_t.
name – Pointer to string representation of the keyexpr.
len – Size of the string.

Returns:

0 if creation successful, negative value otherwise.

z_result_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 keyexpr.
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 is successful, negative value otherwise.

z_result_t z_view_keyexpr_from_substr_autocanonize(z_view_keyexpr_t *keyexpr, char *name, size_t *len)

Builds a z_view_keyexpr_t from a substring 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:

keyexpr – Pointer to an uninitialized z_view_keyexpr_t.
name – Pointer to string representation of the keyexpr.
len – Pointer to the size of the string.

Returns:

0 if creation successful, negative value otherwise.

void z_view_keyexpr_from_substr_unchecked(z_view_keyexpr_t *keyexpr, const char *name, size_t len)

Builds a z_keyexpr_t from a substring. It is a loaned key expression that aliases name. Input key expression is not checked for correctness.

Parameters:

keyexpr – Pointer to an uninitialized z_view_keyexpr_t.
name – Pointer to string representation of the keyexpr.
len – Size of the string.

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

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

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

z_result_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 the passed string is a valid (and canon) key expression, or a negative value otherwise. Error codes are defined in zp_keyexpr_canon_status_t.

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

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.

z_result_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:

keyexpr – Pointer to an uninitialized z_owned_keyexpr_t to store the keyexpr.
left – Pointer to z_loaned_keyexpr_t to the left part of the resulting key expression.
right – Pointer to z_loaned_keyexpr_t to the right part of the resulting key expression.

Returns:

0 if creation successful, negative value otherwise.

bool z_keyexpr_equals(const z_loaned_keyexpr_t *l, const z_loaned_keyexpr_t *r)

Checks if two keyexpr are equal.

Parameters:

l – Pointer to a z_loaned_keyexpr_t.
r – Pointer to a z_loaned_keyexpr_t.

Returns:

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

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:

l – Pointer to a z_loaned_keyexpr_t.
r – Pointer to a z_loaned_keyexpr_t.

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:

l – Pointer to a z_loaned_keyexpr_t.
r – Pointer to a z_loaned_keyexpr_t.

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.

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 the 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:

left – Pointer to z_loaned_keyexpr_t representing left key expression.
right – Pointer to z_loaned_keyexpr_t representing right key expression.

Returns:

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

z_result_t z_declare_keyexpr(const z_loaned_session_t *zs, z_owned_keyexpr_t *declared_keyexpr, 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:

zs – Pointer to a z_loaned_session_t to declare the keyexpr through.
declared_keyexpr – Pointer to an uninitialized z_owned_keyexpr_t to contain the declared keyexpr.
keyexpr – Pointer to a z_loaned_keyexpr_t to bind the keyexpr with.

Returns:

0 if declare is successful, negative value otherwise.

z_result_t z_undeclare_keyexpr(const z_loaned_session_t *zs, z_moved_keyexpr_t *keyexpr)

Undeclares a keyexpr.

Parameters:

zs – Pointer to a z_loaned_session_t to undeclare the data through.
keyexpr – Moved z_owned_keyexpr_t to undeclare.

Returns:

0 if undeclare is successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_keyexpr_drop(z_moved_keyexpr_t *keyexpr)

void z_keyexpr_clone(z_owned_keyexpr_t *dst, const z_loaned_keyexpr_t *keyexpr)

const z_loaned_keyexpr_t *z_view_keyexpr_loan(const z_view_keyexpr_t *keyexpr)

z_loaned_keyexpr_t *z_view_keyexpr_loan_mut(z_view_keyexpr_t *keyexpr)

const z_loaned_keyexpr_t *z_keyexpr_loan(const z_owned_keyexpr_t *keyexpr)

z_loaned_keyexpr_t *z_keyexpr_loan_mut(z_owned_keyexpr_t *keyexpr)

z_result_t z_keyexpr_take_from_loaned(z_owned_keyexpr_t *dst, z_loaned_keyexpr_t *src)

Payload

Types

see details at Owned Types z_owned_xxx_t

type z_owned_bytes_t

type z_loaned_bytes_t

type z_moved_bytes_t

type z_owned_bytes_writter_t

type z_loaned_bytes_writter_t

type z_moved_bytes_writter_t

typedef int z_bytes_reader_t: A reader for data.

type z_bytes_slice_iterator_t: An iterator over slices of data.

Functions

void z_bytes_empty(z_owned_bytes_t *bytes)

Constructs an empty payload.

Parameters:

bytes – Pointer to an unitialized z_loaned_bytes_t instance.

size_t z_bytes_len(const z_loaned_bytes_t *bytes)

Returns total number of bytes in the container.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to decode.

Returns:

Number of the bytes in the container.

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

Converts 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 convert. Ownership is transferred to the bytes.
len – Number of bytes to consider.
deleter – A thread-safe delete function to free the data. Will be called once when bytes is dropped. Can be NULL in the case where data is allocated in static memory.
context – An optional context to be passed to the deleter.

Returns:

0 if conversion is successful, negative value otherwise.

z_result_t z_bytes_from_slice(z_owned_bytes_t *bytes, z_moved_slice_t *slice)

Converts 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 convert. The slice will be consumed upon function return.

Returns:

0 if conversion is successful, negative value otherwise.

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

Converts 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 consider.

Returns:

0 if conversion is successful, negative value otherwise.

z_result_t z_bytes_from_static_str(z_owned_bytes_t *bytes, const char *value)

Converts 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 convert.

Returns:

0 if conversion is successful, negative value otherwise.

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

Converts 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 converts. 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 the case where value is allocated in static memory.
context – An optional context to be passed to the deleter.

Returns:

0 if conversion is successful, negative value otherwise.

z_result_t z_bytes_from_string(z_owned_bytes_t *bytes, z_moved_string_t *s)

Converts 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 convert. The string will be consumed upon function return.

Returns:

0 if conversion is successful, negative value otherwise.

z_result_t z_bytes_copy_from_buf(z_owned_bytes_t *bytes, const uint8_t *data, size_t len)

Converts 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 convert.
len – Number of bytes to consider.

Returns:

0 if conversion is successful, negative value otherwise.

z_result_t z_bytes_copy_from_slice(z_owned_bytes_t *bytes, const z_loaned_slice_t *slice)

Converts 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 convert.

Returns:

0 if conversion is successful, negative value otherwise.

z_result_t z_bytes_copy_from_str(z_owned_bytes_t *bytes, const char *value)

Converts 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 converts.

Returns:

0 if conversion is successful, negative value otherwise.

z_result_t z_bytes_copy_from_string(z_owned_bytes_t *bytes, const z_loaned_string_t *s)

Converts 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 convert.

Returns:

0 if conversion is successful, negative value otherwise.

z_result_t z_bytes_to_slice(const z_loaned_bytes_t *bytes, z_owned_slice_t *dst)

Converts data into a z_owned_slice_t

Parameters:

bytes – Pointer to a z_loaned_bytes_t to decode.
dst – Pointer to an uninitialized z_owned_slice_t to contain the decoded slice.

Returns:

0 if decode is successful, or a negative value otherwise.

z_result_t z_bytes_to_string(const z_loaned_bytes_t *bytes, z_owned_string_t *str)

Converts data into a z_owned_string_t

Parameters:

bytes – Pointer to a z_loaned_bytes_t to decode.
str – Pointer to an uninitialized z_owned_string_t to contain the decoded string.

Returns:

0 if decode is successful, or a negative value otherwise.

z_result_t z_bytes_get_contiguous_view(const z_loaned_bytes_t *bytes, z_view_slice_t *view)

Attempts to get a contiguous view to the underlying bytes (unstable).

This is only possible if data is not fragmented, otherwise the function will fail. In case of fragmented data, consider using z_bytes_get_slice_iterator().

Parameters:

bytes – An instance of Zenoh data.
view – An uninitialized memory location where a contiguous view on data will be constructed.

Returns:

0 in case of success, negative value 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.

size_t z_bytes_reader_remaining(const z_bytes_reader_t *reader)

Gets number of bytes that can still be read.

Parameters:

reader – Data reader.

Returns:

Number of bytes that can still be read.

z_result_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 in case of success, negative value 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_result_t z_bytes_writer_append(z_loaned_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 if write is successful, negative value otherwise.

z_result_t z_bytes_writer_empty(z_owned_bytes_writer_t *writer)

Constructs an empty writer for payload.

Parameters:

writer – An uninitialized memory location where writer is to be constructed.

Returns:

0 in case of success, negative value otherwise.

void z_bytes_writer_finish(z_moved_bytes_writer_t *writer, z_owned_bytes_t *bytes)

Finishes writing and returns underlying bytes.

Parameters:

writer – A data writer.
bytes – An uninitialized memory location where bytes is to be constructed.

z_result_t z_bytes_writer_write_all(z_loaned_bytes_writer_t *writer, const uint8_t *src, size_t len)

Writes len bytes from src into underlying z_loaned_bytes_t.

Parameters:

writer – A data writer.
src – Buffer to write from.
len – Number of bytes to write.

Returns:

0 if write is successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_bytes_drop(z_moved_bytes_t *bytes)

void z_bytes_clone(z_owned_bytes_t *dst, const z_loaned_bytes_t *bytes)

const z_loaned_bytes_t *z_bytes_loan(const z_owned_bytes_t *bytes)

z_loaned_bytes_t *z_bytes_loan_mut(z_owned_bytes_t *bytes)

z_result_t z_bytes_take_from_loaned(z_owned_bytes_t *dst, z_loaned_bytes_t *src)

void z_bytes_writer_drop(z_moved_bytes_writer_t *bytes_writer)

void z_bytes_writer_clone(z_owned_bytes_writer_t *dst, const z_loaned_bytes_writer_t *bytes_writer)

const z_loaned_bytes_writer_t *z_bytes_writer_loan(const z_owned_bytes_writer_t *bytes_writer)

z_loaned_bytes_writer_t *z_bytes_writer_loan_mut(z_owned_bytes_writer_t *bytes_writer)

z_result_t z_bytes_writer_take_from_loaned(z_owned_bytes_writer_t *dst, z_loaned_bytes_writer_t *src)

Encoding

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

Types

See details at Owned Types z_owned_xxx_t

type z_owned_encoding_t

type z_loaned_encoding_t

type z_moved_encoding_t

Functions

z_result_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 is successful,``negative value`` otherwise.

z_result_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 is successful,``negative value`` otherwise.

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

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

z_result_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:

encoding – Pointer to the z_loaned_encoding_t to use.
string – Pointer to an uninitialized z_owned_string_t to store the string.

Returns:

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

bool z_encoding_equals(const z_loaned_encoding_t *left, const z_loaned_encoding_t *right)

Checks if two encodings are equal.

Parameters:

left – Pointer to the first z_loaned_encoding_t to compare.
right – Pointer to the second z_loaned_encoding_t to compare.

Returns:

true if left equals right, false otherwise.

const z_loaned_encoding_t *z_encoding_loan_default(void): Returns a loaned default z_loaned_encoding_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_encoding_drop(z_moved_encoding_t *encoding)

void z_encoding_clone(z_owned_encoding_t *dst, const z_loaned_encoding_t *encoding)

const z_loaned_encoding_t *z_encoding_loan(const z_owned_encoding_t *encoding)

z_loaned_encoding_t *z_encoding_loan_mut(z_owned_encoding_t *encoding)

z_result_t z_encoding_take_from_loaned(z_owned_encoding_t *dst, z_loaned_encoding_t *src)

Predefined Encodings

const z_loaned_encoding_t *z_encoding_zenoh_bytes(void)

Just some bytes.

Constant alias for string: “zenoh/bytes”.

This encoding supposes that the payload was created with c:func:z_bytes_from_buf, c:func:z_bytes_from_slice or similar functions and its data can be accessed via c:func:z_bytes_to_slice.

const z_loaned_encoding_t *z_encoding_zenoh_string(void)

A UTF-8 string. Constant alias for string: “zenoh/string”.

This encoding supposes that the payload was created with c:func:z_bytes_from_str, c:func:z_bytes_from_string or similar functions and its data can be accessed via c:func:z_bytes_to_string.

const z_loaned_encoding_t *z_encoding_zenoh_serialized(void)

Zenoh serialized data. Constant alias for string: “zenoh/serialized”.

This encoding supposes that the payload was created with serialization functions. The schema field may contain the details of serialziation format.

const z_loaned_encoding_t *z_encoding_application_octet_stream(void): An application-specific stream of bytes. Constant alias for string: “application/octet-stream”.

const z_loaned_encoding_t *z_encoding_text_plain(void): A textual file. Constant alias for string: “text/plain”.

const z_loaned_encoding_t *z_encoding_application_json(void): JSON data intended to be consumed by an application. Constant alias for string: “application/json”.

const z_loaned_encoding_t *z_encoding_text_json(void): JSON data intended to be human readable. Constant alias for string: “text/json”.

const z_loaned_encoding_t *z_encoding_application_cdr(void): A Common Data Representation (CDR)-encoded data. Constant alias for string: “application/cdr”.

const z_loaned_encoding_t *z_encoding_application_cbor(void): A Concise Binary Object Representation (CBOR)-encoded data. Constant alias for string: “application/cbor”.

const z_loaned_encoding_t *z_encoding_application_yaml(void): YAML data intended to be consumed by an application. Constant alias for string: “application/yaml”.

const z_loaned_encoding_t *z_encoding_text_yaml(void): YAML data intended to be human readable. Constant alias for string: “text/yaml”.

const z_loaned_encoding_t *z_encoding_text_json5(void): JSON5 encoded data that are human readable. Constant alias for string: “text/json5”.

const z_loaned_encoding_t *z_encoding_application_python_serialized_object(void): A Python object serialized using pickle. Constant alias for string: “application/python-serialized-object”.

const z_loaned_encoding_t *z_encoding_application_protobuf(void): An application-specific protobuf-encoded data. Constant alias for string: “application/protobuf”.

const z_loaned_encoding_t *z_encoding_application_java_serialized_object(void): A Java serialized object. Constant alias for string: “application/java-serialized-object”.

const z_loaned_encoding_t *z_encoding_application_openmetrics_text(void): An openmetrics data, commonly used by Prometheus. Constant alias for string: “application/openmetrics-text”.

const z_loaned_encoding_t *z_encoding_image_png(void): A Portable Network Graphics (PNG) image. Constant alias for string: “image/png”.

const z_loaned_encoding_t *z_encoding_image_jpeg(void): A Joint Photographic Experts Group (JPEG) image. Constant alias for string: “image/jpeg”.

const z_loaned_encoding_t *z_encoding_image_gif(void): A Graphics Interchange Format (GIF) image. Constant alias for string: “image/gif”.

const z_loaned_encoding_t *z_encoding_image_bmp(void): A BitMap (BMP) image. Constant alias for string: “image/bmp”.

const z_loaned_encoding_t *z_encoding_image_webp(void): A Web Portable (WebP) image. Constant alias for string: “image/webp”.

const z_loaned_encoding_t *z_encoding_application_xml(void): An XML file intended to be consumed by an application. Constant alias for string: “application/xml”.

const z_loaned_encoding_t *z_encoding_application_x_www_form_urlencoded(void): An encoded list of tuples, each consisting of a name and a value. Constant alias for string: “application/x-www-form-urlencoded”.

const z_loaned_encoding_t *z_encoding_text_html(void): An HTML file. Constant alias for string: “text/html”.

const z_loaned_encoding_t *z_encoding_text_xml(void): An XML file that is human-readable. Constant alias for string: “text/xml”.

const z_loaned_encoding_t *z_encoding_text_css(void): A CSS file. Constant alias for string: “text/css”.

const z_loaned_encoding_t *z_encoding_text_javascript(void): A JavaScript file. Constant alias for string: “text/javascript”.

const z_loaned_encoding_t *z_encoding_text_markdown(void): A Markdown file. Constant alias for string: “text/markdown”.

const z_loaned_encoding_t *z_encoding_text_csv(void): A CSV file. Constant alias for string: “text/csv”.

const z_loaned_encoding_t *z_encoding_application_sql(void): An application-specific SQL query. Constant alias for string: “application/sql”.

const z_loaned_encoding_t *z_encoding_application_coap_payload(void): Constrained Application Protocol (CoAP) data intended for CoAP-to-HTTP and HTTP-to-CoAP proxies. Constant alias for string: “application/coap-payload”.

const z_loaned_encoding_t *z_encoding_application_json_patch_json(void): Defines a JSON document structure for expressing a sequence of operations to apply to a JSON document. Constant alias for string: “application/json-patch+json”.

const z_loaned_encoding_t *z_encoding_application_json_seq(void): A JSON text sequence consists of any number of JSON texts, all encoded in UTF-8. Constant alias for string: “application/json-seq”.

const z_loaned_encoding_t *z_encoding_application_jsonpath(void): A JSONPath defines a string syntax for selecting and extracting JSON values from within a given JSON value. Constant alias for string: “application/jsonpath”.

const z_loaned_encoding_t *z_encoding_application_jwt(void): A JSON Web Token (JWT). Constant alias for string: “application/jwt”.

const z_loaned_encoding_t *z_encoding_application_mp4(void): An application-specific MPEG-4 encoded data, either audio or video. Constant alias for string: “application/mp4”.

const z_loaned_encoding_t *z_encoding_application_soap_xml(void): A SOAP 1.2 message serialized as XML 1.0. Constant alias for string: “application/soap+xml”.

const z_loaned_encoding_t *z_encoding_application_yang(void): A YANG-encoded data commonly used by the Network Configuration Protocol (NETCONF). Constant alias for string: “application/yang”.

const z_loaned_encoding_t *z_encoding_audio_aac(void): A MPEG-4 Advanced Audio Coding (AAC) media. Constant alias for string: “audio/aac”.

const z_loaned_encoding_t *z_encoding_audio_flac(void): A Free Lossless Audio Codec (FLAC) media. Constant alias for string: “audio/flac”.

const z_loaned_encoding_t *z_encoding_audio_mp4(void): An audio codec defined in MPEG-1, MPEG-2, MPEG-4, or registered at the MP4 registration authority. Constant alias for string: “audio/mp4”.

const z_loaned_encoding_t *z_encoding_audio_ogg(void): An Ogg-encapsulated audio stream. Constant alias for string: “audio/ogg”.

const z_loaned_encoding_t *z_encoding_audio_vorbis(void): A Vorbis-encoded audio stream. Constant alias for string: “audio/vorbis”.

const z_loaned_encoding_t *z_encoding_video_h261(void): A h261-encoded video stream. Constant alias for string: “video/h261”.

const z_loaned_encoding_t *z_encoding_video_h263(void): A h263-encoded video stream. Constant alias for string: “video/h263”.

const z_loaned_encoding_t *z_encoding_video_h264(void): A h264-encoded video stream. Constant alias for string: “video/h264”.

const z_loaned_encoding_t *z_encoding_video_h265(void): A h265-encoded video stream. Constant alias for string: “video/h265”.

const z_loaned_encoding_t *z_encoding_video_h266(void): A h266-encoded video stream. Constant alias for string: “video/h266”.

const z_loaned_encoding_t *z_encoding_video_mp4(void): A video codec defined in MPEG-1, MPEG-2, MPEG-4, or registered at the MP4 registration authority. Constant alias for string: “video/mp4”.

const z_loaned_encoding_t *z_encoding_video_ogg(void): An Ogg-encapsulated video stream. Constant alias for string: “video/ogg”.

const z_loaned_encoding_t *z_encoding_video_raw(void): An uncompressed, studio-quality video stream. Constant alias for string: “video/raw”.

const z_loaned_encoding_t *z_encoding_video_vp8(void): A VP8-encoded video stream. Constant alias for string: “video/vp8”.

const z_loaned_encoding_t *z_encoding_video_vp9(void): A VP9-encoded video stream. Constant alias for string: “video/vp9”.

Reply Error

Represents a Zenoh reply error value.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_reply_err_t

type z_loaned_reply_err_t

type z_moved_reply_err_t

Functions

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:

reply_err – Pointer to a z_loaned_reply_err_t to get data from.

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:

reply_err – Pointer to the z_loaned_reply_err_t to get the encoding from.

Returns:

Pointer to the encoding as a z_loaned_encoding_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_reply_err_drop(z_moved_reply_err_t *reply_err)

void z_reply_err_clone(z_owned_reply_err_t *dst, const z_loaned_reply_err_t *reply_err)

const z_loaned_reply_err_t *z_reply_err_loan(const z_owned_reply_err_t *reply_err)

z_loaned_reply_err_t *z_reply_err_loan_mut(z_owned_reply_err_t *reply_err)

z_result_t z_reply_err_take_from_loaned(z_owned_reply_err_t *dst, z_loaned_reply_err_t *src)

Sample

Represents a data sample.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_sample_t

type z_loaned_sample_t

type z_moved_sample_t

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.

Functions

const z_timestamp_t *z_sample_timestamp(const z_loaned_sample_t *sample)

Gets the timestamp of a sample by aliasing it.

Parameters:

sample – Pointer to a z_loaned_sample_t to get the timestamp from.

Returns:

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

const z_loaned_bytes_t *z_sample_attachment(const z_loaned_sample_t *sample)

Gets the attachment of a sample by aliasing it.

Parameters:

sample – Pointer to a z_loaned_sample_t to get the attachment from.

Returns:

Pointer to the attachment as a z_loaned_bytes_t.

const z_loaned_encoding_t *z_sample_encoding(const z_loaned_sample_t *sample)

Gets the encoding of a sample by aliasing it.

Parameters:

sample – Pointer to a z_loaned_sample_t to get the encoding from.

Returns:

The encoding wrapped as a z_loaned_encoding_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:

sample – Pointer to a z_loaned_sample_t to get the payload from.

Returns:

The payload wrapped as a z_loaned_bytes_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:

sample – Pointer to a z_loaned_sample_t to get the keyexpr from.

Returns:

The keyexpr wrapped as a z_loaned_keyexpr_t.

z_priority_t z_sample_priority(const z_loaned_sample_t *sample)

Gets sample qos priority value.

Parameters:

sample – Pointer to a z_loaned_sample_t to get the qos priority from.

Returns:

The priority wrapped as a z_priority_t.

z_congestion_control_t z_sample_congestion_control(const z_loaned_sample_t *sample)

Got a sample qos congestion control value.

Parameters:

sample – Pointer to a z_loaned_sample_t to get the congestion control from.

Returns:

The congestion control wrapped as a z_congestion_control_t.

bool z_sample_express(const z_loaned_sample_t *sample)

Got whether sample qos express flag was set or not.

Parameters:

sample – Pointer to a z_loaned_sample_t to get the express flag from.

Returns:

The express flag value.

z_reliability_t z_sample_reliability(const z_loaned_sample_t *sample)

Gets the reliability a sample was received with (unstable).

Parameters:

sample – Pointer to a z_loaned_sample_t to get the reliability from.

Returns:

The reliability wrapped as a z_reliability_t.

Warning

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

z_sample_kind_t z_sample_kind(const z_loaned_sample_t *sample)

Gets the kind of a sample by aliasing it.

Parameters:

sample – Pointer to a z_loaned_sample_t to get the kind from.

Returns:

The sample kind wrapped as a z_sample_kind_t.

const z_loaned_source_info_t *z_sample_source_info(const z_loaned_sample_t *sample)

Gets the source info for the sample (unstable).

Parameters:

sample – Pointer to a z_loaned_sample_t to get the source info from.

Returns:

The source info wrapped as a z_loaned_source_info_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_sample_drop(z_moved_sample_t *sample)

void z_sample_clone(z_owned_sample_t *dst, const z_loaned_sample_t *sample)

const z_loaned_sample_t *z_sample_loan(const z_owned_sample_t *sample)

z_loaned_sample_t *z_sample_loan_mut(z_owned_sample_t *sample)

z_result_t z_sample_take_from_loaned(z_owned_sample_t *dst, z_loaned_sample_t *src)

Timestamp

Types

type z_timestamp_t

Functions

z_id_t z_timestamp_id(const z_timestamp_t *ts)

Returns id associated with this timestamp.

Parameters:

ts – Pointer to the valid z_timestamp_t.

Returns:

Associated id represented by c:type:z_id_t

uint64_t z_timestamp_ntp64_time(const z_timestamp_t *ts)

Returns NTP64 time associated with this timestamp.

Parameters:

ts – Pointer to the valid z_timestamp_t.

Returns:

NTP64 time value

Entity Global ID

Represents an entity global id.

Types

type z_entity_global_id_t

Functions

z_result_t z_entity_global_id_new(z_entity_global_id_t *gid, const z_id_t *zid, uint32_t eid)

Creates an entity global id.

Parameters:

gid – An uninitialized z_entity_global_id_t.
zid – Pointer to a z_id_t zenoh id.
eid – uint32_t entity id.

uint32_t z_entity_global_id_eid(const z_entity_global_id_t *gid)

Returns the entity id of the entity global id.

Parameters:

gid – Pointer to the valid z_entity_global_id_t.

Returns:

Entity id represented by c:type:uint32_t.

z_id_t z_entity_global_id_zid(const z_entity_global_id_t *gid)

Returns the zenoh id of entity global id.

Parameters:

gid – Pointer to the valid z_entity_global_id_t.

Returns:

Zenoh id represented by c:type:z_id_t.

Source Info

Represents sample source information.

Types

type z_owned_source_info_t

type z_loaned_source_info_t

type z_moved_source_info_t

Functions

z_result_t z_source_info_new(z_owned_source_info_t *info, const z_entity_global_id_t *source_id, uint32_t source_sn)

Constructs a new source info.

Parameters:

info – An uninitialized z_owned_source_info_t.
source_id – Pointer to a z_entity_global_id_t global entity id.
source_sn – uint32_t sequence number.

Returns:

0 if construction is successful, negative value otherwise.

uint32_t z_source_info_sn(const z_loaned_source_info_t *info)

Returns the sequence number associated with this source info.

Parameters:

info – Pointer to the z_loaned_source_info_t to get the parameters from.

Returns:

uint32_t sequence number.

z_entity_global_id_t z_source_info_id(const z_loaned_source_info_t *info)

Returns the sequence number associated with this source info.

Parameters:

info – Pointer to the z_loaned_source_info_t to get the parameters from.

Returns:

Global entity ID as a z_entity_global_id_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_source_info_drop(z_moved_source_info_t *source_info)

void z_source_info_clone(z_owned_source_info_t *dst, const z_loaned_source_info_t *source_info)

const z_loaned_source_info_t *z_source_info_loan(const z_owned_source_info_t *source_info)

z_loaned_source_info_t *z_source_info_loan_mut(z_owned_source_info_t *source_info)

z_result_t z_source_info_take_from_loaned(z_owned_source_info_t *dst, z_loaned_source_info_t *src)

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.

There is no guarantee closures won’t 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.

Sample closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_sample_t

type z_loaned_closure_sample_t

type z_moved_closure_sample_t

typedef void (*z_closure_sample_callback_t)(z_loaned_sample_t *sample, void *arg);

Function pointer type for handling samples. Represents a callback function that is invoked when a sample is available for processing.

Parameters:

sample - Pointer to a z_loaned_sample_t representing the sample to be processed.
arg - A user-defined pointer to additional data that can be used during the processing of the sample.

Functions

z_result_t z_closure_sample(z_owned_closure_sample_t *closure, z_closure_sample_callback_t call, z_closure_drop_callback_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:

closure – Pointer to an uninitialized z_owned_closure_sample_t.
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:

0 in case of success, negative error code otherwise

void z_closure_sample_call(const z_loaned_closure_sample_t *closure, z_loaned_sample_t *sample)

Calls a sample closure.

Parameters:

closure – Pointer to the z_loaned_closure_sample_t to call.
sample – Pointer to the z_loaned_sample_t to pass to the closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_sample_t *z_closure_sample_loan(const z_owned_closure_sample_t *closure)

void z_closure_sample_drop(z_moved_closure_sample_t *closure)

Query closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_query_t

type z_loaned_closure_query_t

type z_moved_closure_query_t

typedef void (*z_closure_query_callback_t)(z_loaned_query_t *query, void *arg);

Function pointer type for handling queries. Represents a callback function that is invoked when a query is available for processing.

Parameters:

query - Pointer to a z_loaned_query_t representing the query to be processed.
arg - A user-defined pointer to additional data that can be used during the processing of the query.

Functions

z_result_t z_closure_query(z_owned_closure_query_t *closure, z_closure_query_callback_t call, z_closure_drop_callback_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:

closure – Pointer to an uninitialized z_owned_closure_query_t.
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:

0 in case of success, negative error code otherwise

void z_closure_query_call(const z_loaned_closure_query_t *closure, z_loaned_query_t *query)

Calls a query closure.

Parameters:

closure – Pointer to the z_loaned_closure_query_t to call.
query – Pointer to the z_loaned_query_t to pass to the closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_query_t *z_closure_query_loan(const z_owned_closure_query_t *closure)

void z_closure_query_drop(z_moved_closure_query_t *closure)

Reply closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_reply_t

type z_loaned_closure_reply_t

type z_moved_closure_reply_t

typedef void (*z_closure_reply_callback_t)(z_loaned_reply_t *reply, void *arg);

Function pointer type for handling replies. Represents a callback function that is invoked when a reply is available for processing.

Parameters:

reply - Pointer to a z_loaned_reply_t representing the reply to be processed.
arg - A user-defined pointer to additional data that can be used during the processing of the reply.

Functions

z_result_t z_closure_reply(z_owned_closure_reply_t *closure, z_closure_reply_callback_t call, z_closure_drop_callback_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:

closure – Pointer to an uninitialized z_owned_closure_reply_t.
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:

0 in case of success, negative error code otherwise

void z_closure_reply_call(const z_loaned_closure_reply_t *closure, z_loaned_reply_t *reply)

Calls a reply closure.

Parameters:

closure – Pointer to the z_loaned_closure_reply_t to call.
reply – Pointer to the z_loaned_reply_t to pass to the closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_reply_t *z_closure_reply_loan(const z_owned_closure_reply_t *closure)

void z_closure_reply_drop(z_moved_closure_reply_t *closure)

Hello closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_hello_t

type z_loaned_closure_hello_t

type z_moved_closure_hello_t

typedef void (*z_closure_hello_callback_t)(z_loaned_hello_t *hello, void *arg);

Function pointer type for handling scouting response. Represents a callback function that is invoked when a hello is available for processing.

Parameters:

hello - Pointer to a z_loaned_hello_t representing the hello to be processed.
arg - A user-defined pointer to additional data that can be used during the processing of the hello.

Functions

z_result_t z_closure_hello(z_owned_closure_hello_t *closure, z_closure_hello_callback_t call, z_closure_drop_callback_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:

closure – Pointer to an uninitialized z_owned_closure_hello_t.
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:

0 in case of success, negative error code otherwise

void z_closure_hello_call(const z_loaned_closure_hello_t *closure, z_loaned_hello_t *hello)

Calls a hello closure.

Parameters:

closure – Pointer to the z_loaned_closure_hello_t to call.
hello – Pointer to the z_loaned_hello_t to pass to the closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_hello_t *z_closure_hello_loan(const z_owned_closure_hello_t *closure)

void z_closure_hello_drop(z_moved_closure_hello_t *closure)

ID closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_zid_t

type z_loaned_closure_zid_t

type z_moved_closure_zid_t

typedef void (*z_closure_zid_callback_t)(const z_id_t *id, void *arg);

Function pointer type for handling Zenoh ID routers response. Represents a callback function that is invoked when a zid is available for processing.

Parameters:

zid - Pointer to a z_id_t representing the zid to be processed.
arg - A user-defined pointer to additional data that can be used during the processing of the zid.

Functions

z_result_t z_closure_zid(z_owned_closure_zid_t *closure, z_closure_zid_callback_t call, z_closure_drop_callback_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:

closure – Pointer to an uninitialized z_owned_closure_zid_t.
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:

0 in case of success, negative error code otherwise

void z_closure_zid_call(const z_loaned_closure_zid_t *closure, const z_id_t *id)

Calls a zid closure.

Parameters:

closure – Pointer to the z_loaned_closure_zid_t to call.
zid – Pointer to the z_id_t to pass to the closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_zid_t *z_closure_zid_loan(const z_owned_closure_zid_t *closure)

void z_closure_zid_drop(z_moved_closure_zid_t *closure)

Matching closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_matching_status_t

type z_loaned_closure_matching_status_t

type z_moved_closure_matching_status_t

typedef void (*z_closure_matching_status_callback_t)(z_matching_status_t *status, void *arg);

Function pointer type for handling matching status response. Represents a callback function that is invoked when a matching status was changed.

Parameters:

status - Pointer to a z_matching_status_t.
arg - A user-defined pointer to additional data that can be used during the processing of the matching status.

Functions

z_result_t z_closure_matching_status(z_owned_closure_matching_status_t *closure, z_closure_matching_status_callback_t call, z_closure_drop_callback_t drop, void *context)

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

Parameters:

closure – Pointer to an uninitialized z_owned_closure_matching_status_t.
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:

0 in case of success, negative error code otherwise

void z_closure_matching_status_call(const z_loaned_closure_matching_status_t *closure, const z_matching_status_t *status)

Calls a matching status closure.

Parameters:

closure – Pointer to the z_loaned_closure_matching_status_t to call.
status – Pointer to the z_matching_status_t to pass to the closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_matching_status_t *z_closure_matching_status_loan(const z_owned_closure_matching_status_t *closure)

void z_closure_matching_status_drop(z_moved_closure_matching_status_t *closure)

Channels

The concept of channels and handlers revolves around managing communication between different components using two types of channels: FIFO (First-In-First-Out) and Ring Buffers. These channels support handling various item types such as sample, reply, and query, with distinct methods available for each.

The FIFO channel ensures that data is received in the order it was sent. It supports blocking and non-blocking (try) reception of data. If the channel is dropped, the handlers transition into a “gravestone” state, signifying that no more data will be sent or received.

The Ring channel differs from FIFO in that data is overwritten if the buffer is full, but it still supports blocking and non-blocking reception of data. As with the FIFO channel, the handler can be dropped, resetting it to a gravestone state.

The methods common for all channles:

z_yyy_channel_xxx_new: Constructs the send and receive ends of the yyy (fifo or ring) channel for items type xxx.
z_yyy_handler_xxx_recv: Receives an item from the channel (blocking). If no more items are available or the channel is dropped, the item transitions to the gravestone state.
z_yyy_handler_xxx_try_recv: Attempts to receive an item immediately (non-blocking). Returns a gravestone state if no data is available.
z_yyy_handler_xxx_loan: Borrows the handler for access.
z_yyy_handler_xxx_drop: Drops the the handler, setting it to a gravestone state.

Sample channel

Types

See details at Owned Types z_owned_xxx_t

type z_owned_fifo_handler_sample_t

type z_loaned_fifo_handler_sample_t

type z_owned_ring_handler_sample_t

type z_loaned_ring_handler_sample_t

Methods

void z_fifo_channel_sample_new(z_owned_closure_sample_t *callback, z_owned_fifo_handler_sample_t *handler, size_t capacity)

void z_ring_channel_sample_new(z_owned_closure_sample_t *callback, z_owned_ring_handler_sample_t *handler, size_t capacity)

See details at Channels

z_result_t z_fifo_handler_sample_recv(const z_loaned_fifo_handler_sample_t *handler, z_owned_sample_t *sample)

z_result_t z_fifo_handler_sample_try_recv(const z_loaned_fifo_handler_sample_t *handler, z_owned_sample_t *sample)

z_result_t z_ring_handler_sample_recv(const z_loaned_ring_handler_sample_t *handler, z_owned_sample_t *sample)

z_result_t z_ring_handler_sample_try_recv(const z_loaned_ring_handler_sample_t *handler, z_owned_sample_t *sample)

See details at Channels

const z_loaned_fifo_handler_sample_t *z_fifo_handler_sample_loan(const z_owned_fifo_handler_sample_t *handler)

void z_fifo_handler_sample_drop(z_moved_fifo_handler_sample_t *handler)

const z_loaned_ring_handler_sample_t *z_ring_handler_sample_loan(const z_owned_ring_handler_sample_t *handler)

void z_ring_handler_sample_drop(z_moved_ring_handler_sample_t *handler)

See details at Owned Types z_owned_xxx_t

Query channel

Types

See details at Owned Types z_owned_xxx_t

type z_owned_fifo_handler_query_t

type z_loaned_fifo_handler_query_t

type z_owned_ring_handler_query_t

type z_loaned_ring_handler_query_t

Methods

void z_fifo_channel_query_new(z_owned_closure_query_t *callback, z_owned_fifo_handler_query_t *handler, size_t capacity)

void z_ring_channel_query_new(z_owned_closure_query_t *callback, z_owned_ring_handler_query_t *handler, size_t capacity)

See details at Channels

z_result_t z_fifo_handler_query_recv(const z_loaned_fifo_handler_query_t *handler, z_owned_query_t *query)

z_result_t z_fifo_handler_query_try_recv(const z_loaned_fifo_handler_query_t *handler, z_owned_query_t *query)

z_result_t z_ring_handler_query_recv(const z_loaned_ring_handler_query_t *handler, z_owned_query_t *query)

z_result_t z_ring_handler_query_try_recv(const z_loaned_ring_handler_query_t *handler, z_owned_query_t *query)

See details at Channels

const z_loaned_fifo_handler_query_t *z_fifo_handler_query_loan(const z_owned_fifo_handler_query_t *handler)

void z_fifo_handler_query_drop(z_moved_fifo_handler_query_t *handler)

const z_loaned_ring_handler_query_t *z_ring_handler_query_loan(const z_owned_ring_handler_query_t *handler)

void z_ring_handler_query_drop(z_moved_ring_handler_query_t *handler)

See details at Owned Types z_owned_xxx_t

Reply channel

Types

See details at Owned Types z_owned_xxx_t

type z_owned_fifo_handler_reply_t

type z_loaned_fifo_handler_reply_t

type z_owned_ring_handler_reply_t

type z_loaned_ring_handler_reply_t

Methods

void z_fifo_channel_reply_new(z_owned_closure_reply_t *callback, z_owned_fifo_handler_reply_t *handler, size_t capacity)

void z_ring_channel_reply_new(z_owned_closure_reply_t *callback, z_owned_ring_handler_reply_t *handler, size_t capacity)

See details at Channels

z_result_t z_fifo_handler_reply_recv(const z_loaned_fifo_handler_reply_t *handler, z_owned_reply_t *reply)

z_result_t z_fifo_handler_reply_try_recv(const z_loaned_fifo_handler_reply_t *handler, z_owned_reply_t *reply)

z_result_t z_ring_handler_reply_recv(const z_loaned_ring_handler_reply_t *handler, z_owned_reply_t *reply)

z_result_t z_ring_handler_reply_try_recv(const z_loaned_ring_handler_reply_t *handler, z_owned_reply_t *reply)

See details at Channels

const z_loaned_fifo_handler_reply_t *z_fifo_handler_reply_loan(const z_owned_fifo_handler_reply_t *handler)

void z_fifo_handler_reply_drop(z_moved_fifo_handler_reply_t *handler)

const z_loaned_ring_handler_reply_t *z_ring_handler_reply_loan(const z_owned_ring_handler_reply_t *handler)

void z_ring_handler_reply_drop(z_moved_ring_handler_reply_t *handler)

See details at Owned Types z_owned_xxx_t

System

Random

Functions

Sleep

Functions

Time

Types

type z_time_t

A time value that is accurate to the nearest microsecond but also has a range of years.

type z_clock_t

This is like a z_time_t but has nanoseconds instead of microseconds.

Functions

Mutex

Types

Represents a mutual exclusion (mutex) object used to ensure exclusive access to shared resources.

See details at Owned Types z_owned_xxx_t

type z_owned_mutex_t

type z_loaned_mutex_t

type z_moved_mutex_t

Functions

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_mutex_drop(z_moved_mutex_t *mutex)

z_loaned_mutex_t *z_mutex_loan_mut(z_owned_mutex_t *mutex)

Conditional Variable

Types

Represents a condition variable, which is a synchronization primitive that allows threads to wait until a particular condition occurs.

A condition variable is used in conjunction with mutexes to enable threads to wait for signals from other threads. When a thread calls the wait function on a condition variable, it releases the associated mutex and enters a wait state until another thread signals the condition variable.

See details at Owned Types z_owned_xxx_t

type z_owned_condvar_t

type z_loaned_condvar_t

type z_moved_condvar_t

Functions

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_condvar_drop(z_moved_condvar_t *condvar)

const z_loaned_condvar_t *z_condvar_loan(const z_owned_condvar_t *condvar)

Task

Types

Represents a task that can be executed by a thread.

A task is an abstraction for encapsulating a unit of work that can be scheduled and executed by a thread. Tasks are typically used to represent asynchronous operations, allowing the program to perform multiple operations concurrently.

type z_owned_task_t

type z_moved_task_t

Functions

Session

Session configuration

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

Types

See details at Owned Types z_owned_xxx_t

type z_owned_config_t

type z_loaned_config_t

type z_moved_config_t

Functions

z_result_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:

config – Pointer to uninitialized z_owned_config_t.

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.

z_result_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 is successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_config_drop(z_moved_config_t *config)

void z_config_clone(z_owned_config_t *dst, const z_loaned_config_t *config)

const z_loaned_config_t *z_config_loan(const z_owned_config_t *config)

z_loaned_config_t *z_config_loan_mut(z_owned_config_t *config)

Session management

Represents a Zenoh Session.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_session_t

type z_loaned_session_t

type z_moved_session_t

type z_id_t

Functions

z_result_t z_open(z_owned_session_t *zs, z_moved_config_t *config, const z_open_options_t *options)

Opens a Zenoh session.

Parameters:

zs – Pointer to an uninitialized z_owned_session_t to store the session info.
config – Moved z_owned_config_t to configure the session with.
options – Pointer to a z_open_options_t to configure the operation.

Returns:

0 if open is successful, negative value otherwise.

z_result_t z_close(z_loaned_session_t *zs, const z_close_options_t *options)

Closes a Zenoh session.

Parameters:

zs – Loaned z_owned_session_t to close.
options – Pointer to a z_close_options_t to configure the operation.

Returns:

0 if close is successful, negative value otherwise.

bool z_session_is_closed(const z_loaned_session_t *zs)

Checks if Zenoh session is closed.

Parameters:

zs – Loaned z_owned_session_t.

Returns:

true if session is closed, false 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:

zs – Pointer to a z_loaned_session_t to get the id from.

Returns:

The local Zenoh ID of the session as z_id_t.

z_result_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 was successfully triggered, negative value otherwise.

z_result_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 was successfully triggered, negative value otherwise.

z_result_t z_id_to_string(const z_id_t *id, z_owned_string_t *str)

Converts a Zenoh ID into a string for print purposes.

Parameters:

id – Pointer to the id to convert.
str – Pointer to uninitialized z_owned_string_t to store the string.

Returns:

0 if operation is successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_session_t *z_session_loan(const z_owned_session_t *closure)

void z_session_drop(z_moved_session_t *closure)

Matching

Types

See details at Owned Types z_owned_xxx_t

type z_owned_matching_listener_t

type z_loaned_matching_listener_t

type z_moved_matching_listener_t

typedef int z_matching_status_t

A struct that indicates if there exist Subscribers matching the Publisher’s key expression or Queryables matching Querier’s key expression and target.

bool matching: true if there exist matching Zenoh entities, false otherwise.

Functions

z_result_t z_undeclare_matching_listener(z_moved_matching_listener_t *listener)

Undeclares the matching listener.

Parameters:

listener – Moved z_owned_matching_listener_t to undeclare.

Returns:

0 if undeclare is successful, negative value otherwise.

Publication

Represents a Zenoh Publisher entity.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_publisher_t

type z_loaned_publisher_t

type z_moved_publisher_t

Option Types

type z_put_options_t

Represents the configuration used to configure a put operation sent 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.

z_reliability_t reliability: The reliability that should be used to transmit the data (unstable).

z_moved_source_info_t *source_info: The source info for the message (unstable).

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

z_reliability_t reliability: The reliability that should be used to transmit the data (unstable).

z_moved_source_info_t *source_info: The source info for the message (unstable).

type z_publisher_options_t

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

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

z_reliability_t reliability: The reliability that should be used to transmit the data (unstable).

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.

z_moved_source_info_t *source_info: The source info for the message (unstable).

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

z_moved_source_info_t *source_info: The source info for the message (unstable).

Constants

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_reliability_t

Reliability values.

enumerator Z_RELIABILITY_BEST_EFFORT: Defines reliability as BEST_EFFORT

enumerator Z_RELIABILITY_RELIABLE: Defines reliability as RELIABLE

Warning

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

Functions

z_result_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:

zs – Pointer to a z_loaned_session_t to put the data through.
keyexpr – Pointer to a z_loaned_keyexpr_t to put the data for.
payload – Moved z_owned_bytes_t containing the data to put.
options – Pointer to a z_put_options_t to configure the operation.

Returns:

0 if put operation is successful, negative value otherwise.

z_result_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:

zs – Pointer to a z_loaned_session_t to delete the data through.
keyexpr – Pointer to a z_loaned_keyexpr_t to delete the data for.
options – Pointer to a z_delete_options_t to configure the operation.

Returns:

0 if delete operation is successful, negative value otherwise.

z_result_t z_declare_publisher(const z_loaned_session_t *zs, z_owned_publisher_t *pub, 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:

zs – Pointer to a z_loaned_session_t to declare the publisher through.
pub – Pointer to an uninitialized z_owned_publisher_t.
keyexpr – Pointer to a z_loaned_keyexpr_t to bind the publisher with.
options – Pointer to a z_publisher_options_t to configure the operation.

Returns:

0 if declare is successful, negative value otherwise.

z_result_t z_undeclare_publisher(z_moved_publisher_t *pub)

Undeclares the publisher.

Parameters:

pub – Moved z_owned_publisher_t to undeclare.

Returns:

0 if undeclare is successful, negative value otherwise.

z_result_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:

pub – Pointer to a z_loaned_publisher_t from where to put the data.
payload – Moved z_owned_bytes_t containing the data to put.
options – Pointer to a z_publisher_put_options_t to configure the operation.

Returns:

0 if put operation is successful, negative value otherwise.

z_result_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:

pub – Pointer to a z_loaned_publisher_t from where to delete the data.
options – Pointer to a z_publisher_delete_options_t to configure the delete operation.

Returns:

0 if delete operation is successful, negative value otherwise.

const z_loaned_keyexpr_t *z_publisher_keyexpr(const z_loaned_publisher_t *publisher)

Gets the keyexpr from a publisher.

Parameters:

publisher – Pointer to a z_loaned_publisher_t to get the keyexpr from.

Returns:

The keyexpr wrapped as a z_loaned_keyexpr_t.

void z_put_options_default(z_put_options_t *options)

Builds a z_put_options_t with default values.

Parameters:

options – 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.

Parameters:

options – Pointer to an uninitialized z_delete_options_t.

void z_publisher_options_default(z_publisher_options_t *options)

Builds a z_publisher_options_t with default values.

Parameters:

options – Pointer to an uninitialized z_delete_options_t.

void z_publisher_put_options_default(z_publisher_put_options_t *options)

Builds a z_publisher_put_options_t with default values.

Parameters:

options – Pointer to an uninitialized z_publisher_put_options_t.

void z_publisher_delete_options_default(z_publisher_delete_options_t *options)

Builds a z_publisher_delete_options_t with default values.

Parameters:

options – Pointer to an uninitialized z_publisher_delete_options_t.

z_reliability_t z_reliability_default(void)

Gets the default reliability value (unstable).

Returns:: The reliability wrapped as a z_reliability_t.

Warning

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

z_result_t z_publisher_get_matching_status(const z_loaned_publisher_t *publisher, z_matching_status_t *matching_status)

Gets publisher matching status - i.e. if there are any subscribers matching its key expression.

Returns:: 0 if execution was successful, negative value otherwise.

Warning

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

z_result_t z_publisher_declare_matching_listener(const z_loaned_publisher_t *publisher, z_owned_matching_listener_t *matching_listener, z_moved_closure_matching_status_t *callback)

Constructs matching listener, registering a callback for notifying subscribers matching with a given publisher.

Parameters:

publisher – A publisher to associate with matching listener.
matching_listener – An uninitialized memory location where matching listener will be constructed. The matching

listener’s callback will be automatically dropped when the publisher is dropped. callback: A closure that will be called every time the matching status of the publisher changes (If last subscriber disconnects or when the first subscriber connects).

Returns:: 0 if execution was successful, negative value otherwise.

Warning

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

z_result_t z_publisher_declare_background_matching_listener(const z_loaned_publisher_t *publisher, z_moved_closure_matching_status_t *callback)

Declares a matching listener, registering a callback for notifying subscribers matching with a given publisher. The callback will be run in the background until the corresponding publisher is dropped.

Parameters:

publisher – A publisher to associate with matching listener.
callback – A closure that will be called every time the matching status of the publisher changes (If last subscriber

disconnects or when the first subscriber connects).

Returns:: 0 if execution was successful, negative value otherwise.

Warning

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

z_entity_global_id_t z_publisher_id(const z_loaned_publisher_t *publisher)

Gets the entity global Id from a publisher.

Parameters:

publisher – Pointer to a z_loaned_publisher_t to get the entity global Id from.

Returns:

The entity gloabl Id wrapped as a z_entity_global_global_id_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_publisher_t *z_publisher_loan(const z_owned_publisher_t *closure)

void z_publisher_drop(z_moved_publisher_t *closure)

Subscription

Types

Represents a Zenoh Subscriber entity. See details at Owned Types z_owned_xxx_t

type z_owned_subscriber_t

type z_loaned_subscriber_t

type z_moved_subscriber_t

Option Types

type z_subscriber_options_t: Represents the configuration used to configure a subscriber upon declaration z_declare_subscriber().

Functions

z_result_t z_declare_subscriber(const z_loaned_session_t *zs, z_owned_subscriber_t *sub, 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. Note that dropping subscriber drops its callback.

Parameters:

zs – Pointer to a z_loaned_session_t to declare the subscriber through.
sub – Pointer to a z_owned_subscriber_t to contain the subscriber.
keyexpr – Pointer to a z_loaned_keyexpr_t to bind the subscriber with.
callback – Pointer to a`z_owned_closure_sample_t` callback.
options – Pointer to a z_subscriber_options_t to configure the operation

Returns:

0 if declare is successful, negative value otherwise.

z_result_t z_undeclare_subscriber(z_moved_subscriber_t *pub)

Undeclares the subscriber.

Parameters:

pub – Moved z_owned_subscriber_t to undeclare.

Returns:

0 if undeclare is successful, negative value otherwise.

z_result_t z_declare_background_subscriber(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 background subscriber for a given keyexpr. Subscriber callback will be called to process the messages, until the corresponding session is closed or dropped.

Parameters:

zs – Pointer to a z_loaned_session_t to declare the subscriber through.
keyexpr – Pointer to a z_loaned_keyexpr_t to bind the subscriber with.
callback – Pointer to a`z_owned_closure_sample_t` callback.
options – Pointer to a z_subscriber_options_t to configure the operation

Returns:

0 if declare is successful, negative value otherwise.

void z_subscriber_options_default(z_subscriber_options_t *options)

Builds a z_subscriber_options_t with default values.

Parameters:

options – Pointer to an uninitialized z_subscriber_options_t.

const z_loaned_keyexpr_t *z_subscriber_keyexpr(const z_loaned_subscriber_t *subscriber)

Gets the keyexpr from a subscriber.

Parameters:

subscriber – Pointer to a z_loaned_subscriber_t to get the keyexpr from.

Returns:

The keyexpr wrapped as a z_loaned_keyexpr_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_subscriber_t *z_subscriber_loan(const z_owned_subscriber_t *closure)

void z_subscriber_drop(z_moved_subscriber_t *closure)

Queryable

Types

Represents a Zenoh Queryable entity. See details at Owned Types z_owned_xxx_t

type z_owned_queryable_t

type z_loaned_queryable_t

type z_moved_queryable_t

Represents a Zenoh Query entity, received by Zenoh queryable entities. See details at Owned Types z_owned_xxx_t

type z_owned_query_t

type z_loaned_query_t

type z_moved_query_t

Option Types

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 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_query_reply_err_options_t

Represents the configuration used to configure a query reply error sent via z_query_reply_err().

z_moved_encoding_t *encoding: The encoding of the payload.

type z_query_reply_del_options_t

Represents the configuration used to configure a query reply delete sent via z_query_reply_del().

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.

Functions

z_result_t z_declare_queryable(const z_loaned_session_t *zs, z_owned_queryable_t *queryable, 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. Note that dropping queryable drops its callback.

Parameters:

zs – Pointer to a z_loaned_session_t to declare the subscriber through.
queryable – Pointer to an uninitialized z_owned_queryable_t to contain the queryable.
keyexpr – Pointer to a z_loaned_keyexpr_t to bind the subscriber with.
callback – Pointer to a z_owned_closure_query_t callback.
options – Pointer to a z_queryable_options_t to configure the declare.

Returns:

0 if declare operation is successful, negative value otherwise.

z_result_t z_undeclare_queryable(z_moved_queryable_t *pub)

Undeclares the queryable.

Parameters:

pub – Moved z_owned_queryable_t to undeclare.

Returns:

0 if undeclare is successful, negative value otherwise.

z_result_t z_declare_background_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 background queryable for a given keyexpr. The queryable callback will be called to proccess incoming queries until the corresponding session is closed or dropped.

Parameters:

zs – Pointer to a z_loaned_session_t to declare the subscriber through.
keyexpr – Pointer to a z_loaned_keyexpr_t to bind the subscriber with.
callback – Pointer to a z_owned_closure_query_t callback.
options – Pointer to a z_queryable_options_t to configure the declare.

Returns:

0 if declare operation is successful, negative value otherwise.

z_entity_global_id_t z_queryable_id(const z_loaned_queryable_t *queryable)

Gets the entity global Id from a queryable.

Parameters:

publisher – Pointer to a z_loaned_queryable_t to get the entity global Id from.

Returns:

The entity gloabl Id wrapped as a z_loaned_queryable_t.

void z_queryable_options_default(z_queryable_options_t *options)

Builds a z_queryable_options_t with default values.

Parameters:

options – Pointer to an uninitialized z_queryable_options_t.

void z_query_reply_options_default(z_query_reply_options_t *options)

Builds a z_query_reply_options_t with default values.

Parameters:

options – Pointer to an uninitialized z_query_reply_options_t.

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.

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.

const z_loaned_keyexpr_t *z_query_keyexpr(const z_loaned_query_t *query)

Gets a query keyexpr by aliasing it.

Parameters:

query – Pointer to the z_loaned_query_t to get the keyexpr from.

Returns:

The keyexpr wrapped as a:c:type:z_keyexpr_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:

query – Pointer to the z_loaned_query_t to get the value from.

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:

query – Pointer to the z_loaned_query_t to get the value from.

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:

query – Pointer to the z_loaned_query_t to get the attachment from.

Returns:

Pointer to the attachment as a z_loaned_bytes_t.

z_result_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:

query – Pointer to a z_loaned_query_t to reply.
keyexpr – Pointer to a z_loaned_keyexpr_t to bind the reply with.
payload – Pointer to the reply data.
options – Pointer to a z_query_reply_options_t to configure the reply.

Returns:

0 if reply operation is successful, negative value otherwise.

z_result_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 is successful, negative value otherwise.

z_result_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 is successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_queryable_drop(z_moved_queryable_t *closure)

const z_loaned_queryable_t *z_queryable_loan(const z_owned_queryable_t *closure)

void z_query_drop(z_moved_query_t *query)

void z_query_clone(z_owned_query_t *dst, const z_loaned_query_t *query)

const z_loaned_query_t *z_query_loan(const z_owned_query_t *query)

z_loaned_query_t *z_query_loan_mut(z_owned_query_t *query)

z_result_t z_query_take_from_loaned(z_owned_query_t *dst, z_loaned_query_t *src)

Query

Types

Represents the reply to a query. See details at Owned Types z_owned_xxx_t

type z_owned_reply_t

type z_loaned_reply_t

type z_moved_reply_t

Option Types

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.

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.

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.

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

Functions

z_result_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 is successful, negative value otherwise.

void z_get_options_default(z_get_options_t *options)

Builds a z_get_options_t with default values.

Parameters:

options – Pointer to an uninitialized z_get_options_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_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_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.

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_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_target_t z_query_target_default(void)

Builds a default query target.

Returns:: The constructed z_query_target_t.

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:

reply – Pointer to a z_loaned_reply_t to check.

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:

reply – Pointer to a z_loaned_reply_t to get content from.

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:

reply – Pointer to a z_loaned_reply_t to get content from.

Returns:

The error reply content wrapped as a z_loaned_reply_err_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_reply_drop(z_moved_reply_t *reply)

void z_reply_clone(z_owned_reply_t *dst, const z_loaned_reply_t *reply)

const z_loaned_reply_t *z_reply_loan(const z_owned_reply_t *reply)

z_loaned_reply_t *z_reply_loan_mut(z_owned_reply_t *reply)

z_result_t z_reply_take_from_loaned(z_owned_reply_t *dst, z_loaned_reply_t *src)

Querier

Represents a Zenoh Querier entity.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_querier_t

type z_loaned_querier_t

type z_moved_querier_t

Option Types

type z_querier_options_t

Options passed to the z_declare_querier() function.

z_moved_encoding_t *encoding: Default encoding for values sent by this querier.

z_query_target_t target: The Queryables that should be target of the querier queries.

z_query_consolidation_t consolidation: The replies consolidation strategy to apply on replies to the querier queries.

z_congestion_control_t congestion_control: The congestion control to apply when routing the querier queries.

bool is_express: If set to true, the querier queries will not be batched. This usually has a positive impact on latency but negative impact on throughput.

z_priority_t priority: The priority of the querier queries.

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

type z_querier_get_options_t

Options passed to the z_querier_get() function.

z_moved_bytes_t *payload: An optional payload to attach to the query.

z_moved_encoding_t *encoding: An optional encoding of the query payload and or attachment.

z_moved_bytes_t *attachment: An optional attachment to attach to the query.

Constants

Functions

z_result_t z_declare_querier(const z_loaned_session_t *zs, z_owned_querier_t *querier, const z_loaned_keyexpr_t *keyexpr, z_querier_options_t *options)

Constructs and declares a querier on the given key expression.

The queries can be send with the help of the z_querier_get() function.

Parameters:

zs – The Zenoh session.
querier – An uninitialized location in memory where querier will be constructed.
keyexpr – The key expression to send queries on.
options – Additional options for the querier.

Returns:

0 if put operation is successful, negative value otherwise.

Warning

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

z_result_t z_undeclare_querier(z_moved_querier_t *querier): Frees memory and resets querier to its gravestone state.

z_result_t z_querier_get(const z_loaned_querier_t *querier, const char *parameters, z_moved_closure_reply_t *callback, z_querier_get_options_t *options)

Query data from the matching queryables in the system.

Replies are provided through a callback function.

Parameters:

querier – The querier to make query from.
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. It will be automatically dropped once all replies are processed.
options – Additional options for the get. All owned fields will be consumed.

Returns:

0 if put operation is successful, negative value otherwise.

Warning

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

const z_loaned_keyexpr_t *z_querier_keyexpr(const z_loaned_querier_t *querier): Returns the key expression of the querier.

Warning

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

z_result_t z_querier_get_matching_status(const z_loaned_querier_t *querier, z_matching_status_t *matching_status)

Gets querier matching status - i.e. if there are any queryables matching its key expression and target.

Returns:: 0 if put operation is successful, negative value otherwise.

Warning

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

z_result_t z_querier_declare_matching_listener(const z_loaned_querier_t *querier, z_owned_matching_listener_t *matching_listener, z_moved_closure_matching_status_t *callback)

Constructs matching listener, registering a callback for notifying queryables matching with a given querier’s key expression and target.

Parameters:

querier – A querier to associate with matching listener.
matching_listener – An uninitialized memory location where matching listener will be constructed. The matching listener’s callback will be automatically dropped when the querier is dropped.
callback – A closure that will be called every time the matching status of the querier changes (If last queryable disconnects or when the first queryable connects).

Returns:

0 if put operation is successful, negative value otherwise.

Warning

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

z_result_t z_querier_declare_background_matching_listener(const z_loaned_querier_t *querier, z_moved_closure_matching_status_t *callback)

Declares a matching listener, registering a callback for notifying queryables matching the given querier key expression and target. The callback will be run in the background until the corresponding querier is dropped.

Parameters:

querier – A querier to associate with matching listener.
callback – A closure that will be called every time the matching status of the querier changes (If last queryable disconnects or when the first queryable connects).

Returns:

0 if put operation is successful, negative value otherwise.

Warning

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

z_entity_global_id_t z_querier_id(const z_loaned_querier_t *querier)

Gets the entity global Id from a querier.

Parameters:

publisher – Pointer to a z_loaned_querier_t to get the entity global Id from.

Returns:

The entity gloabl Id wrapped as a z_entity_global_global_id_t.

void z_querier_options_default(z_querier_options_t *options): Constructs the default value for z_querier_options_t.

Warning

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

void z_querier_get_options_default(z_querier_get_options_t *options): Constructs the default value for z_querier_get_options_t.

Warning

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

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_querier_t *z_querier_loan(const z_owned_querier_t *closure)

void z_querier_drop(z_moved_querier_t *closure)

Scouting

Types

Represents the content of a hello message returned by a zenoh entity as a reply to a scout message. See details at Owned Types z_owned_xxx_t

type z_owned_hello_t

type z_loaned_hello_t

type z_moved_hello_t

Option Types

type z_scout_options_t

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

uint64_t timeout_ms: The maximum duration in ms the scouting can take.

z_what_t what: Type of entities to scout for.

Functions

z_result_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 was successfully triggered, negative value otherwise.

z_whatami_t z_hello_whatami(const z_loaned_hello_t *hello)

Returns type of Zenoh entity that transmitted hello message.

Parameters:

hello – Pointer to a z_loaned_hello_t message.

Returns:

Type of the Zenoh entity that transmitted hello message.

void z_hello_locators(const z_loaned_hello_t *hello, z_owned_string_array_t *locators_out)

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

Note that it is a method for zenoh-c compatiblity, in zenoh-pico zp_hello_locators() can be used.

Parameters:

hello – Pointer to a z_loaned_hello_t message.
locators_out – An uninitialized memory location where z_owned_string_array_t will be constructed.

const z_loaned_string_array_t *zp_hello_locators(const z_loaned_hello_t *hello)

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

Parameters:

hello – Pointer to a z_loaned_hello_t message.

Returns:

z_loaned_string_array_t containing locators.

z_id_t z_hello_zid(const z_loaned_hello_t *hello)

Returns id of Zenoh entity that transmitted hello message.

Parameters:

hello – Pointer to a z_loaned_hello_t message.

Returns:

Id of the Zenoh entity that transmitted hello message.

z_result_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).

Parameters:

whatami – A whatami bitmask of zenoh entity kind.
str_out – An uninitialized memory location where strring will be constructed.

Returns:

0 in case of success, negative value otherwise.

void z_scout_options_default(z_scout_options_t *options)

Builds a z_scout_options_t with default value.

Parameters:

options – Pointer to an uninitialized z_scout_options_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_hello_drop(z_moved_hello_t *hello)

void z_hello_clone(z_owned_hello_t *dst, const z_loaned_hello_t *hello)

const z_loaned_hello_t *z_hello_loan(const z_owned_hello_t *hello)

z_loaned_hello_t *z_hello_loan(z_owned_hello_t *hello)

z_result_t z_hello_take_from_loaned(z_owned_hello_t *dst, z_loaned_hello_t *src)

Serialization

Types

Represents a data serializer (unstable). See details at Owned Types z_owned_xxx_t

type ze_owned_serializer_t

type ze_loaned_serializer_t

type ze_moved_serializer_t

type ze_deserializer_t: Represents a reader for serialized data.

Functions

ze_deserializer_t ze_deserializer_from_bytes(const z_loaned_bytes_t *bytes)

Returns a deserializer for z_loaned_bytes_t.

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

Parameters:

bytes – Data to deserialize.

Returns:

The constructed ze_deserializer_t.

static inline z_result_t ze_deserializer_deserialize_int8(ze_deserializer_t *deserializer, int8_t *val)

Deserializes next portion of data into a int8_t.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized int8_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_int16(ze_deserializer_t *deserializer, int16_t *val)

Deserializes next portion of data into a int16_t.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized int16_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_int32(ze_deserializer_t *deserializer, int32_t *val)

Deserializes next portion of data into a int32_t.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized int32_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_int64(ze_deserializer_t *deserializer, int64_t *val)

Deserializes next portion of data into a int64_t.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized int64_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_uint8(ze_deserializer_t *deserializer, uint8_t *val)

Deserializes next portion of data into a uint8_t.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized uint8_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_uint16(ze_deserializer_t *deserializer, uint16_t *val)

Deserializes next portion of data into a uint16_t.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized uint16_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_uint32(ze_deserializer_t *deserializer, uint32_t *val)

Deserializes next portion of data into a uint32_t.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized uint32_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_uint64(ze_deserializer_t *deserializer, uint64_t *val)

Deserializes next portion of data into a uint64_t.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized uint64_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_float(ze_deserializer_t *deserializer, float *val)

Deserializes next portion of data into a float.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized float to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_double(ze_deserializer_t *deserializer, double *val)

Deserializes next portion of data into a double.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized double to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

static inline z_result_t ze_deserializer_deserialize_bool(ze_deserializer_t *deserializer, bool *val)

Deserializes next portion of data into a bool.

Parameters:

deserializer – A deserializer instance.
dst – Pointer to an uninitialized bool to contain the deserialized value.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserializer_deserialize_slice(ze_deserializer_t *deserializer, z_owned_slice_t *val)

Deserializes next portion of data and advances the reader position.

Parameters:

deserializer – A deserializer instance.
val – Pointer to an uninitialized z_owned_slice_t to contain the deserialized slice.

Returns:

0 if deserialization is successful, or a negative value otherwise.

z_result_t ze_deserializer_deserialize_string(ze_deserializer_t *deserializer, z_owned_string_t *val)

Deserializes next portion of data and advances the reader position.

Parameters:

deserializer – A deserializer instance.
val – Pointer to an uninitialized z_owned_string_t to contain the deserialized string.

Returns:

0 if deserialization is successful, or a negative value otherwise.

z_result_t ze_deserializer_deserialize_sequence_length(ze_deserializer_t *deserializer, size_t *len)

Initiate deserialization of a sequence of multiple elements.

Parameters:

deserializer – A deserializer instance.
len – A pointer where the length of the sequence (previously passed via ze_serializer_serialize_sequence_length()) will be written.

Returns:

0 if deserialization is successful, or a negative value otherwise.

z_result_t ze_serializer_empty(ze_owned_serializer_t *serializer)

Constructs an empty serializer.

Parameters:

serializer – An uninitialized memory location where serializer is to be constructed.

Returns:

0 in case of success, negative value otherwise.

void ze_serializer_finish(ze_moved_serializer_t *serializer, z_owned_bytes_t *bytes)

Finishes serialization and returns underlying bytes.

Parameters:

serializer – A data serializer.
bytes – An uninitialized memory location where bytes is to be constructed.

static inline z_result_t ze_serializer_serialize_int8(ze_loaned_serializer_t *serializer, int8_t val)

Writes a serialized int8_t into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – int8_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_int16(ze_loaned_serializer_t *serializer, int16_t val)

Writes a serialized int16_t into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – int16_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_int32(ze_loaned_serializer_t *serializer, int32_t val)

Writes a serialized int32_t into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – int32_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_int64(ze_loaned_serializer_t *serializer, int64_t val)

Writes a serialized int64_t into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – int64_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_uint8(ze_loaned_serializer_t *serializer, uint8_t val)

Writes a serialized uint8_t into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – uint8_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_uint16(ze_loaned_serializer_t *serializer, uint16_t val)

Writes a serialized uint16_t into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – uint16_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_uint32(ze_loaned_serializer_t *serializer, uint32_t val)

Writes a serialized uint32_t into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – uint32_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_uint64(ze_loaned_serializer_t *serializer, uint64_t val)

Writes a serialized uint64_t into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – uint64_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_float(ze_loaned_serializer_t *serializer, float val)

Writes a serialized float into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – float value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_double(ze_loaned_serializer_t *serializer, double val)

Writes a serialized double into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – double value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

static inline z_result_t ze_serializer_serialize_bool(ze_loaned_serializer_t *serializer, bool val)

Writes a serialized ‘bool’ into underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – bool value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serializer_serialize_slice(ze_loaned_serializer_t *serializer, const z_loaned_slice_t *val)

Serializes slice and writes it into an underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – A slice to serialize.
len – Number of bytes to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serializer_serialize_buf(ze_loaned_serializer_t *serializer, const uint8_t *val, size_t len)

Serializes array of bytes and writes it into an underlying z_owned_bytes_t.

Parameters:

serializer – A serializer instance.
val – Pointer to the data to serialize.
len – Number of bytes to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serializer_serialize_string(ze_loaned_serializer_t *serializer, const z_loaned_string_t *val)

Serializes a string and writes it into an underlying z_owned_bytes_t. The string should be a valid UTF-8.

Parameters:

serializer – A serializer instance.
val – Pointer to the string to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serializer_serialize_str(ze_loaned_serializer_t *serializer, const char *val)

Serializes a null-terminated string and writes it into an underlying z_owned_bytes_t. The string should be a valid UTF-8.

Parameters:

serializer – A serializer instance.
val – Pointer to the string to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serializer_serialize_substr(ze_loaned_serializer_t *serializer, const char *start, size_t len)

Serializes a substring and writes it into an underlying z_owned_bytes_t. The substring should be a valid UTF-8.

Parameters:

serializer – A serializer instance.
start – Pointer to the start of the substring to serialize.
len – Length of the substring to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serializer_serialize_sequence_length(ze_loaned_serializer_t *serializer, size_t len)

Initiate serialization of a sequence of multiple elements.

Parameters:

serializer – A serializer instance.
len – Length of the sequence. Could be read during deserialization using ze_deserializer_deserialize_sequence_length().

Returns:

0 if deserialization is successful, or a negative value otherwise.

z_result_t ze_deserialize_int8(const z_loaned_bytes_t *bytes, int8_t *dst)

Deserializes data into a int8_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized int8_t to contain the deserialized.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_int16(const z_loaned_bytes_t *bytes, int16_t *dst)

Deserializes data into a int16_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized int16_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_int32(const z_loaned_bytes_t *bytes, int32_t *dst)

Deserializes data into a int32_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized int32_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_int64(const z_loaned_bytes_t *bytes, int64_t *dst)

Deserializes data into a int64_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized int64_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_uint8(const z_loaned_bytes_t *bytes, uint8_t *dst)

Deserializes data into a uint8_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized uint8_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_uint16(const z_loaned_bytes_t *bytes, uint16_t *dst)

Deserializes data into a uint16_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized uint16_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_uint32(const z_loaned_bytes_t *bytes, uint32_t *dst)

Deserializes data into a uint32_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized uint32_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_uint64(const z_loaned_bytes_t *bytes, uint64_t *dst)

Deserializes data into a uint64_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized uint64_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_float(const z_loaned_bytes_t *bytes, float *dst)

Deserializes data into a float.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized float to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_double(const z_loaned_bytes_t *bytes, double *dst)

Deserializes data into a double.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized double to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_bool(const z_loaned_bytes_t *bytes, bool *dst)

Deserializes data into a boolean.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
dst – Pointer to an uninitialized bool to contain the deserialized value.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserialize_slice(const z_loaned_bytes_t *bytes, z_owned_slice_t *dst)

Deserializes data into a z_owned_slice_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
str – Pointer to an uninitialized z_owned_slice_t to contain the deserialized slice.

Returns:

0 if deserialization is successful, or a negative value otherwise.

z_result_t ze_deserialize_string(const z_loaned_bytes_t *bytes, z_owned_string_t *str)

Deserializes data into a z_owned_string_t.

Parameters:

bytes – Pointer to a z_loaned_bytes_t to deserialize.
str – Pointer to an uninitialized z_owned_string_t to contain the deserialized string.

Returns:

0 if deserialization is successful, or a negative value otherwise.

bool ze_deserializer_is_done(const ze_deserializer_t *deserializer)

Checks if deserializer parsed all of its data.

Parameters:

deserializer – A deserializer instance.

Returns:

True if there is no more data to parse, false otherwise.

z_result_t ze_serialize_int8(z_owned_bytes_t *bytes, int8_t val)

Serializes a int8_t into a z_owned_bytes_t .

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – int8_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_int16(z_owned_bytes_t *bytes, int16_t val)

Serializes a int16_t into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – int16_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_int32(z_owned_bytes_t *bytes, int32_t val)

Serializes a int32_t into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – int32_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_int64(z_owned_bytes_t *bytes, int64_t val)

Serializes a int64_t into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – int64_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_uint8(z_owned_bytes_t *bytes, uint8_t val)

Serializes a uint8_t into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – uint8_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_uint16(z_owned_bytes_t *bytes, uint16_t val)

Serializes a uint16_t into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – uint16_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_uint32(z_owned_bytes_t *bytes, uint32_t val)

Serializes a uint32_t into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – uint32_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_uint64(z_owned_bytes_t *bytes, uint64_t val)

Serializes a uint64_t into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – uint64_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_float(z_owned_bytes_t *bytes, float val)

Serializes a float into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – float value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_double(z_owned_bytes_t *bytes, double val)

Serializes a double into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – double value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_bool(z_owned_bytes_t *bytes, bool val)

Serializes a bool into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized int.
val – bool value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_slice(z_owned_bytes_t *bytes, const z_loaned_slice_t *slice)

Serializes a slice into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized slice.
slice – Pointer to the slice to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_buf(z_owned_bytes_t *bytes, const uint8_t *data, size_t len)

Serializes data into a z_owned_bytes_t.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized data.
data – Pointer to the data to serialize.
len – Number of bytes to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_string(z_owned_bytes_t *bytes, const z_loaned_string_t *s)

Serializes a string into a z_owned_bytes_t.

The string should be a valid UTF-8. :param bytes: An uninitialized z_owned_bytes_t to contain the serialized string. :param s: Pointer to the string to serialize.

Returns:: 0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_str(z_owned_bytes_t *bytes, const char *value)

Serializes a null-terminated string into a z_owned_bytes_t. The string should be a valid UTF-8.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized string.
value – Pointer to the string to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_substr(z_owned_bytes_t *bytes, const char *start, size_t len)

Serializes a substring into a z_owned_bytes_t. The substring should be a valid UTF-8.

Parameters:

bytes – An uninitialized z_owned_bytes_t to contain the serialized string.
start – Pointer to the the start of string to serialize.
len – Length of the substring to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void ze_serializer_drop(ze_moved_serializer_t *serializer)

void ze_serializer_clone(ze_owned_serializer_t *dst, const ze_loaned_serializer_t *serializer)

const ze_loaned_serializer_t *ze_serializer_loan(const ze_owned_serializer_t *serializer)

ze_loaned_serializer_t *ze_serializer_loan_mut(ze_owned_serializer_t *serializer)

z_result_t ze_serializer_take_from_loaned(ze_owned_serializer_t *dst, ze_loaned_serializer_t *src)

Liveliness

Types

type z_liveliness_token_options_t: The options for z_liveliness_declare_token().

type z_liveliness_subscriber_options_t: The options for z_liveliness_declare_subscriber()

type z_liveliness_get_options_t: The options for z_liveliness_get()

Represents a Liveliness token entity. See details at Owned Types z_owned_xxx_t

type z_owned_liveliness_token_t

type z_loaned_liveliness_token_t

type z_moved_liveliness_token_t

Functions

z_result_t z_liveliness_token_options_default(z_liveliness_token_options_t *options): Constructs default value for z_liveliness_token_options_t.

z_result_t z_liveliness_declare_token(const z_loaned_session_t *zs, z_owned_liveliness_token_t *token, const z_loaned_keyexpr_t *keyexpr, const z_liveliness_token_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.

Parameters:

zs – A Zenos session to declare the liveliness token.
token – An uninitialized memory location where liveliness token will be constructed.
keyexpr – A keyexpr to declare a liveliess token for.
options – Liveliness token declaration options.

Returns:

0 if put operation is successful, negative value otherwise.

z_result_t z_liveliness_undeclare_token(z_moved_liveliness_token_t *token)

Undeclare a liveliness token, notifying subscribers of its destruction.

Parameters:

token – Moved z_owned_liveliness_token_t to undeclare.

Returns:

0 if put operation is successful, negative value otherwise.

z_result_t z_liveliness_subscriber_options_default(z_liveliness_subscriber_options_t *options): Constucts default value for z_liveliness_subscriber_options_t.

z_result_t z_liveliness_declare_subscriber(const z_loaned_session_t *zs, z_owned_subscriber_t *sub, const z_loaned_keyexpr_t *keyexpr, z_moved_closure_sample_t *callback, z_liveliness_subscriber_options_t *options)

Declares a subscriber on liveliness tokens that intersect keyexpr.

Parameters:

zs – The Zenoh session.
sub – An uninitialized memory location where subscriber will be constructed.
keyexpr – The key expression to subscribe to.
callback – The callback function that will be called each time a liveliness token status is changed.
options – The options to be passed to the liveliness subscriber declaration.

Returns:

0 if put operation is successful, negative value otherwise.

z_result_t z_liveliness_declare_background_subscriber(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, z_moved_closure_sample_t *callback, z_liveliness_subscriber_options_t *options)

Declares a background subscriber on liveliness tokens that intersect keyexpr. Subscriber callback will be called to process the messages, until the corresponding session is closed or dropped.

Parameters:

zs – The Zenoh session.
keyexpr – The key expression to subscribe to.
callback – The callback function that will be called each time a liveliness token status is changed.
options – The options to be passed to the liveliness subscriber declaration.

Returns:

0 if declare is successful, negative value otherwise.

z_result_t z_liveliness_get(const z_loaned_session_t *zs, const z_loaned_keyexpr_t *keyexpr, z_moved_closure_reply_t *callback, z_liveliness_get_options_t *options)

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

Parameters:

zs – The Zenoh session.
keyexpr – The key expression to query liveliness tokens for.
callback – The callback function that will be called for each received reply.
options – Additional options for the liveliness get operation.

Returns:

0 if put operation is successful, negative value otherwise.

Others

Data Structures

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().

Constants

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.

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(dst, src)

Defines a generic function for cloning of the z_owned_X_t types.

Parameters:

dst – The clone destination.
src – The instance to clone.

Returns:

0 in case of success, negative error code otherwise.

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.

Functions

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:

options – Pointer to an uninitialized zp_task_read_options_t.

z_result_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:

zs – Pointer to a z_loaned_session_t to start the task from.
options – Pointer to a zp_task_read_options_t to configure the task.

Returns:

0 if task started successfully, negative value otherwise.

z_result_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:

zs – Pointer to a z_loaned_session_t to stop the task from.

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:

options – Pointer to an uninitialized zp_task_lease_options_t.

z_result_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:

zs – Pointer to a z_loaned_session_t to start the task from.
options – Pointer to a zp_task_lease_options_t to configure the task.

Returns:

0 if task started successfully, negative value otherwise.

z_result_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:

zs – Pointer to a z_loaned_session_t to stop the task from.

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:

options – Pointer to an uninitialized zp_read_options_t.

z_result_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:

zs – Pointer to a z_loaned_session_t to execute the read for.
options – Pointer to a zp_read_options_t to configure the operation.

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:

options – Pointer to an uninitialized zp_send_keep_alive_options_t.

z_result_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:

zs – Pointer to a z_loaned_session_t to execute the send for.
options – Pointer to a zp_send_keep_alive_options_t to configure the operation.

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:

options – Pointer to an uninitialized zp_send_join_options_t.

z_result_t zp_send_join(const z_loaned_session_t *zs, const zp_send_join_options_t *options)

Executes a single send join procedure.

Parameters:

zs – Pointer to a z_loaned_session_t to execute the send for.
options – Pointer to a zp_send_keep_alive_options_t to configure the operation.

Returns:

0 if execution was successful, negative value otherwise.

Logging

Warning

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

Zenoh-Pico provides a flexible logging system to assist with debugging and monitoring. By default, logging is disabled in release builds, but it can be enabled and configured based on the desired level of verbosity.

Logging Levels

Zenoh-Pico supports three logging levels:

Error: Only error messages are logged. This is the least verbose level.
Info: Logs informational messages and error messages.
Debug: Logs debug messages, informational messages, and error messages. This is the most verbose level.

Enabling Logging

CMake build provides a variable ZENOH_LOG which accepts the following values (either uppercase or lowercase):

ERROR to enable error messages.
WARN to enable warning and higher level messages.
INFO to enable informational and higher level messages.
DEBUG to enable debug and higher level messages.
TRACE to enable trace and higher level messages.

ZENOH_LOG=debug make  # build zenoh-pico with debug and higher level messages enabled

When building zenoh-pico from source, logging can be enabled by defining corresponding macro, like -DZENOH_LOG_DEBUG.

Override Logs printing

By default, logging use printf, but it can be overridden by setting ZENOH_LOG_PRINT:

ZENOH_LOG_PRINT=my_print make  # build zenoh-pico using `my_print` instead of `printf` for logging