API Reference

Containers

Slice

Represents an array of bytes.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_slice_t
type z_view_slice_t
type z_loaned_slice_t
type z_moved_slice_t

Functions

void z_slice_empty(z_owned_slice_t *slice)

Builds an empty z_owned_slice_t.

Parameters:
z_result_t z_slice_copy_from_buf(z_owned_slice_t *slice, const uint8_t *data, size_t len)

Builds a z_owned_slice_t by copying a buffer into it.

Parameters:

  • slice – Pointer to an uninitialized z_owned_slice_t.

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

  • len – Number of bytes to copy.

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:

  • slice – Pointer to an uninitialized z_owned_slice_t.

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

  • len –

    Number of bytes in data.

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

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

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

Returns:

0 if creation successful, negative value otherwise.

const uint8_t *z_slice_data(const z_loaned_slice_t *slice)

Gets date pointer of a bytes array.

Parameters:
Returns:

The data pointer.

size_t z_slice_len(const z_loaned_slice_t *slice)

Gets total number of bytes in a bytes array.

Parameters:
Returns:

The number of bytes.

bool z_slice_is_empty(const z_loaned_slice_t *slice)

Checks if slice is empty

Parameters:
Returns:

true if conainer is empty, false otherwise.

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

Builds a z_view_slice_t.

Parameters:

  • slice – Pointer to an uninitialized z_view_slice_t.

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

  • len – Number of bytes in data.

Returns:

0 if creation successful, negative value otherwise.

void z_view_slice_empty(z_view_slice_t *slice)

See z_slice_empty()

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_slice_drop(z_moved_slice_t *slice)
void z_slice_clone(z_owned_slice_t *dst, const z_loaned_slice_t *slice)
const z_loaned_slice_t *z_view_slice_loan(const z_view_slice_t *slice)
z_loaned_slice_t *z_view_slice_loan_mut(z_view_slice_t *slice)
const z_loaned_slice_t *z_slice_loan(const z_owned_slice_t *slice)
z_loaned_slice_t *z_slice_loan_mut(z_owned_slice_t *slice)

String

Represents a string without null-terminator.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_string_t
type z_view_string_t
type z_loaned_string_t
type z_moved_string_t

Functions

void z_string_empty(z_owned_string_t *str)

Builds an empty z_owned_string_t.

Parameters:
z_result_t z_string_copy_from_str(z_owned_string_t *str, const char *value)

Builds a z_string_t by copying a const char * string.

Parameters:

  • str – Pointer to an uninitialized z_owned_string_t.

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

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:

  • value – Pointer to a string.

  • len – String size.

  • str – Pointer to an uninitialized z_owned_string_t.

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:

  • str – Pointer to an uninitialized z_owned_string_t.

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

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

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

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

Returns:

0 if creation successful, negative value otherwise.

const char *z_string_data(const z_loaned_string_t *str)

Gets data from a z_loaned_string_t.

Parameters:
Returns:

Pointer to the string data.

size_t z_string_len(const z_loaned_string_t *str)

Gets string length from a z_loaned_string_t.

Parameters:
Returns:

Length of the string.

bool z_string_is_empty(const z_loaned_string_t *str)

Checks if string is empty

Parameters:
Returns:

true if conainer is empty, false otherwise.

const z_loaned_slice_t *z_string_as_slice(const z_loaned_string_t *str)

Returns z_loaned_slice_t for the string

Parameters:
Returns:

slice containing string data

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

Builds a z_view_string_t by wrapping a const char * string.

Parameters:

  • value – Pointer to a null terminated string.

  • str – Pointer to an uninitialized z_view_string_t.

Returns:

0 if creation successful, negative value otherwise.

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

Builds a z_view_string_t by wrapping a const char * substring.

Parameters:

  • str – Pointer to an uninitialized z_view_string_t.

  • value – Pointer to a null terminated string.

  • len – Size of the string.

Returns:

0 if creation successful, negative value otherwise.

void z_view_string_empty(z_view_string_t *string)

See z_string_empty()

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_string_drop(z_moved_string_t *string)
void z_string_clone(z_owned_string_t *dst, const z_loaned_string_t *string)
const z_loaned_string_t *z_view_string_loan(const z_view_string_t *string)
z_loaned_string_t *z_view_string_loan_mut(z_view_string_t *string)
const z_loaned_string_t *z_string_loan(const z_owned_string_t *string)
z_loaned_string_t *z_string_loan_mut(z_owned_string_t *string)

String Array

Represents an array of non null-terminated strings.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_string_array_t
type z_loaned_string_array_t
type z_moved_string_array_t

Functions

void z_string_array_new(z_owned_string_array_t *a)

Constructs a new empty string array.

Parameters:
size_t z_string_array_push_by_alias(z_loaned_string_array_t *a, const z_loaned_string_t *value)

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

Parameters:
Returns:

the new length of the array.

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

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

Parameters:
Returns:

the new length of the array.

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

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

Parameters:
Returns:

NULL if the index is out of bounds.

size_t z_string_array_len(const z_loaned_string_array_t *a)

Returns number of elements in the array.

bool z_string_array_is_empty(const z_loaned_string_array_t *a)

Returns true if the array is empty, false otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_string_array_drop(z_moved_string_array_t *string_array)
void z_string_array_clone(z_owned_string_array_t *dst, const z_loaned_string_array_t *string_array)
const z_loaned_string_array_t *z_string_array_loan(const z_owned_string_array_t *string_array)
z_loaned_string_array_t *z_string_array_loan_mut(z_owned_string_array_t *string_array)

Common

Key expression

Represents a key expression in Zenoh.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_keyexpr_t
type z_view_keyexpr_t
type z_loaned_keyexpr_t
type z_moved_keyexpr_t
enum z_keyexpr_intersection_level_t

Intersection level of 2 key expressions.

enumerator Z_KEYEXPR_INTERSECTION_LEVEL_DISJOINT

2 key expression 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. Z_KEYEXPR_INTERSECTION_LEVEL_INCLUDES: First key expression is the superset of second one.

Z_KEYEXPR_INTERSECTION_LEVEL_EQUALS: 2 key expressions are equal.

enum zp_keyexpr_canon_status_t

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

enumerator Z_KEYEXPR_CANON_SUCCESS

The key expression is canon.

enumerator Z_KEYEXPR_CANON_LONE_DOLLAR_STAR

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

enumerator Z_KEYEXPR_CANON_SINGLE_STAR_AFTER_DOUBLE_STAR

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

enumerator Z_KEYEXPR_CANON_DOUBLE_STAR_AFTER_DOUBLE_STAR

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

enumerator Z_KEYEXPR_CANON_EMPTY_CHUNK

The key contains empty chunks.

enumerator Z_KEYEXPR_CANON_STARS_IN_CHUNK

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

enumerator Z_KEYEXPR_CANON_DOLLAR_AFTER_DOLLAR_OR_STAR

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

enumerator Z_KEYEXPR_CANON_CONTAINS_SHARP_OR_QMARK

The key contains # or ?, which is forbidden.

enumerator Z_KEYEXPR_CANON_CONTAINS_UNBOUND_DOLLAR

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

Functions

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

Builds a new keyexpr.

Parameters:

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

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

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:

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

  • keyexpr – Pointer to an uninitialized z_view_keyexpr_t.

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:

  • keyexpr – Pointer to an uninitialized z_owned_keyexpr_t.

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

Returns:

0 if creation successful, negative value otherwise.

z_result_t z_view_keyexpr_from_str_autocanonize(z_view_keyexpr_t *keyexpr, char *name)

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

Parameters:

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

  • keyexpr – Pointer to an uninitialized z_view_keyexpr_t.

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:

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

  • keyexpr – Pointer to an uninitialized z_view_keyexpr_t.

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

Builds a new keyexpr from a substring.

Parameters:

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

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

  • len – Length of the substring to consider.

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:

  • keyexpr – Pointer to an uninitialized z_view_keyexpr_t.

  • name – Pointer to string representation of the keyexpr.

  • len – Size of the string.

Returns:

0 if creation successful, negative value otherwise.

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

Builds a z_owned_keyexpr_t from a substring with auto canonization.

Parameters:

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

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

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

expression string length.

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:

  • keyexpr – Pointer to an uninitialized z_view_keyexpr_t.

  • name – Pointer to string representation of the keyexpr.

  • len – Pointer to the size of the string.

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:

  • keyexpr – Pointer to an uninitialized z_view_keyexpr_t.

  • name – Pointer to string representation of the keyexpr.

  • len – Size of the string.

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

Gets a null-terminated string view from a z_keyexpr_t.

Parameters:

  • keyexpr – Pointer to a loaned instance of z_keyexpr_t.

  • str – Pointer to an uninitialized z_view_string_t.

Returns:

0 if creation successful, negative value otherwise.

z_result_t z_keyexpr_canonize(char *start, size_t *len)

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

Parameters:

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

  • len – Number of characters in start.

Returns:

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

z_result_t z_keyexpr_canonize_null_terminated(char *start)

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

Parameters:

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

Returns:

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

z_result_t z_keyexpr_is_canon(const char *start, size_t len)

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

Parameters:

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

  • len – Number of characters in start.

Returns:

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

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

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

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

Parameters:

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

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

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

  • len – Length of the substring to concatenate.

Returns:

0 if creation successful, negative value otherwise.

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

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

Parameters:
Returns:

0 if creation successful, negative value otherwise.

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

Checks if two keyexpr are equal.

Parameters:
Returns:

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

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

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

Parameters:
Returns:

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

defined by r. Otherwise, returns false.

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

Checks if a given keyexpr intersects with another keyexpr.

Parameters:
Returns:

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

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

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

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

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

Parameters:
Returns:

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

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

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

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

Parameters:
Returns:

0 if declare successful, negative value otherwise.

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

Undeclares a keyexpr.

Parameters:
Returns:

0 if undeclare successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_keyexpr_drop(z_moved_keyexpr_t *keyexpr)
void z_keyexpr_clone(z_owned_keyexpr_t *dst, const z_loaned_keyexpr_t *keyexpr)
const z_loaned_keyexpr_t *z_view_keyexpr_loan(const z_view_keyexpr_t *keyexpr)
z_loaned_keyexpr_t *z_view_keyexpr_loan_mut(z_view_keyexpr_t *keyexpr)
const z_loaned_keyexpr_t *z_keyexpr_loan(const z_owned_keyexpr_t *keyexpr)
z_loaned_keyexpr_t *z_keyexpr_loan_mut(z_owned_keyexpr_t *keyexpr)

Encoding

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

Types

See details at Owned Types z_owned_xxx_t

type z_owned_encoding_t
type z_loaned_encoding_t
type z_moved_encoding_t

Functions

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

Builds a z_owned_encoding_t from a null terminated string.

Parameters:

  • encoding – Pointer to an uninitialized z_owned_encoding_t.

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

Returns:

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

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

Builds a z_owned_encoding_t from a null terminated string.

Parameters:

  • encoding – Pointer to an uninitialized z_owned_encoding_t.

  • s – Pointer to the string to use.

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

Returns:

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

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

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

Parameters:

  • encoding – Pointer to initialized z_loaned_encoding_t.

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

Returns:

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

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

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

Parameters:

  • encoding – Pointer to initialized z_loaned_encoding_t.

  • schema – Pointer to the substring start.

  • len – Number of characters to consider.

Returns:

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

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

Builds a string from a z_loaned_encoding_t.

Parameters:
Returns:

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

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

Checks if 2 encodings are equal.

Parameters:
Returns:

true if left equals right, false otherwise.

const z_loaned_encoding_t *z_encoding_loan_default(void)

Returns a loaned default z_loaned_encoding_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_encoding_drop(z_moved_encoding_t *encoding)
void z_encoding_clone(z_owned_encoding_t *dst, const z_loaned_encoding_t *encoding)
const z_loaned_encoding_t *z_encoding_loan(const z_owned_encoding_t *encoding)
z_loaned_encoding_t *z_encoding_loan_mut(z_owned_encoding_t *encoding)

Predefined Encodings

const z_loaned_encoding_t *z_encoding_zenoh_bytes(void)

Just some bytes.

Constant alias for string: “zenoh/bytes”.

Usually used for types: uint8_t[].

const z_loaned_encoding_t *z_encoding_zenoh_int8(void)

A VLE-encoded signed little-endian 8bit integer. Binary representation uses two’s complement. Constant alias for string: “zenoh/int8”.

Usually used for types: int8_t.

const z_loaned_encoding_t *z_encoding_zenoh_int16(void)

A VLE-encoded signed little-endian 16bit integer. Binary representation uses two’s complement. Constant alias for string: “zenoh/int16”.

Usually used for types: int16_t.

const z_loaned_encoding_t *z_encoding_zenoh_int32(void)

A VLE-encoded signed little-endian 32bit integer. Binary representation uses two’s complement. Constant alias for string: “zenoh/int32”.

Usually used for types: int32_t.

const z_loaned_encoding_t *z_encoding_zenoh_int64(void)

A VLE-encoded signed little-endian 64bit integer. Binary representation uses two’s complement. Constant alias for string: “zenoh/int64”.

Usually used for types: int64_t.

const z_loaned_encoding_t *z_encoding_zenoh_int128(void)

A VLE-encoded signed little-endian 128bit integer. Binary representation uses two’s complement. Constant alias for string: “zenoh/int128”.

const z_loaned_encoding_t *z_encoding_zenoh_uint8(void)

A VLE-encoded unsigned little-endian 8bit integer. Constant alias for string: “zenoh/uint8”.

Usually used for types: uint8_t.

const z_loaned_encoding_t *z_encoding_zenoh_uint16(void)

A VLE-encoded unsigned little-endian 16bit integer. Constant alias for string: “zenoh/uint16”.

Usually used for types: uint16_t.

const z_loaned_encoding_t *z_encoding_zenoh_uint32(void)

A VLE-encoded unsigned little-endian 32bit integer. Constant alias for string: “zenoh/uint32”.

Usually used for types: uint32_t.

const z_loaned_encoding_t *z_encoding_zenoh_uint64(void)

A VLE-encoded unsigned little-endian 64bit integer. Constant alias for string: “zenoh/uint64”.

Usually used for types: uint64_t.

const z_loaned_encoding_t *z_encoding_zenoh_uint128(void)

A VLE-encoded unsigned little-endian 128bit integer. Constant alias for string: “zenoh/uint128”.

const z_loaned_encoding_t *z_encoding_zenoh_float32(void)

A VLE-encoded 32bit float. Binary representation uses IEEE 754-2008 binary32. Constant alias for string: “zenoh/float32”.

Usually used for types: float.

const z_loaned_encoding_t *z_encoding_zenoh_float64(void)

A VLE-encoded 64bit float. Binary representation uses IEEE 754-2008 binary64. Constant alias for string: “zenoh/float64”.

Usually used for types: double.

const z_loaned_encoding_t *z_encoding_zenoh_bool(void)

A boolean. 0 is false, 1 is true. Other values are invalid. Constant alias for string: “zenoh/bool”.

Usually used for types: bool.

const z_loaned_encoding_t *z_encoding_zenoh_string(void)

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

Usually used for types: char[].

const z_loaned_encoding_t *z_encoding_zenoh_error(void)

A zenoh error. Constant alias for string: “zenoh/error”.

Usually used for types: z_reply_err_t.

const z_loaned_encoding_t *z_encoding_application_octet_stream(void)

An application-specific stream of bytes. Constant alias for string: “application/octet-stream”.

const z_loaned_encoding_t *z_encoding_text_plain(void)

A textual file. Constant alias for string: “text/plain”.

const z_loaned_encoding_t *z_encoding_application_json(void)

JSON data intended to be consumed by an application. Constant alias for string: “application/json”.

const z_loaned_encoding_t *z_encoding_text_json(void)

JSON data intended to be human readable. Constant alias for string: “text/json”.

const z_loaned_encoding_t *z_encoding_application_cdr(void)

A Common Data Representation (CDR)-encoded data. Constant alias for string: “application/cdr”.

const z_loaned_encoding_t *z_encoding_application_cbor(void)

A Concise Binary Object Representation (CBOR)-encoded data. Constant alias for string: “application/cbor”.

const z_loaned_encoding_t *z_encoding_application_yaml(void)

YAML data intended to be consumed by an application. Constant alias for string: “application/yaml”.

const z_loaned_encoding_t *z_encoding_text_yaml(void)

YAML data intended to be human readable. Constant alias for string: “text/yaml”.

const z_loaned_encoding_t *z_encoding_text_json5(void)

JSON5 encoded data that are human readable. Constant alias for string: “text/json5”.

const z_loaned_encoding_t *z_encoding_application_python_serialized_object(void)

A Python object serialized using [pickle](https://docs.python.org/3/library/pickle.html). Constant alias for string: “application/python-serialized-object”.

const z_loaned_encoding_t *z_encoding_application_protobuf(void)

An application-specific protobuf-encoded data. Constant alias for string: “application/protobuf”.

const z_loaned_encoding_t *z_encoding_application_java_serialized_object(void)

A Java serialized object. Constant alias for string: “application/java-serialized-object”.

const z_loaned_encoding_t *z_encoding_application_openmetrics_text(void)

An [openmetrics](https://github.com/OpenObservability/OpenMetrics) data, commonly used by [Prometheus](https://prometheus.io/). Constant alias for string: “application/openmetrics-text”.

const z_loaned_encoding_t *z_encoding_image_png(void)

A Portable Network Graphics (PNG) image. Constant alias for string: “image/png”.

const z_loaned_encoding_t *z_encoding_image_jpeg(void)

A Joint Photographic Experts Group (JPEG) image. Constant alias for string: “image/jpeg”.

const z_loaned_encoding_t *z_encoding_image_gif(void)

A Graphics Interchange Format (GIF) image. Constant alias for string: “image/gif”.

const z_loaned_encoding_t *z_encoding_image_bmp(void)

A BitMap (BMP) image. Constant alias for string: “image/bmp”.

const z_loaned_encoding_t *z_encoding_image_webp(void)

A Web Portable (WebP) image. Constant alias for string: “image/webp”.

const z_loaned_encoding_t *z_encoding_application_xml(void)

An XML file intended to be consumed by an application. Constant alias for string: “application/xml”.

const z_loaned_encoding_t *z_encoding_application_x_www_form_urlencoded(void)

An encoded list of tuples, each consisting of a name and a value. Constant alias for string: “application/x-www-form-urlencoded”.

const z_loaned_encoding_t *z_encoding_text_html(void)

An HTML file. Constant alias for string: “text/html”.

const z_loaned_encoding_t *z_encoding_text_xml(void)

An XML file that is human-readable. Constant alias for string: “text/xml”.

const z_loaned_encoding_t *z_encoding_text_css(void)

A CSS file. Constant alias for string: “text/css”.

const z_loaned_encoding_t *z_encoding_text_javascript(void)

A JavaScript file. Constant alias for string: “text/javascript”.

const z_loaned_encoding_t *z_encoding_text_markdown(void)

A Markdown file. Constant alias for string: “text/markdown”.

const z_loaned_encoding_t *z_encoding_text_csv(void)

A CSV file. Constant alias for string: “text/csv”.

const z_loaned_encoding_t *z_encoding_application_sql(void)

An application-specific SQL query. Constant alias for string: “application/sql”.

const z_loaned_encoding_t *z_encoding_application_coap_payload(void)

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

const z_loaned_encoding_t *z_encoding_application_json_patch_json(void)

Defines a JSON document structure for expressing a sequence of operations to apply to a JSON document. Constant alias for string: “application/json-patch+json”.

const z_loaned_encoding_t *z_encoding_application_json_seq(void)

A JSON text sequence consists of any number of JSON texts, all encoded in UTF-8. Constant alias for string: “application/json-seq”.

const z_loaned_encoding_t *z_encoding_application_jsonpath(void)

A JSONPath defines a string syntax for selecting and extracting JSON values from within a given JSON value. Constant alias for string: “application/jsonpath”.

const z_loaned_encoding_t *z_encoding_application_jwt(void)

A JSON Web Token (JWT). Constant alias for string: “application/jwt”.

const z_loaned_encoding_t *z_encoding_application_mp4(void)

An application-specific MPEG-4 encoded data, either audio or video. Constant alias for string: “application/mp4”.

const z_loaned_encoding_t *z_encoding_application_soap_xml(void)

A SOAP 1.2 message serialized as XML 1.0. Constant alias for string: “application/soap+xml”.

const z_loaned_encoding_t *z_encoding_application_yang(void)

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

const z_loaned_encoding_t *z_encoding_audio_aac(void)

A MPEG-4 Advanced Audio Coding (AAC) media. Constant alias for string: “audio/aac”.

const z_loaned_encoding_t *z_encoding_audio_flac(void)

A Free Lossless Audio Codec (FLAC) media. Constant alias for string: “audio/flac”.

const z_loaned_encoding_t *z_encoding_audio_mp4(void)

An audio codec defined in MPEG-1, MPEG-2, MPEG-4, or registered at the MP4 registration authority. Constant alias for string: “audio/mp4”.

const z_loaned_encoding_t *z_encoding_audio_ogg(void)

An Ogg-encapsulated audio stream. Constant alias for string: “audio/ogg”.

const z_loaned_encoding_t *z_encoding_audio_vorbis(void)

A Vorbis-encoded audio stream. Constant alias for string: “audio/vorbis”.

const z_loaned_encoding_t *z_encoding_video_h261(void)

A h261-encoded video stream. Constant alias for string: “video/h261”.

const z_loaned_encoding_t *z_encoding_video_h263(void)

A h263-encoded video stream. Constant alias for string: “video/h263”.

const z_loaned_encoding_t *z_encoding_video_h264(void)

A h264-encoded video stream. Constant alias for string: “video/h264”.

const z_loaned_encoding_t *z_encoding_video_h265(void)

A h265-encoded video stream. Constant alias for string: “video/h265”.

const z_loaned_encoding_t *z_encoding_video_h266(void)

A h266-encoded video stream. Constant alias for string: “video/h266”.

const z_loaned_encoding_t *z_encoding_video_mp4(void)

A video codec defined in MPEG-1, MPEG-2, MPEG-4, or registered at the MP4 registration authority. Constant alias for string: “video/mp4”.

const z_loaned_encoding_t *z_encoding_video_ogg(void)

An Ogg-encapsulated video stream. Constant alias for string: “video/ogg”.

const z_loaned_encoding_t *z_encoding_video_raw(void)

An uncompressed, studio-quality video stream. Constant alias for string: “video/raw”.

const z_loaned_encoding_t *z_encoding_video_vp8(void)

A VP8-encoded video stream. Constant alias for string: “video/vp8”.

const z_loaned_encoding_t *z_encoding_video_vp9(void)

A VP9-encoded video stream. Constant alias for string: “video/vp9”.

Reply Error

Represents a Zenoh reply error value.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_reply_err_t
type z_loaned_reply_err_t
type z_moved_reply_err_t

Functions

const z_loaned_bytes_t *z_reply_err_payload(const z_loaned_reply_err_t *reply_err)

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

Parameters:
Returns:

Pointer to the data as a z_loaned_bytes_t.

const z_loaned_encoding_t *z_reply_err_encoding(const z_loaned_reply_err_t *reply_err)

Gets a reply error encoding by aliasing it.

Parameters:
Returns:

Pointer to the encoding as a z_loaned_encoding_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_reply_err_drop(z_moved_reply_err_t *reply_err)
void z_reply_err_clone(z_owned_reply_err_t *dst, const z_loaned_reply_err_t *reply_err)
const z_loaned_reply_err_t *z_reply_err_loan(const z_owned_reply_err_t *reply_err)

Sample

Represents a data sample.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_sample_t
type z_loaned_sample_t
type z_moved_sample_t
enum z_sample_kind_t

Sample kind values.

enumerator Z_SAMPLE_KIND_PUT

The Sample was issued by a put operation.

enumerator Z_SAMPLE_KIND_DELETE

The Sample was issued by a delete operation.

Functions

const z_timestamp_t *z_sample_timestamp(const z_loaned_sample_t *sample)

Gets the timestamp of a sample by aliasing it.

Parameters:
Returns:

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

const z_loaned_bytes_t *z_sample_attachment(const z_loaned_sample_t *sample)

Gets the attachment of a sample by aliasing it.

Parameters:
Returns:

Pointer to the attachment as a z_loaned_bytes_t.

const z_loaned_encoding_t *z_sample_encoding(const z_loaned_sample_t *sample)

Gets the encoding of a sample by aliasing it.

Parameters:
Returns:

The encoding wrapped as a z_loaned_encoding_t.

const z_loaned_bytes_t *z_sample_payload(const z_loaned_sample_t *sample)

Gets the payload of a sample by aliasing it.

Parameters:
Returns:

The payload wrapped as a z_loaned_bytes_t.

const z_loaned_keyexpr_t *z_sample_keyexpr(const z_loaned_sample_t *sample)

Gets the keyexpr from a sample by aliasing it.

Parameters:
Returns:

The keyexpr wrapped as a z_loaned_keyexpr_t.

z_priority_t z_sample_priority(const z_loaned_sample_t *sample)
Parameters:
Returns:

The priority wrapped as a z_priority_t.

Got sample qos priority value.

z_congestion_control_t z_sample_congestion_control(const z_loaned_sample_t *sample)

Got sample qos congestion control value.

Parameters:
Returns:

The congestion control wrapped as a z_congestion_control_t.

bool z_sample_express(const z_loaned_sample_t *sample)

Got whether sample qos express flag was set or not.

Parameters:
Returns:

The express flag value.

z_reliability_t z_sample_reliability(const z_loaned_sample_t *sample)

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

Parameters:
Returns:

The reliability wrapped as a z_reliability_t.

z_sample_kind_t z_sample_kind(const z_loaned_sample_t *sample)

Gets the kind of a sample by aliasing it.

Parameters:
Returns:

The sample kind wrapped as a z_sample_kind_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_sample_drop(z_moved_sample_t *sample)
void z_sample_clone(z_owned_sample_t *dst, const z_loaned_sample_t *sample)
const z_loaned_sample_t *z_sample_loan(const z_owned_sample_t *sample)

Timestamp

Types

type z_timestamp_t

Functions

z_id_t z_timestamp_id(const z_timestamp_t *ts)

Returns id associated with this timestamp.

uint64_t z_timestamp_ntp64_time(const z_timestamp_t *ts)

Returns NTP64 time associated with this timestamp.

bool z_timestamp_check(z_timestamp_t ts)

Checks validity of a timestamp

Parameters:

  • ts – Timestamp value to check validity of.

Returns:

true if timestamp is valid, false otherwise.

Closures

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

  • context: a pointer to an arbitrary state.

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

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

Closures are not guaranteed not to be called concurrently.

It is guaranteed that:

  • call will never be called once drop has started.

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

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

Sample closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_sample_t
type z_loaned_closure_sample_t
type z_moved_closure_sample_t

Functions

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

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

Parameters:

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

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

  • context – Pointer to an arbitrary state.

Returns:

The sample closure.

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

Calls sample closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_sample_t *z_closure_sample_loan(const z_owned_closure_sample_t *closure)
void z_closure_sample_drop(z_moved_closure_sample_t *closure)

Query closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_query_t
type z_loaned_closure_query_t
type z_moved_closure_query_t

Functions

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

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

Parameters:

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

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

  • context – Pointer to an arbitrary state.

Returns:

The query closure.

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

Calls query closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_query_t *z_closure_query_loan(const z_owned_closure_query_t *closure)
void z_closure_query_drop(z_moved_closure_query_t *closure)

Reply closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_reply_t
type z_loaned_closure_reply_t
type z_moved_closure_reply_t

Functions

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

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

Parameters:

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

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

  • context – Pointer to an arbitrary state.

Returns:

The reply closure.

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

Calls reply closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_reply_t *z_closure_reply_loan(const z_owned_closure_reply_t *closure)
void z_closure_reply_drop(z_moved_closure_reply_t *closure)

Hello closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_hello_t
type z_loaned_closure_hello_t
type z_moved_closure_hello_t

Functions

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

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

Parameters:

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

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

  • context – Pointer to an arbitrary state.

Returns:

The hello closure.

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

Calls hello closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_hello_t *z_closure_hello_loan(const z_owned_closure_hello_t *closure)
void z_closure_hello_drop(z_moved_closure_hello_t *closure)

ID closure

Types

See details at Owned Types z_owned_xxx_t

type z_owned_closure_zid_t
type z_loaned_closure_zid_t
type z_moved_closure_zid_t

Functions

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

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

Parameters:

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

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

  • context – Pointer to an arbitrary state.

Returns:

The zid closure.

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

Calls zid closure.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_closure_zid_t *z_closure_zid_loan(const z_owned_closure_zid_t *closure)
void z_closure_zid_drop(z_moved_closure_zid_t *closure)

Channels

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

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

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

The methods common for all channles:

  • z_yyy_channel_xxx_new: Constructs the send and receive ends of the yyy (fifo or ring) channel for items type xxx.

  • z_yyy_handler_xxx_recv: Receives an item from the channel (blocking). If no more items are available or the channel is dropped, the item transitions to the gravestone state.

  • z_yyy_handler_xxx_try_recv: Attempts to receive an item immediately (non-blocking). Returns a gravestone state if no data is available.

  • z_yyy_handler_xxx_loan: Borrows the handler for access.

  • z_yyy_handler_xxx_drop: Drops the the handler, setting it to a gravestone state.

Sample channel

Types

See details at Owned Types z_owned_xxx_t

type z_owned_fifo_handler_sample_t
type z_loaned_fifo_handler_sample_t
type z_owned_ring_handler_sample_t
type z_loaned_ring_handler_sample_t

Methods

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

See details at Channels

z_result_t z_fifo_handler_sample_recv(const z_loaned_fifo_handler_sample_t *handler, z_owned_sample_t *sample)
z_result_t z_fifo_handler_sample_try_recv(const z_loaned_fifo_handler_sample_t *handler, z_owned_sample_t *sample)
z_result_t z_ring_handler_sample_recv(const z_loaned_ring_handler_sample_t *handler, z_owned_sample_t *sample)
z_result_t z_ring_handler_sample_try_recv(const z_loaned_ring_handler_sample_t *handler, z_owned_sample_t *sample)

See details at Channels

const z_loaned_fifo_handler_sample_t *z_fifo_handler_sample_loan(const z_owned_fifo_handler_sample_t *handler)
void z_fifo_handler_sample_drop(z_moved_fifo_handler_sample_t *handler)
const z_loaned_ring_handler_sample_t *z_ring_handler_sample_loan(const z_owned_ring_handler_sample_t *handler)
void z_ring_handler_sample_drop(z_moved_ring_handler_sample_t *handler)

See details at Owned Types z_owned_xxx_t

Query channel

Types

See details at Owned Types z_owned_xxx_t

type z_owned_fifo_handler_query_t
type z_loaned_fifo_handler_query_t
type z_owned_ring_handler_query_t
type z_loaned_ring_handler_query_t

Methods

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

See details at Channels

z_result_t z_fifo_handler_query_recv(const z_loaned_fifo_handler_query_t *handler, z_owned_query_t *query)
z_result_t z_fifo_handler_query_try_recv(const z_loaned_fifo_handler_query_t *handler, z_owned_query_t *query)
z_result_t z_ring_handler_query_recv(const z_loaned_ring_handler_query_t *handler, z_owned_query_t *query)
z_result_t z_ring_handler_query_try_recv(const z_loaned_ring_handler_query_t *handler, z_owned_query_t *query)

See details at Channels

const z_loaned_fifo_handler_query_t *z_fifo_handler_query_loan(const z_owned_fifo_handler_query_t *handler)
void z_fifo_handler_query_drop(z_moved_fifo_handler_query_t *handler)
const z_loaned_ring_handler_query_t *z_ring_handler_query_loan(const z_owned_ring_handler_query_t *handler)
void z_ring_handler_query_drop(z_moved_ring_handler_query_t *handler)

See details at Owned Types z_owned_xxx_t

Reply channel

Types

See details at Owned Types z_owned_xxx_t

type z_owned_fifo_handler_reply_t
type z_loaned_fifo_handler_reply_t
type z_owned_ring_handler_reply_t
type z_loaned_ring_handler_reply_t

Methods

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

See details at Channels

z_result_t z_fifo_handler_reply_recv(const z_loaned_fifo_handler_reply_t *handler, z_owned_reply_t *reply)
z_result_t z_fifo_handler_reply_try_recv(const z_loaned_fifo_handler_reply_t *handler, z_owned_reply_t *reply)
z_result_t z_ring_handler_reply_recv(const z_loaned_ring_handler_reply_t *handler, z_owned_reply_t *reply)
z_result_t z_ring_handler_reply_try_recv(const z_loaned_ring_handler_reply_t *handler, z_owned_reply_t *reply)

See details at Channels

const z_loaned_fifo_handler_reply_t *z_fifo_handler_reply_loan(const z_owned_fifo_handler_reply_t *handler)
void z_fifo_handler_reply_drop(z_moved_fifo_handler_reply_t *handler)
const z_loaned_ring_handler_reply_t *z_ring_handler_reply_loan(const z_owned_ring_handler_reply_t *handler)
void z_ring_handler_reply_drop(z_moved_ring_handler_reply_t *handler)

See details at Owned Types z_owned_xxx_t

System

Random

Functions

uint8_t z_random_u8(void)

Generates a random unsigned 8-bit integer.

uint16_t z_random_u16(void)

Generates a random unsigned 16-bit integer.

uint32_t z_random_u32(void)

Generates a random unsigned 32-bit integer.

uint64_t z_random_u64(void)

Generates a random unsigned 64-bit integer.

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)
z_result_t z_sleep_ms(size_t time)
z_result_t z_sleep_us(size_t time)

Time

Types

type z_clock_t
type z_time_t

Functions

z_clock_t z_clock_now(void)
unsigned long z_clock_elapsed_s(z_clock_t *time)
unsigned long z_clock_elapsed_ms(z_clock_t *time)
unsigned long z_clock_elapsed_us(z_clock_t *time)
z_time_t z_time_now(void)
unsigned long z_time_elapsed_s(z_time_t *time)
unsigned long z_time_elapsed_ms(z_time_t *time)
unsigned long z_time_elapsed_us(z_time_t *time)
const char *z_time_now_as_str(char *const buf, unsigned long buflen)

Mutex

Types

See details at Owned Types z_owned_xxx_t

type z_owned_mutex_t
type z_loaned_mutex_t
type z_moved_mutex_t

Functions

z_result_t z_mutex_init(z_owned_mutex_t *m)

Constructs a mutex.

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_mutex_lock(z_loaned_mutex_t *m)

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

Returns:

0 in case of success, negative error code otherwise.

z_result_t z_mutex_unlock(z_loaned_mutex_t *m)

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(z_loaned_mutex_t *m)

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

Returns:

0 in case of success, negative error code otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_mutex_drop(z_moved_mutex_t *mutex)
const z_loaned_mutex_t *z_mutex_loan(const z_owned_mutex_t *mutex)

Conditional Variable

Types

See details at Owned Types z_owned_xxx_t

type z_owned_condvar_t
type z_loaned_condvar_t
type z_moved_condvar_t

Functions

z_result_t z_condvar_init(z_owned_condvar_t *cv)
z_result_t z_condvar_wait(z_loaned_condvar_t *cv, z_loaned_mutex_t *m)
z_result_t z_condvar_signal(z_loaned_condvar_t *cv)

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_condvar_drop(z_moved_condvar_t *condvar)
const z_loaned_condvar_t *z_condvar_loan(const z_owned_condvar_t *condvar)

Task

Types

type z_owned_task_t
type z_moved_task_t

Functions

z_result_t z_task_init(z_owned_task_t *task, z_task_attr_t *attr, void *(*fun)(void*), void *arg)
z_result_t z_task_join(z_moved_task_t *task)

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_task_drop(z_moved_task_t *task)

Session

Session configuration

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

Types

See details at Owned Types z_owned_xxx_t

type z_owned_config_t
type z_loaned_config_t
type z_moved_config_t

Functions

void z_config_new(z_owned_config_t *config)

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

Parameters:
z_result_t z_config_default(z_owned_config_t *config)

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

Parameters:
Returns:

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

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

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

Parameters:

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

  • key – Integer key of the requested property.

Returns:

The requested property value.

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

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

Parameters:

  • config – Pointer to a z_loaned_config_t to modify.

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

  • value – Property value to be inserted.

Returns:

0 if insertion successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_config_drop(z_moved_config_t *config)
void z_config_clone(z_owned_config_t *dst, const z_loaned_config_t *config)
const z_loaned_config_t *z_config_loan(const z_owned_config_t *config)
z_loaned_config_t *z_config_loan_mut(z_owned_config_t *config)

Session management

Represents a Zenoh Session.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_session_t
type z_loaned_session_t
type z_moved_session_t
type z_id_t

Functions

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

Opens a Zenoh session.

Parameters:
Returns:

0 if open successful, negative value otherwise.

z_result_t z_close(z_moved_session_t *zs, const z_close_options_t *options)

Closes a Zenoh session.

Parameters:
Returns:

0 if close successful, negative value otherwise.

z_id_t z_info_zid(const z_loaned_session_t *zs)

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

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

Parameters:
Returns:

The local Zenoh ID of the session as z_id_t.

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

Fetches Zenoh IDs of all connected routers.

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

Parameters:
Returns:

0 if operation successfully triggered, negative value otherwise.

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

Fetches Zenoh IDs of all connected peers.

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

Parameters:
Returns:

0 if operation successfully triggered, negative value otherwise.

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

Converts a Zenoh ID into a string for print purposes.

Parameters:

  • id – Pointer to the id to convert.

  • str – Pointer to uninitialized z_owned_string_t to store the string.

Returns:

0 if operation successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_session_t *z_session_loan(const z_owned_session_t *closure)
void z_session_drop(z_moved_session_t *closure)

Publication

Represents a Zenoh Publisher entity.

Types

See details at Owned Types z_owned_xxx_t

type z_owned_publisher_t
type z_loaned_publisher_t
type z_moved_publisher_t

Option Types

type z_put_options_t

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

z_moved_encoding_t *encoding

The encoding of the payload.

z_congestion_control_t congestion_control

The congestion control to apply when routing this message.

z_priority_t priority

The priority of this message when routed.

z_timestamp_t *timestamp

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

bool is_express

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

z_moved_bytes_t *attachment

An optional attachment to the publication.

z_reliability_t reliability

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

type z_delete_options_t

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

z_congestion_control_t congestion_control

The congestion control to apply when routing this message.

z_priority_t priority

The priority of this message when router.

bool is_express

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

z_timestamp_t *timestamp

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

z_reliability_t reliability

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

type z_publisher_options_t

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

z_owned_encoding_t *encoding

Default encoding for messages put by this publisher.

z_congestion_control_t congestion_control

The congestion control to apply when routing messages from this

publisher.

z_priority_t priority: The priority of messages issued by this publisher. bool is_express: If true, Zenoh will not wait to batch this operation with others to reduce the bandwidth. z_reliability_t reliability: (unstable) The reliability that should be used to transmit the data.

type z_publisher_put_options_t

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

z_moved_encoding_t *encoding

The encoding of the payload.

z_timestamp_t *timestamp

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

z_moved_bytes_t *attachment

An optional attachment to the publication.

type z_publisher_delete_options_t

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

z_timestamp_t *timestamp

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

Constants

enum z_congestion_control_t

Congestion control values.

enumerator Z_CONGESTION_CONTROL_BLOCK

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

enumerator Z_CONGESTION_CONTROL_DROP

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

enum z_priority_t

Priority of Zenoh messages values.

enumerator _Z_PRIORITY_CONTROL

Priority for Control messages.

enumerator Z_PRIORITY_REAL_TIME

Priority for RealTime messages.

enumerator Z_PRIORITY_INTERACTIVE_HIGH

Highest priority for Interactive messages.

enumerator Z_PRIORITY_INTERACTIVE_LOW

Lowest priority for Interactive messages.

enumerator Z_PRIORITY_DATA_HIGH

Highest priority for Data messages.

enumerator Z_PRIORITY_DATA

Default priority for Data messages.

enumerator Z_PRIORITY_DATA_LOW

Lowest priority for Data messages.

enumerator Z_PRIORITY_BACKGROUND

Priority for Background traffic messages.

enum z_reliability_t

Reliability values.

enumerator Z_RELIABILITY_BEST_EFFORT

Defines reliability as BEST_EFFORT

enumerator Z_RELIABILITY_RELIABLE

Defines reliability as RELIABLE

Functions

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

Puts data for a given keyexpr.

Parameters:

  • zs – Pointer to a z_loaned_session_t to put the data through.

  • keyexpr – Pointer to a z_loaned_keyexpr_t to put the data for.

  • payload – Moved z_owned_bytes_t containing the data to put.

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

Returns:

0 if put operation successful, negative value otherwise.

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

Deletes data for a given keyexpr.

Parameters:
Returns:

0 if delete operation successful, negative value otherwise.

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

Declares a publisher for a given keyexpr.

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

Parameters:
Returns:

0 if declare successful, negative value otherwise.

z_result_t z_publisher_put(const z_loaned_publisher_t *pub, z_moved_bytes_t *payload, const z_publisher_put_options_t *options)

Puts data for the keyexpr bound to the given publisher.

Parameters:
Returns:

0 if put operation successful, negative value otherwise.

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

Deletes data from the keyexpr bound to the given publisher.

Parameters:
Returns:

0 if delete operation successful, negative value otherwise.

z_result_t z_undeclare_publisher(z_moved_publisher_t *pub)

Undeclares and clears the publisher.

Parameters:
Returns:

0 if undeclare successful, negative value otherwise.

const z_loaned_keyexpr_t *z_publisher_keyexpr(const z_loaned_publisher_t *publisher)

Gets the keyexpr from a publisher.

Parameters:
Returns:

The keyexpr wrapped as a z_loaned_keyexpr_t.

void z_put_options_default(z_put_options_t *options)

Builds a z_put_options_t with default values.

:param Pointer to an uninitialized z_put_options_t.:

void z_delete_options_default(z_delete_options_t *options)

Builds a z_delete_options_t with default values.

:param Pointer to an uninitialized z_delete_options_t.:

void z_publisher_options_default(z_publisher_options_t *options)

Builds a z_publisher_options_t with default values.

:param Pointer to an uninitialized z_delete_options_t.:

void z_publisher_put_options_default(z_publisher_put_options_t *options)

Builds a z_publisher_put_options_t with default values.

Parameters:
void z_publisher_delete_options_default(z_publisher_delete_options_t *options)

Builds a z_publisher_delete_options_t with default values.

Parameters:
z_reliability_t z_reliability_default(void)

Gets the default reliability value (unstable).

Returns:

The reliability wrapped as a z_reliability_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_publisher_t *z_publisher_loan(const z_owned_publisher_t *closure)
void z_publisher_drop(z_moved_publisher_t *closure)

Subscription

Types

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

type z_owned_subscriber_t
type z_loaned_subscriber_t
type z_moved_subscriber_t

Option Types

type z_subscriber_options_t

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

Functions

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

Declares a subscriber for a given keyexpr. Note that dropping subscriber does not drop its callback, meaning that after subscriber drop the messages will still be receieved and processed, until the corresponding session is dropped. To disable the callback with cleanup use z_subscriber_undeclare().

Parameters:
Returns:

0 if declare successful, negative value otherwise.

z_result_t z_undeclare_subscriber(z_moved_subscriber_t *sub)

Undeclares and clears the subscriber.

Parameters:
Returns:

0 if undeclare successful, negative value otherwise.

void z_subscriber_options_default(z_subscriber_options_t *options)

Builds a z_subscriber_options_t with default values.

Parameters:
const z_loaned_keyexpr_t *z_subscriber_keyexpr(const z_loaned_subscriber_t *subscriber)

Gets the keyexpr from a subscriber.

Parameters:
Returns:

The keyexpr wrapped as a z_loaned_keyexpr_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

const z_loaned_subscriber_t *z_subscriber_loan(const z_owned_subscriber_t *closure)
void z_subscriber_drop(z_moved_subscriber_t *closure)

Queryable

Types

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

type z_owned_queryable_t
type z_loaned_queryable_t
type z_moved_queryable_t

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

type z_owned_query_t
type z_loaned_query_t
type z_moved_query_t

Option Types

type z_queryable_options_t

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

bool complete

The completeness of the queryable.

type z_query_reply_options_t

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

z_moved_encoding_t *encoding

The encoding of the payload.

z_congestion_control_t congestion_control

The congestion control to apply when routing this message.

z_priority_t priority

The priority of this message when routed.

z_timestamp_t *timestamp

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

bool is_express

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

z_moved_bytes_t *attachment

An optional attachment to the response.

type z_query_reply_err_options_t

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

z_moved_encoding_t *encoding

The encoding of the payload.

type z_query_reply_del_options_t

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

z_congestion_control_t congestion_control

The congestion control to apply when routing this message.

z_priority_t priority

The priority of this message when routed.

z_timestamp_t *timestamp

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

bool is_express

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

z_moved_bytes_t *attachment

An optional attachment to the response.

Functions

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

Declares a queryable for a given keyexpr. Note that dropping queryable does not drop its callback, meaning that after queryable drop the messages will still be receieved and processed, until the corresponding session is dropped. To disable the callback with cleanup use z_undeclare_queryable().

Parameters:
Returns:

0 if declare operation successful, negative value otherwise.

z_result_t z_undeclare_queryable(z_moved_queryable_t *queryable)

Undeclares and clears the queryable.

Parameters:
Returns:

0 if undeclare operation successful, negative value otherwise.

void z_queryable_options_default(z_queryable_options_t *options)

Builds a z_queryable_options_t with default values.

Parameters:
void z_query_reply_options_default(z_query_reply_options_t *options)

Builds a z_query_reply_options_t with default values.

Parameters:
void z_query_reply_err_options_default(z_query_reply_err_options_t *options)

Builds a z_query_reply_err_options_t with default values.

Parameters:
void z_query_reply_del_options_default(z_query_reply_del_options_t *options)

Builds a z_query_reply_del_options_t with default values.

Parameters:
const z_loaned_keyexpr_t *z_query_keyexpr(const z_loaned_query_t *query)

Gets a query keyexpr by aliasing it.

Parameters:
Returns:

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

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

Gets a query parameters field.

Parameters:

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

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

const z_loaned_bytes_t *z_query_payload(const z_loaned_query_t *query)

Gets a query payload by aliasing it.

Parameters:
Returns:

Pointer to the payload as a z_loaned_bytes_t.

const z_loaned_encoding_t *z_query_encoding(const z_loaned_query_t *query)

Gets a query encoding by aliasing it.

Parameters:
Returns:

Pointer to the encoding as a z_loaned_encoding_t.

const z_loaned_bytes_t *z_query_attachment(const z_loaned_query_t *query)

Gets a query attachment value by aliasing it.

Parameters:
Returns:

Pointer to the attachment as a z_loaned_bytes_t.

z_result_t z_query_reply(const z_loaned_query_t *query, const z_loaned_keyexpr_t *keyexpr, z_moved_bytes_t *payload, const z_query_reply_options_t *options)

Sends a reply to a query.

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

Parameters:
Returns:

0 if reply operation successful, negative value otherwise.

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

Sends a reply error to a query.

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

Parameters:
Returns:

0 if reply operation successful, negative value otherwise.

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

Sends a reply delete to a query.

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

Parameters:
Returns:

0 if reply operation successful, negative value otherwise.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_queryable_drop(z_moved_queryable_t *closure)
const z_loaned_queryable_t *z_queryable_loan(const z_owned_queryable_t *closure)
void z_query_drop(z_moved_query_t *query)
void z_query_clone(z_owned_query_t *dst, const z_loaned_query_t *query)
const z_loaned_query_t *z_query_loan(const z_owned_query_t *query)

Query

Types

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

type z_owned_reply_t
type z_loaned_reply_t
type z_moved_reply_t

Option Types

type z_get_options_t

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

z_moved_bytes_t *payload

The payload to include in the query.

z_moved_encoding_t *encoding

Payload encoding.

z_query_consolidation_t consolidation

The replies consolidation strategy to apply on replies.

z_congestion_control_t congestion_control

The congestion control to apply when routing the query.

z_priority_t priority

The priority of the query.

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

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

enum z_query_target_t

Query target values.

enumerator Z_QUERY_TARGET_BEST_MATCHING

The nearest complete queryable if any else all matching queryables.

enumerator Z_QUERY_TARGET_ALL

All matching queryables.

enumerator Z_QUERY_TARGET_ALL_COMPLETE

A set of complete queryables.

enum z_consolidation_mode_t

Consolidation mode values.

enumerator Z_CONSOLIDATION_MODE_AUTO

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

enumerator Z_CONSOLIDATION_MODE_NONE

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

enumerator Z_CONSOLIDATION_MODE_MONOTONIC

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

enumerator Z_CONSOLIDATION_MODE_LATEST

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

type z_query_consolidation_t

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

z_consolidation_mode_t mode

the consolidation mode, see z_consolidation_mode_t

Functions

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

Sends a distributed query for a given keyexpr.

Parameters:
Returns:

0 if put operation successful, negative value otherwise.

void z_get_options_default(z_get_options_t *options)

Builds a z_get_options_t with default values.

Parameters:
z_query_consolidation_t z_query_consolidation_default(void)

Builds a default z_query_consolidation_t.

Returns:

The constructed z_query_consolidation_t.

z_query_consolidation_t z_query_consolidation_auto(void)

Builds an automatic query consolidation z_query_consolidation_t.

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

Returns:

The constructed z_query_consolidation_t.

z_query_consolidation_t z_query_consolidation_none(void)

Builds a no query consolidation z_query_consolidation_t.

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

Returns:

The constructed z_query_consolidation_t.

z_query_consolidation_t z_query_consolidation_monotonic(void)

Builds a monotonic query consolidation z_query_consolidation_t.

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

Returns:

The constructed z_query_consolidation_t.

z_query_consolidation_t z_query_consolidation_latest(void)

Builds a latest query consolidation z_query_consolidation_t.

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

Returns:

The constructed z_query_consolidation_t.

z_query_target_t z_query_target_default(void)

Builds a default query target.

Returns:

The constructed z_query_target_t.

bool z_reply_is_ok(const z_loaned_reply_t *reply)

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

Parameters:
Returns:

true if queryable answered with an OK, false otherwise.

const z_loaned_sample_t *z_reply_ok(const z_loaned_reply_t *reply)

Gets the content of an OK reply.

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

Parameters:
Returns:

The OK reply content wrapped as a z_loaned_sample_t.

const z_loaned_reply_err_t *z_reply_err(const z_loaned_reply_t *reply)

Gets the contents of an error reply.

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

Parameters:
Returns:

The error reply content wrapped as a z_loaned_reply_err_t.

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_reply_drop(z_moved_reply_t *reply)
void z_reply_clone(z_owned_reply_t *dst, const z_loaned_reply_t *reply)
const z_loaned_reply_t *z_reply_loan(const z_owned_reply_t *reply)

Scouting

Types

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

type z_owned_hello_t
type z_loaned_hello_t
type z_moved_hello_t

Option Types

type z_scout_options_t

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

uint64_t timeout_ms

The maximum duration in ms the scouting can take.

z_what_t what

Type of entities to scout for.

Functions

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

Primitives

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

Parameters:
Returns:

0 if scouting successfully triggered, negative value otherwise.

z_whatami_t z_hello_whatami(const z_loaned_hello_t *hello)

Returns type of Zenoh entity that transmitted hello message.

Parameters:
Returns:

Type of the Zenoh entity that transmitted hello message.

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

Constructs an array of locators of Zenoh entity that sent hello message. Note that it is a method for zenoh-c compatiblity, in zenoh-pico zp_hello_locators() can be used.

Parameters:
const z_loaned_string_array_t *zp_hello_locators(const z_loaned_hello_t *hello)

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

Parameters:
Returns:

z_loaned_string_array_t containing locators.

z_id_t z_hello_zid(const z_loaned_hello_t *hello)

Returns id of Zenoh entity that transmitted hello message.

Parameters:
Returns:

Id of the Zenoh entity that transmitted hello message.

z_result_t z_whatami_to_view_string(z_whatami_t whatami, z_view_string_t *str_out)

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

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

Returns:

0 in case of success, negative value otherwise.

void z_scout_options_default(z_scout_options_t *options)

Builds a z_scout_options_t with default value.

Parameters:

Ownership Functions

See details at Owned Types z_owned_xxx_t

void z_hello_drop(z_moved_hello_t *hello)
void z_hello_clone(z_owned_hello_t *dst, const z_loaned_hello_t *hello)
const z_loaned_hello_t *z_hello_loan(const z_owned_hello_t *hello)

Serialization (unstable)

Types

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

type ze_owned_serializer_t
type ze_loaned_serializer_t
type ze_moved_serializer_t
type ze_deserializer_t

Represents a reader for serialized data.

Functions

ze_deserializer_t ze_deserializer_from_bytes(const z_loaned_bytes_t *bytes)

Returns a deserializer for z_loaned_bytes_t.

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

Parameters:

  • bytes – Data to deserialize.

Returns:

The constructed ze_deserializer_t.

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

Deserializes next portion of data into a int8_t.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized int8_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes next portion of data into a int16_t.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized int16_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes next portion of data into a int32_t.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized int32_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes next portion of data into a int64_t.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized int64_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes next portion of data into a uint8_t.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized uint8_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes next portion of data into a uint16_t.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized uint16_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes next portion of data into a uint32_t.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized uint32_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes next portion of data into a uint64_t.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized uint64_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes next portion of data into a float.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized float to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes next portion of data into a double.

Parameters:

  • deserializer – A deserializer instance.

  • dst – Pointer to an uninitialized double to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

z_result_t ze_deserializer_deserialize_slice(ze_deserializer_t *deserializer, z_owned_slice_t *val)

Deserializes next portion of data and advances the reader position.

Parameters:

  • deserializer – A deserializer instance.

  • val – Pointer to an uninitialized z_owned_slice_t to contain the deserialized slice.

Returns:

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

z_result_t ze_deserializer_deserialize_string(ze_deserializer_t *deserializer, z_owned_string_t *val)

Deserializes next portion of data and advances the reader position.

Parameters:

  • deserializer – A deserializer instance.

  • val – Pointer to an uninitialized z_owned_string_t to contain the deserialized string.

Returns:

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

z_result_t ze_deserializer_deserialize_sequence_length(ze_deserializer_t *deserializer, size_t *len)

Initiate deserialization of a sequence of multiple elements.

Parameters:

  • deserializer – A deserializer instance.

  • len – A pointer where the length of the sequence (previously passed via

ze_serializer_serialize_sequence_length()) will be written.

Returns:

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

z_result_t ze_serializer_empty(ze_owned_serializer_t *serializer)

Constructs an empty serializer.

Parameters:

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

Returns:

0 in case of success, negative value otherwise.

void ze_serializer_finish(ze_moved_serializer_t *serializer, z_owned_bytes_t *bytes)

Finishes serialization and returns underlying bytes.

Parameters:

  • serializer – A data serializer.

  • bytes – An uninitialized memory location where bytes is to be constructed.

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

Writes a serialized int8_t into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – int8_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Writes a serialized int16_t into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – int16_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Writes a serialized int32_t into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – int32_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Writes a serialized int64_t into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – int64_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Writes a serialized uint8_t into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – uint8_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Writes a serialized uint16_t into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – uint16_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Writes a serialized uint32_t into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – uint32_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Writes a serialized uint64_t into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – uint64_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Writes a serialized float into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – float value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Writes a serialized double into underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – double value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Serializes slice and writes it into an underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – A slice to serialize.

  • len – Number of bytes to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

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

Parameters:

  • serializer – A serializer instance.

  • val – Pointer to the data to serialize.

  • len – Number of bytes to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Serializes a string and writes it into an underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – Pointer to the string to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Serializes a null-terminated string and writes it into an underlying z_owned_bytes_t.

Parameters:

  • serializer – A serializer instance.

  • val – Pointer to the string to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serializer_serialize_sequence_length(ze_loaned_serializer_t *serializer, size_t len)

Initiate serialization of a sequence of multiple elements.

Parameters:

  • serializer – A serializer instance.

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

ze_deserializer_deserialize_sequence_length().

Returns:

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

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

Deserializes data into a :c:type:`int8_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized int8_t to contain the deserialized.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a int16_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized int16_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a int32_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized int32_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a int64_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized int64_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a uint8_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized uint8_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a uint16_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized uint16_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a uint32_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized uint32_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a :c:type:`uint64_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized uint64_t to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a :c:type:`float.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized float to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a double.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • dst – Pointer to an uninitialized double to contain the deserialized number.

Returns:

0 if deserialization successful, or a negative value otherwise.

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

Deserializes data into a z_owned_slice_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • str – Pointer to an uninitialized z_owned_slice_t to contain the deserialized slice.

Returns:

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

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

Deserializes data into a z_owned_string_t.

Parameters:

  • bytes – Pointer to a z_loaned_bytes_t to deserialize.

  • str – Pointer to an uninitialized z_owned_string_t to contain the deserialized string.

Returns:

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

bool ze_deserializer_is_done(const ze_deserializer_t *deserializer)

Checks if deserializer parsed all of its data.

Parameters:

  • deserializer – A deserializer instance.

Returns:

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

z_result_t ze_serialize_int8(z_owned_bytes_t *bytes, int8_t val)

Serializes a int8_t into a z_owned_bytes_t .

Parameters:

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

  • val – int8_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_int16(z_owned_bytes_t *bytes, int16_t val)

Serializes a int16_t into a z_owned_bytes_t.

Parameters:

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

  • val – int16_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_int32(z_owned_bytes_t *bytes, int32_t val)

Serializes a int32_t into a z_owned_bytes_t.

Parameters:

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

  • val – int32_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_int64(z_owned_bytes_t *bytes, int64_t val)

Serializes a int64_t into a z_owned_bytes_t.

Parameters:

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

  • val – int64_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_uint8(z_owned_bytes_t *bytes, uint8_t val)

Serializes a uint8_t into a z_owned_bytes_t.

Parameters:

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

  • val – uint8_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_uint16(z_owned_bytes_t *bytes, uint16_t val)

Serializes a uint16_t into a z_owned_bytes_t.

Parameters:

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

  • val – uint16_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_uint32(z_owned_bytes_t *bytes, uint32_t val)

Serializes a uint32_t into a z_owned_bytes_t.

Parameters:

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

  • val – uint32_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_uint64(z_owned_bytes_t *bytes, uint64_t val)

Serializes a uint64_t into a z_owned_bytes_t.

Parameters:

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

  • val – uint64_t value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_float(z_owned_bytes_t *bytes, float val)

Serializes a float into a z_owned_bytes_t.

Parameters:

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

  • val – float value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

z_result_t ze_serialize_double(z_owned_bytes_t *bytes, double val)

Serializes a double into a z_owned_bytes_t.

Parameters:

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

  • val – double value to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Serializes a slice into a z_owned_bytes_t.

Parameters:

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

  • slice – Pointer to the slice to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Serializes data into a z_owned_bytes_t.

Parameters:

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

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

  • len – Number of bytes to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Serializes a string into a z_owned_bytes_t.

Parameters:

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

  • s – Pointer to the string to serialize.

Returns:

0 if serialization is successful, negative value otherwise.

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

Serializes a null-terminated string into a z_owned_bytes_t.

Parameters:

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

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

Returns:

0 if serialization is successful, negative value otherwise.

Others

Data Structures

typedef int z_zint_t

Represents a variable-length encoding unsigned integer.

It is equivalent to the size of a size_t.

type zp_task_read_options_t

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

type zp_task_lease_options_t

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

type zp_read_options_t

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

type zp_send_keep_alive_options_t

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

type zp_send_join_options_t

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

Constants

enum z_whatami_t

Whatami values, defined as a bitmask.

enumerator Z_WHATAMI_ROUTER

Bitmask to filter Zenoh routers.

enumerator Z_WHATAMI_PEER

Bitmask to filter for Zenoh peers.

enumerator Z_WHATAMI_CLIENT

Bitmask to filter for Zenoh clients.

Macros

z_loan(x)
z_move(x)

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

Parameters:

  • x – The instance to move.

Returns:

Returns the instance associated with x.

z_clone(dst, src)

Defines a generic function for cloning of the z_owned_X_t types.

Parameters:

  • dst – The clone destination.

  • src – The instance to clone.

Returns:

0 in case of success, negative error code otherwise.

z_drop(x)

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

Parameters:

  • x – The instance to drop.

z_closure()

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

Parameters:

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

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

  • context – a pointer to an arbitrary state.

Returns:

Returns the new closure.

Functions

void zp_task_read_options_default(zp_task_read_options_t *options)

Multi Thread Tasks helpers

Builds a zp_task_read_options_t with default value.

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

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

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

Parameters:
Returns:

0 if task started successfully, negative value otherwise.

z_result_t zp_stop_read_task(z_loaned_session_t *zs)

Stops the read task.

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

Parameters:
Returns:

0 if task stopped successfully, negative value otherwise.

void zp_task_lease_options_default(zp_task_lease_options_t *options)

Builds a zp_task_lease_options_t with default value.

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

Starts a task to handle the session lease.

This task will send KeepAlive messages when needed and will close the session when the lease is expired. When operating over a multicast transport, it also periodically sends the Join messages. Note that the task can be implemented in form of thread, process, etc. and its implementation is platform-dependent.

Parameters:
Returns:

0 if task started successfully, negative value otherwise.

z_result_t zp_stop_lease_task(z_loaned_session_t *zs)

Stops the lease task.

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

Parameters:
Returns:

0 if task stopped successfully, negative value otherwise.

void zp_read_options_default(zp_read_options_t *options)

Single Thread helpers

Builds a zp_read_options_t with default value.

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

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

Parameters:
Returns:

0 if execution was successful, negative value otherwise.

void zp_send_keep_alive_options_default(zp_send_keep_alive_options_t *options)

Builds a zp_send_keep_alive_options_t with default value.

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

Executes a single send keep alive procedure.

Parameters:
Returns:

0 if execution was successful, negative value otherwise.

void zp_send_join_options_default(zp_send_join_options_t *options)

Builds a zp_send_join_options_t with default value.

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

Executes a single send join procedure.

Parameters:
Returns:

0 if execution was successful, negative value otherwise.