initial commit

BUILD.TXT

@@ -0,0 +1,81 @@
+Building Protolib
+=================
+
+Protolib can be built using the Waf build tool, included in the distribution.
+To see a full list of options, run:
+
+    ./waf -h
+
+Configuring
+-----------
+
+To perform the configure checks, run:
+
+    ./waf configure
+
+Some options for the configure step:
+
+    --prefix=<DIR> - Directory to install files to (Default - /usr/local)
+
+    --debug - Builds a debug build (with debugging symbols), otherwise an
+            optimized library is built.
+
+    --build-python - Builds the Python extension (*see notes for building
+    		     protolib python bindings via setup.py outside w/out waf)
+    --build-java - Builds the Java extension
+        You must set the JAVA_HOME environment variable to the location of your
+        JDK directory
+
+	Waf has issues building the java extensions with OpenJDK.  Oracle JDK
+	is recommended.
+
+Building
+--------
+
+To build the library, simply run:
+
+    ./waf
+
+To build examples along with the library, run:
+
+    ./waf --targets=ex1,ex2,...
+
+Where ex1,ex2 is the name of the example you want to build (see ./waf list).
+Additionally, you can add the "--targets=*" flag to build all the example
+programs.
+
+Installing
+----------
+
+To install, run:
+
+    ./waf install
+
+This will install the compiled library and headers to wherever your prefix was
+specified.  (See configure flags)
+
+Uninstalling
+------------
+
+Waf tracks the files it installs, so run:
+
+    ./waf uninstall
+
+to remove all files from a previous ./waf install
+
+Cleaning
+--------
+
+    ./waf clean
+
+will delete all compiled files and configuration settings.
+
+    ./waf distclean
+
+will do the same as clean, and additionally delete the waf cache files.
+
+Building protolib python bindings without waf
+---------------------------------------------
+
+Build protolib (make -f Makefile.<os>)
+python setup.py install (build & install protolib python bindings)

LICENSE

@@ -0,0 +1,28 @@
+/*********************************************************************
+ *
+ * AUTHORIZATION TO USE AND DISTRIBUTE
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that: 
+ *
+ * (1) source code distributions retain this paragraph in its entirety, 
+ *  
+ * (2) distributions including binary code include this paragraph in
+ *     its entirety in the documentation or other materials provided 
+ *     with the distribution.
+ * 
+ *      "This product includes software written and developed 
+ *       by Code 5520 of the Naval Research Laboratory (NRL)." 
+ *         
+ *  The name of NRL, the name(s) of NRL  employee(s), or any entity
+ *  of the United States Government may not be used to endorse or
+ *  promote  products derived from this software, nor does the 
+ *  inclusion of the NRL written and developed software  directly or
+ *  indirectly suggest NRL or United States  Government endorsement
+ *  of this product.
+ * 
+ * THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+ * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ ********************************************************************/

README.md

@@ -0,0 +1,170 @@
+       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, efficient 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.
+
+ProtoPipe:       Socket-like mechanism (with both datagram and
+                 stream support) useful for interprocess
+                 communications (uses Unix domain sockets on
+                 Unix, other stuff on Win32 & WinCE)
+
+ProtoCap:        Interface class for raw MAC-layer packet capture.
+                 Platform implementations of this class vary
+                 including a "pcap" based implementation.
+
+ProtoDetour:     Inbound/outbound packet _interception_ class.
+                 Platform implementations vary ... works with
+                 firewall stuff.  Win32 version based around
+                 NDIS intermediate driver in progress.
+
+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.)
+
+NsProtoTCPSocketAgent: TCP implementation of the NSSocketProxy 
+		 class for providing TCP support within Protolib.  
+		 This class provides a hub for interfacing with 
+		 the underlying TCP toolkit for providing access 
+		 to the TCP support.  NsProtoTCPSocketAgent 
+	         essentially auto-detects which sockets it should 
+		 be (i.e. a client or a server) and then instantiates 
+		 the underlying implementations in order to provide 
+		 that behaviour, which are either a TCPSocketAgent
+		 or a TCPServerSocketAgent:
+
+TCPSocketAgent:  The TCP socket agent implementation that can be 
+		 used for clients and that can be used as the socket 
+		 responsible for the server-side of the  connection 
+		 after a call to accept.
+
+TCPServerSocketAgent: The TCP server implementation that only 
+		 implements part of the TCP protocol (by listening 
+		 for the initial SYN connection requests from clients).  
+		 The server simply acts as a broker for assigning 
+		 TCPSocketAgents when clients request connections, 
+		 either by creating the sockets itself or by sending an 
+		 ACCEPT event to the application in order for it to 
+		 create the socket and call the accept function 
+		 manually.  The latter approach is the norm.
+
+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 <[email protected]> 30 September 2003
+
+
+
+

TODO.TXT

@@ -0,0 +1,22 @@
+Protolib is a work in progress.  Its features reflect the current (and past) 
+needs of our research group.  This list is a list of things we might add in 
+the future:
+
+0) Documentation, documentation, documentation!!!  Code documentation and
+   "Developers' Guide" materials.
+
+1) ProtoDisptacher use of "epoll()" (Linux), "kqueue()" (BSD), and "/dev/poll"
+   (Solaris) for enhanced performance over the current use of "select()".  We 
+   may also explore use of "pselect()" further if it makes sense.
+
+2) Generalize the Mutex stuff used in ProtoDispatcher for general purpose
+   thread synchronization purposes ...
+
+3) Make code truly UNICODE compliant ... In particular, any functions which 
+   take/return strings (currently "char*") should instead use "tchar" 
+   types/functions as appropriate.
+
+
+Brian Adamson
+<[email protected]>
+9 June 2005

VERSION.TXT

@@ -0,0 +1,60 @@
+
+This file provides information on changes to Protolib code indexed by the
+version number found in the "common/protoVersion.h" file.  Serious version
+tracking was not maintained for Protolib for a long time since it was 
+typically included in full source form in the projects for which it was
+used and those projects were assumed to maintain configuration control for
+themselves and the Protolib code they used.  Protolib has matured into a
+more substantial code base and used by multiple projects, so the time has come
+to provide some additional description of significant changes made.  
+Additionally, the developers will try to provide more timely releases of 
+the Protolib source tree outside of the SVN repository.
+
+
+
+
+Version 2.1b1
+=============
+  - Added "ProtoTime" class that is used by ProtoTimer, etc to
+    provide a basis for time references, manipulations, etc.  The
+    scope of ProtoTime will likely be expanded in our quest to 
+    eventually provide a standards means to access precision
+    time facilities as they come available to different operating
+    system environments.
+
+   - The "ManetMsg" implementation of the "draft-ietf-manet-packetbb"
+     specification was updated to Draft Version 13.
+     (Thanks to Ulrich Herberg for this!)
+
+   - The ns-2 ProtoSocket(TCP) adaption was fixed to be consistent
+     with the real-world behavior of the ProtoSocket(TCP).
+
+   - Initial support for Doxygen-based documentation of the Protolib
+     code base was integrated.
+
+   - Fixed WIN32 ProtoDispatcher::BoostPriority() by using 
+     THREAD_SET_INFORMATION access level (more portable)
+     Thanks to Renee Carignan!
+
+Version 2.0b4
+=============
+  - This was the last version annotation _before_ this tracking file
+    was established.  The "2.x" indicates the refactoring of the code
+    after the original miscellaneous collection of C++ classes
+    that became the foundation for the Protolib "toolkit".
+    (aka "Protokit").  With 2.0, the code was written to be far
+    more consistent in design and conventions.
+
+    The philosophy of the code is to provide a suite of C++ classes
+    where each can be used fairly independently if desired, but also
+    to provide a framework for the suite of classes to be used for
+    experimental protocol implementations, applications.  For example,
+    individual classes like "ProtoSocket", "ProtoTimer", etc can be
+    used somewhat independently and/or adapted into other codes or
+    be used with the provided ProtoDispatcher/ ProtoApp "framework"
+    to build simple applications.  In some cases (e.g., wxProtoApp),
+    code is provided to allow Protolib components/implementations to
+    be integrated as part other application code.  Similarly, the
+    ProtoSimAgent provides a means to adapt Protolib code into 
+    discrete event network simulation environments with a relatively
+    small amount of care on the programmers' part.