chickadee » packedobjects

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

packedobjects

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).

packedobjects is suitable for simple cross platform request/response protocols that require efficient encoding.

So far packedobjects has been run on the following platforms:

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

Author

John P. T. Moore <jptmoore@gmail.com>

Version

Building from subversion repository

svn checkout http://anonymous:@code.call-cc.org/svn/chicken-eggs/release/4/packedobjects/trunk packedobjects
cd packedobjects
chicken-install

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> 'read-message <fd>)

Reads a message from a file descriptor into the PDU buffer.

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

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

A message consists of the encoded data plus a 2 byte header representing the length of the message. Therefore, the maximum message size is 2^16-1 bytes.

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

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

(<packedobject> 'free)

Explicitly frees the PDU buffer. N.B. This call is optional as the memory will be automatically garbage collected.

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 "afafaf")
description
String of hexadecimal characters with no length restriction.

numeric-string

protocol
(foobar numeric-string ())
values
(foobar "123")
description
String of numeric 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.

null

protocol
(foobar null)
values
(foobar)
description
Null value.

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.

Constraints

Constraints may be placed on all string types as well as integers. Restricting the size of strings and the range of integers can reduce the amount of bits encoded.

The following are valid string contraints:

The following are valid integer constraints:

Note, min and max denotes no lower bound and upper bound respectively, therefore () is equivalent to (size min max) or (range min max).

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