API Reference
Zenoh Types
Enums
-
enum z_whatami_t
Whatami values, defined as a bitmask.
-
enumerator Z_WHATAMI_ROUTER
Bitmask to filter Zenoh routers.
-
enumerator Z_WHATAMI_PEER
Bitmask to filter for Zenoh peers.
-
enumerator Z_WHATAMI_CLIENT
Bitmask to filter for Zenoh clients.
-
enumerator Z_WHATAMI_ROUTER
-
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()
orz_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.
-
enumerator Z_KEYEXPR_CANON_SUCCESS
-
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.
-
enumerator Z_SAMPLE_KIND_PUT
-
enum z_encoding_prefix_t
Zenoh encoding values. These values are based on already existing HTTP MIME types and extended with other relevant encodings.
-
enumerator Z_ENCODING_PREFIX_EMPTY
Encoding not defined.
-
enumerator Z_ENCODING_PREFIX_APP_OCTET_STREAM
application/octet-stream
. Default value for all other cases. An unknown file type should use this type. Z_ENCODING_PREFIX_APP_CUSTOM: Custom application type. Non IANA standard.
-
enumerator Z_ENCODING_PREFIX_TEXT_PLAIN
text/plain
. Default value for textual files. A textual file should be human-readable and must not contain binary data. Z_ENCODING_PREFIX_APP_PROPERTIES: Application properties type. Non IANA standard. Z_ENCODING_PREFIX_APP_JSON:application/json
. JSON format.
-
enumerator Z_ENCODING_PREFIX_APP_SQL
Application sql type. Non IANA standard. Z_ENCODING_PREFIX_APP_INTEGER: Application integer type. Non IANA standard. Z_ENCODING_PREFIX_APP_FLOAT: Application float type. Non IANA standard.
-
enumerator Z_ENCODING_PREFIX_APP_XML
application/xml
. XML.
-
enumerator Z_ENCODING_PREFIX_APP_XHTML_XML
application/xhtml+xml
. XHTML.
-
enumerator Z_ENCODING_PREFIX_APP_X_WWW_FORM_URLENCODED
application/x-www-form-urlencoded
. The keys and values areencoded in key-value tuples separated by ‘&’, with a ‘=’ between the key and the value.
- Z_ENCODING_PREFIX_TEXT_JSON: Text JSON. Non IANA standard. Z_ENCODING_PREFIX_TEXT_HTML:
text/html
. HyperText Markup Language (HTML). Z_ENCODING_PREFIX_TEXT_XML:
text/xml
. Application/xml is recommended as of RFC 7303 (section 4.1), but text/xml is still used sometimes. Z_ENCODING_PREFIX_TEXT_CSS:text/css
. Cascading Style Sheets (CSS). Z_ENCODING_PREFIX_TEXT_CSV:text/csv
. Comma-separated values (CSV).
-
enumerator Z_ENCODING_PREFIX_TEXT_JAVASCRIPT
text/javascript
. JavaScript.
-
enumerator Z_ENCODING_PREFIX_IMAGE_JPEG
image/jpeg
. JPEG images.
-
enumerator Z_ENCODING_PREFIX_IMAGE_PNG
image/png
. Portable Network Graphics.
-
enumerator Z_ENCODING_PREFIX_IMAGE_GIF
image/gif
. Graphics Interchange Format (GIF).
-
enumerator Z_ENCODING_PREFIX_EMPTY
-
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.
-
enumerator Z_CONSOLIDATION_MODE_AUTO
-
enum z_reliability_t
Reliability values.
-
enumerator Z_RELIABILITY_BEST_EFFORT
Defines reliability as
BEST_EFFORT
-
enumerator Z_RELIABILITY_RELIABLE
Defines reliability as
RELIABLE
-
enumerator Z_RELIABILITY_BEST_EFFORT
-
enum z_reply_tag_t
Reply tag values.
-
enumerator Z_REPLY_TAG_DATA
Tag identifying that the reply contains some data.
-
enumerator Z_REPLY_TAG_FINAL
Tag identifying that the reply does not contain any data and that there will be no more replies for this query.
-
enumerator Z_REPLY_TAG_DATA
-
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.
-
enumerator Z_CONGESTION_CONTROL_BLOCK
-
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.
-
enumerator _Z_PRIORITY_CONTROL
Data Structures
-
typedef int z_zint_t
Represents a variable-length encoding unsigned integer.
It is equivalent to the size of a
size_t
.
-
typedef int z_bytes_t
Represents an array of bytes.
-
size_t len
The length of the bytes array.
-
uint8_t *start
A pointer to the bytes array.
-
size_t len
-
typedef int z_id_t
Represents a Zenoh ID.
In general, valid Zenoh IDs are LSB-first 128bit unsigned and non-zero integers.
-
uint8_t id[16]
The array containing the 16 octets of a Zenoh ID.
-
uint8_t id[16]
-
typedef int z_string_t
Represents a string without null-terminator.
-
size_t len
The length of the string.
-
const char *val
A pointer to the string.
-
size_t len
-
typedef int z_keyexpr_t
Represents a key expression in Zenoh.
Operations over
z_keyexpr_t
must be done using the provided functions:
-
type z_config_t
Represents a Zenoh configuration.
Configurations are usually used to set the parameters of a Zenoh session upon its opening.
Operations over
z_config_t
must be done using the provided functions:
-
type z_session_t
Represents a Zenoh session.
-
type z_subscriber_t
Represents a Zenoh (push) Subscriber entity.
Operations over
z_subscriber_t
must be done using the provided functions:
-
type z_pull_subscriber_t
Represents a Zenoh Pull Subscriber entity.
Operations over
z_pull_subscriber_t
must be done using the provided functions:
-
type z_publisher_t
Represents a Zenoh Publisher entity.
Operations over
z_publisher_t
must be done using the provided functions:
-
type z_queryable_t
Represents a Zenoh Queryable entity.
Operations over
z_queryable_t
must be done using the provided functions:
-
typedef int z_encoding_t
Represents the encoding of a payload, in a MIME-like format.
-
z_encoding_prefix_t prefix
The integer prefix of this encoding.
-
z_encoding_prefix_t prefix
-
typedef int z_value_t
Represents a Zenoh value.
-
z_encoding_t encoding
The encoding of the payload.
-
z_encoding_t encoding
-
type z_subscriber_options_t
Represents the set of options that can be applied to a (push) subscriber, upon its declaration via
z_declare_subscriber()
.-
z_reliability_t reliability
The subscription reliability.
-
z_reliability_t reliability
-
type z_pull_subscriber_options_t
Represents the set of options that can be applied to a pull subscriber, upon its declaration via
z_declare_pull_subscriber()
.-
z_reliability_t reliability
The subscription reliability.
-
z_reliability_t reliability
-
type z_query_consolidation_t
Represents the replies consolidation to apply on replies to a
z_get()
.-
z_consolidation_mode_t mode
Defines the consolidation mode to apply to the replies.
-
z_consolidation_mode_t mode
-
type z_publisher_options_t
Represents the set of options that can be applied to a publisher, upon its declaration via
z_declare_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.
-
z_congestion_control_t congestion_control
-
type z_queryable_options_t
Represents the set of options that can be applied to a queryable, upon its declaration via
z_declare_queryable()
.-
_Bool complete
The completeness of the queryable.
-
_Bool complete
-
type z_query_reply_options_t
Represents the set of options that can be applied to a query reply, sent via
z_query_reply()
.-
z_encoding_t encoding
The encoding of the payload.
-
z_attachment_t attachment
an attachment to the response.
-
z_encoding_t encoding
-
type z_put_options_t
Represents the set of options that can be applied to the put operation, whenever issued via
z_put()
.-
z_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_encoding_t encoding
-
type z_delete_options_t
Represents the set of options that can be applied to the delete operation, whenever issued 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.
-
z_congestion_control_t congestion_control
-
type z_publisher_put_options_t
Represents the set of options that can be applied to the put operation by a previously declared publisher, whenever issued via
z_publisher_put()
.-
z_encoding_t encoding
The encoding of the payload.
-
z_encoding_t encoding
-
type z_publisher_delete_options_t
Represents the set of options that can be applied to the delete operation by a previously declared publisher, whenever issued via
z_publisher_delete()
.
-
type z_get_options_t
Represents the set of options that can be applied to the get operation, whenever issued via
z_get()
.-
z_query_target_t target
The queryables that should be targeted by this get.
-
z_query_consolidation_t consolidation
The replies consolidation strategy to apply on replies.
-
z_query_target_t target
-
typedef int z_sample_t
Represents a data sample.
A sample is the value associated to a given
z_keyexpr_t
at a given point in time.-
z_keyexpr_t keyexpr
The keyexpr of this data sample.
-
z_encoding_t encoding
The encoding of the value of this data sample.
-
z_sample_kind_t kind
The kind of this data sample (PUT or DELETE).
-
z_timestamp_t timestamp
The timestamp of this data sample.
-
z_qos_t qos
Quality of service settings used to deliver this sample.
-
z_keyexpr_t keyexpr
-
typedef int z_hello_t
Represents the content of a hello message returned by a zenoh entity as a reply to a scout message.
-
z_whatami_t whatami
The kind of zenoh entity.
-
z_str_array_t locators
The locators of the scouted entity.
-
z_whatami_t whatami
-
typedef int z_reply_t
Represents the reply to a query.
-
z_reply_data_t data
the content of the reply.
-
z_reply_data_t data
-
typedef int z_reply_data_t
Represents the content of a reply to a query.
-
z_sample_t sample
The
_z_sample_t
containing the key and value of the reply.
-
z_sample_t sample
-
type zp_task_read_options_t
Represents the set of options that can be applied to the read task, whenever issued via
zp_start_read_task()
.
-
type zp_task_lease_options_t
Represents the set of options that can be applied to the lease task, whenever issued via
zp_start_lease_task()
.
-
type zp_read_options_t
Represents the set of options that can be applied to the read operation, whenever issued via
zp_read()
.
-
type zp_send_keep_alive_options_t
Represents the set of options that can be applied to the keep alive send, whenever issued via
zp_send_keep_alive()
.
Arrays
-
type z_str_array_t
Represents an array of
char *
.Operations over
z_str_array_t
must be done using the provided functions:char *z_str_array_get(z_str_array_t *a, size_t k);
size_t z_str_array_len(z_str_array_t *a);
_Bool z_str_array_array_is_empty(z_str_array_t *a);
Owned Types
Like most z_owned_X_t
types, you may obtain an instance of z_X_t
by loaning it using z_X_loan(&val)
.
The z_loan(val)
macro, available if your compiler supports C11’s _Generic
, is equivalent to writing z_X_loan(&val)
.
Like all z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved.
To make this fact more obvious when reading your code, consider using z_move(val)
instead of &val
as the argument.
After a move, val
will still exist, but will no longer be valid. The destructors are double-free-safe, but other functions will still trust that your val
is valid.
To check if val
is still valid, you may use z_X_check(&val)
or z_check(val)
if your compiler supports _Generic
, which will return true
if val
is valid.
-
type z_owned_str_t
A zenoh-allocated
char *
.
-
type z_owned_keyexpr_t
A zenoh-allocated
z_keyexpr_t
.
-
type z_owned_config_t
A zenoh-allocated
z_config_t
.
-
type z_owned_session_t
A zenoh-allocated
z_session_t
.
-
type z_owned_subscriber_t
A zenoh-allocated
z_subscriber_t
.
-
type z_owned_pull_subscriber_t
A zenoh-allocated
z_pull_subscriber_t
.
-
type z_owned_publisher_t
A zenoh-allocated
z_publisher_t
.
-
type z_owned_queryable_t
A zenoh-allocated
z_queryable_t
.
-
type z_owned_str_array_t
A zenoh-allocated
z_str_array_t
.
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 oncedrop
has started.drop
will only be called once, and after everycall
has ended.The two previous guarantees imply that
call
anddrop
are never called concurrently.
-
type z_owned_closure_sample_t
Represents the sample closure.
A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks.
-
_z_data_handler_t call
void *call(const struct z_sample_t*, const void *context) is the callback function.
-
_z_dropper_handler_t drop
void *drop(void*) allows the callback’s state to be freed.
-
void *context
a pointer to an arbitrary state.
-
_z_data_handler_t call
-
type z_owned_closure_query_t
Represents the query callback closure.
A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks.
-
_z_queryable_handler_t call
void (*_z_queryable_handler_t)(z_query_t *query, void *arg) is the
- callback function.
_z_dropper_handler_t drop: void *drop(void*) allows the callback’s state to be freed. void *context: a pointer to an arbitrary state.
-
_z_queryable_handler_t call
-
type z_owned_closure_reply_t
Represents the query reply callback closure.
A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks.
-
z_owned_reply_handler_t call
void (*z_owned_reply_handler_t)(z_owned_reply_t reply, void *arg) is the callback
- function.
_z_dropper_handler_t drop: void *drop(void*) allows the callback’s state to be freed. void *context: a pointer to an arbitrary state.
-
z_owned_reply_handler_t call
-
type z_owned_closure_hello_t
Represents the Zenoh ID callback closure.
A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks.
-
z_owned_hello_handler_t call
void (*z_owned_hello_handler_t)(const z_owned_hello_t *hello, void *arg) is the
- callback function.
_z_dropper_handler_t drop: void *drop(void*) allows the callback’s state to be freed. void *context: a pointer to an arbitrary state.
-
z_owned_hello_handler_t call
-
type z_owned_closure_zid_t
Represents the Zenoh ID callback closure.
A closure is a structure that contains all the elements for stateful, memory-leak-free callbacks.
-
z_id_handler_t call
void (*z_id_handler_t)(const z_id_t *id, void *arg) is the callback function.
-
_z_dropper_handler_t drop
void *drop(void*) allows the callback’s state to be freed.
-
void *context
a pointer to an arbitrary state.
-
z_id_handler_t call
Zenoh Functions
Macros
-
z_loan(x)
-
z_move(x)
Defines a generic function for moving any of the
z_owned_X_t
types.- Parameters:
x – The instance to move.
- Returns:
Returns the instance associated with x.
-
z_check(x)
-
z_clone(x)
Defines a generic function for cloning any of the
z_owned_X_t
types.- Parameters:
x – The instance to clone.
- Returns:
Returns the cloned instance of x.
-
z_drop(x)
Defines a generic function for dropping any of the
z_owned_X_t
types.- Parameters:
x – The instance to drop.
-
z_closure()
Defines a variadic macro to ease the definition of callback closures.
- Parameters:
callback – the typical
callback
function.context
will be passed as its last argument.dropper – allows the callback’s state to be freed.
context
will be passed as its last argument.context – a pointer to an arbitrary state.
- Returns:
Returns the new closure.
-
z_null(x)
Defines a generic function for making null object of any of the
z_owned_X_t
types.- Returns:
Returns the uninitialized instance of x.
Primitives
-
z_keyexpr_t z_keyexpr(const char *name)
Constructs a
z_keyexpr_t
departing from a string. It is a loaned key expression that aliasesname
. Unlike it’s counterpart in zenoh-c, this function does not test passed expression to correctness.- Parameters:
name – Pointer to string representation of the keyexpr as a null terminated string.
- Returns:
The
z_keyexpr_t
corresponding to the given string.
-
z_owned_str_t z_keyexpr_to_string(z_keyexpr_t keyexpr)
Get null-terminated string departing from a
z_keyexpr_t
.If given keyexpr contains a declared keyexpr, the resulting owned string will be uninitialized. In that case, the user must use
zp_keyexpr_resolve()
to resolve the nesting declarations and get its full expanded representation.- Parameters:
keyexpr – A loaned instance of
z_keyexpr_t
- Returns:
The
z_owned_str_t
containing key expression string representation if it’s possible
-
z_owned_str_t zp_keyexpr_resolve(z_session_t zs, z_keyexpr_t keyexpr)
Constructs a null-terminated string departing from a
z_keyexpr_t
for a givenz_session_t
. The user is responsible of dropping the returned string usingz_free
.- Parameters:
zs – A loaned instance of the the
z_session_t
to resolve the keyexpr.keyexpr – A loaned instance of
z_keyexpr_t
to be resolved.
- Returns:
The string representation of a keyexpr for a given session.
-
_Bool z_keyexpr_is_initialized(const z_keyexpr_t *keyexpr)
Checks if a given keyexpr is valid.
- Parameters:
keyexpr – A loaned instance of
z_keyexpr_t
to be checked.
- Returns:
Returns
true
if the keyexpr is valid, orfalse
otherwise.
-
int8_t z_keyexpr_is_canon(const char *start, size_t len)
Check if a given keyexpr is valid and in its 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:
Returns
0
if the passed string is a valid (and canon) key expression, or anegative value
otherwise. Error codes are defined inzp_keyexpr_canon_status_t
.
-
int8_t zp_keyexpr_is_canon_null_terminated(const char *start)
Check if a given keyexpr is valid and in its canonical form.
- Parameters:
start – Pointer to the keyexpr in its string representation as a null terminated string.
len – Number of characters in
start
.
- Returns:
Returns
0
if the passed string is a valid (and canon) key expression, or anegative value
otherwise. Error codes are defined inzp_keyexpr_canon_status_t
.
-
int8_t z_keyexpr_canonize(char *start, size_t *len)
Canonization of a given keyexpr in its its 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:
Returns
0
if the canonization is successful, or anegative value
otherwise. Error codes are defined inzp_keyexpr_canon_status_t
.
-
int8_t zp_keyexpr_canonize_null_terminated(char *start)
Canonization of a given keyexpr in its its 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 null terminated string.
len – Number of characters in
start
.
- Returns:
Returns
0
if the canonization is successful, or anegative value
otherwise. Error codes are defined inzp_keyexpr_canon_status_t
.
-
int8_t z_keyexpr_includes(z_keyexpr_t l, z_keyexpr_t r)
Check if a given keyexpr contains another keyexpr in its set.
- Parameters:
l – The first keyexpr.
r – The second keyexpr.
- Returns:
Returns
0
ifl
includesr
, i.e. the set defined byl
contains every key belonging to the set
defined by
r
. Otherwise, it returns a-1
, or othernegative value
for errors.
-
int8_t zp_keyexpr_includes_null_terminated(const char *l, const char *r)
Check if a given keyexpr contains another keyexpr in its set.
- Parameters:
l – Pointer to the keyexpr in its string representation as a null terminated string.
llen – Number of characters in
l
.r – Pointer to the keyexpr in its string representation as a null terminated string.
rlen – Number of characters in
r
.
- Returns:
Returns
0
ifl
includesr
, i.e. the set defined byl
contains every key belonging to the set
defined by
r
. Otherwise, it returns a-1
, or othernegative value
for errors.
-
int8_t z_keyexpr_intersects(z_keyexpr_t l, z_keyexpr_t r)
Check if a given keyexpr intersects with another keyexpr.
- Parameters:
l – The first keyexpr.
r – The second keyexpr.
- Returns:
Returns
0
if the keyexprs intersect, i.e. there exists at least one key which is contained in both of the
sets defined by
l
andr
. Otherwise, it returns a-1
, or othernegative value
for errors.
-
int8_t zp_keyexpr_intersect_null_terminated(const char *l, const char *r)
Check if a given keyexpr intersects with another keyexpr.
- Parameters:
l – Pointer to the keyexpr in its string representation as a null terminated string.
llen – Number of characters in
l
.r – Pointer to the keyexpr in its string representation as a null terminated string.
rlen – Number of characters in
r
.
- Returns:
Returns
0
if the keyexprs intersect, i.e. there exists at least one key which is contained in both of the
sets defined by
l
andr
. Otherwise, it returns a-1
, or othernegative value
for errors.
-
int8_t z_keyexpr_equals(z_keyexpr_t l, z_keyexpr_t r)
Check if a two keyexprs are equal.
- Parameters:
l – The first keyexpr.
r – The second keyexpr.
- Returns:
Returns
0
if bothl
andr
are equal. Otherwise, it returns a-1
, or othernegative value
for
errors.
-
int8_t zp_keyexpr_equals_null_terminated(const char *l, const char *r)
Check if a two keyexprs are equal.
- Parameters:
l – Pointer to the keyexpr in its string representation as a null terminated string.
llen – Number of characters in
l
.r – Pointer to the keyexpr in its string representation as a null terminated string.
rlen – Number of characters in
r
.
- Returns:
Returns
0
if bothl
andr
are equal. Otherwise, it returns a-1
, or othernegative value
for
errors.
-
z_owned_config_t z_config_new(void)
Return a new, zenoh-allocated, empty configuration. It consists in an empty set of properties for zenoh session configuration.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_config_t
by loaning it usingz_config_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_config_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_config_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Returns:
Returns a new, zenoh-allocated, empty configuration.
-
z_owned_config_t z_config_default(void)
Return a new, zenoh-allocated, default configuration. It consists in a default set of properties for zenoh session configuration.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_config_t
by loaning it usingz_config_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_config_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_config_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Returns:
Returns a new, zenoh-allocated, default configuration.
-
const char *zp_config_get(z_config_t config, uint8_t key)
Gets the property with the given integer key from the configuration.
- Parameters:
config – A loaned instance of
z_owned_config_t
.key – Integer key for the requested property.
- Returns:
Returns the property with the given integer key from the configuration.
-
int8_t zp_config_insert(z_config_t config, uint8_t key, z_string_t value)
Inserts or replaces the property with the given integer key in the configuration.
- Parameters:
config – A loaned instance of
z_owned_config_t
.key – Integer key for the property to be inserted.
value – Property value to be inserted.
- Returns:
Returns
0
if the insertion is successful, or anegative value
otherwise.
-
z_owned_scouting_config_t z_scouting_config_default(void)
Return a new, zenoh-allocated, default scouting configuration. It consists in a default set of properties for scouting configuration.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_scouting_config_t
by loaning it usingz_scouting_config_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_config_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_scouting_config_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Returns:
Returns a new, zenoh-allocated, default scouting configuration.
-
z_owned_scouting_config_t z_scouting_config_from(z_config_t config)
Return a new, zenoh-allocated, scouting configuration extracted from a
z_owned_config_t
. It consists in a default set of properties for scouting configuration.Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_scouting_config_t
by loaning it usingz_scouting_config_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_config_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_scouting_config_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
config – A loaned instance of
z_owned_config_t
.
- Returns:
Returns a new, zenoh-allocated, default scouting configuration.
-
const char *zp_scouting_config_get(z_scouting_config_t config, uint8_t key)
Gets the property with the given integer key from the configuration.
- Parameters:
config – A loaned instance of
z_owned_scouting_config_t
.key – Integer key for the requested property.
- Returns:
Returns the property with the given integer key from the configuration.
-
int8_t zp_scouting_config_insert(z_scouting_config_t config, uint8_t key, z_string_t value)
Inserts or replaces the property with the given integer key in the configuration.
- Parameters:
config – A loaned instance of
z_owned_scouting_config_t
.key – Integer key for the property to be inserted.
value – Property value to be inserted.
- Returns:
Returns
0
if the insertion is successful, or anegative value
otherwise.
-
z_encoding_t z_encoding_default(void)
Constructs a default encoding.
- Returns:
Returns the constructed
z_encoding_t
.
-
z_query_target_t z_query_target_default(void)
Constructs a default query target.
- Returns:
Returns the constructed
z_query_target_t
.
-
z_query_consolidation_t z_query_consolidation_auto(void)
Automatic query consolidation strategy selection.
A query consolidation strategy will automatically be selected depending the query selector. If the selector contains time range properties, no consolidation is performed. Otherwise the
z_query_consolidation_latest()
strategy is used.- Returns:
Returns the constructed
z_query_consolidation_t
.
-
z_query_consolidation_t z_query_consolidation_default(void)
Constructs a default
z_query_consolidation_t
.- Returns:
Returns the constructed
z_query_consolidation_t
.
-
z_query_consolidation_t z_query_consolidation_latest(void)
Latest consolidation.
This strategy optimizes bandwidth on all links in the system but will provide a very poor latency.
- Returns:
Returns the constructed
z_query_consolidation_t
.
-
z_query_consolidation_t z_query_consolidation_monotonic(void)
Monotonic consolidation.
This strategy offers the best latency. Replies are directly transmitted to the application when received without needing to wait for all replies. This mode does not guarantee that there will be no duplicates.
- Returns:
Returns the constructed
z_query_consolidation_t
.
-
z_query_consolidation_t z_query_consolidation_none(void)
No consolidation.
This strategy is useful when querying timeseries data bases or when using quorums.
- Returns:
Returns the constructed
z_query_consolidation_t
.
-
z_bytes_t z_query_parameters(const z_query_t *query)
Get a query’s value selector by aliasing it.
- Parameters:
query – Pointer to the query to get the value selector from.
- Returns:
Returns the value selector wrapped as a
z_bytes_t
, since value selector is a user-defined representation.
-
z_keyexpr_t z_query_keyexpr(const z_query_t *query)
Get a query’s key by aliasing it.
- Parameters:
query – Pointer to the query to get keyexpr from.
- Returns:
Returns the
z_keyexpr_t
associated to the query.
-
z_value_t z_query_value(const z_query_t *query)
Get a query’s payload value by aliasing it. Note: This API has been marked as unstable: it works as advertised, but we may change it in a future release.
- Parameters:
query – Pointer to the query to get the value selector from.
- Returns:
Returns the payload value wrapped as a
z_value_t
, since payload value is a user-defined representation.
-
_Bool z_value_is_initialized(z_value_t *value)
Checks if a given value is valid.
- Parameters:
value – A loaned instance of
z_value_t
to be checked.
- Returns:
Returns
true
if the value is valid, orfalse
otherwise.
-
z_owned_closure_sample_t z_closure_sample(_z_data_handler_t call, _z_dropper_handler_t drop, void *context)
Return a new sample closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_closure_sample_t
by loaning it usingz_closure_sample_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_closure_sample_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_closure_sample_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
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.context – a pointer to an arbitrary state.
- Returns:
Returns a new sample closure.
-
z_owned_closure_query_t z_closure_query(_z_queryable_handler_t call, _z_dropper_handler_t drop, void *context)
Return a new query closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_closure_query_t
by loaning it usingz_closure_query_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_closure_query_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_closure_query_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
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.context – a pointer to an arbitrary state.
- Returns:
Returns a new query closure.
-
z_owned_closure_reply_t z_closure_reply(z_owned_reply_handler_t call, _z_dropper_handler_t drop, void *context)
Return a new reply closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_closure_reply_t
by loaning it usingz_closure_reply_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_closure_reply_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_closure_reply_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
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.context – a pointer to an arbitrary state.
- Returns:
Returns a new reply closure.
-
z_owned_closure_hello_t z_closure_hello(z_owned_hello_handler_t call, _z_dropper_handler_t drop, void *context)
Return a new hello closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_closure_hello_t
by loaning it usingz_closure_hello_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_closure_hello_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_closure_hello_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
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.context – a pointer to an arbitrary state.
- Returns:
Returns a new hello closure.
-
z_owned_closure_zid_t z_closure_zid(z_id_handler_t call, _z_dropper_handler_t drop, void *context)
Return a new zid closure. It consists on a structure that contains all the elements for stateful, memory-leak-free callbacks.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_closure_zid_t
by loaning it usingz_closure_zid_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_closure_zid_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_closure_zid_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
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.context – a pointer to an arbitrary state.
- Returns:
Returns a new zid closure.
-
int8_t z_scout(z_owned_scouting_config_t *config, z_owned_closure_hello_t *callback)
Primitives
Looks for other Zenoh-enabled entities like routers and/or peers.
- Parameters:
config – A moved instance of
z_owned_scouting_config_t
containing the set properties to configure the
scouting. callback: A moved instance of
z_owned_closure_hello_t
containing the callbacks to be called.- Returns:
Returns
0
if the scouting is successful triggered, or anegative value
otherwise.
-
z_owned_session_t z_open(z_owned_config_t *config)
Opens a Zenoh session.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_session_t
by loaning it usingz_session_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_session_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_session_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
config – A moved instance of
z_owned_config_t
containing the set properties to configure the session.
- Returns:
A
z_owned_session_t
with either a valid open session or a failing session. Should the session opening fail,z_check(val)
ing the returned value will returnfalse
.
-
int8_t z_close(z_owned_session_t *zs)
Closes a Zenoh session.
- Parameters:
zs – A moved instance of the the
z_owned_session_t
to close.
- Returns:
Returns
0
if the session is successful closed, or anegative value
otherwise.
-
int8_t z_info_peers_zid(const z_session_t zs, z_owned_closure_zid_t *callback)
Fetches the Zenoh IDs of all connected peers.
callback
will be called once for each ID. It is guaranteed to never be called concurrently, and to be dropped before this function exits.- Parameters:
zs – A loaned instance of the the
z_session_t
to inquiry.callback – A moved instance of
z_owned_closure_zid_t
containing the callbacks to be called.
- Returns:
Returns
0
if the info is successful triggered, or anegative value
otherwise.
-
int8_t z_info_routers_zid(const z_session_t zs, z_owned_closure_zid_t *callback)
Fetches the Zenoh IDs of all connected routers.
callback
will be called once for each ID. It is guaranteed to never be called concurrently, and to be dropped before this function exits.- Parameters:
zs – A loaned instance of the the
z_session_t
to inquiry.callback – A moved instance of
z_owned_closure_zid_t
containing the callbacks to be called.
- Returns:
Returns
0
if the info is successful triggered, or anegative value
otherwise.
-
z_id_t z_info_zid(const z_session_t zs)
Get the local Zenoh ID associated to a given Zenoh session.
Unless the
z_session_t
is invalid, that ID is guaranteed to be non-zero. In other words, this function returning an array of 16 zeros means you failed to pass it a valid session.- Parameters:
zs – A loaned instance of the the
z_session_t
to inquiry.
- Returns:
Returns the local Zenoh ID of the given
z_session_t
.
-
z_put_options_t z_put_options_default(void)
Constructs the default values for the put operation.
- Returns:
Returns the constructed
z_put_options_t
.
-
z_delete_options_t z_delete_options_default(void)
Constructs the default values for the delete operation.
- Returns:
Returns the constructed
z_delete_options_t
.
-
int8_t z_put(z_session_t zs, z_keyexpr_t keyexpr, const uint8_t *payload, z_zint_t payload_len, const z_put_options_t *options)
Puts data for a given keyexpr.
- Parameters:
zs – A loaned instance of the the
z_session_t
through where data will be put.keyexpr – A loaned instance of
z_keyexpr_t
to put.payload – Pointer to the data to put.
payload_len – The length of the
payload
.options – The put options to be applied in the put operation.
- Returns:
Returns
0
if the put operation is successful, or anegative value
otherwise.
-
int8_t z_delete(z_session_t zs, z_keyexpr_t keyexpr, const z_delete_options_t *options)
Deletes data from a given keyexpr.
- Parameters:
zs – A loaned instance of the the
z_session_t
through where data will be put.keyexpr – A loaned instance of
z_keyexpr_t
to put.options – The delete options to be applied in the delete operation.
- Returns:
Returns
0
if the delete operation is successful, or anegative value
otherwise.
-
z_get_options_t z_get_options_default(void)
Constructs the default values for the get operation.
- Returns:
Returns the constructed
z_get_options_t
.
-
int8_t z_get(z_session_t zs, z_keyexpr_t keyexpr, const char *parameters, z_owned_closure_reply_t *callback, const z_get_options_t *options)
Issues a distributed query for a given keyexpr.
- Parameters:
zs – A loaned instance of the the
z_session_t
through where data will be put.keyexpr – A loaned instance of
z_keyexpr_t
to put.parameters – Pointer to the parameters as a null-terminated string.
callback – A moved instance of
z_owned_closure_reply_t
containing the callbacks to be called.options – The get options to be applied in the distributed query.
- Returns:
Returns
0
if the put operation is successful, or anegative value
otherwise.
-
z_owned_keyexpr_t z_declare_keyexpr(z_session_t zs, z_keyexpr_t keyexpr)
Declares a keyexpr, so that it is internally mapped into into 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.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_keyexpr_t
by loaning it usingz_keyexpr_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_keyexpr_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_keyexpr_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
zs – A loaned instance of the the
z_session_t
where to declare the keyexpr.keyexpr – A loaned instance of
z_keyexpr_t
to declare.
- Returns:
A
z_owned_keyexpr_t
with either a valid or invalid keyexpr. Should the keyexpr be invalid,z_check(val)
ing the returned value will returnfalse
.
-
int8_t z_undeclare_keyexpr(z_session_t zs, z_owned_keyexpr_t *keyexpr)
Undeclares the keyexpr generated by a call to
z_declare_keyexpr()
.- Parameters:
zs – A loaned instance of the the
z_session_t
through where data will be put.keyexpr – A moved instance of
z_owned_keyexpr_t
to undeclare.
- Returns:
Returns
0
if the undeclare keyexpr operation is successful, or anegative value
otherwise.
-
z_publisher_options_t z_publisher_options_default(void)
Constructs the default values for the publisher entity.
- Returns:
Returns the constructed
z_publisher_options_t
.
-
z_owned_publisher_t z_declare_publisher(z_session_t zs, z_keyexpr_t keyexpr, const z_publisher_options_t *options)
Declares a publisher for the given keyexpr.
Data can be put and deleted with this publisher with the help of the
z_publisher_put()
andz_publisher_delete()
functions.Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_publisher_t
by loaning it usingz_publisher_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_publisher_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_publisher_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
zs – A loaned instance of the the
z_session_t
where to declare the publisher.keyexpr – A loaned instance of
z_keyexpr_t
to associate with the publisher.options – The options to apply to the publisher. If
NULL
is passed, the default options will be applied.
- Returns:
A
z_owned_publisher_t
with either a valid publisher or a failing publisher. Should the publisher be invalid,z_check(val)
ing the returned value will returnfalse
.
-
int8_t z_undeclare_publisher(z_owned_publisher_t *pub)
Undeclare the publisher generated by a call to
z_declare_publisher()
.- Parameters:
pub – A moved instance of
z_owned_publisher_t
to undeclare.
- Returns:
Returns
0
if the undeclare publisher operation is successful, or anegative value
otherwise.
-
z_publisher_put_options_t z_publisher_put_options_default(void)
Constructs the default values for the put operation via a publisher entity.
- Returns:
Returns the constructed
z_publisher_put_options_t
.
-
z_publisher_delete_options_t z_publisher_delete_options_default(void)
Constructs the default values for the delete operation via a publisher entity.
- Returns:
Returns the constructed
z_publisher_delete_options_t
.
-
int8_t z_publisher_put(const z_publisher_t pub, const uint8_t *payload, size_t len, const z_publisher_put_options_t *options)
Puts data for the keyexpr associated to the given publisher.
- Parameters:
pub – A loaned instance of
z_publisher_t
from where to put the data.options – The options to apply to the put operation. If
NULL
is passed, the default options will be applied.
- Returns:
Returns
0
if the put operation is successful, or anegative value
otherwise.
-
int8_t z_publisher_delete(const z_publisher_t pub, const z_publisher_delete_options_t *options)
Deletes data from the keyexpr associated to the given publisher.
- Parameters:
pub – A loaned instance of
z_publisher_t
from where to delete the data.options – The options to apply to the delete operation. If
NULL
is passed, the default options will be applied.
- Returns:
Returns
0
if the delete operation is successful, or anegative value
otherwise.
-
z_subscriber_options_t z_subscriber_options_default(void)
Constructs the default values for the subscriber entity.
- Returns:
Returns the constructed
z_subscriber_options_t
.
-
z_owned_subscriber_t z_declare_subscriber(z_session_t zs, z_keyexpr_t keyexpr, z_owned_closure_sample_t *callback, const z_subscriber_options_t *options)
Declares a (push) subscriber for the given keyexpr.
Received data is processed by means of callbacks.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_subscriber_t
by loaning it usingz_subscriber_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_subscriber_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_subscriber_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
zs – A loaned instance of the the
z_session_t
where to declare the subscriber.keyexpr – A loaned instance of
z_keyexpr_t
to associate with the subscriber.callback – A moved instance of
z_owned_closure_sample_t
containg the callbacks to be called and the
context to pass to them. options: The options to apply to the subscriber. If
NULL
is passed, the default options will be applied.- Returns:
A
z_owned_subscriber_t
with either a valid subscriber or a failing subscriber. Should the subscriber be invalid,z_check(val)
ing the returned value will returnfalse
.
-
int8_t z_undeclare_subscriber(z_owned_subscriber_t *sub)
Undeclares the (push) subscriber generated by a call to
z_declare_subscriber()
.- Parameters:
sub – A moved instance of
z_owned_subscriber_t
to undeclare.
- Returns:
Returns
0
if the undeclare (push) subscriber operation is successful, or anegative value
otherwise.
-
z_pull_subscriber_options_t z_pull_subscriber_options_default(void)
Constructs the default values for the pull subscriber entity.
- Returns:
Returns the constructed
z_pull_subscriber_options_t
.
-
z_owned_pull_subscriber_t z_declare_pull_subscriber(z_session_t zs, z_keyexpr_t keyexpr, z_owned_closure_sample_t *callback, const z_pull_subscriber_options_t *options)
Declares a pull subscriber for the given keyexpr.
Data can be pulled with this subscriber with the help of the
z_pull()
function. Received data is processed by means of callbacks.Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_pull_subscriber_t
by loaning it usingz_pull_subscriber_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_pull_subscriber_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_pull_subscriber_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
zs – A loaned instance of the the
z_session_t
where to declare the subscriber.keyexpr – A loaned instance of
z_keyexpr_t
to associate with the subscriber.callback – A moved instance of
z_owned_closure_sample_t
containing the callbacks to be called and the
context to pass to them. options: The options to apply to the pull subscriber. If
NULL
is passed, the default options will be applied.- Returns:
A
z_owned_pull_subscriber_t
with either a valid subscriber or a failing subscriber. Should the pull subscriber be invalid,z_check(val)
ing the returned value will returnfalse
.
-
int8_t z_undeclare_pull_subscriber(z_owned_pull_subscriber_t *sub)
Undeclares the pull subscriber generated by a call to
z_declare_pull_subscriber()
.- Parameters:
sub – A moved instance of
z_owned_pull_subscriber_t
to undeclare.
- Returns:
Returns
0
if the undeclare pull subscriber operation is successful, or anegative value
otherwise.
-
int8_t z_subscriber_pull(const z_pull_subscriber_t sub)
Pulls data for
z_owned_pull_subscriber_t
. The pulled data will be provided by calling the callback function provided to thez_declare_pull_subscriber()
function.- Parameters:
sub – A loaned instance of
z_pull_subscriber_t
from where to pull the data.
- Returns:
Returns
0
if the pull operation is successful, or anegative value
otherwise.
-
z_queryable_options_t z_queryable_options_default(void)
Constructs the default values for the queryable entity.
- Returns:
Returns the constructed
z_queryable_options_t
.
-
z_owned_queryable_t z_declare_queryable(z_session_t zs, z_keyexpr_t keyexpr, z_owned_closure_query_t *callback, const z_queryable_options_t *options)
Declares a queryable for the given keyexpr.
Received queries are processed by means of callbacks.
Like most
z_owned_X_t
types, you may obtain an instance ofz_owned_queryable_t
by loaning it usingz_queryable_loan(&val)
. Thez_loan(val)
macro, available if your compiler supports C11’s_Generic
, is equivalent to writingz_queryable_loan(&val)
.Like all
z_owned_X_t
, an instance will be destroyed by any function which takes a mutable pointer to said instance, as this implies the instance’s inners were moved. To make this fact more obvious when reading your code, consider usingz_move(val)
instead of&val
as the argument. After az_move
,val
will still exist, but will no longer be valid. The destructors are double-drop-safe, but other functions will still trust that yourval
is valid.To check if
val
is still valid, you may usez_queryable_check(&val)
orz_check(val)
if your compiler supports_Generic
, which will returntrue
ifval
is valid, orfalse
otherwise.- Parameters:
zs – A loaned instance of the the
z_session_t
where to declare the subscriber.keyexpr – A loaned instance of
z_keyexpr_t
to associate with the subscriber.callback – A moved instance of
z_owned_closure_query_t
containing the callbacks to be called and the
context to pass to them. options: The options to apply to the queryable. If
NULL
is passed, the default options will be applied.- Returns:
A
z_owned_queryable_t
with either a valid queryable or a failing queryable. Should the queryable be invalid,z_check(val)
ing the returned value will returnfalse
.
-
int8_t z_undeclare_queryable(z_owned_queryable_t *queryable)
Undeclares the queryable generated by a call to
z_declare_queryable()
.- Parameters:
queryable – A moved instance of
z_owned_queryable_t
to undeclare.
- Returns:
Returns
0
if the undeclare queryable operation is successful, or anegative value
otherwise.
-
int8_t z_query_reply(const z_query_t *query, const z_keyexpr_t keyexpr, const uint8_t *payload, size_t payload_len, 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 thez_owned_queryable_t
, passing the received query as parameters of the callback function. This function can be called multiple times to send multiple replies to a query. The reply will be considered complete when the callback returns.- Parameters:
query – Pointer to the received query.
keyexpr – A loaned instance of
z_keyexpr_t
to associate with the subscriber.payload – Pointer to the data to put.
payload_len – The length of the
payload
.options – The options to apply to the send query reply operation. If
NULL
is passed, the default options will be
applied.
- Returns:
Returns
0
if the send query reply operation is successful, or anegative value
otherwise.
-
_Bool z_reply_is_ok(const z_owned_reply_t *reply)
Checks if the queryable answered with an OK, which allows this value to be treated as a sample.
If this returns
false
, you should usez_check
before trying to usez_reply_err()
if you want to process the error that may be here.- Parameters:
reply – Pointer to the received query reply.
- Returns:
Returns
true
if the queryable answered with an OK, which allows this value to be treated as a sample, or
false
otherwise.
-
z_sample_t z_reply_ok(const z_owned_reply_t *reply)
Yields the contents of the reply by asserting it indicates a success.
You should always make sure that
z_reply_is_ok()
returnstrue
before calling this function.- Parameters:
reply – Pointer to the received query reply.
- Returns:
Returns the
z_sample_t
wrapped in the query reply.
-
z_value_t z_reply_err(const z_owned_reply_t *reply)
Yields the contents of the reply by asserting it indicates a failure.
You should always make sure that
z_reply_is_ok()
returnsfalse
before calling this function.- Parameters:
reply – Pointer to the received query reply.
- Returns:
Returns the
z_value_t
wrapped in the query reply.
-
zp_task_read_options_t zp_task_read_options_default(void)
Multi Thread Tasks helpers
Constructs the default values for the session read task.
- Returns:
Returns the constructed
zp_task_read_options_t
.
-
int8_t zp_start_read_task(z_session_t zs, const zp_task_read_options_t *options)
Start a separate task to read from the network and process the messages as soon as they are received.
Note that the task can be implemented in form of thread, process, etc. and its implementation is platform-dependent.
- Parameters:
zs – A loaned instance of the the
z_session_t
where to start the read task.options – The options to apply when starting the read task. If
NULL
is passed, the default options will be
applied.
- Returns:
Returns
0
if the read task started successfully, or anegative value
otherwise.
-
int8_t zp_stop_read_task(z_session_t zs)
Stop the read task.
This may result in stopping a thread or a process depending on the target platform.
- Parameters:
zs – A loaned instance of the the
z_session_t
where to stop the read task.
- Returns:
Returns
0
if the read task stopped successfully, or anegative value
otherwise.
-
zp_task_lease_options_t zp_task_lease_options_default(void)
Constructs the default values for the session lease task.
- Returns:
Returns the constructed
zp_task_lease_options_t
.
-
int8_t zp_start_lease_task(z_session_t zs, const zp_task_lease_options_t *options)
Start a separate 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 theJoin
messages. Note that the task can be implemented in form of thread, process, etc. and its implementation is platform-dependent.- Parameters:
zs – A loaned instance of the the
z_session_t
where to start the lease task.options – The options to apply when starting the lease task. If
NULL
is passed, the default options will be
applied.
- Returns:
Returns
0
if the lease task started successfully, or anegative value
otherwise.
-
int8_t zp_stop_lease_task(z_session_t zs)
Stop the lease task.
This may result in stopping a thread or a process depending on the target platform.
- Parameters:
zs – A loaned instance of the the
z_session_t
where to stop the lease task.
- Returns:
Returns
0
if the lease task stopped successfully, or anegative value
otherwise.
-
zp_read_options_t zp_read_options_default(void)
Single Thread helpers
Constructs the default values for the reading procedure.
- Returns:
Returns the constructed
zp_read_options_t
.
-
int8_t zp_read(z_session_t zs, const zp_read_options_t *options)
Triggers a single execution of reading procedure from the network and processes of any received the message.
- Parameters:
zs – A loaned instance of the the
z_session_t
where trigger the reading procedure.options – The options to apply to the read. If
NULL
is passed, the default options will be
applied.
- Returns:
Returns
0
if the reading procedure was executed successfully, or anegative value
otherwise.
-
zp_send_keep_alive_options_t zp_send_keep_alive_options_default(void)
Constructs the default values for sending the keep alive.
- Returns:
Returns the constructed
zp_send_keep_alive_options_t
.
-
int8_t zp_send_keep_alive(z_session_t zs, const zp_send_keep_alive_options_t *options)
Triggers a single execution of keep alive procedure.
It will send
KeepAlive
messages when needed and will close the session when the lease is expired.- Parameters:
zs – A loaned instance of the the
z_session_t
where trigger the leasing procedure.options – The options to apply to the send of a
KeepAlive
messages. IfNULL
is passed, the default options
will be applied.
- Returns:
Returns
0
if the leasing procedure was executed successfully, or anegative value
otherwise.