       Protean Protocol Prototyping Library (PROTOLIB)

OVERVIEW

Protolib is not so much a library as it is a toolkit.  The goal
of the Protolib is to provide a set of simple, cross-platform
C++ classes that allow development of network protocols and
applications that can run on different platforms and in network
simulation environments.  Although Protolib is principally for
research purposes, the code has been constructed to provide
robust, nefficient performance and adaptability to real
applications.

Currently Protolib supports most Unix platforms (including
MacOS X) and WIN32 platforms.  The most recent version also
supports building Protolib-based code for the ns-2 simulation
environment.  The OPNET simulation tool has also been supported
in the past and could be once again with a small amount of
effort.

CLASSES:

ProtoAddress:    Network address container class with support
                 for IPv4, IPv6, and "SIM" address types.  Also
                 includes functions for name/address
                 resolution.

ProtoSocket:     Network socket container class that provides
                 consistent interface for use of operating
                 system (or simulation environment) transport
                 sockets. Provides support for asynchronous
                 notification to ProtoSocket::Listeners.  The
                 ProtoSocket class may be used stand-alone, or
                 with other classes described below.  A
                 ProtoSocket may be instantiated as either a
                 UDP or TCP socket.

ProtoTimer:      This is a generic timer class which will
                 notify a ProtoTimer::Listener upon timeout.

ProtoTimerMgr:   This class manages ProtoTimer instances when
                 they are "activated".  The ProtoDispatcher
                 (below) derives from this to manage
                 ProtoTimers for an application.  (The
                 ProtoSimAgent base class contains a
                 ProtoTimerMgr to similarly manage timers for a
                 simulation instance).

ProtoTree:       Flexible implementation of a Patricia tree
                 data structure.  Includes a ProtoTree::Item
                 which may be derived from or used as a
                 container for  whatever data structures and
                 application may require.

ProtoRouteTable: Class based on the ProtoTree Patricia tree to
                 store routing table information. Uses the
                 ProtoAddress class to store network routing
                 addresses.  It's a pretty dumbed-down routing
                 table at the moment, but may be enhanced in
                 the future.  Example use of the ProtoTree.

ProtoRouteMgr:   Base class for providing  a conistent
                 interface to manage operating system (or
                 other) routing engines.

ProtoDispatcher: This class provides a core around which Unix
                 and Win32 applications using Protolib can be
                 implemented.  It's "Run()" method provides a
                 "main loop" which uses the "select()" system
                 call on Unix and the similar
                 "MsgWaitForMultipleObjectsEx()" system call on
                 Win32.  It is planned to eventually provide
                 some built-in support for threading in the
                 future (e.g. the ProtoDispatcher::Run() method
                 might execute in a thread, dispatching events
                 to a parent thread).

ProtoApp:        Provides a base class for implementing
                 Protolib-based command-line applications. Note
                 that "ProtoApp" and "ProtoSimAgent" are
                 designed such that subclasses can be derived
                 from either to reuse the same code in either a
                 real-world applications or as an "agent"
                 (entity) within a network simulation
                 environment (e.g. ns-2, OPNET).  A "background"
                 command is included for Win32 to launch the
                 app without a terminal window.

ProtoSimAgent:   Base class for simulation agent derivations. 
                 Currently an ns-2 agent base class is derived
                 from this, but it is possible that other
                 simulation environments  (e.g. OPNET, Qualnet)
                 might be supported in a similar fashion.

NsProtoSimAgent: Simulation agent base class for creating ns-2
                 instantiations of Protolib-based network
                 protocols and applications.

ProtoExample:    Example class which derives either from
                 ProtoApp or NsProtoSimAgent, depending upon
                 compile-time macro definitions.  It provides
                 equivalent functionality in either the
                 simulation environment or as a real-world
                 command-line application.  It demonstrates the
                 use/operation of ProtoSocket based UDP
                 transmission/reception, a ProtoTimer, and an
                 example ProtoSocket-based TCP client-server
                 exchange.   (NOTE: TCP operation is not yet
                 supported in the simulation environment.  This
                 will completed in coming months.  I plan to
                 extend ns-2 TCP agents to support actual
                 transfer of user data to support this.)

OTHER:

The Protolib code also includes some simple, general purpose debugging
routines which can output to "stderr" or optionally log to a specified file. 
See "protoDebug.h" for details.

There are also some supporting classes not described here and some work to be
done.  For example, the ProtoRouteMgr includes implementations for Linux and
BSD (incl. MacOS), but not yet for WIN32 (This is work in progress).  Also,
more complete documentation, including Doxygen-based code documentation and
a "Developer's Guide" with examples needs to be provided. 

Brian Adamson <adamson@itd.nrl.navy.mil> 30 September 2003




