API Reference

Containers

Slice

Types

Warning

doxygenstruct: Cannot find class “z_owned_slice_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_view_slice_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_slice_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

void z_slice_null(struct z_owned_slice_t *this_)

Constructs an empty z_owned_slice_t.

void z_view_slice_null(struct z_view_slice_t *this_)

Constructs an empty view slice.

bool z_slice_check(const struct z_owned_slice_t *this_)

Returns:

true if slice is not empty, false otherwise.

bool z_view_slice_check(const struct z_view_slice_t *this_)

Returns:

true if the slice is not empty, false otherwise.

const struct z_loaned_slice_t *z_slice_loan(const struct z_owned_slice_t *this_)

Borrows slice.

const struct z_loaned_slice_t *z_view_slice_loan(const struct z_view_slice_t *this_)

Borrows view slice.

void z_slice_drop(struct z_owned_slice_t *this_)

Frees the memory and invalidates the slice.

void z_slice_empty(struct z_owned_slice_t *this_)

Constructs an empty z_owned_slice_t.

void z_view_slice_empty(struct z_view_slice_t *this_)

Constructs an empty view slice.

z_error_t z_slice_wrap(struct z_owned_slice_t *this_, const uint8_t *start, size_t len)

Constructs a slice by copying a len bytes long sequence starting at start.

Returns:

-1 if start == NULL and len > 0 (creating an empty slice), 0 otherwise.

z_error_t z_view_slice_wrap(struct z_view_slice_t *this_, const uint8_t *start, size_t len)

Constructs a len bytes long view starting at start.

Returns:

-1 if start == NULL and len > 0 (and creates an empty view slice), 0 otherwise.

z_error_t z_slice_from_str(struct z_owned_slice_t *this_, const char *str)

Copies a string into z_owned_slice_t using strlen (this should therefore not be used with untrusted inputs).

Returns:

-1 if str == NULL (and creates an empty slice), 0 otherwise.

const uint8_t *z_slice_data(const struct z_loaned_slice_t *this_)

Returns:

the pointer to the slice data.

size_t z_slice_len(const struct z_loaned_slice_t *this_)

Returns:

the length of the slice.

bool z_slice_is_empty(const struct z_loaned_slice_t *this_)

Returns:

true if slice is empty, false otherwise.

String

Types

Warning

doxygenstruct: Cannot find class “z_owned_string_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_view_string_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_str_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

bool z_string_check(const struct z_owned_string_t *this_)

Returns:

true if this_ is a valid string, false if it is in gravestone state.

Warning

doxygenfunction: Cannot find function “z_view_str_check” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

void z_string_null(struct z_owned_string_t *this_)

Constructs owned string in a gravestone state.

Warning

doxygenfunction: Cannot find function “z_view_str_null” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

const struct z_loaned_string_t *z_string_loan(const struct z_owned_string_t *this_)

Borrows string.

Warning

doxygenfunction: Cannot find function “z_view_str_loan” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

void z_string_drop(struct z_owned_string_t *this_)

Frees memory and invalidates z_owned_string_t, putting it in gravestone state.

void z_string_empty(struct z_owned_string_t *this_)

Constructs an empty owned string.

Warning

doxygenfunction: Cannot find function “z_view_str_empty” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_string_wrap” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_view_str_wrap” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

z_error_t z_string_from_substr(struct z_owned_string_t *this_, const char *str, size_t len)

Constructs an owned string by copying a str substring of length len.

Returns:

-1 if str == NULL and len > 0 (and creates a string in a gravestone state), 0 otherwise.

const char *z_string_data(const struct z_loaned_string_t *this_)

Returns:

the pointer of the string data.

size_t z_string_len(const struct z_loaned_string_t *this_)

Returns:

the length of the string (without terminating 0 character).

bool z_string_is_empty(const struct z_loaned_string_t *this_)

Returns:

true if string is empty, false otherwise.

Slice map

Types

Warning

doxygenstruct: Cannot find class “z_owned_slice_map_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_slice_map_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

bool z_slice_map_check(const struct z_owned_slice_map_t *map)

Returns:

true if the map is not in its gravestone state, false otherwise.

void z_slice_map_null(struct z_owned_slice_map_t *this_)

Constructs the gravestone value for z_owned_slice_map_t.

void z_slice_map_drop(struct z_owned_slice_map_t *this_)

Destroys the map, resetting it to its gravestone value.

const struct z_loaned_slice_map_t *z_slice_map_loan(const struct z_owned_slice_map_t *this_)

Borrows slice map.

struct z_loaned_slice_map_t *z_slice_map_loan_mut(struct z_owned_slice_map_t *this_)

Mutably borrows slice map.

void z_slice_map_new(struct z_owned_slice_map_t *this_)

Constructs a new empty map.

const struct z_loaned_slice_t *z_slice_map_get(const struct z_loaned_slice_map_t *this_, const struct z_loaned_slice_t *key)

Returns:

the value associated with key (NULL if the key is not present in the map.).

size_t z_slice_map_len(const struct z_loaned_slice_map_t *this_)

Returns:

number of key-value pairs in the map.

bool z_slice_map_is_empty(const struct z_loaned_slice_map_t *this_)

Returns:

true if the map is empty, false otherwise.

z_error_t z_slice_map_insert_by_alias(struct z_loaned_slice_map_t *this_, const struct z_loaned_slice_t *key, const struct z_loaned_slice_t *value)

Associates value to key in the map, aliasing them.

If the key was already present in the map, its value is updated.

Returns:

1 if there was already an entry associated with the key, 0 otherwise.

uint8_t z_slice_map_insert_by_copy(struct z_loaned_slice_map_t *this_, const struct z_loaned_slice_t *key, const struct z_loaned_slice_t *value)

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

If the key was already present in the map, its value is updated.

Returns:

1 if there was already an entry associated with the key, 0 otherwise.

void z_slice_map_iterate(const struct z_loaned_slice_map_t *this_, bool (*body)(const struct z_loaned_slice_t *key, const struct z_loaned_slice_t *value, void *context), void *context)

Iterates over key-value pairs of a slice map.

Parameters:

• this_ – Slice map to iterate over.

• body – Iterator body function. Returning true is treated as iteration loop break.

• context – Some data passed to every body invocation.

string array

Types

Warning

doxygenstruct: Cannot find class “z_owned_str_array_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_str_array_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

bool z_string_array_check(const struct z_owned_string_array_t *this_)

Returns:

true if the string array is valid, false if it is in a gravestone state.

void z_string_array_null(struct z_owned_string_array_t *this_)

Constructs string array in its gravestone state.

void z_string_array_drop(struct z_owned_string_array_t *this_)

Destroys the string array, resetting it to its gravestone value.

const struct z_loaned_string_array_t *z_string_array_loan(const struct z_owned_string_array_t *this_)

Borrows string array.

struct z_loaned_string_array_t *z_string_array_loan_mut(struct z_owned_string_array_t *this_)

Mutably borrows string array.

void z_string_array_new(struct z_owned_string_array_t *this_)

Constructs a new empty string array.

const struct z_loaned_string_t *z_string_array_get(const struct z_loaned_string_array_t *this_, size_t index)

Will return NULL if the index is out of bounds.

Returns:

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

size_t z_string_array_len(const struct z_loaned_string_array_t *this_)

Returns:

number of elements in the array.

bool z_string_array_is_empty(const struct z_loaned_string_array_t *this_)

Returns:

true if the array is empty, false otherwise.

Common

Serialization / Deserialization

Types

Warning

doxygenstruct: Cannot find class “z_owned_bytes_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_bytes_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_bytes_iterator_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_bytes_reader_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

size_t z_bytes_len(const struct z_loaned_bytes_t *this_)

Returns total number of bytes in the payload.

void z_bytes_serialize_from_slice(struct z_owned_bytes_t *this_, const uint8_t *data, size_t len)

Serializes from an immutable SHM buffer consuming it Serializes from an immutable SHM buffer copying it Serializes from a mutable SHM buffer consuming it Serializes a slice by aliasing.

Warning

doxygenfunction: Cannot find function “z_bytes_serialize_from_string” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

void z_bytes_serialize_from_slice_map(struct z_owned_bytes_t *this_, const struct z_loaned_slice_map_t *bytes_map)

Serializes slice map by aliasing.

z_error_t z_bytes_serialize_from_iter(struct z_owned_bytes_t *this_, bool (*iterator_body)(struct z_owned_bytes_t *data, void *context), void *context)

Constructs payload from an iterator to z_owned_bytes_t.

Parameters:

• this_ – An uninitialized location in memory for z_owned_bytes_t will be constructed.

• iterator_body – Iterator body function, providing data items. Returning false is treated as iteration end.

• context – Arbitrary context that will be passed to iterator_body.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_serialize_from_pair(struct z_owned_bytes_t *this_, struct z_owned_bytes_t *first, struct z_owned_bytes_t *second)

Serializes a pair of z_owned_bytes_t objects which are consumed in the process.

Returns:

0 in case of success, negative error code otherwise.

void z_bytes_serialize_from_uint8(struct z_owned_bytes_t *this_, uint8_t val)

Serializes an unsigned integer.

void z_bytes_serialize_from_uint16(struct z_owned_bytes_t *this_, uint16_t val)

Serializes an unsigned integer.

void z_bytes_serialize_from_uint32(struct z_owned_bytes_t *this_, uint32_t val)

Serializes an unsigned integer.

void z_bytes_serialize_from_uint64(struct z_owned_bytes_t *this_, uint64_t val)

Serializes an unsigned integer.

void z_bytes_serialize_from_int8(struct z_owned_bytes_t *this_, int8_t val)

Serializes a signed integer.

void z_bytes_serialize_from_int16(struct z_owned_bytes_t *this_, int16_t val)

Serializes a signed integer.

void z_bytes_serialize_from_int32(struct z_owned_bytes_t *this_, int32_t val)

Serializes a signed integer.

void z_bytes_serialize_from_int64(struct z_owned_bytes_t *this_, int64_t val)

Serializes a signed integer.

void z_bytes_serialize_from_float(struct z_owned_bytes_t *this_, float val)

Serializes a float.

void z_bytes_serialize_from_double(struct z_owned_bytes_t *this_, double val)

Serializes a double.

z_error_t z_bytes_deserialize_into_slice(const struct z_loaned_bytes_t *this_, struct z_owned_slice_t *dst)

Deserializes data into an owned slice.

Parameters:

• this_ – Data to deserialize.

• dst – An uninitialized memory location where to construct a slice.

z_error_t z_bytes_deserialize_into_string(const struct z_loaned_bytes_t *this_, struct z_owned_string_t *dst)

Deserializes data into an owned non-null-terminated string.

Parameters:

• this_ – Data to deserialize.

• dst – An uninitialized memory location where to construct a deserialized string.

z_error_t z_bytes_deserialize_into_slice_map(const struct z_loaned_bytes_t *this_, struct z_owned_slice_map_t *dst)

Deserializes data into an owned bytes map.

Parameters:

• this_ – Data to deserialize.

• dst – An uninitialized memory location where to construct a deserialized map.

Warning

doxygenfunction: Cannot find function “z_bytes_deserialize_into_iter” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

z_error_t z_bytes_deserialize_into_pair(const struct z_loaned_bytes_t *this_, struct z_owned_bytes_t *first, struct z_owned_bytes_t *second)

Deserializes data into a loaned SHM buffer

Parameters:

• this_ – Data to deserialize.

• dst – An uninitialized memory location where to construct a deserialized string. Deserializes data into a mutably loaned SHM buffer

• this_ – Data to deserialize.

• dst – An uninitialized memory location where to construct a deserialized string. Deserializes data into an owned SHM buffer by copying it’s shared reference

• this_ – Data to deserialize.

• dst – An uninitialized memory location where to construct a deserialized string. Deserializes into a pair of z_owned_bytes_t objects.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_uint8(const struct z_loaned_bytes_t *this_, uint8_t *dst)

Deserializes into an unsigned integer.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_uint16(const struct z_loaned_bytes_t *this_, uint16_t *dst)

Deserializes into an unsigned integer.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_uint32(const struct z_loaned_bytes_t *this_, uint32_t *dst)

Deserializes into an unsigned integer.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_uint64(const struct z_loaned_bytes_t *this_, uint64_t *dst)

Deserializes into an unsigned integer.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_int8(const struct z_loaned_bytes_t *this_, int8_t *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_int16(const struct z_loaned_bytes_t *this_, int16_t *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_int32(const struct z_loaned_bytes_t *this_, int32_t *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_int64(const struct z_loaned_bytes_t *this_, int64_t *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_float(const struct z_loaned_bytes_t *this_, float *dst)

Deserializes into a float.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_bytes_deserialize_into_double(const struct z_loaned_bytes_t *this_, double *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

void z_bytes_empty(struct z_owned_bytes_t *this_)

Constructs an empty instance of z_owned_bytes_t.

void z_bytes_clone(struct z_owned_bytes_t *dst, const struct z_loaned_bytes_t *this_)

Constructs an owned shallow copy of data in provided uninitialized memory location.

const struct z_loaned_bytes_t *z_bytes_loan(const struct z_owned_bytes_t *this_)

Borrows data.

struct z_loaned_bytes_t *z_bytes_loan_mut(struct z_owned_bytes_t *this_)

Muatably borrows data.

void z_bytes_null(struct z_owned_bytes_t *this_)

The gravestone value for z_owned_bytes_t.

bool z_bytes_check(const struct z_owned_bytes_t *this_)

Returns true if this is valid. Deletes Alloc Layout Borrows Alloc Layout Creates a new Alloc Layout for SHM Provider Constructs Alloc Layout in its gravestone value. Returns true if this is valid. Deletes Buf Alloc Result Borrows Buf Alloc Result Constructs Buf Alloc Result in its gravestone value. Returns true if this_ is in a valid state, false if it is in a gravestone state.

void z_bytes_drop(struct z_owned_bytes_t *this_)

Drops this_, resetting it to gravestone value. If there are any shallow copies created by z_bytes_clone(), they would still stay valid.

struct z_bytes_reader_t z_bytes_get_reader(const struct z_loaned_bytes_t *data)

Returns a reader for the data.

The data should outlive the reader.

size_t z_bytes_reader_read(struct z_bytes_reader_t *this_, uint8_t *dst, size_t len)

Reads data into specified destination.

Parameters:

• this_ – 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 theend of the data was reached.

z_error_t z_bytes_reader_seek(struct z_bytes_reader_t *this_, 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. Return ​0​ upon success, negative error code otherwise.

int64_t z_bytes_reader_tell(struct z_bytes_reader_t *this_)

Gets the read position indicator.

Returns:

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

struct z_bytes_iterator_t z_bytes_get_iterator(const struct z_loaned_bytes_t *data)

Returns an iterator for multi-element serialized data.

The data should outlive the iterator.

bool z_bytes_iterator_next(struct z_bytes_iterator_t *iter, struct z_owned_bytes_t *out)

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

Will construct null-state z_owned_bytes_t when iterator reaches the end.

Returns:

false when iterator reaches the end, true otherwise

void z_bytes_get_writer(struct z_loaned_bytes_t *this_, struct z_owned_bytes_writer_t *out)

Gets writer for this_.

const struct z_loaned_bytes_writer_t *z_bytes_writer_loan(const struct z_owned_bytes_writer_t *this_)

Borrows writer.

struct z_loaned_bytes_writer_t *z_bytes_writer_loan_mut(struct z_owned_bytes_writer_t *this_)

Muatably borrows writer.

void z_bytes_writer_null(struct z_owned_bytes_writer_t *this_)

The gravestone value for z_owned_bytes_reader_t.

bool z_bytes_writer_check(const struct z_owned_bytes_writer_t *this_)

Returns true if this_ is in a valid state, false if it is in a gravestone state.

void z_bytes_writer_drop(struct z_owned_bytes_writer_t *this_)

Drops this_, resetting it to gravestone value.

z_error_t z_bytes_writer_write(struct z_loaned_bytes_writer_t *this_, const uint8_t *src, size_t len)

Writes len bytes from src into underlying data

Returns:

0 in case of success, negative error code otherwise

Key expression

Types

Warning

doxygenstruct: Cannot find class “z_owned_keyexpr_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_view_keyexpr_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_keyexpr_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

enum z_keyexpr_intersection_level_t

Intersection level of 2 key expressions.

Values:

enumerator Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT

2 key expressions do not intersect.

enumerator Z_KEYEXPR_INTERSECTION_LEVEL_INTERSECTS

2 key expressions intersect, i.e. there exists at least one key expression that is included by both.

enumerator Z_KEYEXPR_INTERSECTION_LEVEL_INCLUDES

First key expression is the superset of second one.

enumerator Z_KEYEXPR_INTERSECTION_LEVEL_EQUALS

2 key expressions are equal.

Functions

Warning

doxygenfunction: Cannot find function “z_keyexpr_from_string” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_view_keyexpr_from_string” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_keyexpr_from_string_autocanonize” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_view_keyexpr_from_string_autocanonize” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_view_keyexpr_from_string_unchecked” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

z_error_t z_keyexpr_from_substr(struct z_owned_keyexpr_t *this_, const char *expr, size_t len)

Constructs a z_owned_keyexpr_t by copying a substring.

Parameters:

• this_ – An uninitialized location in memory where key expression will be constructed.

• expr – A buffer with length >= len.

• len – Number of characters from expr to consider.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_view_keyexpr_from_substr(struct z_view_keyexpr_t *this_, const char *expr, size_t len)

Constructs a z_view_keyexpr_t by aliasing a substring. expr must outlive the constucted key expression.

Parameters:

• this_ – An uninitialized location in memory where key expression will be constructed.

• expr – A buffer with length >= len.

• len – Number of characters from expr to consider.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_keyexpr_from_substr_autocanonize(struct z_owned_keyexpr_t *this_, const char *start, size_t *len)

Constructs a z_keyexpr_t by copying a substring.

Parameters:

• this_ – An uninitialized location in memory where key expression will be constructed.

• expr – A buffer of with length >= len.

• len – Number of characters from expr to consider. Will be modified to be equal to canonized key expression length.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_view_keyexpr_from_substr_autocanonize(struct z_view_keyexpr_t *this_, char *start, size_t *len)

Constructs a z_view_keyexpr_t by aliasing a substring. May SEGFAULT if start is NULL or lies in read-only memory (as values initialized with string litterals do). expr must outlive the constucted key expression.

Parameters:

• this_ – An uninitialized location in memory where key expression will be constructed

• expr – A buffer of with length >= len.

• len – Number of characters from expr to consider. Will be modified to be equal to canonized key expression length.

Returns:

0 in case of success, negative error code otherwise.

void z_view_keyexpr_from_substr_unchecked(struct z_view_keyexpr_t *this_, const char *start, size_t len)

Constructs a z_view_keyexpr_t by aliasing a substring without checking any of z_view_keyexpr_t’s assertions:

• start MUST be valid UTF8.

• start MUST follow the Key Expression specification, i.e.:

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

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

  • the key expression must have canon form.

start must outlive constructed key expression.

const struct z_loaned_keyexpr_t *z_keyexpr_loan(const struct z_owned_keyexpr_t *this_)

Borrows z_owned_keyexpr_t.

const struct z_loaned_keyexpr_t *z_view_keyexpr_loan(const struct z_view_keyexpr_t *this_)

Borrows z_view_keyexpr_t.

bool z_keyexpr_check(const struct z_owned_keyexpr_t *this_)

Returns true if keyexpr is valid, false if it is in gravestone state.

bool z_view_keyexpr_check(const struct z_view_keyexpr_t *this_)

Returns true if keyexpr is valid, false if it is in gravestone state.

void z_keyexpr_drop(struct z_owned_keyexpr_t *this_)

Frees key expression and resets it to its gravestone state.

void z_keyexpr_as_view_string(const struct z_loaned_keyexpr_t *this_, struct z_view_string_t *out_string)

Constructs a non-owned non-null-terminated string from key expression.

z_error_t z_keyexpr_canonize(char *start, size_t *len)

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

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

Returns:

0 upon success, negative error values upon failure (if the passed string was an invalid key expression for reasons other than a non-canon form).

z_error_t z_keyexpr_canonize_null_terminated(char *start)

Canonizes the passed string in place, possibly shortening it by placing a new null-terminator. May SEGFAULT if start is NULL or lies in read-only memory (as values initialized with string litterals do).

Returns:

0 upon success, negative error values upon failure (if the passed string was an invalid key expression for reasons other than a non-canon form).

z_error_t z_keyexpr_is_canon(const char *start, size_t len)

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

z_error_t z_keyexpr_concat(struct z_owned_keyexpr_t *this_, const struct z_loaned_keyexpr_t *left, const char *right_start, size_t right_len)

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

You should probably prefer z_keyexpr_join as Zenoh may then take advantage of the hierachical separation it inserts. To avoid odd behaviors, concatenating a key expression starting with * to one ending with * is forbidden by this operation, as this would extremely likely cause bugs.

z_error_t z_keyexpr_join(struct z_owned_keyexpr_t *this_, const struct z_loaned_keyexpr_t *left, const struct z_loaned_keyexpr_t *right)

Constructs key expression by performing path-joining (automatically inserting) of left with right.

Returns:

0 in case of success, negative error code otherwise.

bool z_keyexpr_equals(const struct z_loaned_keyexpr_t *left, const struct z_loaned_keyexpr_t *right)

Returns true if both left and right are equal, false otherwise.

bool z_keyexpr_includes(const struct z_loaned_keyexpr_t *left, const struct z_loaned_keyexpr_t *right)

Returns true if left includes right, i.e. the set defined by left contains every key belonging to the set defined by right, false otherwise.

bool z_keyexpr_intersects(const struct z_loaned_keyexpr_t *left, const struct z_loaned_keyexpr_t *right)

Returns true if the keyexprs intersect, i.e. there exists at least one key which is contained in both of the sets defined by left and right, false otherwise.

z_error_t z_declare_keyexpr(struct z_owned_keyexpr_t *this_, const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr)

Constructs and declares a key expression on the network. This reduces key key expression to a numerical id, which allows to save the bandwith, when passing key expression between Zenoh entities.

Parameters:

• this_ – An uninitialized location in memory where key expression will be constructed.

• session – Session on which to declare key expression.

• key_expr – Key expression to declare on network.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_undeclare_keyexpr(struct z_owned_keyexpr_t *this_, const struct z_loaned_session_t *session)

Undeclares the key expression generated by a call to z_declare_keyexpr(). The key expression is consumed.

Returns:

0 in case of success, negative error code otherwise.

Encoding

Types

Warning

doxygenstruct: Cannot find class “z_owned_encoding_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_encoding_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

void z_encoding_null(struct z_owned_encoding_t *this_)

Constructs a default z_owned_encoding_t.

const struct z_loaned_encoding_t *z_encoding_loan(const struct z_owned_encoding_t *this_)

Borrows encoding.

bool z_encoding_check(const struct z_owned_encoding_t *this_)

Returns true if encoding is in non-default state, false otherwise.

void z_encoding_drop(struct z_owned_encoding_t *this_)

Frees the memory and resets the encoding it to its default value.

const struct z_loaned_encoding_t *z_encoding_loan_default(void)

Returns a loaned default z_loaned_encoding_t.

z_error_t z_encoding_from_str(struct z_owned_encoding_t *this_, const char *s)

Constructs a z_owned_encoding_t from a specified string.

z_error_t z_encoding_from_substr(struct z_owned_encoding_t *this_, const char *s, size_t len)

Constructs a z_owned_encoding_t from a specified substring.

void z_encoding_to_string(const struct z_loaned_encoding_t *this_, struct z_owned_string_t *out_str)

Constructs an owned non-null-terminated string from encoding

Parameters:

• this_ – Encoding.

• out_str – Uninitialized memory location where a string to be constructed.

Value

Types

Warning

doxygenstruct: Cannot find class “z_loaned_value_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

Warning

doxygenfunction: Cannot find function “z_value_payload” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_value_encoding” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_value_null” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_value_loan” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_value_check” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenfunction: Cannot find function “z_value_drop” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Sample

Types

Warning

doxygenstruct: Cannot find class “z_owned_sample_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_sample_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

enum z_sample_kind_t

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 struct z_loaned_sample_t *z_sample_loan(const struct z_owned_sample_t *this_)

Borrows sample.

bool z_sample_check(const struct z_owned_sample_t *this_)

Returns true if sample is valid, false if it is in gravestone state.

void z_sample_null(struct z_owned_sample_t *this_)

Constructs sample in its gravestone state.

void z_sample_drop(struct z_owned_sample_t *this_)

Frees the memory and invalidates the sample, resetting it to a gravestone state.

const struct z_timestamp_t *z_sample_timestamp(const struct z_loaned_sample_t *this_)

Returns the sample timestamp.

Will return NULL, if sample is not associated with a timestamp.

const struct z_loaned_bytes_t *z_sample_attachment(const struct z_loaned_sample_t *this_)

Returns sample attachment.

Returns NULL, if sample does not contain any attachement.

const struct z_loaned_encoding_t *z_sample_encoding(const struct z_loaned_sample_t *this_)

Returns the encoding associated with the sample data.

const struct z_loaned_bytes_t *z_sample_payload(const struct z_loaned_sample_t *this_)

Returns the sample payload data.

enum z_priority_t z_sample_priority(const struct z_loaned_sample_t *this_)

Returns sample qos priority value.

enum z_congestion_control_t z_sample_congestion_control(const struct z_loaned_sample_t *this_)

Returns sample qos congestion control value.

bool z_sample_express(const struct z_loaned_sample_t *this_)

Returns whether sample qos express flag was set or not.

Timestamp

Types

Warning

doxygenstruct: Cannot find class “z_timestamp_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

struct z_id_t z_timestamp_id(const struct z_timestamp_t *this_)

Returns id associated with this timestamp.

uint64_t z_timestamp_npt64_time(const struct z_timestamp_t *this_)

Returns NPT64 time associated with this timestamp.

System

Random

Functions

uint8_t z_random_u8(void)

Generates random uint8_t.

uint16_t z_random_u16(void)

Generates random uint16_t.

uint32_t z_random_u32(void)

Generates random uint32_t.

uint64_t z_random_u64(void)

Generates random uint64_t.

void z_random_fill(void *buf, size_t len)

Fills buffer with random data.

Sleep

Functions

int8_t z_sleep_s(size_t time)

Puts current thread to sleep for specified amount of seconds.

int8_t z_sleep_ms(size_t time)

Returns true if this is valid. Returns true if this is valid. Deletes SHM Client Creates a new SHM Client Constructs SHM client in its gravestone value. Returns true if this is valid. Derefs SHM Client Storage Borrows SHM Client Storage Constructs SHM Client Storage in its gravestone value. Converts borrowed ZShm slice to owned ZShm slice by performing a shallow SHM reference copy

Returns:

the pointer of the ZShm slice Deletes ZShm slice Constructs ZShm slice from ZShmMut slice

Returns:

the length of the ZShm slice Borrows ZShm slice Mutably borrows ZShm slice Returns true if this is valid.

Returns:

the mutable pointer of the ZShmMut slice Deletes ZShmMut slice

Returns:

the length of the ZShmMut slice Borrows ZShmMut slice Constructs ZShmMut slice in its gravestone value. Tries to construct ZShmMut slice from ZShm slice Constructs ZShm slice in its gravestone value. Returns true if this is valid. Deletes SHM Provider Borrows SHM Provider Creates a new SHM Provider Constructs SHM Provider in its gravestone value. Creates a new threadsafe SHM Provider Mutably borrows ZShm slice as borrowed ZShmMut slice Tries to reborrow mutably-borrowed ZShm slice as borrowed ZShmMut slice Puts current thread to sleep for specified amount of milliseconds.

int8_t z_sleep_us(size_t time)

Puts current thread to sleep for specified amount of microseconds.

Time

Types

struct z_clock_t

A tread-safe droppable context. Contexts are idiomatically used in C together with callback interfaces to deliver associated state information to each callback.

This is a thread-safe context - the associated callbacks may be executed concurrently with the same zc_context_t instance. In other words, all the callbacks associated with this context data MUST be thread-safe.

Once moved to zenoh-c ownership, this context is guaranteed to execute delete_fn when deleted.The delete_fn is guaranteed to be executed only once at some point of time after the last associated callback call returns. NOTE: if user doesn’t pass the instance of this context to zenoh-c, the delete_fn callback won’t be executed. Unique segment identifier Chunk id within it’s segment A ChunkDescriptor An AllocatedChunk Monotonic clock

struct z_time_t

Returns system clock time point corresponding to the current time instant.

Functions

struct z_clock_t z_clock_now(void)

Returns monotonic clock time point corresponding to the current time instant.

uint64_t z_clock_elapsed_s(const struct z_clock_t *time)

Get number of seconds passed since creation of time.

uint64_t z_clock_elapsed_ms(const struct z_clock_t *time)

Returns true if this is valid. Deletes Chunk Alloc Result Borrows Chunk Alloc Result Creates a new Chunk Alloc Result with Error value Creates a new Chunk Alloc Result with Ok value Constructs Chunk Alloc Result in its gravestone value. Get number of milliseconds passed since creation of time.

uint64_t z_clock_elapsed_us(const struct z_clock_t *time)

Get number of microseconds passed since creation of time.

struct z_time_t z_time_now(void)

Initialize clock with current time instant.

uint64_t z_time_elapsed_s(const struct z_time_t *time)

Get number of seconds passed since creation of time.

uint64_t z_time_elapsed_ms(const struct z_time_t *time)

Get number of milliseconds passed since creation of time.

uint64_t z_time_elapsed_us(const struct z_time_t *time)

Get number of microseconds passed since creation of time.

const char *z_time_now_as_str(const char *buf, size_t len)

Converts current system time into null-terminated human readable string and writes it to the buf.

Parameters:

• buf – A buffer where the string will be writtent

• len – Maximum number of characters to write (including terminating 0). The string will be truncated if it is longer than len.

Mutex

Types

Warning

doxygenstruct: Cannot find class “z_owned_mutex_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_mutex_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

bool z_mutex_check(const struct z_owned_mutex_t *this_)

Returns true if this is valid. Deletes Memory Layout Deletes Memory Layout Borrows Memory Layout Creates a new Memory Layout Constructs Memory Layout in its gravestone value. Returns true if mutex is valid, false otherwise.

void z_mutex_null(struct z_owned_mutex_t *this_)

Constructs mutex in a gravestone state.

struct z_loaned_mutex_t *z_mutex_loan_mut(struct z_owned_mutex_t *this_)

Mutably borrows mutex.

void z_mutex_drop(struct z_owned_mutex_t *this_)

Drops mutex and resets it to its gravestone state.

z_error_t z_mutex_init(struct z_owned_mutex_t *this_)

Constructs a mutex.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_mutex_lock(struct z_loaned_mutex_t *this_)

Locks mutex. If mutex is already locked, blocks the thread until it aquires the lock.

Returns:

0 in case of success, negative error code in case of failure.

z_error_t z_mutex_unlock(struct z_loaned_mutex_t *this_)

Unlocks previously locked mutex. If mutex was not locked by the current thread, the behaviour is undefined.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_mutex_try_lock(struct z_loaned_mutex_t *this_)

Tries to lock mutex. If mutex is already locked, return immediately.

Returns:

0 in case of success, negative value if failed to aquire the lock.

Conditional Variable

Types

Warning

doxygenstruct: Cannot find class “z_owned_condvar_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_condvar_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

bool z_condvar_check(const struct z_owned_condvar_t *this_)

Returns true if conditional variable is valid, false otherwise.

void z_condvar_null(struct z_owned_condvar_t *this_)

Constructs conditional variable in a gravestone state.

const struct z_loaned_condvar_t *z_condvar_loan(const struct z_owned_condvar_t *this_)

Borrows conditional variable.

void z_condvar_drop(struct z_owned_condvar_t *this_)

Drops conditional variable.

void z_condvar_init(struct z_owned_condvar_t *this_)

Constructs conditional variable.

z_error_t z_condvar_wait(const struct z_loaned_condvar_t *this_, struct z_loaned_mutex_t *m)

Blocks the current thread until the conditional variable receives a notification.

The function atomically unlocks the guard mutex m and blocks the current thread. When the function returns the lock will have been re-aquired again. Note: The function may be subject to spurious wakeups.

z_error_t z_condvar_signal(const struct z_loaned_condvar_t *this_)

Wakes up one blocked thread waiting on this condiitonal variable.

Returns:

0 in case of success, negative error code in case of failure.

Task

Types

Warning

doxygenstruct: Cannot find class “z_owned_task_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

bool z_task_check(const struct z_owned_task_t *this_)

Returns true if task is valid, false otherwise.

void z_task_null(struct z_owned_task_t *this_)

Constructs task in a gravestone state.

z_error_t z_task_join(struct z_owned_task_t *this_)

Joins the task and releases all allocated resources

void z_task_detach(struct z_owned_task_t *this_)

Detaches the task and releases all allocated resources.

Session

Session configuration

Types

Warning

doxygenstruct: Cannot find class “z_owned_config_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_config_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

void z_config_null(struct z_owned_config_t *this_)

Constructs config in its gravestone state.

const struct z_loaned_config_t *z_config_loan(const struct z_owned_config_t *this_)

Borrows config.

struct z_loaned_config_t *z_config_loan_mut(struct z_owned_config_t *this_)

Mutably borrows config.

bool z_config_check(const struct z_owned_config_t *this_)

Returns true if config is valid, false if it is in a gravestone state.

void z_config_drop(struct z_owned_config_t *this_)

Frees config, and resets it to its gravestone state.

z_error_t z_config_default(struct z_owned_config_t *this_)

Constructs a new empty configuration.

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

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

Parameters:

• peers – Array with size >= n_peers, containing peer locators to add to the config.

• n_peers – Number of peers to add to the config.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_config_peer(struct z_owned_config_t *this_)

Constructs a default peer mode configuration.

z_error_t zc_config_from_file(struct z_owned_config_t *this_, const char *path)

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

Returns 0 in case of success, negative error code otherwise.

z_error_t zc_config_from_str(struct z_owned_config_t *this_, const char *s)

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

Returns 0 in case of success, negative error code otherwise.

z_error_t zc_config_insert_json(struct z_loaned_config_t *this_, const char *key, const char *value)

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

Returns 0 if successful, a negative error code otherwise.

Warning

doxygenfunction: Cannot find function “zc_config_get” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

z_error_t zc_config_to_string(const struct z_loaned_config_t *config, struct z_owned_string_t *out_config_string)

Constructs a json string representation of the config, such as ‘{“mode”:”client”,”connect”:{“endpoints”:[“tcp/127.0.0.1:7447”]}}’.

Returns 0 in case of success, negative error code otherwise.

Session management

Types

Warning

doxygenstruct: Cannot find class “z_owned_session_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_session_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_id_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

struct z_owned_closure_zid_t

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

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

• call will never be called once drop has started.

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

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

Public Members

void *context

An optional pointer to a closure state.

void (*call)(const struct z_id_t *z_id, void *context)

A callback function.

void (*drop)(void *context)

An optional function that will be called upon closure drop.

Functions

z_error_t z_open(struct z_owned_session_t *this_, struct z_owned_config_t *config)

Constructs and opens a new Zenoh session.

Returns:

0 in case of success, negative error code otherwise (in this case the session will be in its gravestone state).

z_error_t z_close(struct z_owned_session_t *this_)

Closes a zenoh session. This alos drops and invalidates session.

Returns:

0 in case of success, a negative value if an error occured while closing the session, the remaining reference count (number of shallow copies) of the session otherwise, saturating at i8::MAX.

const struct z_loaned_session_t *z_session_loan(const struct z_owned_session_t *this_)

Borrows session.

bool z_session_check(const struct z_owned_session_t *this_)

Returns true if session is valid, false otherwise.

void z_session_null(struct z_owned_session_t *this_)

Constructs a Zenoh session in its gravestone state.

void z_session_drop(struct z_owned_session_t *this_)

Frees memory and invalidates the session.

This will also close the session if it does not have any clones left.

void z_session_clone(struct z_owned_session_t *dst, const struct z_loaned_session_t *this_)

Constructs an owned shallow copy of the session in provided uninitialized memory location.

struct z_id_t z_info_zid(const struct z_loaned_session_t *session)

Returns the session’s Zenoh ID.

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

z_error_t z_info_routers_zid(const struct z_loaned_session_t *session, struct z_owned_closure_zid_t *callback)

Fetches the Zenoh IDs of all connected routers.

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

Retuns 0 on success, negative values on failure.

z_error_t z_info_peers_zid(const struct z_loaned_session_t *session, struct z_owned_closure_zid_t *callback)

Fetches the Zenoh IDs of all connected peers.

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

Retuns 0 on success, negative values on failure

bool z_closure_zid_check(const struct z_owned_closure_zid_t *this_)

Returns true if closure is valid, false if it is in gravestone state.

void z_closure_zid_null(struct z_owned_closure_zid_t *this_)

Constructs a null closure.

void z_closure_zid_drop(struct z_owned_closure_zid_t *closure)

Drops the closure, resetting it to its gravestone state. Droping an uninitialized (null) closure is a no-op.

void z_closure_zid_call(const struct z_loaned_closure_zid_t *closure, const struct z_id_t *z_id)

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

Publication

Types

Warning

doxygenstruct: Cannot find class “z_owned_publisher_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_publisher_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

enum z_congestion_control_t

Allocation errors

- **NEED_DEFRAGMENT**: defragmentation needed
- **OUT_OF_MEMORY**: the provider is out of memory
- **OTHER**: other error

Values:

enumerator Z_CONGESTION_CONTROL_BLOCK

Messages are not dropped in case of congestion.

enumerator Z_CONGESTION_CONTROL_DROP

Messages are dropped in case of congestion.

enum z_priority_t

The priority of zenoh messages.

Values:

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.

struct z_put_options_t

Options passed to the z_put() function.

Public Members

struct z_owned_encoding_t *encoding

The encoding of the message.

enum z_congestion_control_t congestion_control

The congestion control to apply when routing this message.

enum z_priority_t priority

The priority of this message.

bool is_express

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

struct z_timestamp_t *timestamp

The timestamp of this message.

enum zcu_locality_t allowed_destination

The allowed destination of this message.

struct z_owned_source_info_t *source_info

The source info for the message.

struct z_owned_bytes_t *attachment

The attachment to this message.

struct z_delete_options_t

Options passed to the z_delete() function.

struct z_publisher_options_t

Options passed to the z_declare_publisher() function.

Public Members

enum z_congestion_control_t congestion_control

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

enum z_priority_t priority

The priority of messages from this publisher.

bool is_express

If true, Zenoh will not wait to batch this message with others to reduce the bandwith

enum zcu_locality_t allowed_destination

The allowed destination for this publisher.

struct z_publisher_put_options_t

Options passed to the z_publisher_put() function.

Public Members

struct z_owned_encoding_t *encoding

The encoding of the data to publish.

struct z_timestamp_t *timestamp

The timestamp of the publication.

struct z_owned_source_info_t *source_info

The source info for the publication.

struct z_owned_bytes_t *attachment

The attachment to attach to the publication.

struct z_publisher_delete_options_t

Represents the set of options that can be applied to the delete operation by a previously declared publisher, whenever issued via z_publisher_delete().

Warning

doxygenstruct: Cannot find class “zcu_owned_matching_listener_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

struct zcu_owned_closure_matching_status_t

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

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

• call will never be called once drop has started.

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

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

Public Members

void *context

An optional pointer to a closure state.

void (*call)(const struct zcu_matching_status_t *matching_status, void *context)

A closure body.

void (*drop)(void *context)

An optional drop function that will be called when the closure is dropped.

Functions

z_error_t z_put(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_owned_bytes_t *payload, struct z_put_options_t *options)

Publishes data on specified key expression.

Parameters:

• session – The Zenoh session.

• key_expr – The key expression to publish to.

• payload – The value to put (consumed upon function return).

• options – The put options (all owned values will be consumed upon function return).

Returns:

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

z_error_t z_delete(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_delete_options_t *options)

Sends request to delete data on specified key expression (used when working with Zenoh storages ).

Parameters:

• session – The zenoh session.

• key_expr – The key expression to delete.

• options – The delete options.

Returns:

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

z_error_t z_declare_publisher(struct z_owned_publisher_t *this_, const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, const struct z_publisher_options_t *options)

Constructs and declares a publisher for the given key expression.

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

Parameters:

• this_ – An unitilized location in memory where publisher will be constructed.

• session – The Zenoh session.

• key_expr – The key expression to publish.

• options – Additional options for the publisher.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_publisher_put(const struct z_loaned_publisher_t *this_, struct z_owned_bytes_t *payload, struct z_publisher_put_options_t *options)

Sends a PUT message onto the publisher’s key expression, transfering the payload ownership.

The payload and all owned options fields are consumed upon function return.

Parameters:

• this_ – The publisher.

• session – The Zenoh session.

• payload – The dat to publish. WIll be consumed.

• options – The publisher put options. All owned fields will be consumed.

Returns:

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

z_error_t z_publisher_delete(const struct z_loaned_publisher_t *publisher, const struct z_publisher_delete_options_t *options)

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

Returns:

0 in case of success, negative error code in case of failure.

z_error_t z_undeclare_publisher(struct z_owned_publisher_t *this_)

Undeclares the given publisher, droping and invalidating it.

Returns:

0 in case of success, negative error code otherwise.

const struct z_loaned_keyexpr_t *z_publisher_keyexpr(const struct z_loaned_publisher_t *publisher)

Returns the key expression of the publisher.

struct z_entity_global_id_t z_publisher_id(const struct z_loaned_publisher_t *publisher)

Returns the ID of the publisher.

void z_publisher_null(struct z_owned_publisher_t *this_)

Constructs a publisher in a gravestone state.

const struct z_loaned_publisher_t *z_publisher_loan(const struct z_owned_publisher_t *this_)

Borrows publisher.

bool z_publisher_check(const struct z_owned_publisher_t *this_)

Returns true if publisher is valid, false otherwise.

void z_publisher_drop(struct z_owned_publisher_t *this_)

Frees memory and resets publisher to its gravestone state. Also attempts undeclare publisher.

void z_put_options_default(struct z_put_options_t *this_)

Constructs the default value for z_put_options_t.

void z_delete_options_default(struct z_delete_options_t *this_)

Constructs the default value for z_delete_options_t.

void z_publisher_options_default(struct z_publisher_options_t *this_)

Constructs the default value for z_publisher_options_t.

void z_publisher_put_options_default(struct z_publisher_put_options_t *this_)

Constructs the default value for z_publisher_put_options_t.

void z_publisher_delete_options_default(struct z_publisher_delete_options_t *this_)

Constructs the default values for the delete operation via a publisher entity.

bool zcu_closure_matching_status_check(const struct zcu_owned_closure_matching_status_t *this_)

Returns true if closure is valid, false if it is in gravestone state.

void zcu_closure_matching_status_null(struct zcu_owned_closure_matching_status_t *this_)

Constructs a null value of ‘zcu_owned_closure_matching_status_t’ type

void zcu_closure_matching_status_drop(struct zcu_owned_closure_matching_status_t *closure)

Drops the closure, resetting it to its gravestone state. Droping an uninitialized closure is a no-op.

void zcu_closure_matching_status_call(const struct zcu_loaned_closure_matching_status_t *closure, const struct zcu_matching_status_t *mathing_status)

Returns true if this is valid. Deletes list of SHM Clients Borrows list of SHM Clients Mutably borrows list of SHM Clients Creates a new empty list of SHM Clients Constructs SHM client list in its gravestone value. Calls the closure. Calling an uninitialized closure is a no-op.

Subscription

Types

Warning

doxygenstruct: Cannot find class “z_owned_subscriber_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_subscriber_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

struct z_owned_closure_sample_t

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

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

• call will never be called once drop has started.

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

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

Public Members

void *context

An optional pointer to a context representing a closure state.

void (*call)(const struct z_loaned_sample_t *sample, void *context)

A closure body.

void (*drop)(void *context)

An optional drop function that will be called when the closure is dropped.

enum z_reliability_t

The subscription reliability.

Values:

enumerator Z_RELIABILITY_BEST_EFFORT

Defines reliability as BEST_EFFORT

enumerator Z_RELIABILITY_RELIABLE

Defines reliability as RELIABLE

struct z_subscriber_options_t

Options passed to the z_declare_subscriber() function.

Public Members

enum z_reliability_t reliability

The subscription reliability.

Warning

doxygenstruct: Cannot find class “z_owned_fifo_handler_sample_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_fifo_handler_sample_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_owned_ring_handler_sample_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_ring_handler_sample_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

z_error_t z_declare_subscriber(struct z_owned_subscriber_t *this_, const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_owned_closure_sample_t *callback, struct z_subscriber_options_t *options)

Constructs and declares a subscriber for a given key expression. Dropping subscriber

Parameters:

• this_ – An uninitialized location in memory, where subscriber will be constructed.

• session – The zenoh session.

• key_expr – The key expression to subscribe.

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

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

Returns:

0 in case of success, negative error code otherwise (in this case subscriber will be in its gravestone state).

z_error_t z_undeclare_subscriber(struct z_owned_subscriber_t *this_)

Undeclares subscriber and drops subscriber.

Returns:

0 in case of success, negative error code otherwise.

bool z_subscriber_check(const struct z_owned_subscriber_t *this_)

Returns true if subscriber is valid, false otherwise.

void z_subscriber_null(struct z_owned_subscriber_t *this_)

Constructs a subscriber in a gravestone state.

void z_subscriber_drop(struct z_owned_subscriber_t *this_)

Drops subscriber and resets it to its gravestone state. Also attempts to undeclare it.

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

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

void z_closure_sample_drop(struct z_owned_closure_sample_t *closure)

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

void z_closure_sample_null(struct z_owned_closure_sample_t *this_)

Constructs a closure in its gravestone state.

bool z_closure_sample_check(const struct z_owned_closure_sample_t *this_)

Returns true if closure is valid, false if it is in gravestone state.

void z_subscriber_options_default(struct z_subscriber_options_t *this_)

Constructs the default value for z_subscriber_options_t.

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

Constructs send and recieve ends of the fifo channel

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

Constructs send and recieve ends of the ring channel

bool z_fifo_handler_sample_check(const struct z_owned_fifo_handler_sample_t *this_)

Returns true if handler is valid, false if it is in gravestone state.

void z_fifo_handler_sample_null(struct z_owned_fifo_handler_sample_t *this_)

Constructs a handler in gravestone state.

void z_fifo_handler_sample_drop(struct z_owned_fifo_handler_sample_t *this_)

Drops the handler and resets it to a gravestone state.

const struct z_loaned_fifo_handler_sample_t *z_fifo_handler_sample_loan(const struct z_owned_fifo_handler_sample_t *this_)

Borrows handler.

bool z_fifo_handler_sample_recv(const struct z_loaned_fifo_handler_sample_t *this_, struct z_owned_sample_t *sample)

Returns sample from the fifo buffer. If there are no more pending replies will block until next sample is received, or until the channel is dropped (normally when there are no more samples to receive). In the later case will return false and sample will be in the gravestone state.

bool z_fifo_handler_sample_try_recv(const struct z_loaned_fifo_handler_sample_t *this_, struct z_owned_sample_t *sample)

Returns sample from the fifo buffer. If there are no more pending replies will return immediately (with sample set to its gravestone state). Will return false if the channel is dropped (normally when there are no more samples to receive) and there are no more replies in the fifo.

bool z_ring_handler_sample_check(const struct z_owned_ring_handler_sample_t *this_)

Returns true if handler is valid, false if it is in gravestone state.

void z_ring_handler_sample_null(struct z_owned_ring_handler_sample_t *this_)

Constructs a handler in gravestone state.

void z_ring_handler_sample_drop(struct z_owned_ring_handler_sample_t *this_)

Drops the handler and resets it to a gravestone state.

const struct z_loaned_ring_handler_sample_t *z_ring_handler_sample_loan(const struct z_owned_ring_handler_sample_t *this_)

Borrows handler.

bool z_ring_handler_sample_recv(const struct z_loaned_ring_handler_sample_t *this_, struct z_owned_sample_t *sample)

Returns sample from the ring buffer. If there are no more pending replies will block until next sample is received, or until the channel is dropped (normally when there are no more samples to receive). In the later case will return false and sample will be in the gravestone state.

bool z_ring_handler_sample_try_recv(const struct z_loaned_ring_handler_sample_t *this_, struct z_owned_sample_t *sample)

Returns sample from the ring buffer. If there are no more pending replies will return immediately (with sample set to its gravestone state). Will return false if the channel is dropped (normally when there are no more samples to receive) and there are no more replies in the fifo.

Queryable

Types

Warning

doxygenstruct: Cannot find class “z_owned_queryable_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_owned_query_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_query_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

struct z_owned_closure_query_t

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

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

• call will never be called once drop has started.

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

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

Public Members

void *context

An optional pointer to a context representing a closure state.

void (*call)(const struct z_loaned_query_t *reply, void *context)

A closure body.

void (*drop)(void *context)

An optional drop function that will be called when the closure is dropped.

struct z_queryable_options_t

Options passed to the z_declare_queryable() function.

Public Members

bool complete

The completeness of the Queryable.

struct z_query_reply_options_t

Represents the set of options that can be applied to a query reply, sent via z_query_reply().

Public Members

struct z_owned_encoding_t *encoding

The encoding of the reply payload.

enum z_congestion_control_t congestion_control

The congestion control to apply when routing the reply.

enum z_priority_t priority

The priority of the reply.

bool is_express

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

struct z_timestamp_t *timestamp

The timestamp of the reply.

struct z_owned_source_info_t *source_info

The source info for the reply.

struct z_owned_bytes_t *attachment

The attachment to this reply.

struct z_query_reply_err_options_t

Represents the set of options that can be applied to a query reply error, sent via z_query_reply_err().

Public Members

struct z_owned_encoding_t *encoding

The encoding of the error payload.

Warning

doxygenstruct: Cannot find class “z_owned_fifo_handler_query_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_fifo_handler_query_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_owned_ring_handler_query_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_ring_handler_query_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

z_error_t z_declare_queryable(struct z_owned_queryable_t *this_, const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_owned_closure_query_t *callback, struct z_queryable_options_t *options)

Constructs a Queryable for the given key expression.

Parameters:

• this_ – An uninitialized memory location where queryable will be constructed.

• session – The zenoh session.

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

• callback – The callback function that will be called each time a matching query is received. Its ownership is passed to queryable.

• options – Options for the queryable.

Returns:

0 in case of success, negative error code otherwise (in this case )

z_error_t z_undeclare_queryable(struct z_owned_queryable_t *this_)

Undeclares a z_owned_queryable_t and drops it.

Returns 0 in case of success, negative error code otherwise.

void z_queryable_options_default(struct z_queryable_options_t *this_)

Constructs the default value for z_query_reply_options_t.

void z_query_reply_options_default(struct z_query_reply_options_t *this_)

Constructs the default value for z_query_reply_options_t.

void z_query_reply_err_options_default(struct z_query_reply_err_options_t *this_)

Constructs the default value for z_query_reply_err_options_t.

void z_queryable_null(struct z_owned_queryable_t *this_)

Constructs a queryable in its gravestone value.

bool z_queryable_check(const struct z_owned_queryable_t *this_)

Returns true if queryable is valid, false otherwise.

const struct z_loaned_queryable_t *z_queryable_loan(const struct z_owned_queryable_t *this_)

void z_queryable_drop(struct z_owned_queryable_t *this_)

Frees memory and resets it to its gravesztone state. Will also attempt to undeclare queryable.

void z_query_null(struct z_owned_query_t *this_)

Constructs query in its gravestone value.

bool z_query_check(const struct z_owned_query_t *query)

Returns false if this is in a gravestone state, true otherwise.

const struct z_loaned_query_t *z_query_loan(const struct z_owned_query_t *this_)

Borrows the query.

void z_query_drop(struct z_owned_query_t *this_)

Destroys the query resetting it to its gravestone value.

void z_query_clone(struct z_owned_query_t *dst, const struct z_loaned_query_t *this_)

Constructs a shallow copy of the query, allowing to keep it in an “open” state past the callback’s return.

This operation is infallible, but may return a gravestone value if query itself was a gravestone value (which cannot be the case in a callback).

const struct z_loaned_keyexpr_t *z_query_keyexpr(const struct z_loaned_query_t *this_)

Gets query key expression.

void z_query_parameters(const struct z_loaned_query_t *this_, struct z_view_string_t *parameters)

Gets query value selector.

Warning

doxygenfunction: Cannot find function “z_query_value” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

const struct z_loaned_bytes_t *z_query_attachment(const struct z_loaned_query_t *this_)

Gets query attachment.

Returns NULL if query does not contain an attachment.

z_error_t z_query_reply(const struct z_loaned_query_t *this_, const struct z_loaned_keyexpr_t *key_expr, struct z_owned_bytes_t *payload, struct z_query_reply_options_t *options)

Sends a reply to a query.

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

Parameters:

• this_ – The query to reply to.

• key_expr – The key of this reply.

• payload – The payload of this reply. Will be consumed.

• options – The options of this reply. All owned fields will be consumed.

Returns:

0 in case of success, negative error code otherwise.

z_error_t z_query_reply_err(const struct z_loaned_query_t *this_, struct z_owned_bytes_t *payload, struct z_query_reply_err_options_t *options)

Sends a error reply to a query.

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

Parameters:

• this_ – The query to reply to.

• payload – The payload carrying error message. Will be consumed.

• options – The options of this reply. All owned fields will be consumed.

Returns:

0 in case of success, negative error code otherwise.

void z_closure_query_null(struct z_owned_closure_query_t *this_)

Constructs a closure in its gravestone state.

bool z_closure_query_check(const struct z_owned_closure_query_t *this_)

Returns true if closure is valid, false if it is in gravestone state.

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

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

void z_closure_query_drop(struct z_owned_closure_query_t *closure)

Drops the closure, resetting it to its gravestone state.

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

Constructs send and recieve ends of the fifo channel

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

Constructs send and recieve ends of the ring channel

bool z_fifo_handler_query_check(const struct z_owned_fifo_handler_query_t *this_)

Returns true if handler is valid, false if it is in gravestone state.

void z_fifo_handler_query_null(struct z_owned_fifo_handler_query_t *this_)

Constructs a handler in gravestone state.

void z_fifo_handler_query_drop(struct z_owned_fifo_handler_query_t *this_)

Drops the handler and resets it to a gravestone state.

const struct z_loaned_fifo_handler_query_t *z_fifo_handler_query_loan(const struct z_owned_fifo_handler_query_t *this_)

Borrows handler.

bool z_fifo_handler_query_recv(const struct z_loaned_fifo_handler_query_t *this_, struct z_owned_query_t *query)

Returns query from the fifo buffer. If there are no more pending queries will block until next query is received, or until the channel is dropped (normally when Queryable is dropped). In the later case will return false and query will be in the gravestone state.

bool z_fifo_handler_query_try_recv(const struct z_loaned_fifo_handler_query_t *this_, struct z_owned_query_t *query)

Returns query from the fifo buffer. If there are no more pending queries will return immediately (with query set to its gravestone state). Will return false if the channel is dropped (normally when Queryable is dropped) and there are no more queries in the fifo.

bool z_ring_handler_query_check(const struct z_owned_ring_handler_query_t *this_)

Returns true if handler is valid, false if it is in gravestone state.

void z_ring_handler_query_null(struct z_owned_ring_handler_query_t *this_)

Constructs a handler in gravestone state.

void z_ring_handler_query_drop(struct z_owned_ring_handler_query_t *this_)

Drops the handler and resets it to a gravestone state.

const struct z_loaned_ring_handler_query_t *z_ring_handler_query_loan(const struct z_owned_ring_handler_query_t *this_)

Borrows handler.

bool z_ring_handler_query_recv(const struct z_loaned_ring_handler_query_t *this_, struct z_owned_query_t *query)

Returns query from the ring buffer. If there are no more pending queries will block until next query is received, or until the channel is dropped (normally when Queryable is dropped). In the later case will return false and query will be in the gravestone state.

bool z_ring_handler_query_try_recv(const struct z_loaned_ring_handler_query_t *this_, struct z_owned_query_t *query)

Returns query from the ring buffer. If there are no more pending queries will return immediately (with query set to its gravestone state). Will return false if the channel is dropped (normally when Queryable is dropped) and there are no more queries in the fifo.

Query

Types

Warning

doxygenstruct: Cannot find class “z_owned_reply_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_reply_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

struct z_owned_closure_reply_t

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

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

• call will never be called once drop has started.

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

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

Public Members

void *context

An optional pointer to a context representing a closure state.

void (*call)(const struct z_loaned_reply_t *reply, void *context)

A closure body.

void (*drop)(void *context)

An optional drop function that will be called when the closure is dropped.

struct z_get_options_t

Options passed to the z_get() function.

Public Members

enum z_query_target_t target

The Queryables that should be target of the query.

struct z_query_consolidation_t consolidation

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

struct z_owned_bytes_t *payload

An optional payload to attach to the query.

struct z_owned_encoding_t *encoding

An optional encoding of the query payload and or attachment.

enum z_congestion_control_t congestion_control

The congestion control to apply when routing the query.

enum zcu_locality_t allowed_destination

The allowed destination for the query.

enum zcu_reply_keyexpr_t accept_replies

The accepted replies for the query.

enum z_priority_t priority

The priority of the query.

struct z_owned_source_info_t *source_info

The source info for the query.

struct z_owned_bytes_t *attachment

An optional attachment to attach to the query.

uint64_t timeout_ms

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

enum z_query_target_t

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

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

All complete queryables.

enum z_consolidation_mode_t

Consolidation mode values.

Values:

enumerator Z_CONSOLIDATION_MODE_AUTO

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

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.

struct z_query_consolidation_t

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

Warning

doxygenstruct: Cannot find class “z_owned_fifo_handler_reply_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_fifo_handler_reply_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_owned_ring_handler_reply_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_ring_handler_reply_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Functions

z_error_t z_get(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, const char *parameters, struct z_owned_closure_reply_t *callback, struct z_get_options_t *options)

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

Parameters:

• session – The zenoh session.

• key_expr – The key expression matching resources to query.

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

• callback – The callback function that will be called on reception of replies for this query. It will be automatically dropped once all replies are processed.

• options – Additional options for the get. All owned fields will be consumed.

Returns:

0 in case of success, a negative error value upon failure.

void z_get_options_default(struct z_get_options_t *this_)

Constructs default z_get_options_t

struct z_query_consolidation_t z_query_consolidation_default(void)

Creates a default z_query_consolidation_t (consolidation mode AUTO).

struct z_query_consolidation_t z_query_consolidation_auto(void)

Automatic query consolidation strategy selection.

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

struct z_query_consolidation_t z_query_consolidation_none(void)

No consolidation.

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

struct z_query_consolidation_t z_query_consolidation_monotonic(void)

Monotonic consolidation.

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.

struct z_query_consolidation_t z_query_consolidation_latest(void)

Latest consolidation.

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

enum z_query_target_t z_query_target_default(void)

Create a default z_query_target_t.

bool z_reply_check(const struct z_owned_reply_t *this_)

Returns true if reply is valid, false otherwise.

void z_reply_drop(struct z_owned_reply_t *this_)

Frees reply, resetting it to its gravestone state.

void z_reply_clone(struct z_owned_reply_t *dst, const struct z_loaned_reply_t *this_)

Constructs an owned shallow copy of reply in provided uninitialized memory location.

bool z_reply_is_ok(const struct z_loaned_reply_t *this_)

Returns true if reply contains a valid response, false otherwise (in this case it contains a errror value).

const struct z_loaned_sample_t *z_reply_ok(const struct z_loaned_reply_t *this_)

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

Returns NULL if reply does not contain a sample (i. e. if z_reply_is_ok returns false).

const struct z_loaned_reply_err_t *z_reply_err(const struct z_loaned_reply_t *this_)

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

Returns NULL if reply does not contain a error (i. e. if z_reply_is_ok returns true).

void z_reply_null(struct z_owned_reply_t *this_)

Constructs the reply in its gravestone state.

void z_closure_reply_null(struct z_owned_closure_reply_t *this_)

Constructs a closure int its gravestone state.

bool z_closure_reply_check(const struct z_owned_closure_reply_t *this_)

Returns true if closure is valid, false if it is in gravestone state.

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

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

void z_closure_reply_drop(struct z_owned_closure_reply_t *closure)

Drops the closure, resetting it to its gravestone state. Droping an uninitialized closure is a no-op.

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

Constructs send and recieve ends of the fifo channel

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

Constructs send and recieve ends of the ring channel

bool z_fifo_handler_reply_check(const struct z_owned_fifo_handler_reply_t *this_)

Returns true if handler is valid, false if it is in gravestone state.

void z_fifo_handler_reply_null(struct z_owned_fifo_handler_reply_t *this_)

Constructs a handler in gravestone state.

void z_fifo_handler_reply_drop(struct z_owned_fifo_handler_reply_t *this_)

Drops the handler and resets it to a gravestone state.

const struct z_loaned_fifo_handler_reply_t *z_fifo_handler_reply_loan(const struct z_owned_fifo_handler_reply_t *this_)

Borrows handler.

bool z_fifo_handler_reply_recv(const struct z_loaned_fifo_handler_reply_t *this_, struct z_owned_reply_t *reply)

Returns reply from the fifo buffer. If there are no more pending replies will block until next reply is received, or until the channel is dropped (normally when all replies are received). In the later case will return false and reply will be in the gravestone state.

bool z_fifo_handler_reply_try_recv(const struct z_loaned_fifo_handler_reply_t *this_, struct z_owned_reply_t *reply)

Returns reply from the fifo buffer. If there are no more pending replies will return immediately (with reply set to its gravestone state). Will return false if the channel is dropped (normally when all replies are received) and there are no more replies in the fifo.

bool z_ring_handler_reply_check(const struct z_owned_ring_handler_reply_t *this_)

Returns true if handler is valid, false if it is in gravestone state.

void z_ring_handler_reply_null(struct z_owned_ring_handler_reply_t *this_)

Constructs a handler in gravestone state.

void z_ring_handler_reply_drop(struct z_owned_ring_handler_reply_t *this_)

Drops the handler and resets it to a gravestone state.

const struct z_loaned_ring_handler_reply_t *z_ring_handler_reply_loan(const struct z_owned_ring_handler_reply_t *this_)

Borrows handler.

bool z_ring_handler_reply_recv(const struct z_loaned_ring_handler_reply_t *this_, struct z_owned_reply_t *reply)

Returns reply from the ring buffer. If there are no more pending replies will block until next reply is received, or until the channel is dropped (normally when all replies are received). In the later case will return false and reply will be in the gravestone state.

bool z_ring_handler_reply_try_recv(const struct z_loaned_ring_handler_reply_t *this_, struct z_owned_reply_t *reply)

Returns reply from the ring buffer. If there are no more pending replies will return immediately (with reply set to its gravestone state). Will return false if the channel is dropped (normally when all replies are received) and there are no more replies in the fifo.

Scouting

Types

Warning

doxygenstruct: Cannot find class “z_owned_hello_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “z_loaned_hello_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

struct z_scout_options_t

Options to pass to z_scout().

Public Members

uint64_t timeout_ms

The maximum duration in ms the scouting can take.

enum z_what_t what

Type of entities to scout for.

struct z_owned_closure_hello_t

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

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

• call will never be called once drop has started.

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

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

Public Members

void *context

An optional pointer to a closure state.

void (*call)(const struct z_loaned_hello_t *hello, void *context)

A closure body.

void (*drop)(void *context)

An optional drop function that will be called when the closure is dropped.

Functions

z_error_t z_scout(struct z_owned_config_t *config, struct z_owned_closure_hello_t *callback, const struct z_scout_options_t *options)

Scout for routers and/or peers.

Parameters:

• config – A set of properties to configure scouting session.

• callback – A closure that will be called on each hello message received from discoverd Zenoh entities.

• options – A set of scouting options

Returns:

0 if successful, negative error values upon failure.

enum z_whatami_t z_hello_whatami(const struct z_loaned_hello_t *this_)

Returns type of Zenoh entity that transmitted hello message.

void z_hello_locators(const struct z_loaned_hello_t *this_, struct z_owned_string_array_t *locators_out)

Constructs an array of non-owned locators (in the form non-null-terminated strings) of Zenoh entity that sent hello message.

The lifetime of locator strings is bound to this_.

struct z_id_t z_hello_zid(const struct z_loaned_hello_t *this_)

Returns id of Zenoh entity that transmitted hello message.

const struct z_loaned_hello_t *z_hello_loan(const struct z_owned_hello_t *this_)

Borrows hello message.

void z_hello_drop(struct z_owned_hello_t *this_)

Frees memory and resets hello message to its gravestone state.

void z_hello_null(struct z_owned_hello_t *this_)

Constructs hello message in a gravestone state.

bool z_hello_check(const struct z_owned_hello_t *this_)

Returns true if hello message is valid, false if it is in a gravestone state.

z_error_t z_whatami_to_view_string(enum z_whatami_t whatami, struct 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.

• len – Maximum number of bytes that can be written to the buf.

Returns:

0 if successful, negative error values if whatami contains an invalid bitmask.

void z_scout_options_default(struct z_scout_options_t *this_)

Constructs the default values for the scouting operation.

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

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

void z_closure_hello_drop(struct z_owned_closure_hello_t *closure)

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

void z_closure_hello_null(struct z_owned_closure_hello_t *this_)

Constructs a closure in a gravestone state.

bool z_closure_hello_check(const struct z_owned_closure_hello_t *this_)

Returns true if closure is valid, false if it is in gravestone state.

Liveliness

Types

Warning

doxygenstruct: Cannot find class “zc_owned_liveliness_token_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

struct zc_liveliness_declaration_options_t

The options for zc_liveliness_declare_token().

struct zc_liveliness_get_options_t

The options for zc_liveliness_get()

struct zc_liveliness_subscriber_options_t

The options for zc_liveliness_declare_subscriber()

Functions

z_error_t zc_liveliness_declare_subscriber(struct z_owned_subscriber_t *this_, const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_owned_closure_sample_t *callback, struct zc_liveliness_subscriber_options_t *_options)

Declares a subscriber on liveliness tokens that intersect key_expr.

Parameters:

• this_ – An uninitialized memory location where subscriber will be constructed.

• session – The Zenoh session.

• key_expr – 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 in case of success, negative error values otherwise.

z_error_t zc_liveliness_get(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_owned_closure_reply_t *callback, struct zc_liveliness_get_options_t *options)

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

Parameters:

• session – The Zenoh session.

• key_expr – 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.

z_error_t zc_liveliness_declare_token(struct zc_owned_liveliness_token_t *this_, const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, const struct zc_liveliness_declaration_options_t *_options)

Constructs and declares a liveliness token on the network.

Liveliness token subscribers on an intersecting key expression will receive a PUT sample when connectivity is achieved, and a DELETE sample if it’s lost.

Parameters:

• this_ – An uninitialized memory location where liveliness token will be constructed.

• session – A Zenos session to declare the liveliness token.

• key_expr – A keyexpr to declare a liveliess token for.

• _options – Liveliness token declaration properties.

z_error_t zc_liveliness_undeclare_token(struct zc_owned_liveliness_token_t *this_)

Destroys a liveliness token, notifying subscribers of its destruction.

const struct zc_loaned_liveliness_token_t *zc_liveliness_token_loan(const struct zc_owned_liveliness_token_t *this_)

Borrows token.

void zc_liveliness_token_null(struct zc_owned_liveliness_token_t *this_)

Constructs liveliness token in its gravestone state.

bool zc_liveliness_token_check(const struct zc_owned_liveliness_token_t *this_)

Returns true if liveliness token is valid, false otherwise.

void zc_liveliness_token_drop(struct zc_owned_liveliness_token_t *this_)

Undeclares liveliness token, frees memory and resets it to a gravestone state.

void zc_liveliness_subscriber_options_default(struct zc_liveliness_subscriber_options_t *this_)

Constucts default value for zc_liveliness_declare_subscriber_options_t.

void zc_liveliness_declaration_options_default(struct zc_liveliness_declaration_options_t *this_)

Constructs default value for zc_liveliness_declaration_options_t.

void zc_liveliness_get_options_default(struct zc_liveliness_get_options_t *this_)

Constructs default value zc_liveliness_get_options_t.

Publication Cache

Types

Warning

doxygenstruct: Cannot find class “ze_owned_publication_cache_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

struct ze_publication_cache_options_t

Options passed to the ze_declare_publication_cache() function.

Public Members

const struct z_loaned_keyexpr_t *queryable_prefix

The prefix used for queryable.

bool queryable_complete

The complete option for the queryable.

size_t history

The the history size (i.e. maximum number of messages to store).

size_t resources_limit

The limit number of cached resources.

enum zcu_locality_t

The locality of samples to be received by subscribers or targeted by publishers.

Values:

enumerator ZCU_LOCALITY_ANY

Any

enumerator ZCU_LOCALITY_SESSION_LOCAL

Only from local sessions.

enumerator ZCU_LOCALITY_REMOTE

Only from remote sessions.

Functions

z_error_t ze_declare_publication_cache(struct ze_owned_publication_cache_t *this_, const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct ze_publication_cache_options_t *options)

Constructs and declares a publication cache.

Parameters:

• this_ – An uninitialized location in memory where publication cache will be constructed.

• session – A Zenoh session.

• key_expr – The key expression to publish to.

• options – Additional options for the publication cache.

Returns:

0 in case of success, negative error code otherwise.

z_error_t ze_undeclare_publication_cache(struct ze_owned_publication_cache_t *this_)

Undeclares and drops publication cache.

Returns:

0 in case of success, negative error code otherwise.

bool ze_publication_cache_check(const struct ze_owned_publication_cache_t *this_)

Returns true if publication cache is valid, false otherwise.

void ze_publication_cache_null(struct ze_owned_publication_cache_t *this_)

Constructs a publication cache in a gravestone state.

void ze_publication_cache_drop(struct ze_owned_publication_cache_t *this_)

Drops publication cache. Also attempts to undeclare it.

void ze_publication_cache_options_default(struct ze_publication_cache_options_t *this_)

Constructs the default value for ze_publication_cache_options_t.

Querying Subscriber

Types

Warning

doxygenstruct: Cannot find class “ze_owned_querying_subscriber_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

Warning

doxygenstruct: Cannot find class “ze_loaned_querying_subscriber_t” in doxygen xml output for project “zenoh-c” from directory: ./doxyxml/xml/

struct ze_querying_subscriber_options_t

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

Public Members

enum z_reliability_t reliability

The subscription reliability.

const struct z_loaned_keyexpr_t *query_selector

The selector to be used for queries.

enum z_query_target_t query_target

The target to be used for queries.

struct z_query_consolidation_t query_consolidation

The consolidation mode to be used for queries.

enum zcu_reply_keyexpr_t query_accept_replies

The accepted replies for queries.

uint64_t query_timeout_ms

The timeout to be used for queries.

enum zcu_reply_keyexpr_t

Key expressions types to which Queryable should reply to.

Values:

enumerator ZCU_REPLY_KEYEXPR_ANY

Replies to any key expression queries.

enumerator ZCU_REPLY_KEYEXPR_MATCHING_QUERY

Replies only to queries with intersecting key expressions.

Functions

z_error_t ze_declare_querying_subscriber(struct ze_owned_querying_subscriber_t *this_, const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_owned_closure_sample_t *callback, struct ze_querying_subscriber_options_t *options)

Constructs and declares a querying subscriber for a given key expression.

Parameters:

• this_ – An uninitialized memory location where querying subscriber will be constructed.

• session – A Zenoh session.

• key_expr – A key expression to subscribe to.

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

• options – Additional options for the querying subscriber.

Returns:

0 in case of success, negative error code otherwise.

z_error_t ze_undeclare_querying_subscriber(struct ze_owned_querying_subscriber_t *this_)

Undeclares the given querying subscriber, drops it and resets to a gravestone state.

Returns:

0 in case of success, negative error code otherwise.

z_error_t ze_querying_subscriber_get(const struct ze_loaned_querying_subscriber_t *this_, const struct z_loaned_keyexpr_t *selector, const struct z_get_options_t *options)

Make querying subscriber perform an additional query on a specified selector. The queried samples will be merged with the received publications and made available in the subscriber callback.

Returns:

0 in case of success, negative error code otherwise.

bool ze_querying_subscriber_check(const struct ze_owned_querying_subscriber_t *this_)

Returns true if querying subscriber is valid, false otherwise.

void ze_querying_subscriber_null(struct ze_owned_querying_subscriber_t *this_)

Constructs a querying subscriber in a gravestone state.

void ze_querying_subscriber_drop(struct ze_owned_querying_subscriber_t *this_)

Drops querying subscriber. Also attempts to undeclare it.

void ze_querying_subscriber_options_default(struct ze_querying_subscriber_options_t *this_)

Constructs the default value for ze_querying_subscriber_options_t.

enum zcu_reply_keyexpr_t zcu_reply_keyexpr_default(void)

Returns the default value of zcu_reply_keyexpr_t.