Commonly used types

Enums

Enum types are C++ - style typedefs for corrresponding enums of zenoh-c / zenoh-pico C API.

typedef ::z_sample_kind_t zenoh::SampleKind

zenoh::Sample kind values.

Values:

Z_SAMPLE_KIND_PUT: The Sample was issued by a “put” operation.
Z_SAMPLE_KIND_DELETE: The Sample was issued by a “delete” operation.

typedef ::z_consolidation_mode_t zenoh::ConsolidationMode

Consolidation mode values.

Values:

Z_CONSOLIDATION_MODE_AUTO: Let Zenoh decide the best consolidation mode depending on the query selector.
Z_CONSOLIDATION_MODE_NONE: No consolidation is applied. Replies may come in any order and any number.
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.
Z_CONSOLIDATION_MODE_LATEST: It guarantees unicity of replies for the same key expression. It optimizes bandwidth.

typedef ::z_reliability_t zenoh::Reliability

Publisher reliability values.

Values:

Z_RELIABILITY_BEST_EFFORT: Defines reliability as “best effort”
Z_RELIABILITY_RELIABLE: Defines reliability as “reliable”

Note

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

Warning

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

typedef ::z_congestion_control_t zenoh::CongestionControl

Congestion control values.

Values:

Z_CONGESTION_CONTROL_BLOCK: Defines congestion control as “block”. Messages are not dropped in case of congestion control
Z_CONGESTION_CONTROL_DROP: Defines congestion control as “drop”. Messages are dropped in case of congestion control

typedef ::z_priority_t zenoh::Priority

Priority of Zenoh messages values.

Values:

Z_PRIORITY_REAL_TIME: Priority for “realtime” messages.
Z_PRIORITY_INTERACTIVE_HIGH: Highest priority for “interactive” messages.
Z_PRIORITY_INTERACTIVE_LOW: Lowest priority for “interactive” messages.
Z_PRIORITY_DATA_HIGH: Highest priority for “data” messages.
Z_PRIORITY_DATA: Default priority for “data” messages.
Z_PRIORITY_DATA_LOW: Lowest priority for “data” messages.
Z_PRIORITY_BACKGROUND: Priority for “background traffic” messages.

typedef ::z_query_target_t zenoh::QueryTarget

Query target values.

Values:

Z_QUERY_TARGET_BEST_MATCHING: The nearest complete queryable if any else all matching queryables.
Z_QUERY_TARGET_ALL: All matching queryables.
Z_QUERY_TARGET_ALL_COMPLETE: A set of complete queryables.

typedef ::z_whatami_t zenoh::WhatAmI: Enum indicating type of Zenoh entity.

typedef ::zc_locality_t zenoh::Locality

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

Values:

ZC_LOCALITY_ANY: Any.
ZC_LOCALITY_SESSION_LOCAL: Only from local sessions.
ZC_LOCALITY_SESSION_REMOTE: Only from remote sessions.

Warning

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

inline std::string_view zenoh::whatami_as_str(WhatAmI whatami)

Get a human-readable representation of the given zenoh::WhatAmI flag.

Parameters:: whatami – the zenoh::WhatAmI flag.
Returns:: a string representation of the given flag.

Source Info

class Id : public zenoh::Copyable<::z_id_t>

A representation of a Zenoh ID.

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

Warning

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

Methods

inline const std::array<uint8_t, 16> &bytes() const: Return the byte sequence of the Id.

inline std::string to_string() const: Formats the Id into 16-digit hex string (LSB-first order).

inline std::ostream &zenoh::operator<<(std::ostream &os, const Id &id): Print Id in the hex format.

class EntityGlobalId : public zenoh::Copyable<::z_entity_global_id_t>

The global unique id of a Zenoh entity.

Note

Zenoh-c only.

Warning

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

Methods

inline Id id() const: Get Zenoh id.

inline uint32_t eid() const: Get eid.

class SourceInfo : public zenoh::Owned<::z_owned_source_info_t>

Informations on the Zenoh source.

Note

Zenoh-c only.

Warning

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

Constructors

inline SourceInfo(const EntityGlobalId &id, uint32_t sn): Construct from global id and sequence number.

Methods

inline EntityGlobalId id() const: Get the source id.

inline uint32_t sn() const: Get the sequence number of the sample from the given source.

Timestamp

class Timestamp : public zenoh::Copyable<::z_timestamp_t>

Zenoh Timestamp.

Methods

inline uint64_t get_time() const

Get the NTP64 time part of the timestamp.

Returns:: time in NTP64 format.

inline Id get_id() const

Get the unique id of the timestamp.

Returns:: session id associated with this timestamp.

Warning

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

Encoding

class Encoding : public zenoh::Owned<::z_owned_encoding_t>

The encoding of Zenoh data.

Constructors

inline Encoding(): Construct default encoding.

inline Encoding(std::string_view s, ZResult *err = nullptr): Construct encoding from string.

inline Encoding(const Encoding &other): Copy constructor.

Methods

inline std::string as_string() const: Get string representation of encoding.

inline void set_schema(std::string_view schema, ZResult *err = nullptr)

Set a schema to this encoding from a 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.

Operators

inline Encoding &operator=(const Encoding &other): Assignment operator.

inline bool operator==(const Encoding &other) const

Equality relation.

Parameters:: other – an encoding to compare with.
Returns:: true if both encodings are equal, false otherwise.

struct Predefined

Methods

static inline const Encoding &zenoh_bytes(): Just some bytes. Constant alias for string: "zenoh/bytes". This encoding supposes that the payload was constructed directly from std::vector<uint8_t> and its data can be accessed via Bytes::as_vector.

static inline const Encoding &zenoh_string(): A UTF-8 string. Constant alias for string: "zenoh/string". This encoding supposes that the payload was created directly from std::string, std::string_view or a null-terminated string and its data can be accessed via Bytes::as_string.

static inline const Encoding &zenoh_serialized()

Zenoh serialized data.

Constant alias for string: "zenoh/serialized".

This encoding supposes that the payload was created using zenoh::ext::serialize or with the help of zenoh::ext::Serializer and its data can be accessed via zenoh::ext::deserialize or with the help of zenoh::ext::Deserializer.

static inline const Encoding &application_octet_stream(): An application-specific stream of bytes. Constant alias for string: "application/octet-stream".

static inline const Encoding &text_plain(): A textual file. Constant alias for string: "text/plain".

static inline const Encoding &application_json(): JSON data intended to be consumed by an application. Constant alias for string: "application/json".

static inline const Encoding &text_json(): JSON data intended to be human readable. Constant alias for string: "text/json".

static inline const Encoding &application_cdr(): A Common Data Representation (CDR)-encoded data. Constant alias for string: "application/cdr".

static inline const Encoding &application_cbor(): A Concise Binary Object Representation (CBOR)-encoded data. Constant alias for string: "application/cbor".

static inline const Encoding &application_yaml(): YAML data intended to be consumed by an application. Constant alias for string: "application/yaml".

static inline const Encoding &text_yaml(): YAML data intended to be human readable. Constant alias for string: "text/yaml".

static inline const Encoding &text_json5(): JSON5 encoded data that are human readable. Constant alias for string: "text/json5".

static inline const Encoding &application_python_serialized_object(): A Python object serialized using pickle. Constant alias for string: "application/python-serialized-object".

static inline const Encoding &application_protobuf(): An application-specific protobuf-encoded data. Constant alias for string: "application/protobuf".

static inline const Encoding &application_java_serialized_object(): A Java serialized object. Constant alias for string: "application/java-serialized-object".

static inline const Encoding &application_openmetrics_text(): An openmetrics data, commonly used by Prometheus. Constant alias for string: "application/openmetrics-text".

static inline const Encoding &image_png(): A Portable Network Graphics (PNG) image. Constant alias for string: "image/png".

static inline const Encoding &image_jpeg(): A Joint Photographic Experts Group (JPEG) image. Constant alias for string: "image/jpeg".

static inline const Encoding &image_gif(): A Graphics Interchange Format (GIF) image. Constant alias for string: "image/gif".

static inline const Encoding &image_bmp(): A BitMap (BMP) image. Constant alias for string: "image/bmp".

static inline const Encoding &image_webp(): A Web Portable (WebP) image. Constant alias for string: "image/webp".

static inline const Encoding &application_xml(): An XML file intended to be consumed by an application. Constant alias for string: "application/xml".

static inline const Encoding &application_x_www_form_urlencoded(): An encoded list of tuples, each consisting of a name and a value. Constant alias for string: "application/x-www-form-urlencoded".

static inline const Encoding &text_html(): An HTML file. Constant alias for string: "text/html".

static inline const Encoding &text_xml(): An XML file that is human-readable. Constant alias for string: "text/xml".

static inline const Encoding &text_css(): A CSS file. Constant alias for string: "text/css".

static inline const Encoding &text_javascript(): A JavaScript file. Constant alias for string: "text/javascript".

static inline const Encoding &text_markdown(): A Markdown file. Constant alias for string: "text/markdown".

static inline const Encoding &text_csv(): A CSV file. Constant alias for string: "text/csv".

static inline const Encoding &application_sql(): An application-specific SQL query. Constant alias for string: "application/sql".

static inline const Encoding &application_coap_payload(): Constrained Application Protocol (CoAP) data intended for CoAP-to-HTTP and HTTP-to-CoAP proxies. Constant alias for string: "application/coap-payload".

static inline const Encoding &application_json_patch_json(): 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".

static inline const Encoding &application_json_seq(): A JSON text sequence consists of any number of JSON texts, all encoded in UTF-8. Constant alias for string: "application/json-seq".

static inline const Encoding &application_jsonpath(): A JSONPath defines a string syntax for selecting and extracting JSON values from within a given JSON value. Constant alias for string: "application/jsonpath".

static inline const Encoding &application_jwt(): A JSON Web Token (JWT). Constant alias for string: "application/jwt".

static inline const Encoding &application_mp4(): An application-specific MPEG-4 encoded data, either audio or video. Constant alias for string: "application/mp4".

static inline const Encoding &application_soap_xml(): A SOAP 1.2 message serialized as XML 1.0. Constant alias for string: "application/soap+xml".

static inline const Encoding &application_yang(): A YANG-encoded data commonly used by the Network Configuration Protocol (NETCONF). Constant alias for string: "application/yang".

static inline const Encoding &audio_aac(): A MPEG-4 Advanced Audio Coding (AAC) media. Constant alias for string: "audio/aac".

static inline const Encoding &audio_flac(): A Free Lossless Audio Codec (FLAC) media. Constant alias for string: "audio/flac".

static inline const Encoding &audio_mp4(): An audio codec defined in MPEG-1, MPEG-2, MPEG-4, or registered at the MP4 registration authority. Constant alias for string: "audio/mp4".

static inline const Encoding &audio_ogg(): An Ogg-encapsulated audio stream. Constant alias for string: "audio/ogg".

static inline const Encoding &audio_vorbis(): A Vorbis-encoded audio stream. Constant alias for string: "audio/vorbis".

static inline const Encoding &video_h261(): A h261-encoded video stream. Constant alias for string: "video/h261".

static inline const Encoding &video_h263(): A h263-encoded video stream. Constant alias for string: "video/h263".

static inline const Encoding &video_h264(): A h264-encoded video stream. Constant alias for string: "video/h264".

static inline const Encoding &video_h265(): A h265-encoded video stream. Constant alias for string: "video/h265".

static inline const Encoding &video_h266(): A h266-encoded video stream. Constant alias for string: "video/h266".

static inline const Encoding &video_mp4(): A video codec defined in MPEG-1, MPEG-2, MPEG-4, or registered at the MP4 registration authority. Constant alias for string: "video/mp4".

static inline const Encoding &video_ogg(): An Ogg-encapsulated video stream. Constant alias for string: "video/ogg".

static inline const Encoding &video_raw(): An uncompressed, studio-quality video stream. Constant alias for string: "video/raw".

static inline const Encoding &video_vp8(): A VP8-encoded video stream. Constant alias for string: "video/vp8".

static inline const Encoding &video_vp9(): A VP9-encoded video stream. Constant alias for string: "video/vp9".

Sample

class Sample : public zenoh::Owned<::z_owned_sample_t>

A data sample.

A sample is the value associated to a given resource at a given point in time.

Methods

inline const KeyExpr &get_keyexpr() const

Get the resource key of this sample.

Returns:: KeyExpr object representing the resource key.

inline const Bytes &get_payload() const

Get the data of this sample.

Returns:: Bytes object representing the sample payload.

inline Bytes &get_payload()

Get the data of this sample.

Returns:: Bytes object representing the sample payload.

inline const Encoding &get_encoding() const

Get the encoding of the data of this sample.

Returns:: Encoding object.

inline SampleKind get_kind() const

Get the kind of this sample.

Returns:: zenoh::SampleKind value (PUT or DELETE).

inline std::optional<std::reference_wrapper<const Bytes>> get_attachment() const

Get the attachment of this sample.

Returns:: Bytes object representing sample attachment.

inline std::optional<Timestamp> get_timestamp() const

Get the timestamp of this sample.

Returns:: Timestamp object.

inline Priority get_priority() const

Get the priority this sample was sent with.

Returns:: Priority value.

inline CongestionControl get_congestion_control() const

Get the congestion control setting this sample was sent with.

Returns:: CongestionControl value.

inline bool get_express() const

Get the express setting this sample was sent with.

Returns:: CongestionControl value.

inline Reliability reliability() const

Get the reliability this sample was sent with.

Returns:: Reliability value.

Warning

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

inline Sample clone() const: Construct a shallow copy of this sample.

Bytes

class Bytes : public zenoh::Owned<::z_owned_bytes_t>

A Zenoh data representation.

Constructors

template<class Allocator> inline Bytes(const std::vector<uint8_t, Allocator> &v): Construct by copying sequence of bytes.

template<class Allocator> inline Bytes(std::vector<uint8_t, Allocator> &&v): Construct by moving sequence of bytes.

inline Bytes(std::string_view v): Construct by copying sequence of charactes.

inline Bytes(const char *v): Construct by copying sequence of charactes.

inline Bytes(const std::string &v): Construct by copying sequence of charactes.

inline Bytes(std::string &&v): Construct by moving a string.

template<class Deleter> inline Bytes(uint8_t *ptr, size_t len, Deleter deleter)

Construct by taking ownership of sequence of bytes.

Template Parameters:

Deleter – callable with signature void Deleter(uint8_t*).

Parameters:

ptr – pointer to data.
len – number of bytes to consider.
deleter – a thread-safe delete function to be invoked once corresponding Bytes object and all of its clones are destroyed.

inline Bytes clone() const: Construct a shallow copy of this data.

inline Bytes(): Construct an empty data.

inline Bytes(ZShm &&shm, ZResult *err = nullptr): Warning

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

inline Bytes(ZShmMut &&shm, ZResult *err = nullptr): Warning

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

Methods

inline std::vector<uint8_t> as_vector() const: Conver to vector of bytes.

inline std::string as_string() const: Convert to string.

inline std::optional<Slice> get_contiguous_view() const

Attempt to get a contiguous view to the underlying bytes.

This is only possible if data is not fragmented, otherwise the function will fail. In case of fragmented data, consider using Bytes::slice_iter.

Returns:: A Slice containing pointer to underlying data and its length if data is non fragmented, an empty value otherwise.

Warning

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

inline std::optional<std::reference_wrapper<const ZShm>> as_shm() const: Warning

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

inline std::optional<std::reference_wrapper<ZShm>> as_shm(): Warning

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

inline size_t size() const: Get number of bytes in the pyload.

inline SliceIterator slice_iter() const: Returns an iterator on raw bytes slices. Zenoh may store data in non-contiguous regions of memory, this iterator then allows to access raw data directly without any attempt of deserializing it. Please note that no guarantee is provided on the internal memory layout. The only provided guarantee is on the bytes order that is preserved.

inline Reader reader() const

Create data reader.

Returns:: reader instance.

class Reader : public zenoh::Copyable<::z_bytes_reader_t>

A reader for zenoh payload.

Constructors

inline Reader(const Bytes &b): Construct reader for specified data.

Methods

inline size_t read(uint8_t *dst, size_t len)

Read data into specified destination.

Parameters:

dst – buffer where read data is written.
len – number of bytes to read.

Returns:

number of bytes that were read. Might be less than len if there is not enough data.

inline int64_t tell()

Return the read position indicator.

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

inline size_t remaining() const

Return the number of bytes that can still be read.

Returns:: number of bytes that can still be read.

inline void seek_from_current(int64_t offset, ZResult *err = nullptr)

Set the reader position indicator to the value pointed to by offset, starting from the current position.

Parameters:

offset – offset in bytes starting from the current position.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline void seek_from_start(int64_t offset, ZResult *err = nullptr)

Set the reader position indicator to the value pointed to by offset, starting from the start of the data.

Parameters:

offset – offset in bytes starting from the 0-th byte position.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline void seek_from_end(int64_t offset, ZResult *err = nullptr)

Set the reader position indicator to the value pointed to by offset with respect to the end of the data.

Parameters:

offset – offset in bytes starting from end position.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

class SliceIterator : private zenoh::Copyable<::z_bytes_slice_iterator_t>

An iterator over raw bytes slices.

Methods

inline std::optional<Slice> next()

Return next raw slice of serialized data.

Returns:: next raw slice of serialized data. If the iterator reached the end, an empty optional will be returned.

class Writer : public zenoh::Owned<::z_owned_bytes_writer_t>

A writer for zenoh payload.

Constructors

inline Writer(): Construct an empty writer.

Methods

inline void write_all(const uint8_t *src, size_t len, ZResult *err = nullptr)

Copy data from sepcified source into underlying Bytes instance.

Parameters:

src – source to copy data from.
len – number of bytes to copy from src to the underlying Bytes instance.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline void append(Bytes &&data, ZResult *err = nullptr)

Append another Bytes instance. This allows to compose data out of multiple Bytes that may point to different memory regions. Said in other terms, it allows to create a linear view on different memory regions without copy.

Parameters:

data – data to append.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline Bytes finish() &&

Finalize all writes and return underlying Bytes object.

Returns:: underlying Bytes object.

Logging

inline void zenoh::try_init_log_from_env(): Initializes the zenoh runtime logger, using rust environment settings. E.g.: RUST_LOG=info will enable logging at info level. Similarly, you can set the variable to error or debug. Note that if the environment variable is not set, then logging will not be enabled. See https://docs.rs/env_logger/latest/env_logger/index.html for accepted filter format.

Note

Zenoh-c only.

inline void zenoh::init_log_from_env_or(const std::string &fallback_filter)

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

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

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

Note

Zenoh-c only.