Crate ndn_tlv 

ndn-tlv

Provides abstractions for working with TLV-encoded data.

It defines the core traits for encoding, decoding, and representing TLV records, so higher-level NDN crates can (de)serialize their packet types without hand-rolling the wire format themselves.

Installation

cargo add ndn-tlv

How it works

• Tlv should be implemented on types that represent a whole TLV record – ones that, in their encoded form, start with a type and a length.
• TlvEncode and TlvDecode are implemented on any type that can be encoded/decoded as part of a TLV record’s value, including all types that implement Tlv.
• A Tlv derive macro (from ndn-tlv-derive) implements all three traits for you, so you rarely have to write them by hand. See its documentation for how to use it.

Example

Here is a quick example of how the library may be used:

use bytes::{Buf, BufMut, Bytes, BytesMut};
use ndn_tlv::{Tlv, TlvEncode, TlvDecode, Result, VarNum, TlvError};

#[derive(Debug, Tlv, PartialEq)]
#[tlv(8)]
struct GenericNameComponent {
    name: Bytes,
}

#[derive(Debug, Tlv, PartialEq)]
#[tlv(1)]
struct ImplicitSha256DigestComponent {
    name: Bytes,
}

#[derive(Debug, Tlv, PartialEq)]
enum NameComponent {
    GenericNameComponent(GenericNameComponent),
    ImplicitSha256DigestComponent(ImplicitSha256DigestComponent),
}

#[derive(Debug, Tlv, PartialEq)]
#[tlv(7)]
struct Name {
    components: Vec<NameComponent>,
}

fn main() {
    let name = Name {
        components: vec![
            NameComponent::GenericNameComponent(GenericNameComponent {
                name: Bytes::from(&b"hello"[..])
            }),
            NameComponent::GenericNameComponent(GenericNameComponent {
                name: Bytes::from(&b"world"[..])
            }),
        ]
    };

    let data = name.encode();
    assert_eq!(data, &[
            7, 14, 8, 5, b'h', b'e', b'l', b'l', b'o',
                   8, 5, b'w', b'o', b'r', b'l', b'd'
        ][..]);
    let decoded = Name::decode(&mut data.clone()).unwrap();
    assert_eq!(decoded, name);
}

Related crates

• ndn-app is an application framework for building NDN producers and consumers, built on top of ndn-protocol, ndn-ndnlp, and ndn-nfd-mgmt.
• ndn-tlv-derive provides the derive macros ndn-tlv uses to generate TLV encoding/decoding for structs and enums.
• ndn-protocol implements the core NDN packet types (Interest, Data, Names, signatures) on top of ndn-tlv.
• ndn-ndnlp implements NDNLPv2, the link-layer protocol used to send NDN packets over a transport.
• ndn-nfd-mgmt implements the NFD management protocol, used e.g. to register routes with a local forwarder.

ndn-tlv is the base layer of the stack – every other crate here builds on it.

License

MIT

---

Produced as part of a Master’s thesis in Computer Science.

Re-exports

pub use ::bytes;

Structs

GenericTlv

A generic TLV record whose type is only known at runtime

VarNum

A variable-length number as used by TLV encoded values

Enums

NonNegativeInteger

A non-negative integer, not encoded using VarNum

TlvError

Common error enum for library functions

Traits

Tlv

A TLV record

TlvDecode

Decode data in TLV format

TlvEncode

Encode data in TLV format

Functions

find_tlv

Advance bytes until a valid TLV record of type T is found

tlv_critical

Returns whether a TLV is “critical”

tlv_typ_critical

Returns whether a TLV with a given type typ is “critical”

Type Aliases

Result

Common result type for library functions

Derive Macros

Tlv

Implements Tlv, TlvEncode, and TlvDecode for a struct or enum.