Crate micropb

This crate provides a thin “library layer” used by the code generated by micropb-gen. Its main purpose is to provide traits and APIs for encoding and decoding Protobuf messages.

For info on the generated code, see micropb-gen.

Decoder and Encoder

micropb does not force a specific implementation for Protobuf data streams. Instead, streams are represented as the PbRead and PbWrite traits, similar to Read and Write from the standard library.

In addition, micropb provides PbDecoder and PbEncoder, which wrap input and output streams respectively. Their job is to read and write the generated Rust types into Protobuf data streams.

Message traits

Rust message structs generated by micropb-gen all implement MessageDecode and MessageEncode, which provide logic to read or write the message onto the data stream.

use micropb::{PbRead, PbDecoder, PbWrite, PbEncoder, MessageEncode, MessageDecode};
use micropb::heapless::Vec;


// ProtoMessage was generated by micropb
let mut message = ProtoMessage::default();
                                                                                                                                       
// Create decoder out of a byte slice, which is our input data stream
let data = [0x08, 0x96, 0x01, /* additional bytes */];
let mut decoder = PbDecoder::new(data.as_slice());
// Decode an instance of `ProtoMessage` from the decoder
message.decode(&mut decoder, data.len()).unwrap();
// Or, decode directly from the bytes
message.decode_from_bytes(data.as_slice()).unwrap();

// Use heapless::Vec as the output stream and build an encoder around it
let mut output = Vec::<u8, 16>::new();
let mut encoder = PbEncoder::new(&mut output);
// Encode a `ProtoMessage` to the encoder
message.encode(&mut encoder).unwrap();

Container Traits

micropb provides several options out of the box for handling “collection fields” that have multiple elements, such as strings and repeated fields. These include containers from heapless and arrayvec, as well as the ol’ reliable Vec, String, and Cow for environments with allocators.

However, if you need to use your own container types, you’ll have to implement the traits in the container module yourself. For more info on configuring container types, refer to the micropb-gen docs.

Feature Flags

• encode: Enable support for encoding and computing the size of messages. If disabled, the generator should be configured to not generate encoding logic via Generator::encode_decode. Enabled by default.

• decode: Enable support for decoding messages. If disabled, the generator should be configured to not generate decoding logic via Generator::encode_decode. Enabled by default.

• enable-64bit: Enable 64-bit integer operations. If disabled, then 64-bit fields such as int64 or sint64 should have Config::int_size set to 32 bits or less. Has no effect on double fields. Enabled by default.

• alloc: Implements container traits on Vec, String, and BTreeMap from alloc, allowing them to be used as container fields. Corresponds with Generator::use_container_alloc from micropb-gen.

• std: Enables standard library and implements PbMap on HashMap. Corresponds with Generator::use_container_std from micropb-gen.

• container-heapless: Implements container traits on Vec, String, and IndexMap from heapless, allowing them to be used as container fields. Corresponds with Generator::use_container_heapless from micropb-gen.

• container-arrayvec: Implements container traits on ArrayVec and ArrayString from arrayvec, allowing them to be used as container fields. Corresponds with Generator::use_container_arrayvec from micropb-gen.

Re-exports

pub use container::PbBytes;

pub use container::PbMap;

pub use container::PbString;

pub use container::PbVec;

pub use field::FieldDecode;

pub use field::FieldEncode;

Modules

container

Traits for Rust representations of Protobuf string, bytes, repeated, and map fields.

field

Traits for decoding and encoding Protobuf fields.

size

Functions for calculating the size of Protobuf values on the wire, which is necessary for encoding Protobuf messages.

Structs

FixedLenString

String with fixed length, used for representing Protobuf string fields with constant size.

PbDecoder

Decoder that reads Protobuf bytes and decodes them into Rust types.

PbEncoder

Encoder that serializes Rust types into Protobuf messages and values.

Tag

Protobuf tag, consisting of the field number and wire type.

Enums

DecodeError

Protobuf decoder error.

Presence

Field presence discipline

Constants

WIRE_TYPE_I32

Protobuf wire type for fixed 32-bit values.

WIRE_TYPE_I64

Protobuf wire type for fixed 64-bit values.

WIRE_TYPE_LEN

Protobuf wire type for length-delimited records.

WIRE_TYPE_VARINT

Protobuf wire type for varints.

Traits

MessageDecode

Protobuf message that can be decoded from the wire.

MessageEncode

Protobuf message that can be encoded onto the wire.

PbRead

A reader from which Protobuf data is read, similar to std::io::BufRead.

PbWrite

A writer to which Protobuf data is written, similar to std::io::Write.