You are looking at historical revision 2166 of this page. It may differ significantly from its current revision.

Introduction

packedobjects is a data encoding tool based on the telecommunications standard Packed Encoding Rules (PER). An abstract syntax language is used to define a protocol specification. packedobjects uses the Scheme programming language to represent the protocol specification within a symbolic expression (s-expression).

For a more detailed introduction refer to the following short paper.

packedobjects is suitable for simple cross platform request/response protocols that require efficient encoding. So far packedobjects has been tested on the following platforms:

Author

John P. T. Moore

Version

0.62

Usage

(packedobjects <protocol> #!key <pdusize> <strsize>)

Creates a packedobject using the supplied protocol specification. Optional values for the PDU and string buffer sizes can be specified. They default to 5000 and 1000 respectively. Both the PDU buffer and string buffer are fixed in size. The string buffer must be large enough to handle any string used by the protocol. The PDU buffer must be manually freed.

(<packedobject> 'pack <values>)

Encodes a list of values and returns the number of bytes used.

(<packedobject> 'unpack)

Returns a list of values.

(<packedobject> 'read <fd> <size>)

Reads a number of bytes from a file descriptor into the PDU buffer.

(<packedobject> 'write <fd> <size>)

Writes a number of bytes from the PDU buffer to a file descriptor.

(<packedobject> 'dump-buffer <filename> <size>)

Dumps a number of bytes from the PDU buffer to a file.

(<packedobject> 'free)

Frees the PDU buffer.

Data types with examples

The following data types are currently supported.

string

protocol
(foobar string (size 1 10))
values
(foobar "foobar")
description
7 bit string limited to 10 characters in length.

octet-string

protocol
(foobar octet-string ())
values
(foobar "foobar")
description
8 bit string with no length restriction.

bit-string

protocol
(foobar bit-string (size 8))
values
(foobar "10101010")
description
Bitstring fixed in length.

hex-string

protocol
(foobar hex-string (size 1 max))
values
(foobar "foobar")
description
String of hexadecimal characters with no length restriction.

integer

protocol
(foobar integer (range 1 10))
values
(foobar 5)
description
Integer with a minimum allowed value of 1 and maximum allowed value of 10.

boolean

protocol
(foobar boolean)
values
(foobar #t)
description
Boolean value.

enumerated

protocol
(foobar enumerated (mon tues wed thurs fri))
values
(foobar fri)
description
List of alternative symbols.

sequence

protocol
(foobar sequence (foo string (size 1 10)) (bar string (size 1 10)))
values
(foobar (foo "foo") (bar "bar"))
description
Ordered sequence of types.

sequence-of

protocol
(foobar sequence-of (foo string (size 1 10)) (bar string (size 1 10)))
values
(foobar ((foo "foo") (bar "bar")) ((foo "anotherfoo") (bar "anotherbar")))
description
Ordered sequence of types where the sequence may repeat.

set

protocol
(foobar set (foo string (size 1 10)) (bar string (size 1 10)))
values
(foobar (bar "bar") (foo "foo"))
description
Unordered sequence of types. Each element of a set is also optional.

choice

protocol
(foobar choice (foo integer ()) (bar integer ()))
values
(foobar (bar 100))
description
Single item from a series of types.

Examples

(require-extension packedobjects)
 
(define bbcard
  '(bbcard sequence
           (name string (size 1 60))
           (team string (size 1 60))
           (age integer (range 1 100))
           (position string (size 1 60))
           (handedness enumerated (left-handed right-handed ambidextrous))
           (batting-average sequence
                            (mantissa integer ())
                            (base enumerated (2 10))
                            (exponent integer ()))))
 
(define bbcard-values
  '(bbcard
    (name "Casey")
    (team "Mudville Nine")
    (age 32)
    (position "left field")
    (handedness ambidextrous)
    (batting-average
     (mantissa 250)
     (base 10)
     (exponent -3))))
 
(define po (packedobjects bbcard))
(print* "encoded in " (po 'pack bbcard-values) " bytes.\n")
(print (po 'unpack))
(po 'free)

The following example retrieves random numbers from random.org.

The client talks to a server process which in turn obtains the numbers using HTTP. The data transferred between client and server is significantly more efficient, in terms of bits on the wire, than if the client talked directly to random.org using HTTP.

tcpclient.scm

tcpserver.scm

Limitations

To do

License

Copyright (c) 2006, John P. T. Moore

All rights reserved.

BSD license