The packet Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The packet Reference Manual

This is the packet Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 09:08:45 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

PACKET

PACKET is a simple library for defining C-style structures and packing/unpacking them into Common Lisp arrays.

It is typically used for handling UDP packets, but could also be used for unpacking e.g. mmap'ed data files.

Packet type definitions

Packet comes with some pre-defined intrinsic data types:

Users define their packet type and associated CLOS class using:

(defpacket name
  ((slot-name slot-type &rest slot-options)
   ...)
  &rest options)

This expands to a defclass for the structure and code for defining the new packet type.

The slot-type can either be a symbol referring to a previously defined type (either primitive or a previous defpacket) or it can be a form (slot-type length) which means an array of length of slot-type objects.

The slot-options are passed into the defclass slot specifier.

Options can include:

(:packing <integer packing>) ;; sets the packing width for the slots
(:size <integer size>)       ;; sets the total packet buffer size

All other options are passed as options to defclass.

Usage

Make a packet buffer using:

(pack object type) 

This returns the buffer filled in with information.

Extract an object from a buffer using:

(unpack buffer type)

Utilities

Along with the serialization functions, there are also several other utilities which provide commonly required functionality:

(defflags *example-flags*
  ((:myflag1 0 "My flag1")
   (:myflag2 1 "My flag2")))
(pack-flags '(:myflag1 :myflag2) *example-flags*)
(defenum *example-enum*
  ((:a 0 "A")
   (:b 1 "B")))
(enum :a *example-enum*)
(hd #(1 2 3 4))

Both the flags and enums expand to eval-when forms so that they can be computed at compile time e.g. like:

(defun test ()
  (list #.(enum :a *example-enum*)))

Example

We are trying to send packets to a UDP server (written in C) expecting something like

struct person_s {
  char name[20];
  uint32_t flags;
};

struct people_s {
  uint32_t magic;
  int32_t npeople;
  struct person_s people[20];
  uint32_t flags;
};

We define our packet type using:

(defconstant +magic-number+ #x1E2B3A4D)

(defpacket person-s
  ((name (:string 20) :initform "" :initarg :name)
   (flags :uint32 :initform 0 :initarg :flags))
  (:documentation "Person structure."))

(defpacket people-s 
  ((magic :uint32 :initform +magic-number+)
   (npeople :int32 :initform 0 :initarg :npeople)
   (people (person-s 20) :initform nil :initarg :people)
   (flags :uint32 :initform 0 :initarg :flags))
  (:documentation "Collection of people."))

;; pack an instance into a buffer
(pack (make-instance 'people-s 
                     :npeople 2
                     :people (list (make-instance 'person-s :name "frank" :flags 123)
		                   (make-instance 'person-s :name "james" :flags 321))
                     :flags 456)
      'people-s)
-> #(77 58 43 30 2 0 0 0 102 114 97 110 107 ... )

;; unpack a buffer into an instance
(unpack buffer 'people-s)
-> #<PEOPLE-S {24CB5061}>

See example.lisp for more simple usages.

TODO

Frank James March 2014


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 packet

Author

Frank James <frank.a.james@gmail.com>

License

BSD

Description

Simple binary serialization library.

Dependency

ieee-floats

Source

packet.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 packet.asd

Location

packet.asd

Systems

packet (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 packet/package.lisp

Parent

packet (system)

Location

package.lisp

Packages

packet


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 packet/utils.lisp

Dependency

package.lisp (file)

Parent

packet (system)

Location

utils.lisp

Exported Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 packet/packet.lisp

Dependency

utils.lisp (file)

Parent

packet (system)

Location

packet.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 packet

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: defenum NAME ENUMS

Define a list of enums

Package

packet

Source

utils.lisp (file)

Macro: defflags NAME FLAGS &optional DOCUMENTATION

Macro to define a set of flags

Package

packet

Source

utils.lisp (file)

Macro: defpacket NAME SLOTS &rest OPTIONS

Macro to define the CLOS class and packet type.

SLOTS should be a list of format (SLOT-NAME SLOT-TYPE &rest SLOT-OPTIONS).

SLOT-NAME should be a symbol used for refering to the CLOS class slot.

SLOT-TYPE should be a symbol refering to a previously defined packet type (forward references are forbidden because we need to know the total packet size at definition time).
Use (SLOT-TYPE LENGTH) for arrays.

SLOT-OPTIONS are passed to the corresponding defclass slot specifier.

OPTIONS can contain (:packing PACKING) and (:size SIZE). These are used to
set the packing width and total packet size. If not specified PACKING defaults to *DEFAULT-PACKING*, SIZE defaults to the total size of packet type. If specified, SIZE may not be less than this, but can be more, to allow for unused space at the end of the structure.

All other options are passed to defclass.

Package

packet

Source

packet.lisp (file)

Macro: defpacket* NAME SLOTS &rest OPTIONS

Like DEFPACKET but defines a DEFSTRUCT instead of a DEFCLASS.

Each slot should be of the form (slot-name slot-type &optional initial-value).

Initial value defaults to 0.

Package

packet

Source

packet.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: enum ENUM ENUMS
Package

packet

Source

utils.lisp (file)

Function: enum-id NUMBER ENUMS
Package

packet

Source

utils.lisp (file)

Function: enum-p NUMBER ENUM ENUMS
Package

packet

Source

utils.lisp (file)

Function: flag-p NUMBER FLAG-NAME FLAGS
Package

packet

Source

utils.lisp (file)

Function: hd DATA

Hexdump output

Package

packet

Source

utils.lisp (file)

Function: list-types ()

List all defined PACKET types.

Package

packet

Source

packet.lisp (file)

Function: pack OBJECT TYPE

Make a packet buffer from the initial object.

Package

packet

Source

packet.lisp (file)

Function: pack-flags FLAG-NAMES FLAGS

Combine flags

Package

packet

Source

utils.lisp (file)

Function: pad ARRAY LEN

Pad array with zeros if its too short

Package

packet

Source

utils.lisp (file)

Function: pad* ARRAY &optional WIDTH

Pad to a length multiple of WIDTH

Package

packet

Source

utils.lisp (file)

Function: subseq* SEQUENCE START &optional LEN

Subsequence with length

Package

packet

Source

utils.lisp (file)

Function: type-size TYPE

Get the total size in bytes for this type.

Package

packet

Source

packet.lisp (file)

Function: unpack BUFFER TYPE

Unpack a buffer into an object. Returns any extra (unused) bytes as the 2nd value

Package

packet

Source

packet.lisp (file)

Function: unpack-flags NUMBER FLAGS

Split the number into its flags.

Package

packet

Source

utils.lisp (file)

Function: usb8 &rest SEQUENCES

Make an (unsigned byte 8) vector from the sequences

Package

packet

Source

utils.lisp (file)

Function: usb8* &rest NUMBERS

Make an (unsigned-byte 8) vector from the numbers

Package

packet

Source

utils.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *default-packing*

Default packing boundary.

Package

packet

Source

packet.lisp (file)

Special Variable: *type-definitions*

Global table storing type definitions.

Package

packet

Source

packet.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: define-alias ALIAS NAME
Package

packet

Source

packet.lisp (file)

Macro: define-type NAME ((POBJECT PBUFFER PSTART) &body PBODY) ((UBUFFER USTART) &body UBODY) SIZE
Package

packet

Source

packet.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: %define-alias ALIAS NAME

Define an alias for a type. Allows refering to the same type by a different name.

Package

packet

Source

packet.lisp (file)

Function: %define-type NAME PACK-HANDLER UNPACK-HANDLER SIZE

Intern a new type definition.

PACK-HANDLER is a function with lambda-list (object buffer start)
and should encode the object into the buffer starting at offset START.

UNPACK-HANDLE is a function with lambda-list (buffer start)
and should extract information about the desired object starting at offset START. It should return the object.

SIZE is the total number of bytes this object consumes.

Package

packet

Source

packet.lisp (file)

Function: bytes INTEGER SIZE

Expand an INTEGER into its consituent number of SIZE bytes.

Package

packet

Source

packet.lisp (file)

Function: compute-real-slots SLOTS PACKING &optional SIZE

Compute the offsets of each slot. We use this information in the closures generated by DEFPACKET to pack/unpack the object.

Package

packet

Source

packet.lisp (file)

Function: get-type NAME

Find the type definition.

Package

packet

Source

packet.lisp (file)

Function: merge-bytes BYTES &optional SIGNED

Convert a list of bytes into a signed/unsigned integer

Package

packet

Source

packet.lisp (file)

Function: pack-array ARRAY TYPE BUFFER START

Pack an array of object into the buffer.

Package

packet

Source

packet.lisp (file)

Function: pack-bytes BYTES BUFFER START

Pack a list of bytes into a buffer

Package

packet

Source

packet.lisp (file)

Function: pack-object OBJECT SLOTS BUFFER START

Pack an OBJECT specified by SLOTS into the BUFFER starting at offset START.

Package

packet

Source

packet.lisp (file)

Function: pack-string STRING LENGTH BUFFER START

Pack a string into the buffer.

Package

packet

Source

packet.lisp (file)

Function: pack-type OBJECT TYPE BUFFER START

Pack an object into the buffer.

Package

packet

Source

packet.lisp (file)

Function: pack-wstring STRING LENGTH BUFFER START

Pack a string into the buffer.

Package

packet

Source

packet.lisp (file)

Function: round-offset OFFSET PACKING

Round the offset to the nearest packing boundary

Package

packet

Source

packet.lisp (file)

Function: type-packer TYPE

Get the packing handler for this type.

Package

packet

Source

packet.lisp (file)

Function: type-unpacker TYPE

Get the unpacking handler for this type.

Package

packet

Source

packet.lisp (file)

Function: unpack-array LENGTH TYPE BUFFER START

Extract an array of objects from the buffer.

Package

packet

Source

packet.lisp (file)

Function: unpack-bytes BUFFER START SIZE &optional SIGNED

Get an integer from the buffer.

Package

packet

Source

packet.lisp (file)

Function: unpack-object OBJECT SLOTS BUFFER START

Unpack the SLOTS of OBJECT from BUFFER starting at offset START.

Package

packet

Source

packet.lisp (file)

Function: unpack-string LENGTH BUFFER START

Unpack a string from the buffer.

Package

packet

Source

packet.lisp (file)

Function: unpack-type TYPE BUFFER START

Unpack an objcet from the buffer.

Package

packet

Source

packet.lisp (file)

Function: unpack-wstring LENGTH BUFFER START

Unpack a string from the buffer.

Package

packet

Source

packet.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   P  
Index Entry  Section

F
File, Lisp, packet.asd: The packet<dot>asd file
File, Lisp, packet/package.lisp: The packet/package<dot>lisp file
File, Lisp, packet/packet.lisp: The packet/packet<dot>lisp file
File, Lisp, packet/utils.lisp: The packet/utils<dot>lisp file

L
Lisp File, packet.asd: The packet<dot>asd file
Lisp File, packet/package.lisp: The packet/package<dot>lisp file
Lisp File, packet/packet.lisp: The packet/packet<dot>lisp file
Lisp File, packet/utils.lisp: The packet/utils<dot>lisp file

P
packet.asd: The packet<dot>asd file
packet/package.lisp: The packet/package<dot>lisp file
packet/packet.lisp: The packet/packet<dot>lisp file
packet/utils.lisp: The packet/utils<dot>lisp file

Jump to:   F   L   P  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %  
B   C   D   E   F   G   H   L   M   P   R   S   T   U  
Index Entry  Section

%
%define-alias: Internal functions
%define-type: Internal functions

B
bytes: Internal functions

C
compute-real-slots: Internal functions

D
defenum: Exported macros
defflags: Exported macros
define-alias: Internal macros
define-type: Internal macros
defpacket: Exported macros
defpacket*: Exported macros

E
enum: Exported functions
enum-id: Exported functions
enum-p: Exported functions

F
flag-p: Exported functions
Function, %define-alias: Internal functions
Function, %define-type: Internal functions
Function, bytes: Internal functions
Function, compute-real-slots: Internal functions
Function, enum: Exported functions
Function, enum-id: Exported functions
Function, enum-p: Exported functions
Function, flag-p: Exported functions
Function, get-type: Internal functions
Function, hd: Exported functions
Function, list-types: Exported functions
Function, merge-bytes: Internal functions
Function, pack: Exported functions
Function, pack-array: Internal functions
Function, pack-bytes: Internal functions
Function, pack-flags: Exported functions
Function, pack-object: Internal functions
Function, pack-string: Internal functions
Function, pack-type: Internal functions
Function, pack-wstring: Internal functions
Function, pad: Exported functions
Function, pad*: Exported functions
Function, round-offset: Internal functions
Function, subseq*: Exported functions
Function, type-packer: Internal functions
Function, type-size: Exported functions
Function, type-unpacker: Internal functions
Function, unpack: Exported functions
Function, unpack-array: Internal functions
Function, unpack-bytes: Internal functions
Function, unpack-flags: Exported functions
Function, unpack-object: Internal functions
Function, unpack-string: Internal functions
Function, unpack-type: Internal functions
Function, unpack-wstring: Internal functions
Function, usb8: Exported functions
Function, usb8*: Exported functions

G
get-type: Internal functions

H
hd: Exported functions

L
list-types: Exported functions

M
Macro, defenum: Exported macros
Macro, defflags: Exported macros
Macro, define-alias: Internal macros
Macro, define-type: Internal macros
Macro, defpacket: Exported macros
Macro, defpacket*: Exported macros
merge-bytes: Internal functions

P
pack: Exported functions
pack-array: Internal functions
pack-bytes: Internal functions
pack-flags: Exported functions
pack-object: Internal functions
pack-string: Internal functions
pack-type: Internal functions
pack-wstring: Internal functions
pad: Exported functions
pad*: Exported functions

R
round-offset: Internal functions

S
subseq*: Exported functions

T
type-packer: Internal functions
type-size: Exported functions
type-unpacker: Internal functions

U
unpack: Exported functions
unpack-array: Internal functions
unpack-bytes: Internal functions
unpack-flags: Exported functions
unpack-object: Internal functions
unpack-string: Internal functions
unpack-type: Internal functions
unpack-wstring: Internal functions
usb8: Exported functions
usb8*: Exported functions

Jump to:   %  
B   C   D   E   F   G   H   L   M   P   R   S   T   U  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*default-packing*: Internal special variables
*type-definitions*: Internal special variables

S
Special Variable, *default-packing*: Internal special variables
Special Variable, *type-definitions*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S  
Index Entry  Section

P
Package, packet: The packet package
packet: The packet system
packet: The packet package

S
System, packet: The packet system

Jump to:   P   S