hdlc

README

HDLC for Go

Simple implementation of an Encoder/Decoder for the High-Level Data Link Control as used in the PPP (Point-to-Point Protocol).

Implements validations of frames based on the standard CRC16 checksum.

Tested and working with pppd.

Documentation

Please read the godocs here.

Documentation

Overview

Package hdlc provides a simple implementation of an Encoder/Decoder for the High-Level Data Link Control as used in the PPP (Point-to-Point Protocol).

Example

conn1, conn2 := net.Pipe()

// Decode
frameCh := make(chan *hdlc.Frame)
go func() {
	decoder := hdlc.NewDecoder(conn2)
	frame, err := decoder.ReadFrame()
	if err != nil {
		panic(err)
	}
	frameCh <- frame
}()

// Encode
{
	encoder := hdlc.NewEncoder(conn1)
	frame := hdlc.Encapsulate([]byte("hello world"), false)
	if _, err := encoder.WriteFrame(frame); err != nil {
		panic(err)
	}
}

frame := <-frameCh

fmt.Printf("%s", frame.Payload)

Output:

hello world

Example (Accm)

Register the Line Feed and Horizontal Tab characters in the Async-Control-Character-Map.

conn1, conn2 := net.Pipe()
accm := hdlc.CharHT | hdlc.CharLF

// Decode
frameCh := make(chan *hdlc.Frame)
go func() {
	decoder := hdlc.NewDecoder(conn2).SetACCM(accm)
	frame, err := decoder.ReadFrame()
	if err != nil {
		panic(err)
	}
	frameCh <- frame
}()

// Encode
{
	encoder := hdlc.NewEncoder(conn1).SetACCM(accm)
	frame := hdlc.Encapsulate([]byte("hello\n\tworld"), false)
	if _, err := encoder.WriteFrame(frame); err != nil {
		panic(err)
	}
}

frame := <-frameCh

fmt.Printf("%s", frame.Payload)

Output:

hello
	world

Index

• Variables
• type ControlChar
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (fd *Decoder) ReadFrame() (*Frame, error)
  • func (fd *Decoder) SetACCM(chars ControlChar) *Decoder
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) SetACCM(chars ControlChar) *Encoder
  • func (e *Encoder) WriteFrame(f *Frame) (int, error)
• type Frame
  • func Encapsulate(p []byte, hasAddressCtrlPrefix bool) *Frame
  • func (f Frame) Valid() bool

Examples

• Package
• Package (Accm)

Variables

var (
	// ErrInvalidFrame represents any decoding error where the data received
	// doesn't respect the HDLC spec.
	ErrInvalidFrame = errors.New("invalid frame")

	// ErrEmptyFrame is returned every time there's an empty frame on the stream,
	// ie. when decoding.
	ErrEmptyFrame = errors.New("empty frame")
)

Types

type ControlChar

type ControlChar uint32

ControlChar is an ASCII control character, which is a character less than 0x20.

https://en.wikipedia.org/wiki/ASCII#Control_code_chart

const (
	CharNUL ControlChar = 1 << iota // Null
	CharSOH                         // Start of Head
	CharSTX                         // Start of Text
	CharETX                         // End of Text
	CharEOT                         // End of Transmission
	CharENQ                         // Enquiry
	CharACK                         // Acknowledgement
	CharBEL                         // Bell
	CharBS                          // Backspace
	CharHT                          // Horizontal Tab
	CharLF                          // Line Feed
	CharVT                          // vertical Tab
	CharFF                          // Form Feed
	CharCR                          // Carriage Return
	CharSO                          // Shift Out
	CharSI                          // Shift In
	CharDLE                         // Data Link Escape
	CharDC1                         // Device Control 1 (XON)
	CharDC2                         // Device Control 2
	CharDC3                         // Device Control 3 (XOFF)
	CharDC4                         // Device Control 4
	CharNAK                         // Negative Acknowledgement
	CharSYN                         // Synchronous Idle
	CharETB                         // End of Transmission Block
	CharCAN                         // Cancel
	CharEM                          // End of Medium
	CharSUB                         // Substitute
	CharESC                         // Escape
	CharFS                          // File Separator
	CharGS                          // Group Separator
	CharRS                          // Record Separator
	CharUS                          // Unit Separator

	// All control characters
	CharALL = CharNUL | CharSOH | CharSTX | CharETX | CharEOT | CharENQ |
		CharACK | CharBEL | CharBS | CharHT | CharLF | CharVT | CharFF | CharCR |
		CharSO | CharSI | CharDLE | CharDC1 | CharDC2 | CharDC3 | CharDC4 |
		CharNAK | CharSYN | CharETB | CharCAN | CharEM | CharSUB | CharESC |
		CharFS | CharGS | CharRS | CharUS
)

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder reads HDLC frames from an input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r. The decoder introduces its own buffering and may read data from r beyond the requested frames.

func (*Decoder) ReadFrame

func (fd *Decoder) ReadFrame() (*Frame, error)

ReadFrame re-syncs the Decoder if necessary and reads the next frame. Returns ErrInvalidFrame if the decoding fails. Returns ErrEmptyFrame when the frame has no content to decode.

func (*Decoder) SetACCM

func (fd *Decoder) SetACCM(chars ControlChar) *Decoder

SetACCM sets the decoder's Async-Control-Character-Map (ACCM). The default ACCM value is 0, meaning that the decoder does not escape any control characters.

Note that this implementation does not negotiate the ACCM with the peer.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

An Encoder writes HDLC frames to an output stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) SetACCM

func (e *Encoder) SetACCM(chars ControlChar) *Encoder

SetACCM sets the encoder's Async-Control-Character-Map (ACCM). The default ACCM value is 0, meaning that the encoder does not escape any control characters.

Note that this implementation does not negotiate the ACCM with the peer.

func (*Encoder) WriteFrame

func (e *Encoder) WriteFrame(f *Frame) (int, error)

WriteFrame writes the frame f on the output stream, encoding it's content.

type Frame

type Frame struct {
	Payload              []byte
	FCS                  []byte
	HasAddressCtrlPrefix bool
}

A Frame is an HDLC frame. Use Encapsulate to create a new one starting from a payload.

func Encapsulate

func Encapsulate(p []byte, hasAddressCtrlPrefix bool) *Frame

Encapsulate takes a payload p and some configuration and creates a frame that can be written with an Encoder.

func (Frame) Valid

func (f Frame) Valid() bool

Valid performs a CRC on the frame, based on the FCS and the other fields.