API Reference

Containers

Slice

Types

struct z_owned_slice_t

struct z_view_slice_t

A contiguous sequence of bytes owned by some other entity.

struct z_loaned_slice_t

A loaned sequence of bytes.

Functions

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_moved_slice_t *this_)

Frees the memory and invalidates the slice.

void z_slice_clone(struct z_owned_slice_t *dst, const struct z_loaned_slice_t *this_)

Constructs an owned copy of a slice.

void z_slice_empty(struct z_owned_slice_t *this_)

Constructs an empty z_owned_slice_t.

z_result_t z_slice_copy_from_buf(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_result_t z_slice_from_buf(struct z_owned_slice_t *this_, uint8_t *data, size_t len, void (*drop)(void *data, void *context), void *context)

Constructs a slice by transferring ownership of data to it.

Parameters:

• this_ – Pointer to an uninitialized memoery location where slice will be constructed.

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

• len – Number of bytes in data.

• drop – A thread-safe delete function to free the data. Will be called once when this_ is dropped. Can be NULL, in case if data is allocated in static memory.

• context – An optional context to be passed to the deleter.

Returns:

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

void z_view_slice_empty(struct z_view_slice_t *this_)

Constructs an empty view slice.

z_result_t z_view_slice_from_buf(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.

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

struct z_owned_string_t

The wrapper type for strings allocated by Zenoh.

struct z_view_string_t

The view over a string.

struct z_loaned_string_t

A loaned string.

Functions

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

Borrows string.

const struct z_loaned_string_t *z_view_string_loan(const struct z_view_string_t *this_)

Borrows view string.

void z_string_drop(struct z_moved_string_t *this_)

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

void z_string_clone(struct z_owned_string_t *dst, const struct z_loaned_string_t *this_)

Constructs an owned copy of a string.

void z_string_empty(struct z_owned_string_t *this_)

Constructs an empty owned string.

void z_view_string_empty(struct z_view_string_t *this_)

Constructs an empty view string.

z_result_t z_string_copy_from_str(struct z_owned_string_t *this_, const char *str)

Constructs an owned string by copying str into it (including terminating 0), using strlen (this should therefore not be used with untrusted inputs).

Returns:

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

z_result_t z_view_string_from_str(struct z_view_string_t *this_, const char *str)

Constructs a view string of str, using strlen (this should therefore not be used with untrusted inputs).

Returns:

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

z_result_t z_string_copy_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.

z_result_t z_view_string_from_substr(struct z_view_string_t *this_, const char *str, size_t len)

Constructs a view string to a specified substring of length len.

Returns:

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

z_result_t z_string_from_str(struct z_owned_string_t *this_, char *str, void (*drop)(void *value, void *context), void *context)

Constructs an owned string by transferring ownership of a null-terminated string str to it.

Parameters:

• this_ – Pointer to an uninitialized memory location where an owned string will be constructed.

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

• drop – A thread-safe delete function to free the str. Will be called once when str is dropped. Can be NULL, in case if str is allocated in static memory.

• context – An optional context to be passed to the deleter.

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.

const struct z_loaned_slice_t *z_string_as_slice(const struct z_loaned_string_t *this_)

String Array

Types

struct z_owned_string_array_t

An array of maybe-owned non-null terminated strings.

struct z_loaned_string_array_t

A loaned string array.

Functions

void z_string_array_drop(struct z_moved_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_clone(struct z_owned_string_array_t *dst, const struct z_loaned_string_array_t *this_)

Constructs an owned copy of a string array.

void z_string_array_new(struct z_owned_string_array_t *this_)

Constructs a new empty string array.

size_t z_string_array_push_by_alias(struct z_loaned_string_array_t *this_, const struct z_loaned_string_t *value)

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

Returns:

the new length of the array.

size_t z_string_array_push_by_copy(struct z_loaned_string_array_t *this_, const struct z_loaned_string_t *value)

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

Returns:

the new length of the 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

struct z_owned_bytes_t

A serialized Zenoh data.

To minimize copies and reallocations, Zenoh may provide data in several separate buffers.

struct z_loaned_bytes_t

A loaned serialized Zenoh data.

struct z_bytes_reader_t

A reader for payload.

struct z_owned_bytes_writer_t

An owned writer for payload.

struct z_loaned_bytes_writer_t

An loaned writer for payload.

struct ze_owned_serializer_t

An owned Zenoh serializer.

struct ze_loaned_serializer_t

A loaned Zenoh serializer.

struct ze_deserializer_t

A Zenoh serializer.

Functions

size_t z_bytes_len(const struct z_loaned_bytes_t *this_)

Returns total number of bytes in the payload.

void z_bytes_copy_from_slice(struct z_owned_bytes_t *this_, const struct z_loaned_slice_t *slice)

Converts a slice into z_owned_bytes_t by copying.

void z_bytes_from_slice(struct z_owned_bytes_t *this_, struct z_moved_slice_t *slice)

Converts a slice into z_owned_bytes_t. The slice is consumed upon function return.

z_result_t z_bytes_copy_from_buf(struct z_owned_bytes_t *this_, const uint8_t *data, size_t len)

Converts a data from buffer into z_owned_bytes_t by copying.

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• data – A pointer to the buffer containing data.

• len – Length of the buffer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_bytes_from_buf(struct z_owned_bytes_t *this_, uint8_t *data, size_t len, void (*deleter)(void *data, void *context), void *context)

Converts buffer into z_owned_bytes_t.

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• data – A pointer to the buffer containing data. this_ will take ownership of the buffer.

• len – Length of the buffer.

• deleter – A thread-safe function, that will be called on data when this_ is dropped. Can be NULL if data is located in static memory and does not require a drop.

• context – An optional context to be passed to deleter.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_bytes_from_static_buf(struct z_owned_bytes_t *this_, uint8_t *data, size_t len)

Converts a statically allocated constant buffer into z_owned_bytes_t.

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• data – A pointer to the statically allocated constant data.

• len – A length of the buffer.

Returns:

0 in case of success, negative error code otherwise.

void z_bytes_copy_from_string(struct z_owned_bytes_t *this_, const struct z_loaned_string_t *str)

Converts a string into z_owned_bytes_t by copying.

void z_bytes_from_string(struct z_owned_bytes_t *this_, struct z_moved_string_t *s)

Converts a string into z_owned_bytes_t. The string is consumed upon function return.

z_result_t z_bytes_copy_from_str(struct z_owned_bytes_t *this_, const char *str)

Converts a null-terminated string into z_owned_bytes_t by copying.

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• str – a pointer to the null-terminated string.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_bytes_from_str(struct z_owned_bytes_t *this_, char *str, void (*deleter)(void *data, void *context), void *context)

Converts a null-terminated string into z_owned_bytes_t.

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• str – a pointer to the string. this_ will take ownership of the string.

• deleter – A thread-safe function, that will be called on str when this_ is dropped. Can be NULL if str is located in static memory and does not require a drop.

• context – An optional context to be passed to deleter.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_bytes_from_static_str(struct z_owned_bytes_t *this_, const char *str)

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

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• str – a pointer to the statically allocated constant string.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_bytes_to_slice(const struct z_loaned_bytes_t *this_, struct z_owned_slice_t *dst)

Converts data into an owned slice.

Parameters:

• this_ – Data to convert.

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

z_result_t z_bytes_to_string(const struct z_loaned_bytes_t *this_, struct z_owned_string_t *dst)

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

Parameters:

• this_ – Data to convert.

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

z_result_t ze_serialize_slice(struct z_owned_bytes_t *this_, const struct z_loaned_slice_t *slice)

Serializes a slice.

z_result_t ze_serialize_buf(struct z_owned_bytes_t *this_, const uint8_t *data, size_t len)

Serializes a data from buffer by.

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• data – A pointer to the buffer containing data.

• len – Length of the buffer.

z_result_t ze_serialize_string(struct z_owned_bytes_t *this_, const struct z_loaned_string_t *str)

Serializes a string. The string should be a valid UTF-8.

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• str – a string to serialize.

z_result_t ze_serialize_str(struct z_owned_bytes_t *this_, const char *str)

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

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• str – a pointer to the null-terminated string.

z_result_t ze_serialize_substr(struct z_owned_bytes_t *this_, const char *start, size_t len)

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

Parameters:

• this_ – An uninitialized location in memory where z_owned_bytes_t is to be constructed.

• start – a pointer to the the start of the substring.

• len – the length of the substring.

z_result_t ze_serialize_uint8(struct z_owned_bytes_t *this_, uint8_t val)

Serializes an unsigned integer.

z_result_t ze_serialize_uint16(struct z_owned_bytes_t *this_, uint16_t val)

Serializes an unsigned integer.

z_result_t ze_serialize_uint32(struct z_owned_bytes_t *this_, uint32_t val)

Serializes an unsigned integer.

z_result_t ze_serialize_uint64(struct z_owned_bytes_t *this_, uint64_t val)

Serializes an unsigned integer.

z_result_t ze_serialize_int8(struct z_owned_bytes_t *this_, int8_t val)

Serializes a signed integer.

z_result_t ze_serialize_int16(struct z_owned_bytes_t *this_, int16_t val)

Serializes a signed integer.

z_result_t ze_serialize_int32(struct z_owned_bytes_t *this_, int32_t val)

Serializes a signed integer.

z_result_t ze_serialize_int64(struct z_owned_bytes_t *this_, int64_t val)

Serializes a signed integer.

z_result_t ze_serialize_float(struct z_owned_bytes_t *this_, float val)

Serializes a float.

z_result_t ze_serialize_double(struct z_owned_bytes_t *this_, double val)

Serializes a double.

z_result_t ze_serialize_bool(struct z_owned_bytes_t *this_, bool val)

Serializes a bool.

z_result_t ze_deserialize_slice(const struct z_loaned_bytes_t *this_, struct z_owned_slice_t *slice)

Deserializes into a slice.

z_result_t ze_deserialize_string(const struct z_loaned_bytes_t *this_, struct z_owned_string_t *str)

Deserializes into a UTF-8 string.

z_result_t ze_deserialize_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_result_t ze_deserialize_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_result_t ze_deserialize_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_result_t ze_deserialize_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_result_t ze_deserialize_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_result_t ze_deserialize_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_result_t ze_deserialize_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_result_t ze_deserialize_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_result_t ze_deserialize_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_result_t ze_deserialize_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.

z_result_t ze_deserialize_bool(const struct z_loaned_bytes_t *this_, bool *dst)

Deserializes into a bool.

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_drop(struct z_moved_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_result_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.

Returns:

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

size_t z_bytes_reader_remaining(const struct z_bytes_reader_t *this_)

Gets the number of bytes that can still be read.

z_result_t z_bytes_writer_empty(struct z_owned_bytes_writer_t *this_)

Constructs a data writer with empty payload.

Parameters:

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

Returns:

0 in case of success, negative error code otherwise.

void z_bytes_writer_finish(struct z_moved_bytes_writer_t *this_, struct z_owned_bytes_t *bytes)

Drop writer and extract underlying bytes object it was writing to.

Parameters:

• this_ – A writer instance.

• bytes – An uninitialized memory location where bytes object` will be written to.

z_result_t z_bytes_writer_write_all(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.

z_result_t z_bytes_writer_append(struct z_loaned_bytes_writer_t *this_, struct z_moved_bytes_t *bytes)

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

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_serializer_empty(struct ze_owned_serializer_t *this_)

Constructs a serializer with empty payload.

Parameters:

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

Returns:

0 in case of success, negative error code otherwise.

void ze_serializer_finish(struct ze_moved_serializer_t *this_, struct z_owned_bytes_t *bytes)

Drop serializer and extract underlying bytes object it was writing to.

Parameters:

• this_ – A serializer instance.

• bytes – An uninitialized memory location where bytes object` will be written to.

z_result_t ze_serializer_serialize_slice(struct ze_loaned_serializer_t *this_, const struct z_loaned_slice_t *slice)

Serializes a slice.

z_result_t ze_serializer_serialize_buf(struct ze_loaned_serializer_t *this_, const uint8_t *data, size_t len)

Serializes a data from buffer.

Parameters:

• this_ – A serializer instance.

• data – A pointer to the buffer containing data.

• len – Length of the buffer.

z_result_t ze_serializer_serialize_string(struct ze_loaned_serializer_t *this_, const struct z_loaned_string_t *str)

Serializes a string. The string should be a valid UTF-8.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_serializer_serialize_str(struct ze_loaned_serializer_t *this_, const char *str)

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

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_serializer_serialize_substr(struct ze_loaned_serializer_t *this_, const char *start, size_t len)

Serializes a substring of specified length. The subsstring should be a valid UTF-8.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_serializer_serialize_uint8(struct ze_loaned_serializer_t *this_, uint8_t val)

Serializes an unsigned integer.

z_result_t ze_serializer_serialize_uint16(struct ze_loaned_serializer_t *this_, uint16_t val)

Serializes an unsigned integer.

z_result_t ze_serializer_serialize_uint32(struct ze_loaned_serializer_t *this_, uint32_t val)

Serializes an unsigned integer.

z_result_t ze_serializer_serialize_uint64(struct ze_loaned_serializer_t *this_, uint64_t val)

Serializes an unsigned integer.

z_result_t ze_serializer_serialize_int8(struct ze_loaned_serializer_t *this_, int8_t val)

Serializes a signed integer.

z_result_t ze_serializer_serialize_int16(struct ze_loaned_serializer_t *this_, int16_t val)

Serializes a signed integer.

z_result_t ze_serializer_serialize_int32(struct ze_loaned_serializer_t *this_, int32_t val)

Serializes a signed integer.

z_result_t ze_serializer_serialize_int64(struct ze_loaned_serializer_t *this_, int64_t val)

Serializes a signed integer.

z_result_t ze_serializer_serialize_float(struct ze_loaned_serializer_t *this_, float val)

Serializes a float.

z_result_t ze_serializer_serialize_double(struct ze_loaned_serializer_t *this_, double val)

Serializes a double.

z_result_t ze_serializer_serialize_bool(struct ze_loaned_serializer_t *this_, bool val)

Serializes a bool.

z_result_t ze_serializer_serialize_sequence_length(struct ze_loaned_serializer_t *this_, size_t len)

Initiates serialization of a sequence of multiple elements.

Parameters:

• this_ – A serializer instance.

• len – Length of the sequence. Could be read during deserialization using ze_deserializer_deserialize_sequence_length.

struct ze_deserializer_t ze_deserializer_from_bytes(const struct z_loaned_bytes_t *this_)

Gets deserializer forthis_.

bool ze_deserializer_is_done(const struct ze_deserializer_t *this_)

Checks if deserializer parsed all of its data.

Returns:

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

z_result_t ze_deserializer_deserialize_slice(struct ze_deserializer_t *this_, struct z_owned_slice_t *slice)

Deserializes into a slice.

z_result_t ze_deserializer_deserialize_string(struct ze_deserializer_t *this_, struct z_owned_string_t *str)

Deserializes into a string.

z_result_t ze_deserializer_deserialize_uint8(struct ze_deserializer_t *this_, uint8_t *dst)

Deserializes into an unsigned integer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_uint16(struct ze_deserializer_t *this_, uint16_t *dst)

Deserializes into an unsigned integer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_uint32(struct ze_deserializer_t *this_, uint32_t *dst)

Deserializes into an unsigned integer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_uint64(struct ze_deserializer_t *this_, uint64_t *dst)

Deserializes into an unsigned integer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_int8(struct ze_deserializer_t *this_, int8_t *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_int16(struct ze_deserializer_t *this_, int16_t *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_int32(struct ze_deserializer_t *this_, int32_t *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_int64(struct ze_deserializer_t *this_, int64_t *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_float(struct ze_deserializer_t *this_, float *dst)

Deserializes into a float.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_double(struct ze_deserializer_t *this_, double *dst)

Deserializes into a signed integer.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_bool(struct ze_deserializer_t *this_, bool *dst)

Deserializes into a bool.

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_deserializer_deserialize_sequence_length(struct ze_deserializer_t *this_, size_t *len)

Initiates deserialization of a sequence of multiple elements.

Parameters:

• this_ – A serializer instance.

• len – pointer where the length of the sequence (previously passed via z_bytes_writer_serialize_sequence_begin) will be written.

Returns:

0 in case of success, negative error code otherwise.

Key expression

Types

struct z_owned_keyexpr_t

A Zenoh-allocated key expression .

Key expressions can identify a single key or a set of keys.

Examples :

• "key/expression".

• "key/ex*".

Key expressions can be mapped to numerical ids through z_declare_keyexpr for wire and computation efficiency.

Internally key expressiobn can be either:

• A plain string expression.

• A pure numerical id.

• The combination of a numerical prefix and a string suffix.

struct z_view_keyexpr_t

A user allocated string, viewed as a key expression.

struct z_loaned_keyexpr_t

A loaned key expression.

Key expressions can identify a single key or a set of keys.

Examples :

• "key/expression".

• "key/ex*".

Using z_declare_keyexpr allows Zenoh to optimize a key expression, both for local processing and network-wise.

enum z_keyexpr_intersection_level_t

Intersection level of 2 key expressions.

Warning

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

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

z_result_t z_keyexpr_from_str(struct z_owned_keyexpr_t *this_, const char *expr)

Constructs a z_owned_keyexpr_t from a string, copying the passed string.

Returns:

0 in case of success, negative error code in case of failure (for example if expr is not a valid key expression or if it is not in canon form.

z_result_t z_view_keyexpr_from_str(struct z_view_keyexpr_t *this_, const char *expr)

Constructs a z_view_keyexpr_t by aliasing a string.

Returns:

0 in case of success, negative error code in case of failure (for example if expr is not a valid key expression or if it is not in canon form. expr must outlive the constucted key expression.

z_result_t z_keyexpr_from_str_autocanonize(struct z_owned_keyexpr_t *this_, const char *expr)

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

Returns:

0 in case of success, negative error code in case of failure (for example if expr is not a valid key expression even despite canonization).

z_result_t z_view_keyexpr_from_str_autocanonize(struct z_view_keyexpr_t *this_, char *expr)

Constructs a z_view_keyexpr_t by aliasing a string. The string is canonized in-place before being passed to keyexpr, possibly shortening it by modifying len. May SEGFAULT if expr is NULL or lies in read-only memory (as values initialized with string litterals do). expr must outlive the constucted key expression.

void z_view_keyexpr_from_str_unchecked(struct z_view_keyexpr_t *this_, const char *s)

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

• s MUST be valid UTF8.

• s 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.

s must outlive constructed key expression.

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

• start – 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_result_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

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

void z_keyexpr_clone(struct z_owned_keyexpr_t *dst, const struct z_loaned_keyexpr_t *this_)

Constructs a copy of the key expression.

void z_keyexpr_drop(struct z_moved_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_result_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_result_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_result_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_result_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_result_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.

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

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

Note

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

Warning

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

z_result_t z_declare_keyexpr(const struct z_loaned_session_t *session, struct z_owned_keyexpr_t *declared_key_expr, 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:

• session – Session on which to declare key expression.

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

• key_expr – Key expression to declare on network.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_undeclare_keyexpr(const struct z_loaned_session_t *session, struct z_moved_keyexpr_t *key_expr)

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

struct z_owned_encoding_t

The encoding of Zenoh data.

struct z_loaned_encoding_t

A loaned Zenoh encoding.

Functions

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

Borrows encoding.

struct z_loaned_encoding_t *z_encoding_loan_mut(struct z_owned_encoding_t *this_)

Mutably borrows encoding.

void z_encoding_drop(struct z_moved_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_result_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_result_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.

z_result_t z_encoding_set_schema_from_str(struct z_loaned_encoding_t *this_, const char *s)

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

z_result_t z_encoding_set_schema_from_substr(struct z_loaned_encoding_t *this_, const char *s, size_t len)

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

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.

bool z_encoding_equals(const struct z_loaned_encoding_t *this_, const struct z_loaned_encoding_t *other)

Returns true if this_ equals to other, false otherwise.

void z_encoding_clone(struct z_owned_encoding_t *dst, const struct z_loaned_encoding_t *this_)

Constructs an owned copy of the encoding in provided uninitilized memory location.

Predefined Encodings

const struct z_loaned_encoding_t *z_encoding_zenoh_bytes(void)

Just some bytes.

Constant alias for string: "zenoh/bytes".

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

const struct z_loaned_encoding_t *z_encoding_zenoh_string(void)

A UTF-8 string.

Constant alias for string: "zenoh/string".

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

const struct z_loaned_encoding_t *z_encoding_zenoh_serialized(void)

Zenoh serialized data.

Constant alias for string: "zenoh/serialized".

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

const struct z_loaned_encoding_t *z_encoding_application_octet_stream(void)

An application-specific stream of bytes.

Constant alias for string: "application/octet-stream".

const struct z_loaned_encoding_t *z_encoding_text_plain(void)

A textual file.

Constant alias for string: "text/plain".

const struct z_loaned_encoding_t *z_encoding_application_json(void)

JSON data intended to be consumed by an application.

Constant alias for string: "application/json".

const struct z_loaned_encoding_t *z_encoding_text_json(void)

JSON data intended to be human readable.

Constant alias for string: "text/json".

const struct z_loaned_encoding_t *z_encoding_application_cdr(void)

A Common Data Representation (CDR)-encoded data.

Constant alias for string: "application/cdr".

const struct z_loaned_encoding_t *z_encoding_application_cbor(void)

A Concise Binary Object Representation (CBOR)-encoded data.

Constant alias for string: "application/cbor".

const struct z_loaned_encoding_t *z_encoding_application_yaml(void)

YAML data intended to be consumed by an application.

Constant alias for string: "application/yaml".

const struct z_loaned_encoding_t *z_encoding_text_yaml(void)

YAML data intended to be human readable.

Constant alias for string: "text/yaml".

const struct z_loaned_encoding_t *z_encoding_text_json5(void)

JSON5 encoded data that are human readable.

Constant alias for string: "text/json5".

const struct z_loaned_encoding_t *z_encoding_application_python_serialized_object(void)

A Python object serialized using pickle.

Constant alias for string: "application/python-serialized-object".

const struct z_loaned_encoding_t *z_encoding_application_protobuf(void)

An application-specific protobuf-encoded data.

Constant alias for string: "application/protobuf".

const struct z_loaned_encoding_t *z_encoding_application_java_serialized_object(void)

A Java serialized object.

Constant alias for string: "application/java-serialized-object".

const struct z_loaned_encoding_t *z_encoding_application_openmetrics_text(void)

An openmetrics data, common used by Prometheus.

Constant alias for string: "application/openmetrics-text".

const struct z_loaned_encoding_t *z_encoding_image_png(void)

A Portable Network Graphics (PNG) image.

Constant alias for string: "image/png".

const struct z_loaned_encoding_t *z_encoding_image_jpeg(void)

A Joint Photographic Experts Group (JPEG) image.

Constant alias for string: "image/jpeg".

const struct z_loaned_encoding_t *z_encoding_image_gif(void)

A Graphics Interchange Format (GIF) image.

Constant alias for string: "image/gif".

const struct z_loaned_encoding_t *z_encoding_image_bmp(void)

A BitMap (BMP) image.

Constant alias for string: "image/bmp".

const struct z_loaned_encoding_t *z_encoding_image_webp(void)

A Web Portable (WebP) image.

Constant alias for string: "image/webp".

const struct z_loaned_encoding_t *z_encoding_application_xml(void)

An XML file intended to be consumed by an application..

Constant alias for string: "application/xml".

const struct z_loaned_encoding_t *z_encoding_application_x_www_form_urlencoded(void)

An encoded a list of tuples, each consisting of a name and a value.

Constant alias for string: "application/x-www-form-urlencoded".

const struct z_loaned_encoding_t *z_encoding_text_html(void)

An HTML file.

Constant alias for string: "text/html".

const struct z_loaned_encoding_t *z_encoding_text_xml(void)

An XML file that is human readable.

Constant alias for string: "text/xml".

const struct z_loaned_encoding_t *z_encoding_text_css(void)

A CSS file.

Constant alias for string: "text/css".

const struct z_loaned_encoding_t *z_encoding_text_javascript(void)

A JavaScript file.

Constant alias for string: "text/javascript".

const struct z_loaned_encoding_t *z_encoding_text_markdown(void)

A MarkDown file.

Constant alias for string: "text/markdown".

const struct z_loaned_encoding_t *z_encoding_text_csv(void)

A CSV file.

Constant alias for string: "text/csv".

const struct z_loaned_encoding_t *z_encoding_application_sql(void)

An application-specific SQL query.

Constant alias for string: "application/sql".

const struct z_loaned_encoding_t *z_encoding_application_coap_payload(void)

Constrained Application Protocol (CoAP) data intended for CoAP-to-HTTP and HTTP-to-CoAP proxies.

Constant alias for string: "application/coap-payload".

const struct z_loaned_encoding_t *z_encoding_application_json_patch_json(void)

Defines a JSON document structure for expressing a sequence of operations to apply to a JSON document.

Constant alias for string: "application/json-patch+json".

const struct z_loaned_encoding_t *z_encoding_application_json_seq(void)

A JSON text sequence consists of any number of JSON texts, all encoded in UTF-8.

Constant alias for string: "application/json-seq".

const struct z_loaned_encoding_t *z_encoding_application_jsonpath(void)

A JSONPath defines a string syntax for selecting and extracting JSON values from within a given JSON value.

Constant alias for string: "application/jsonpath".

const struct z_loaned_encoding_t *z_encoding_application_jwt(void)

A JSON Web Token (JWT).

Constant alias for string: "application/jwt".

const struct z_loaned_encoding_t *z_encoding_application_mp4(void)

An application-specific MPEG-4 encoded data, either audio or video.

Constant alias for string: "application/mp4".

const struct z_loaned_encoding_t *z_encoding_application_soap_xml(void)

A SOAP 1.2 message serialized as XML 1.0.

Constant alias for string: "application/soap+xml".

const struct z_loaned_encoding_t *z_encoding_application_yang(void)

A YANG-encoded data commonly used by the Network Configuration Protocol (NETCONF).

Constant alias for string: "application/yang".

const struct z_loaned_encoding_t *z_encoding_audio_aac(void)

A MPEG-4 Advanced Audio Coding (AAC) media.

Constant alias for string: "audio/aac".

const struct z_loaned_encoding_t *z_encoding_audio_flac(void)

A Free Lossless Audio Codec (FLAC) media.

Constant alias for string: "audio/flac".

const struct z_loaned_encoding_t *z_encoding_audio_mp4(void)

An audio codec defined in MPEG-1, MPEG-2, MPEG-4, or registered at the MP4 registration authority.

Constant alias for string: "audio/mp4".

const struct z_loaned_encoding_t *z_encoding_audio_ogg(void)

An Ogg-encapsulated audio stream.

Constant alias for string: "audio/ogg".

const struct z_loaned_encoding_t *z_encoding_audio_vorbis(void)

A Vorbis-encoded audio stream.

Constant alias for string: "audio/vorbis".

const struct z_loaned_encoding_t *z_encoding_video_h261(void)

A h261-encoded video stream.

Constant alias for string: "video/h261".

const struct z_loaned_encoding_t *z_encoding_video_h263(void)

A h263-encoded video stream.

Constant alias for string: "video/h263".

const struct z_loaned_encoding_t *z_encoding_video_h264(void)

A h264-encoded video stream.

Constant alias for string: "video/h264".

const struct z_loaned_encoding_t *z_encoding_video_h265(void)

A h265-encoded video stream.

Constant alias for string: "video/h265".

const struct z_loaned_encoding_t *z_encoding_video_h266(void)

A h266-encoded video stream.

Constant alias for string: "video/h266".

const struct z_loaned_encoding_t *z_encoding_video_mp4(void)

A video codec defined in MPEG-1, MPEG-2, MPEG-4, or registered at the MP4 registration authority.

Constant alias for string: "video/mp4".

const struct z_loaned_encoding_t *z_encoding_video_ogg(void)

An Ogg-encapsulated video stream.

Constant alias for string: "video/ogg".

const struct z_loaned_encoding_t *z_encoding_video_raw(void)

An uncompressed, studio-quality video stream.

Constant alias for string: "video/raw".

const struct z_loaned_encoding_t *z_encoding_video_vp8(void)

A VP8-encoded video stream.

Constant alias for string: "video/vp8".

const struct z_loaned_encoding_t *z_encoding_video_vp9(void)

A VP9-encoded video stream.

Constant alias for string: "video/vp9".

Reply Error

Types

struct z_owned_reply_err_t

A Zenoh reply error - a combination of reply error payload and its encoding.

struct z_loaned_reply_err_t

A loaned Zenoh reply error.

Functions

const struct z_loaned_bytes_t *z_reply_err_payload(const struct z_loaned_reply_err_t *this_)

Returns reply error payload.

const struct z_loaned_encoding_t *z_reply_err_encoding(const struct z_loaned_reply_err_t *this_)

Returns reply error encoding.

const struct z_loaned_reply_err_t *z_reply_err_loan(const struct z_owned_reply_err_t *this_)

Borrows reply error.

void z_reply_err_clone(struct z_owned_reply_err_t *dst, const struct z_loaned_reply_err_t *this_)

Constructs a copy of the reply error message.

void z_reply_err_drop(struct z_moved_reply_err_t *this_)

Frees the memory and resets the reply error it to its default value.

Sample

Types

struct z_owned_sample_t

An owned Zenoh sample.

This is a read only type that can only be constructed by cloning a z_loaned_sample_t. Like all owned types, it should be freed using z_drop or z_sample_drop.

struct z_loaned_sample_t

A loaned Zenoh sample.

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.

void z_sample_drop(struct z_moved_sample_t *this_)

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

void z_sample_clone(struct z_owned_sample_t *dst, const struct z_loaned_sample_t *this_)

Constructs an owned shallow copy of the sample (i.e. all modficiations applied to the copy, might be visible in the original) in provided uninitilized memory location.

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

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.

enum z_reliability_t z_sample_reliability(const struct z_loaned_sample_t *this_)

Returns the reliability setting the sample was delivered with.

Warning

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

const struct z_loaned_keyexpr_t *z_sample_keyexpr(const struct z_loaned_sample_t *this_)

Returns the key expression of the sample.

enum z_sample_kind_t z_sample_kind(const struct z_loaned_sample_t *this_)

Returns the sample kind.

Timestamp

Types

struct z_timestamp_t

A Zenoh timestamp .

It consists of a time generated by a Hybrid Logical Clock (HLC) in NPT64 format and a unique zenoh identifier.

Functions

struct z_id_t z_timestamp_id(const struct z_timestamp_t *this_)

Returns id associated with this timestamp.

uint64_t z_timestamp_ntp64_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

z_result_t z_sleep_s(size_t time)

Puts current thread to sleep for specified amount of seconds.

z_result_t z_sleep_ms(size_t time)

Puts current thread to sleep for specified amount of milliseconds.

z_result_t z_sleep_us(size_t time)

Puts current thread to sleep for specified amount of microseconds.

Time

Types

struct z_clock_t

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)

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

struct z_owned_mutex_t

An owned mutex.

struct z_loaned_mutex_t

A loaned mutex.

Functions

struct z_loaned_mutex_t *z_mutex_loan_mut(struct z_owned_mutex_t *this_)

Mutably borrows mutex.

void z_mutex_drop(struct z_moved_mutex_t *this_)

Drops mutex and resets it to its gravestone state.

z_result_t z_mutex_init(struct z_owned_mutex_t *this_)

Constructs a mutex.

Returns:

0 in case of success, negative error code otherwise.

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

struct z_owned_condvar_t

An owned conditional variable.

Used in combination with z_owned_mutex_t to wake up thread when certain conditions are met.

struct z_loaned_condvar_t

A loaned conditional variable.

Functions

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_moved_condvar_t *this_)

Drops conditional variable.

void z_condvar_init(struct z_owned_condvar_t *this_)

Constructs conditional variable.

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

struct z_owned_task_t

An owned Zenoh task.

Functions

z_result_t z_task_init(struct z_owned_task_t *this_, const struct z_task_attr_t *_attr, void *(*fun)(void *arg), void *arg)

Constructs a new task.

Parameters:

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

• _attr – Attributes of the task (currently unused).

• fun – Function to be executed by the task.

• arg – Argument that will be passed to the function fun.

void z_task_drop(struct z_moved_task_t *this_)

Drop the task. Same as z_task_detach. Use z_task_join to wait for the task completion.

z_result_t z_task_join(struct z_moved_task_t *this_)

Joins the task and releases all allocated resources

void z_task_detach(struct z_moved_task_t *this_)

Detaches the task and releases all allocated resources.

Session

Session configuration

Types

struct z_owned_config_t

An owned Zenoh configuration.

struct z_loaned_config_t

A loaned Zenoh configuration.

Functions

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.

void z_config_drop(struct z_moved_config_t *this_)

Frees config, and resets it to its gravestone state.

void z_config_clone(struct z_owned_config_t *dst, const struct z_loaned_config_t *this_)

Clones the config into provided uninitialized memory location.

z_result_t z_config_default(struct z_owned_config_t *this_)

Constructs a new empty configuration.

z_result_t zc_config_from_env(struct z_owned_config_t *this_)

Constructs a configuration by parsing a file path stored in ZENOH_CONFIG environmental variable.

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

z_result_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_result_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_result_t zc_config_insert_json5(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.

z_result_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

struct z_owned_session_t

An owned Zenoh session.

struct z_loaned_session_t

A loaned Zenoh session.

struct z_id_t

A Zenoh ID.

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

struct z_loaned_closure_zid_t

Loaned closure.

struct z_owned_closure_zid_t

A zenoh id-processing closure.

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

Functions

z_result_t z_open(struct z_owned_session_t *this_, struct z_moved_config_t *config, const struct z_open_options_t *_options)

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_result_t z_close(struct z_loaned_session_t *session, const struct z_close_options_t *_options)

Closes zenoh session. This also drops all the closure callbacks remaining from dropped, but not undeclared subscribers.

Returns:

0 in case of success, a negative value if an error occured while closing the session.

bool z_session_is_closed(const struct z_loaned_session_t *session)

Checks if zenoh session is closed.

Returns:

true if session is closed, false otherwise.

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

Borrows session.

struct z_loaned_session_t *z_session_loan_mut(struct z_owned_session_t *this_)

void z_session_drop(struct z_moved_session_t *this_)

Closes and invalidates the session.

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_result_t z_info_routers_zid(const struct z_loaned_session_t *session, struct z_moved_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_result_t z_info_peers_zid(const struct z_loaned_session_t *session, struct z_moved_closure_zid_t *callback)

Fetches the Zenoh IDs of all connected peers.

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

Retuns 0 on success, negative values on failure

void z_id_to_string(const struct z_id_t *zid, struct z_owned_string_t *dst)

Formats the z_id_t into 16-digit hex string (LSB-first order)

void z_closure_zid_drop(struct z_moved_closure_zid_t *closure_)

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

const struct z_loaned_closure_zid_t *z_closure_zid_loan(const struct z_owned_closure_zid_t *closure)

Borrows closure.

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.

void z_closure_zid(struct z_owned_closure_zid_t *this_, void (*call)(const struct z_id_t *z_id, void *context), void (*drop)(void *context), void *context)

Constructs closure.

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.

Parameters:

• this_ – uninitialized memory location where new closure will be constructed.

• call – a closure body.

• drop – an optional function to be called once on closure drop.

• context – closure context.

Publication

Types

struct z_owned_publisher_t

An owned Zenoh publisher .

struct z_loaned_publisher_t

A loaned Zenoh publisher.

enum z_congestion_control_t

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.

enum z_reliability_t

The publisher reliability.

Note

Currently reliability does not trigger any data retransmission on the wire. It is rather used as a marker on the wire and it may be used to select the best link available (e.g. TCP for reliable data and UDP for best effort data).

Warning

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

Values:

enumerator Z_RELIABILITY_BEST_EFFORT

Defines reliability as BEST_EFFORT

enumerator Z_RELIABILITY_RELIABLE

Defines reliability as RELIABLE

struct z_put_options_t

Options passed to the z_put() function.

Public Members

struct z_moved_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 z_reliability_t reliability

The put operation reliability.

Warning

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

enum zc_locality_t allowed_destination

The allowed destination of this message.

Warning

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

struct z_moved_source_info_t *source_info

The source info for the message.

Warning

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

struct z_moved_bytes_t *attachment

The attachment to this message.

struct z_delete_options_t

Options passed to the z_delete() function.

Public Members

enum z_congestion_control_t congestion_control

The congestion control to apply when routing this delete message.

enum z_priority_t priority

The priority of the delete 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 z_reliability_t reliability

The delete operation reliability.

Warning

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

enum zc_locality_t allowed_destination

The allowed destination of this message.

Warning

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

struct z_publisher_options_t

Options passed to the z_declare_publisher() function.

Public Members

struct z_moved_encoding_t *encoding

Default encoding for messages put by this publisher.

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 z_reliability_t reliability

The publisher reliability.

Warning

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

enum zc_locality_t allowed_destination

The allowed destination for this publisher.

Warning

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

struct z_publisher_put_options_t

Options passed to the z_publisher_put() function.

Public Members

struct z_moved_encoding_t *encoding

The encoding of the data to publish.

const struct z_timestamp_t *timestamp

The timestamp of the publication.

struct z_moved_source_info_t *source_info

The source info for the publication.

Warning

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

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

Public Members

const struct z_timestamp_t *timestamp

The timestamp of this message.

struct zc_owned_matching_listener_t

An owned Zenoh matching listener.

A listener that sends notifications when the [MatchingStatus] of a publisher changes. Dropping the corresponding publisher, also drops matching listener.

Warning

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

struct zc_owned_closure_matching_status_t

A matching status-processing closure.

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

Warning

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

Functions

z_result_t z_put(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_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_result_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_result_t z_declare_publisher(const struct z_loaned_session_t *session, struct z_owned_publisher_t *publisher, const struct z_loaned_keyexpr_t *key_expr, 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:

• session – The Zenoh session.

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

• key_expr – The key expression to publish.

• options – Additional options for the publisher.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_undeclare_publisher(struct z_moved_publisher_t *this_)

Undeclares the given publisher.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_publisher_put(const struct z_loaned_publisher_t *this_, struct z_moved_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.

• payload – The data 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_result_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.

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.

Warning

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

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

Borrows publisher.

void z_publisher_drop(struct z_moved_publisher_t *this_)

Frees memory and resets publisher to its gravestone state. This is equivalent to calling z_undeclare_publisher() and discarding its return value.

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.

enum z_reliability_t z_reliability_default(void)

Returns the default value for reliability.

Warning

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

void zc_closure_matching_status_drop(struct zc_moved_closure_matching_status_t *closure_)

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

Warning

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

const struct zc_loaned_closure_matching_status_t *zc_closure_matching_status_loan(const struct zc_owned_closure_matching_status_t *closure)

Borrows closure.

Warning

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

void zc_closure_matching_status_call(const struct zc_loaned_closure_matching_status_t *closure, const struct zc_matching_status_t *mathing_status)

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

Warning

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

void zc_closure_matching_status(struct zc_owned_closure_matching_status_t *this_, void (*call)(const struct zc_matching_status_t *matching_status, void *context), void (*drop)(void *context), void *context)

Constructs closure.

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.

Warning

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

Parameters:

• this_ – uninitialized memory location where new closure will be constructed.

• call – a closure body.

• drop – an optional function to be called once on closure drop.

• context – closure context.

z_result_t zc_publisher_get_matching_status(const struct z_loaned_publisher_t *this_, struct zc_matching_status_t *matching_status)

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

Warning

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

Returns:

0 in case of success, negative error code otherwise (in this case matching_status is not updated).

z_result_t zc_publisher_declare_matching_listener(const struct z_loaned_publisher_t *publisher, struct zc_owned_matching_listener_t *matching_listener, struct zc_moved_closure_matching_status_t *callback)

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

Warning

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

Parameters:

• publisher – A publisher to associate with matching listener.

• matching_listener – An unitilized memory location where matching listener will be constructed. The matching listener will be automatically dropped when publisher is dropped.

• callback – A closure that will be called every time the matching status of the publisher changes (If last subscriber, disconnects or when the first subscriber connects).

Returns:

0 in case of success, negative error code otherwise.

z_result_t zc_publisher_declare_background_matching_listener(const struct z_loaned_publisher_t *publisher, struct zc_moved_closure_matching_status_t *callback)

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

Warning

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

Parameters:

• publisher – A publisher to associate with matching listener.

• callback – A closure that will be called every time the matching status of the publisher changes (If last subscriber, disconnects or when the first subscriber connects).

Returns:

0 in case of success, negative error code otherwise.

void zc_publisher_matching_listener_drop(struct zc_moved_matching_listener_t *this_)

Undeclares the given matching listener, droping and invalidating it.

Warning

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

Subscription

Types

struct z_owned_subscriber_t

An owned Zenoh subscriber .

Receives data from publication on intersecting key expressions. Destroying the subscriber cancels the subscription.

struct z_loaned_subscriber_t

A loaned Zenoh subscriber.

struct z_loaned_closure_sample_t

Loaned closure.

struct z_owned_closure_sample_t

A sample-processing closure.

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

struct z_subscriber_options_t

Options passed to the z_declare_subscriber() function.

Public Members

uint8_t _0

Dummy field to avoid having fieldless struct

struct z_owned_fifo_handler_sample_t

An owned Zenoh fifo sample handler.

struct z_loaned_fifo_handler_sample_t

An loaned Zenoh fifo sample handler.

struct z_owned_ring_handler_sample_t

An owned Zenoh ring sample handler.

struct z_loaned_ring_handler_sample_t

An loaned Zenoh ring sample handler.

Functions

z_result_t z_declare_subscriber(const struct z_loaned_session_t *session, struct z_owned_subscriber_t *subscriber, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_closure_sample_t *callback, struct z_subscriber_options_t *_options)

Constructs and declares a subscriber for a given key expression. Dropping subscriber undeclares its callback.

Parameters:

• session – The zenoh session.

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

• 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_result_t z_undeclare_subscriber(struct z_moved_subscriber_t *this_)

Undeclares the subscriber.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_declare_background_subscriber(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_closure_sample_t *callback, struct z_subscriber_options_t *_options)

Constructs and declares a background subscriber. Subscriber callback will be called to process the messages, until the corresponding session is closed or dropped.

Parameters:

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

const struct z_loaned_keyexpr_t *z_subscriber_keyexpr(const struct z_loaned_subscriber_t *subscriber)

Returns the key expression of the subscriber.

void z_subscriber_drop(struct z_moved_subscriber_t *this_)

Undeclares subscriber callback and resets it to its gravestone state. This is equivalent to calling z_undeclare_subscriber() and discarding its return value.

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

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

const struct z_loaned_closure_sample_t *z_closure_sample_loan(const struct z_owned_closure_sample_t *closure)

Borrows closure.

void z_closure_sample_drop(struct z_moved_closure_sample_t *closure_)

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

void z_closure_sample(struct z_owned_closure_sample_t *this_, void (*call)(struct z_loaned_sample_t *sample, void *context), void (*drop)(void *context), void *context)

Constructs closure.

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.

Parameters:

• this_ – uninitialized memory location where new closure will be constructed.

• call – a closure body.

• drop – an optional function to be called once on closure drop.

• context – closure context.

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

void z_fifo_handler_sample_drop(struct z_moved_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.

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the sample will be in the gravestone state).

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the sample will be in the gravestone state), Z_CHANNEL_NODATA if the channel is still alive, but its buffer is empty (the sample will be in the gravestone state).

void z_ring_handler_sample_drop(struct z_moved_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.

z_result_t 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 replies to receive).

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the sample will be in the gravestone state).

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the sample will be in the gravestone state), Z_CHANNEL_NODATA if the channel is still alive, but its buffer is empty (the sample will be in the gravestone state).

Queryable

Types

struct z_owned_queryable_t

An owned Zenoh queryable .

Responds to queries sent via z_get() with intersecting key expression.

struct z_loaned_queryable_t

A loaned Zenoh queryable.

struct z_owned_query_t

An owned Zenoh query received by a queryable.

Queries are atomically reference-counted, letting you extract them from the callback that handed them to you by cloning.

struct z_loaned_query_t

A loaned Zenoh query.

struct z_loaned_closure_query_t

Loaned closure.

struct z_owned_closure_query_t

A query-processing closure.

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

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_moved_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_moved_source_info_t *source_info

The source info for the reply.

Warning

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

struct z_moved_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_moved_encoding_t *encoding

The encoding of the error payload.

struct z_query_reply_del_options_t

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

Public Members

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_moved_source_info_t *source_info

The source info for the reply.

Warning

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

struct z_moved_bytes_t *attachment

The attachment to this reply.

struct z_owned_fifo_handler_query_t

An owned Zenoh fifo query handler.

struct z_loaned_fifo_handler_query_t

An loaned Zenoh fifo query handler.

struct z_owned_ring_handler_query_t

An owned Zenoh ring query handler.

struct z_loaned_ring_handler_query_t

An loaned Zenoh ring query handler.

Functions

z_result_t z_declare_queryable(const struct z_loaned_session_t *session, struct z_owned_queryable_t *queryable, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_closure_query_t *callback, struct z_queryable_options_t *options)

Constructs a Queryable for the given key expression.

Parameters:

• session – A Zenoh session.

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

• 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_result_t z_undeclare_queryable(struct z_moved_queryable_t *this_)

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

z_result_t z_declare_background_queryable(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_closure_query_t *callback, struct z_queryable_options_t *options)

Declares a background queryable for a given keyexpr. The queryable callback will be be called to proccess incoming queries until the corresponding session is closed or dropped.

Parameters:

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

struct z_entity_global_id_t z_queryable_id(const struct z_loaned_queryable_t *queryable)

Returns the ID of the queryable.

Warning

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

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_query_reply_del_options_default(struct z_query_reply_del_options_t *this_)

Constructs the default value for z_query_reply_del_options_t.

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

void z_queryable_drop(struct z_moved_queryable_t *this_)

Undeclares queryable callback and resets it to its gravestone state. This is equivalent to calling z_undeclare_queryable() and discarding its return value.

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

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

Gets query payload.

Returns NULL if query does not contain a payload.

const struct z_loaned_encoding_t *z_query_encoding(const struct z_loaned_query_t *this_)

Gets query payload encoding.

Returns NULL if query does not contain an encoding.

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_result_t z_query_reply(const struct z_loaned_query_t *this_, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_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_result_t z_query_reply_err(const struct z_loaned_query_t *this_, struct z_moved_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.

z_result_t z_query_reply_del(const struct z_loaned_query_t *this_, const struct z_loaned_keyexpr_t *key_expr, struct z_query_reply_del_options_t *options)

Sends a delete 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 delete reply.

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

Returns:

0 in case of success, negative error code otherwise.

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

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

const struct z_loaned_closure_query_t *z_closure_query_loan(const struct z_owned_closure_query_t *closure)

Borrows closure.

void z_closure_query_drop(struct z_moved_closure_query_t *closure_)

Drops the closure, resetting it to its gravestone state.

void z_closure_query(struct z_owned_closure_query_t *this_, void (*call)(struct z_loaned_query_t *query, void *context), void (*drop)(void *context), void *context)

Constructs closure.

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.

Parameters:

• this_ – uninitialized memory location where new closure will be constructed.

• call – a closure body.

• drop – an optional function to be called once on closure drop.

• context – closure context.

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

void z_fifo_handler_query_drop(struct z_moved_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.

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the query will be in the gravestone state), Z_CHANNEL_NODATA if the channel is still alive, but its buffer is empty (the query will be in the gravestone state).

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the query will be in the gravestone state), Z_CHANNEL_NODATA if the channel is still alive, but its buffer is empty (the query will be in the gravestone state).

void z_ring_handler_query_drop(struct z_moved_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.

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the query will be in the gravestone state).

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the query will be in the gravestone state), Z_CHANNEL_NODATA if the channel is still alive, but its buffer is empty (the query will be in the gravestone state).

Query

Types

struct z_owned_reply_t

An owned reply from a Queryable to a z_get().

struct z_loaned_reply_t

A loaned reply.

struct z_loaned_closure_reply_t

Loaned closure.

struct z_owned_closure_reply_t

A reply-processing closure.

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

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_moved_bytes_t *payload

An optional payload to attach to the query.

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

bool is_express

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

enum zc_locality_t allowed_destination

The allowed destination for the query.

Warning

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

enum zc_reply_keyexpr_t accept_replies

The accepted replies for the query.

Warning

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

enum z_priority_t priority

The priority of the query.

struct z_moved_source_info_t *source_info

The source info for the query.

Warning

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

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

struct z_owned_fifo_handler_reply_t

An owned Zenoh fifo reply handler.

struct z_loaned_fifo_handler_reply_t

An loaned Zenoh fifo reply handler.

struct z_owned_ring_handler_reply_t

An owned Zenoh ring reply handler.

struct z_loaned_ring_handler_reply_t

An loaned Zenoh ring reply handler.

Functions

z_result_t z_get(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, const char *parameters, struct z_moved_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.

void z_reply_drop(struct z_moved_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.

const struct z_loaned_reply_t *z_reply_loan(const struct z_owned_reply_t *this_)

Borrows reply.

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_closure_reply_call(const struct z_loaned_closure_reply_t *closure, struct z_loaned_reply_t *reply)

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

const struct z_loaned_closure_reply_t *z_closure_reply_loan(const struct z_owned_closure_reply_t *closure)

Borrows closure.

void z_closure_reply_drop(struct z_moved_closure_reply_t *closure_)

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

void z_closure_reply(struct z_owned_closure_reply_t *this_, void (*call)(struct z_loaned_reply_t *reply, void *context), void (*drop)(void *context), void *context)

Constructs closure.

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.

Parameters:

• this_ – uninitialized memory location where new closure will be constructed.

• call – a closure body.

• drop – an optional function to be called once on closure drop.

• context – closure context.

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

void z_fifo_handler_reply_drop(struct z_moved_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.

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the reply will be in the gravestone state).

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the reply will be in the gravestone state), Z_CHANNEL_NODATA if the channel is still alive, but its buffer is empty (the reply will be in the gravestone state).

void z_ring_handler_reply_drop(struct z_moved_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.

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the reply will be in the gravestone state).

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

Returns:

0 in case of success, Z_CHANNEL_DISCONNECTED if channel was dropped (the reply will be in the gravestone state), Z_CHANNEL_NODATA if the channel is still alive, but its buffer is empty (the reply will be in the gravestone state).

Scouting

Types

struct z_owned_hello_t

An owned Zenoh-allocated hello message returned by a Zenoh entity to a scout message sent with z_scout().

struct z_loaned_hello_t

A loaned hello message.

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_loaned_closure_hello_t

Loaned closure.

struct z_owned_closure_hello_t

A hello message-processing closure.

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

Functions

z_result_t z_scout(struct z_moved_config_t *config, struct z_moved_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_clone(struct z_owned_hello_t *dst, const struct z_loaned_hello_t *this_)

Constructs an owned copy of hello message.

void z_hello_drop(struct z_moved_hello_t *this_)

Frees memory and resets hello message to its gravestone state.

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

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, struct z_loaned_hello_t *hello)

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

const struct z_loaned_closure_hello_t *z_closure_hello_loan(const struct z_owned_closure_hello_t *closure)

Borrows closure.

void z_closure_hello_drop(struct z_moved_closure_hello_t *this_)

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

void z_closure_hello(struct z_owned_closure_hello_t *this_, void (*call)(struct z_loaned_hello_t *hello, void *context), void (*drop)(void *context), void *context)

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

Parameters:

• this_ – uninitialized memory location where new closure will be constructed.

• call – a closure body.

• drop – an optional function to be called once on closure drop.

• context – closure context.

Liveliness

Types

struct zc_owned_liveliness_token_t

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

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

Warning

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

struct zc_liveliness_declaration_options_t

The options for zc_liveliness_declare_token().

Warning

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

struct zc_liveliness_get_options_t

The options for zc_liveliness_get()

Warning

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

struct zc_liveliness_subscriber_options_t

The options for zc_liveliness_declare_subscriber()

Warning

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

Functions

z_result_t zc_liveliness_declare_subscriber(const struct z_loaned_session_t *session, struct z_owned_subscriber_t *subscriber, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_closure_sample_t *callback, struct zc_liveliness_subscriber_options_t *options)

Declares a subscriber on liveliness tokens that intersect key_expr.

Warning

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

Parameters:

• session – A Zenoh session.

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

• 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_result_t zc_liveliness_declare_background_subscriber(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_closure_sample_t *callback, struct zc_liveliness_subscriber_options_t *options)

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

Warning

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

Parameters:

• 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_result_t zc_liveliness_get(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_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.

Warning

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

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_result_t zc_liveliness_declare_token(const struct z_loaned_session_t *session, struct zc_owned_liveliness_token_t *token, 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.

Warning

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

Parameters:

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

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

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

• _options – Liveliness token declaration properties.

z_result_t zc_liveliness_undeclare_token(struct zc_moved_liveliness_token_t *this_)

Destroys a liveliness token, notifying subscribers of its destruction.

Warning

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

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

Borrows token.

Warning

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

void zc_liveliness_token_drop(struct zc_moved_liveliness_token_t *this_)

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

Warning

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

void zc_liveliness_subscriber_options_default(struct zc_liveliness_subscriber_options_t *this_)

Constucts default value for zc_liveliness_declare_subscriber_options_t.

Warning

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

void zc_liveliness_declaration_options_default(struct zc_liveliness_declaration_options_t *this_)

Constructs default value for zc_liveliness_declaration_options_t.

Warning

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

void zc_liveliness_get_options_default(struct zc_liveliness_get_options_t *this_)

Constructs default value zc_liveliness_get_options_t.

Warning

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

Publication Cache

Types

struct ze_owned_publication_cache_t

An owned Zenoh publication cache.

Used to store publications on intersecting key expressions. Can be queried later via z_get() to retrieve this data (for example by ze_owned_querying_subscriber_t).

Warning

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

struct ze_loaned_publication_cache_t

A loaned Zenoh publication cache.

Warning

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

struct ze_publication_cache_options_t

Options passed to the ze_declare_publication_cache() function.

Warning

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

Public Members

const struct z_loaned_keyexpr_t *queryable_prefix

The prefix used for queryable.

enum zc_locality_t queryable_origin

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

bool queryable_complete

The complete option for the queryable.

size_t history

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

size_t resources_limit

The limit number of cached resources.

enum zc_locality_t

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

Values:

enumerator ZC_LOCALITY_ANY

Any

enumerator ZC_LOCALITY_SESSION_LOCAL

Only from local sessions.

enumerator ZC_LOCALITY_REMOTE

Only from remote sessions.

Functions

z_result_t ze_declare_publication_cache(const struct z_loaned_session_t *session, struct ze_owned_publication_cache_t *pub_cache, const struct z_loaned_keyexpr_t *key_expr, struct ze_publication_cache_options_t *options)

Constructs and declares a publication cache.

Warning

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

Parameters:

• session – A Zenoh session.

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

• 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_result_t ze_undeclare_publication_cache(struct ze_moved_publication_cache_t *this_)

Undeclares publication cache.

Warning

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

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_declare_background_publication_cache(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct ze_publication_cache_options_t *options)

Declares a background publication cache. It will function in background until the corresponding session is closed or dropped.

Warning

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

Parameters:

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

void ze_publication_cache_drop(struct ze_moved_publication_cache_t *this_)

Drops publication cache and resets it to its gravestone state. This is equivalent to calling ze_undeclare_publication_cache() and discarding its return value.

Warning

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

const struct ze_loaned_publication_cache_t *ze_publication_cache_loan(const struct ze_owned_publication_cache_t *this_)

Borrows publication cache.

Warning

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

const struct z_loaned_keyexpr_t *ze_publication_cache_keyexpr(const struct ze_loaned_publication_cache_t *this_)

Returns the key expression of the publication cache.

Warning

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

void ze_publication_cache_options_default(struct ze_publication_cache_options_t *this_)

Constructs the default value for ze_publication_cache_options_t.

Warning

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

Querying Subscriber

Types

struct ze_owned_querying_subscriber_t

An owned Zenoh querying subscriber.

In addition to receiving the data it is subscribed to, it also will fetch data from a Queryable at startup and peridodically (using ze_querying_subscriber_get()).

Warning

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

struct ze_loaned_querying_subscriber_t

A loaned Zenoh querying subscriber.

Warning

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

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

Warning

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

Public Members

enum zc_locality_t allowed_origin

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

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 zc_reply_keyexpr_t query_accept_replies

The accepted replies for queries.

uint64_t query_timeout_ms

The timeout to be used for queries.

enum zc_reply_keyexpr_t

Key expressions types to which Queryable should reply to.

Warning

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

Values:

enumerator ZC_REPLY_KEYEXPR_ANY

Replies to any key expression queries.

enumerator ZC_REPLY_KEYEXPR_MATCHING_QUERY

Replies only to queries with intersecting key expressions.

Functions

z_result_t ze_declare_querying_subscriber(const struct z_loaned_session_t *session, struct ze_owned_querying_subscriber_t *querying_subscriber, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_closure_sample_t *callback, struct ze_querying_subscriber_options_t *options)

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

Warning

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

Parameters:

• session – A Zenoh session.

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

• 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_result_t ze_undeclare_querying_subscriber(struct ze_moved_querying_subscriber_t *this_)

Undeclares the given querying subscriber.

Warning

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

Returns:

0 in case of success, negative error code otherwise.

z_result_t ze_declare_background_querying_subscriber(const struct z_loaned_session_t *session, const struct z_loaned_keyexpr_t *key_expr, struct z_moved_closure_sample_t *callback, struct ze_querying_subscriber_options_t *options)

Declares a background querying subscriber for a given key expression. Subscriber callback will be called to process the messages, until the corresponding session is closed or dropped.

Warning

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

Parameters:

• 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_result_t ze_querying_subscriber_get(const struct ze_loaned_querying_subscriber_t *this_, const struct z_loaned_keyexpr_t *selector, 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.

Warning

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

Returns:

0 in case of success, negative error code otherwise.

void ze_querying_subscriber_drop(struct ze_moved_querying_subscriber_t *this_)

Undeclares querying subscriber callback and resets it to its gravestone state. This is equivalent to calling ze_undeclare_querying_subscriber() and discarding its return value.

Warning

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

void ze_querying_subscriber_options_default(struct ze_querying_subscriber_options_t *this_)

Constructs the default value for ze_querying_subscriber_options_t.

Warning

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

enum zc_reply_keyexpr_t zc_reply_keyexpr_default(void)

Returns the default value of zc_reply_keyexpr_t.

Warning

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

Logging

Types

struct zc_owned_closure_log_t

A log-processing closure.

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

struct zc_loaned_closure_log_t

Loaned closure.

enum zc_log_severity_t

Severity level of Zenoh log message.

Values:

enumerator ZC_LOG_SEVERITY_TRACE

The trace level.

Designates very low priority, often extremely verbose, information.

enumerator ZC_LOG_SEVERITY_DEBUG

The “debug” level.

Designates lower priority information.

enumerator ZC_LOG_SEVERITY_INFO

The “info” level.

Designates useful information.

enumerator ZC_LOG_SEVERITY_WARN

The “warn” level.

Designates hazardous situations.

enumerator ZC_LOG_SEVERITY_ERROR

The “error” level.

Designates very serious errors.

Functions

void zc_try_init_log_from_env(void)

Initializes the zenoh runtime logger, using rust environment settings. E.g.: RUST_LOG=info will enable logging at info level. Similarly, you can set the variable to error or debug.

Note that if the environment variable is not set, then logging will not be enabled. See https://docs.rs/env_logger/latest/env_logger/index.html for accepted filter format.

z_result_t zc_init_log_from_env_or(const char *fallback_filter)

Initializes the zenoh runtime logger, using rust environment settings or the provided fallback level. E.g.: RUST_LOG=info will enable logging at info level. Similarly, you can set the variable to error or debug.

Note that if the environment variable is not set, then fallback filter will be used instead. See https://docs.rs/env_logger/latest/env_logger/index.html for accepted filter format.

Parameters:

fallback_filter – The fallback filter if the RUST_LOG environment variable is not set.

void zc_init_log_with_callback(enum zc_log_severity_t min_severity, struct zc_moved_closure_log_t *callback)

Initializes the zenoh runtime logger with custom callback.

Parameters:

• min_severity – Minimum severity level of log message to be be passed to the callback. Messages with lower severity levels will be ignored.

• callback – A closure that will be called with each log message severity level and content.

void zc_closure_log_call(const struct zc_loaned_closure_log_t *closure, enum zc_log_severity_t severity, const struct z_loaned_string_t *msg)

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

const struct zc_loaned_closure_log_t *zc_closure_log_loan(const struct zc_owned_closure_log_t *closure)

Borrows closure.

void zc_closure_log_drop(struct zc_moved_closure_log_t *closure_)

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

void zc_closure_log(struct zc_owned_closure_log_t *this_, void (*call)(enum zc_log_severity_t severity, const struct z_loaned_string_t *msg, void *context), void (*drop)(void *context), void *context)

Constructs closure.

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.

Parameters:

• this_ – uninitialized memory location where new closure will be constructed.

• call – a closure body.

• drop – an optional function to be called once on closure drop.

• context – closure context.

Other

Functions

void zc_stop_z_runtime(void)

Stops all Zenoh tasks and drops all related static variables. All Zenoh-related structures should be properly dropped/undeclared PRIOR to this call. None of Zenoh functionality can be used after this call. Useful to suppress memory leaks messages due to Zenoh static variables (since they are never destroyed due to Rust language design).

void zc_cleanup_orphaned_shm_segments(void)

Linux: Trigger cleanup for orphaned SHM segments If process that created named SHM segment crashes or exits by a signal, the segment persists in the system disregarding if it is used by other Zenoh processes or not. This is the detail of POSIX specification for shared memory that is hard to bypass. To deal with this we developed a cleanup routine that enumerates all segments and tries to find processes that are using it. If no such process found, segment will be removed. There is no ideal signal to trigger this cleanup, so by default, zenoh triggers it in the following moments:

For non-linux platforms this function currently does nothing

Warning

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

• first POSIX SHM segment creation

• process exit via exit() call or return from maint function It is OK to additionally trigger this function at any time, but be aware that this can be costly.