Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the packet Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 05:32:01 2022 GMT+0.
Next: Systems, Previous: The packet Reference Manual, Up: The packet Reference Manual [Contents][Index]
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 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.
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)
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*)))
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.
Frank James March 2014
Next: Files, Previous: Introduction, Up: The packet Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Simple binary serialization library.
Frank James <frank.a.james@gmail.com>
BSD
ieee-floats (system).
Next: Packages, Previous: Systems, Up: The packet Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: packet/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
packet (system).
Next: packet/utils.lisp, Previous: packet/packet.asd, Up: Lisp [Contents][Index]
packet (system).
Next: packet/packet.lisp, Previous: packet/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
packet (system).
Previous: packet/utils.lisp, Up: Lisp [Contents][Index]
utils.lisp (file).
packet (system).
Next: Definitions, Previous: Files, Up: The packet Reference Manual [Contents][Index]
Packages are listed by definition order.
common-lisp.
Next: Indexes, Previous: Packages, Up: The packet Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Public Interface, Up: Public Interface [Contents][Index]
Define a list of enums
Macro to define a set of flags
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.
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.
Previous: Macros, Up: Public Interface [Contents][Index]
Hexdump output
List all defined PACKET types.
Make a packet buffer from the initial object.
Combine flags
Pad array with zeros if its too short
Pad to a length multiple of WIDTH
Subsequence with length
Get the total size in bytes for this type.
Unpack a buffer into an object. Returns any extra (unused) bytes as the 2nd value
Split the number into its flags.
Make an (unsigned byte 8) vector from the sequences
Make an (unsigned-byte 8) vector from the numbers
Previous: Public Interface, Up: Definitions [Contents][Index]
Default packing boundary.
Global table storing type definitions.
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Define an alias for a type. Allows refering to the same type by a different name.
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.
Expand an INTEGER into its consituent number of SIZE bytes.
Compute the offsets of each slot. We use this information in the closures generated by DEFPACKET to pack/unpack the object.
Find the type definition.
Convert a list of bytes into a signed/unsigned integer
Pack an array of object into the buffer.
Pack a list of bytes into a buffer
Pack an OBJECT specified by SLOTS into the BUFFER starting at offset START.
Pack a string into the buffer.
Pack an object into the buffer.
Pack a string into the buffer.
Round the offset to the nearest packing boundary
Get the packing handler for this type.
Get the unpacking handler for this type.
Extract an array of objects from the buffer.
Get an integer from the buffer.
Unpack the SLOTS of OBJECT from BUFFER starting at offset START.
Unpack a string from the buffer.
Unpack an objcet from the buffer.
Unpack a string from the buffer.
Previous: Definitions, Up: The packet Reference Manual [Contents][Index]
| Jump to: | %
B C D E F G H L M P R S T U |
|---|
| Jump to: | %
B C D E F G H L M P R S T U |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
S |
|---|
| Jump to: | *
S |
|---|
| Jump to: | F P S U |
|---|
| Jump to: | F P S U |
|---|