[][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 slightly modified form of this format, GVariant is also very common and will be supported by a future version of 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);

// 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 an extremely difficult to accomplish, if at all possible.

Optional features

FeatureDescription
arrayvecImplement Type for arrayvec::ArrayVec and [arrayvec::ArrayString]
enumflags2Implement 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.

Structs

Array

A helper type to wrap arrays in a Value.

Deserializer

Our deserialization implementation.

Dict

A helper type to wrap dictionaries in a Value.

EncodingContext

The encoding context to use with the serialization and deserialization API.

Fd

A RawFd wrapper.

ObjectPath

String that identifies objects at a given destination on the D-Bus bus.

OwnedValue

Owned Value

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

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.

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.

Traits

Basic

Trait for basic types.

Type

Trait implemented by all serializable types.

Functions

from_slice

Deserialize T from a given slice of bytes.

from_slice_fds

Deserialize T from a given slice of bytes, containing file descriptor indices.

from_slice_fds_for_signature

Deserialize T from a given slice of bytes containing file descriptor indices, with the given signature.

from_slice_for_signature

Deserialize T from a given slice of bytes with the given signature.

serialized_size

Calculate the serialized size of T.

serialized_size_fds

Calculate the serialized size of T that (potentially) contains FDs.

to_bytes

Serialize T as a byte vector.

to_bytes_fds

Serialize T that (potentially) contains FDs, as a byte vector.

to_bytes_fds_for_signature

Serialize T that (potentially) contains FDs and has the given signature, to a new byte vector.

to_bytes_for_signature

Serialize T that has the given signature, to a new byte vector.

to_writer

Serialize T to the given writer.

to_writer_fds

Serialize T that (potentially) contains FDs, to the given writer.

to_writer_fds_for_signature

Serialize T that (potentially) contains FDs and has the given signature, to the given writer.

to_writer_for_signature

Serialize T that has the given signature, to the given writer.

Type Definitions

Result

Alias for a Result with the error type zvariant::Error.