tlv

README

tlv

It marshals and unmarshals go types directly to packet format with run-time reflection.

Supported types

• encoding.BinaryMarshaler and encoding.BinaryUnmarshaler
• bool
• uint64
• string
• pointer and slice of any types above
• struct of any types above

Documentation

Overview

Package tlv implements Type-Length-Value (TLV) Encoding.

See http://named-data.net/doc/ndn-tlv/tlv.html.

Index

• Constants
• Variables
• func CacheType(v interface{}) error
• func Copy(dst ReadFrom, src WriteTo) error
• func Hash(f func() hash.Hash, v interface{}) ([]byte, error)
• func Marshal(v interface{}, t uint64) ([]byte, error)
• func Unmarshal(b []byte, v interface{}, t uint64) error
• type ReadFrom
• type Reader
  • func NewReader(r io.Reader) Reader
• type WriteTo
• type Writer
  • func NewWriter(w io.Writer) Writer

Constants

const (
	// MaxSize is the upper limit for tlv buffers.
	// 1. One "common" size of Ethernet jumbo packets is 9000 octets
	// 2. It is generally sufficient to carry an 8192 byte payload in a content object
	// 3. 8800 bytes was a message size limit in ONC-RPC over UDP
	// 4. Some OSs have a limited default UDP packet size (MacOS: net.inet.udp.maxdgram: 9216) and/or a limited space for receive buffers (MacOS: net.inet.udp.recvspace: 42080)
	// 5. When a ContentObject is signed it is not known whether the transmission path will be UDP / TCP / ..
	MaxSize = 8800
)

Variables

var (
	ErrPacketTooLarge = errors.New("exceed max size")
	ErrNotSupported   = errors.New("feature not supported")
	ErrUnexpectedType = errors.New("type not match")
	ErrInvalidPtr     = errors.New("invalid pointer")
)

Errors introduced by encoding and decoding.

var (
	ErrMissingType = errors.New("type not specified")
)

Errors introduced by parsing struct tags.

Functions

func CacheType

func CacheType(v interface{}) error

CacheType caches struct tags to prevent allocation on common types.

func Copy

func Copy(dst ReadFrom, src WriteTo) error

Copy copies from src to dst. If src and dst have the same type, it will perform direct copying with reflection. Otherwise copying will happen with tlv representation.

func Hash

func Hash(f func() hash.Hash, v interface{}) ([]byte, error)

Hash returns the digest of tlv-encoded data.

See Marshal.

'*' after type number indicates this tlv is signature, and should be omitted in digest calculation.

func Marshal

func Marshal(v interface{}, t uint64) ([]byte, error)

Marshal returns the tlv encoding of v.

The "tlv" struct tag specifies tlv type number. '?' after type number indicates that this tlv should be omitted if the value is empty.

func Unmarshal

func Unmarshal(b []byte, v interface{}, t uint64) error

Unmarshal parses the tlv-encoded data and stores the result in the value pointed to by v.

Types

type ReadFrom

type ReadFrom interface {
	ReadFrom(Reader) error
}

ReadFrom includes its type number, and can be directly decoded with Reader.

type Reader

type Reader interface {
	// Peek returns the tlv type without advancing.
	//
	// If the buffer is invalid, it will be filled with the next tlv block.
	Peek() uint64
	// Read reads current tlv block into v.
	//
	// If the buffer is invalid, it will be filled with the next tlv block.
	Read(interface{}, uint64) error
}

Reader decodes tlv-encoded data.

func NewReader

func NewReader(r io.Reader) Reader

NewReader creates a new buffered Reader.

type WriteTo

type WriteTo interface {
	WriteTo(Writer) error
}

WriteTo includes its type number, and can be directly encoded with Writer.

type Writer

type Writer interface {
	Write(interface{}, uint64) error
}

Writer encodes data in tlv.

func NewWriter

func NewWriter(w io.Writer) Writer

NewWriter creates a new buffered Writer.