[−][src]Crate zvariant
This crate provides API for serialization/deserialization of data to/from D-Bus wire format. This binary wire format is simple and very efficient and hence useful outside of D-Bus context as well. A modified form of this format, GVariant is very commonly used for efficient storage of arbitrary data and is also supported by this crate.
Since version 2.0, the API is serde-based and hence you'll find it very intuitive if you're already familiar with serde. If you're not familiar with serde, you may want to first read its tutorial before learning further about this crate.
Serialization and deserialization is achieved through the toplevel functions:
use std::collections::HashMap; use byteorder::LE; use zvariant::{from_slice, to_bytes}; use zvariant::EncodingContext as Context; // All serialization and deserialization API, needs a context. let ctxt = Context::<LE>::new_dbus(0); // i16 let encoded = to_bytes(ctxt, &42i16).unwrap(); let decoded: i16 = from_slice(&encoded, ctxt).unwrap(); assert_eq!(decoded, 42); // strings let encoded = to_bytes(ctxt, &"hello").unwrap(); let decoded: &str = from_slice(&encoded, ctxt).unwrap(); assert_eq!(decoded, "hello"); // tuples let t = ("hello", 42i32, true); let encoded = to_bytes(ctxt, &t).unwrap(); let decoded: (&str, i32, bool) = from_slice(&encoded, ctxt).unwrap(); assert_eq!(decoded, t); // Let's use the more efficient GVariant format. let ctxt = Context::<LE>::new_gvariant(0); // Vec let v = vec!["hello", "world!"]; let encoded = to_bytes(ctxt, &v).unwrap(); let decoded: Vec<&str> = from_slice(&encoded, ctxt).unwrap(); assert_eq!(decoded, v); // Dictionary let mut map: HashMap<i64, &str> = HashMap::new(); map.insert(1, "123"); map.insert(2, "456"); let encoded = to_bytes(ctxt, &map).unwrap(); let decoded: HashMap<i64, &str> = from_slice(&encoded, ctxt).unwrap(); assert_eq!(decoded[&1], "123"); assert_eq!(decoded[&2], "456");
Apart from the obvious requirement of EncodingContext
instance by the main serialization and
deserialization API, the type being serialized or deserialized must also implement Type
trait in addition to Serialize
or Deserialize
, respectively. Please refer to Type
module documentation for more details.
Most of the basic types of D-Bus match 1-1 wit all the primitive Rust types. The only two
exceptions being, Signature
and ObjectPath
, which are really just strings. These types
are covered by the Basic
trait.
Similarly, most of the container types also map nicely to the usual Rust types and
collections (as can be seen in the example code above). The only note worthy exception being
ARRAY type. As arrays in Rust are fixed-sized, serde treats them as tuples and so does this
crate. This means they are encoded as STRUCT type of D-Bus. If you need to serialize to, or
deserialize from a D-Bus array, you'll need to use a slice (array can easily be converted to a
slice), a Vec
or an arrayvec::ArrayVec
.
The generic D-Bus type, VARIANT
is represented by Value
, an enum that holds exactly one
value of any of the other types. Please refer to Value
module documentation for examples.
no-std
While std
is currently a hard requirement, optional no-std
support is planned in the future.
On the other hand, noalloc
support is not planned as it will be extremely difficult to
accomplish. However, community contribution can change that. 😊
Optional features
Feature | Description |
---|---|
arrayvec | Implement Type for arrayvec::ArrayVec and arrayvec::ArrayString |
enumflags2 | Implement Type for [enumflags2::BitFlags<F> ] |
Portability
zvariant is currently Unix-only and will fail to build on non-unix. This is hopefully a temporary limitation.
Modules
derive |
Structs
Array | A helper type to wrap arrays in a |
DeserializeValue | A wrapper to deserialize a value to |
Deserializer | Our deserialization implementation. |
Dict | A helper type to wrap dictionaries in a |
EncodingContext | The encoding context to use with the serialization and deserialization API. |
Fd | A |
Maybe | A helper type to wrap Option |
ObjectPath | String that identifies objects at a given destination on the D-Bus bus. |
OwnedObjectPath | Owned |
OwnedSignature | Owned |
OwnedValue | Owned |
SerializeValue | A wrapper to serialize |
Serializer | Our serialization implementation. |
Signature | String that identifies the type of an encoded value. |
Str | A string wrapper. |
Structure | A helper type to wrap structs in |
StructureBuilder | Use this to efficiently build a |
Enums
EncodingFormat | The encoding format. |
Error | Error type used by zvariant API. |
Value | A generic container, in the form of an enum that holds exactly one value of any of the other types. |
Constants
ARRAY_SIGNATURE_CHAR | The prefix of ARRAY type signature, as a character. Provided for manual signature creation. |
ARRAY_SIGNATURE_STR | The prefix of ARRAY type signature, as a string. Provided for manual signature creation. |
DICT_ENTRY_SIG_END_CHAR | The closing character of DICT_ENTRY type signature. Provided for manual signature creation. |
DICT_ENTRY_SIG_END_STR | The closing character of DICT_ENTRY type signature, as a string. Provided for manual signature creation. |
DICT_ENTRY_SIG_START_CHAR | The opening character of DICT_ENTRY type signature. Provided for manual signature creation. |
DICT_ENTRY_SIG_START_STR | The opening character of DICT_ENTRY type signature, as a string. Provided for manual signature creation. |
MAYBE_SIGNATURE_CHAR | The prefix of MAYBE (GVariant-specific) type signature, as a character. Provided for manual signature creation. |
MAYBE_SIGNATURE_STR | The prefix of MAYBE (GVariant-specific) type signature, as a string. Provided for manual signature creation. |
STRUCT_SIG_END_CHAR | The closing character of STRUCT type signature. Provided for manual signature creation. |
STRUCT_SIG_END_STR | The closing character of STRUCT type signature, as a string. Provided for manual signature creation. |
STRUCT_SIG_START_CHAR | The opening character of STRUCT type signature. Provided for manual signature creation. |
STRUCT_SIG_START_STR | The opening character of STRUCT type signature, as a string. Provided for manual signature creation. |
VARIANT_SIGNATURE_CHAR | The VARIANT type signature. Provided for manual signature creation. |
VARIANT_SIGNATURE_STR | The VARIANT type signature, as a string. Provided for manual signature creation. |
Traits
Basic | Trait for basic types. |
Type | Trait implemented by all serializable types. |
Functions
from_slice | Deserialize |
from_slice_fds | Deserialize |
from_slice_fds_for_signature | Deserialize |
from_slice_for_signature | Deserialize |
serialized_size | Calculate the serialized size of |
serialized_size_fds | Calculate the serialized size of |
to_bytes | Serialize |
to_bytes_fds | Serialize |
to_bytes_fds_for_signature | Serialize |
to_bytes_for_signature | Serialize |
to_writer | Serialize |
to_writer_fds | Serialize |
to_writer_fds_for_signature | Serialize |
to_writer_for_signature | Serialize |
Type Definitions
Result | Alias for a |