| 1 |
|
| 2 |
/** |
| 3 |
|
| 4 |
@page mainpage_introduction Introduction |
| 5 |
|
| 6 |
@li @ref page_introduction_whatis |
| 7 |
@li @ref page_introduction_key_classes |
| 8 |
@li @ref page_introduction_downloads |
| 9 |
@li @ref page_introduction_acknowledgements |
| 10 |
@li @ref page_introduction_authorization |
| 11 |
|
| 12 |
<hr> |
| 13 |
|
| 14 |
@section page_introduction_whatis What is Protolib? |
| 15 |
|
| 16 |
The Protean Protocol Prototyping Library (ProtoLib) is a cross-platform C/C++ |
| 17 |
library that allows applications to be built while supporting a variety of |
| 18 |
platforms including Linux, Windows, WinCE/PocketPC, MacOS, FreeBSD, Solaris, |
| 19 |
etc as well as the simulation environments of NS2 and Opnet. |
| 20 |
|
| 21 |
Protolib is not so much a library as it is a toolkit. "Protokit" is a term we |
| 22 |
have gravitated towards. In either case, the goal of the Protolib is to provide |
| 23 |
a set of simple, cross-platform C++ classes that allow development of network |
| 24 |
protocols and applications that can run on different platforms and in network |
| 25 |
simulation environments. While Protolib provides an overall framework for |
| 26 |
developing working protocol implementations, applications, and simulation modules, |
| 27 |
the individual classes are designed for use as stand-alone components when possible. |
| 28 |
Although Protolib is principally for research purposes, the code has been |
| 29 |
constructed to provide robust, inefficient performance and adaptability to real |
| 30 |
applications. In some cases, the code consists of data structures, etc useful in |
| 31 |
protocol implementations and, in other cases, provides common, cross-platform |
| 32 |
interfaces to system services and functions (e.g., sockets, timers, routing |
| 33 |
tables, etc). |
| 34 |
|
| 35 |
Currently Protolib supports most Unix platforms (including MacOS X) and WIN32 |
| 36 |
platforms. The most recent version also supports building Protolib-based code |
| 37 |
for the ns-2 and OPNET simulation environments. Some code is also provided to |
| 38 |
allow code based on Protolib to be used in a wxWidgets application. The wxWidgets |
| 39 |
project is a cross-platform graphical user interface (GUI) toolkit for creating |
| 40 |
applications using the C++ programming language. We have used wxWidgets for |
| 41 |
providing graphical user interfaces for some of our prototype network applications. |
| 42 |
A java native interface for ProtoPipe is included as well. |
| 43 |
|
| 44 |
<hr> |
| 45 |
@section page_introduction_key_classes Some of the classes available |
| 46 |
|
| 47 |
This table provides a listing and explanation of many of the classes contained in |
| 48 |
Protolib. Work is in progress to create and embed Doxygen-based documentation |
| 49 |
within the Protolib source code tree. |
| 50 |
|
| 51 |
@li ProtoAddress: Network address container class with support for IPv4, IPv6, |
| 52 |
ETH, and "SIM" address types. Also includes functions for name/address resolution. |
| 53 |
|
| 54 |
@li ProtoSocket: Network socket container class that provides consistent interface |
| 55 |
for use of operating system (or simulation environment) transport sockets. Provides |
| 56 |
support for synchronous notification to ProtoSocket::Listeners. The ProtoSocket |
| 57 |
class may be used stand-alone, or with other classes described below. A ProtoSocket |
| 58 |
may be instantiated as either a UDP or TCP socket. |
| 59 |
|
| 60 |
@li ProtoTimer This is a generic timer class which will notify a |
| 61 |
ProtoTimer::Listener upon timeout. |
| 62 |
|
| 63 |
@li ProtoTimerMgr This class manages ProtoTimer instances when they are |
| 64 |
"activated". The ProtoDispatcher(see below) derives from this to manage |
| 65 |
ProtoTimers for an application. (The ProtoSimAgent base class contains a ProtoTimerMgr |
| 66 |
to similarly manage timers for a simulation instance). |
| 67 |
|
| 68 |
@li ProtoTree Flexible implementation of a Patricia tree data structure. |
| 69 |
Includes a ProtoTree::Item which may be derived from or used as a container for |
| 70 |
whatever data structures and application may require. |
| 71 |
|
| 72 |
@li ProtoRouteTable Class based on the ProtoTree Patricia tree to store routing |
| 73 |
table information. Uses the ProtoAddress class to store network routing addresses. It's a |
| 74 |
pretty dumbed-down routing table at the moment, but may be enhanced in the future. |
| 75 |
|
| 76 |
@li ProtoRouteMgr Base class used to provide a common interface to system (or other |
| 77 |
external) router tables. Implementations for Linux, BSD (incl. MacOS), and Win32/WinCE |
| 78 |
are included. Implementations for other routing/forwarding daemons like Quagga or |
| 79 |
Xorp may be provided in the future. |
| 80 |
|
| 81 |
@li ProtoPkt Base class for a suite of network protocol packet/message building/parsing |
| 82 |
classes that provide methods for setting/getting protocol field values to/from a buffer. |
| 83 |
|
| 84 |
@li ProtoPktIP Classes are provided for building/parsing IPv4 and IPv6 packets to/from |
| 85 |
a buffer space. A ProtoPktUDP class is also provided. |
| 86 |
|
| 87 |
@li ProtoPktETH This class that provides access to and control of ETHernet |
| 88 |
header fields for the associated buffer space. |
| 89 |
|
| 90 |
@li ProtoPktARP Useful for building/parsing ARP packets. |
| 91 |
|
| 92 |
@li ProtoPktRTP Useful for building/parsing Real-Time Protocol (RTP), RFC3550, messages. |
| 93 |
|
| 94 |
@li ProtoGraph Base class for managing graph data structures. |
| 95 |
|
| 96 |
@li ManetMsg Class that implements the General packet format being developed by the |
| 97 |
IETF MANET working group (based on ProtoPkt). |
| 98 |
|
| 99 |
@li ManetGraph Derived from ProtoGraph and uses ProtoAddress structures to provide |
| 100 |
a suitable graph structure for keeping and exploring multi-hop network state. Supports |
| 101 |
a notion of multiple interfaces per node, etc. |
| 102 |
|
| 103 |
@li ProtoBitmask Classes for managing and manipulating bitmasks to maintain binary |
| 104 |
state. A "sliding" bitmask class is provided that uses a circular buffer approach to |
| 105 |
maintain continuing, sequenced state. |
| 106 |
|
| 107 |
@li ProtoXml Classes for parsing and creating XML content. |
| 108 |
|
| 109 |
@li ProtoPipe Socket-like mechanism (with both datagram and stream support) useful |
| 110 |
for interprocess communications (uses Unix domain sockets on Unix, other stuff on |
| 111 |
Win32 & WinCE) |
| 112 |
|
| 113 |
@li ProtoCap Interface class for raw MAC-layer packet capture. Platform implementations |
| 114 |
of this class vary including a "libpcap" based implementation. |
| 115 |
|
| 116 |
@li ProtoVif Base class providing interface support for virtual interfaces. |
| 117 |
|
| 118 |
@li ProtoDetour Inbound/outbound packet _interception_ class. Platform implementations |
| 119 |
vary ... but generally leverages system firewall interfaces. A Win32 version based |
| 120 |
around NDIS intermediate driver is in progress. |
| 121 |
|
| 122 |
@li ProtoChannel Base class for hooking into asynchronous I/O (via Unix file descriptors |
| 123 |
or Win32 HANDLEs). Used as base class for ProtoPipe, ProtoDetour, ProtoCap, etc |
| 124 |
(ProtoSocket is currently an exception here because of distinction of SOCKETs vs. |
| 125 |
HANDLEs on Win32 platforms - This may be revisited in the future). |
| 126 |
|
| 127 |
@li ProtoDispatcher This class provides a core around which Unix and Win32 |
| 128 |
applications using Protolib can be implemented. It's "Run()" method provides a |
| 129 |
"main loop" which uses the "select()" system call on Unix and the similar |
| 130 |
"MsgWaitForMultipleObjectsEx()" system call on Win32. It is planned to eventually |
| 131 |
provide some built-in support for threading in the future (e.g. the |
| 132 |
ProtoDispatcher::Run() method might execute in a thread, dispatching events to a |
| 133 |
parent thread). |
| 134 |
|
| 135 |
@li ProtoApp Provides a base class for implementing Protolib-based command-line |
| 136 |
applications. Note that "ProtoApp" and "ProtoSimAgent" are designed such that subclasses |
| 137 |
can be derived from either to reuse the same code in either a real-world applications or |
| 138 |
as an "agent" (entity) within a network simulation environment (e.g. ns-2, OPNET). Also |
| 139 |
note a built-in "background" command is included for Win32 to launch the app without a |
| 140 |
terminal window. |
| 141 |
|
| 142 |
@li wxProtoApp Base class that can be used to create applications using Protolib |
| 143 |
components and the wxWidgets GUI toolkit. |
| 144 |
|
| 145 |
@li ProtoSimAgent Base class for simulation agent derivations. Currently an ns-2 |
| 146 |
agent base class is derived from this, but it is possible that other simulation |
| 147 |
environments (e.g. OPNET, Qualnet) might be supported in a similar fashion. |
| 148 |
|
| 149 |
@li NsProtoSimAgent Simulation agent base class for creating ns-2 instantiations |
| 150 |
of Protolib-based network protocols and applications. |
| 151 |
|
| 152 |
@li OpnetProtoSimProcess Simulation process base class for creating OPNET |
| 153 |
instantiations of Protolib-based network protocols and applications. |
| 154 |
|
| 155 |
@li ProtoExample Example class which derives either from ProtoApp or NsProtoSimAgent, |
| 156 |
depending upon compile-time macro definitions. It provides equivalent functionality |
| 157 |
in either the simulation environment or as a real-world command-line application. It |
| 158 |
demonstrates the use/operation of ProtoSocket based UDP transmission/reception, a |
| 159 |
ProtoTimer, and an example ProtoSocket-based TCP client-server exchange. (NOTE: |
| 160 |
Protolib TCP operation is not yet supported in the ns-2 simulation environment. This |
| 161 |
will completed in the near future. The plan is to extend ns-2 TCP agents to support |
| 162 |
actual transfer of user data to support this.) |
| 163 |
|
| 164 |
<hr> |
| 165 |
@section page_introduction_downloads Downloads |
| 166 |
|
| 167 |
Protolib source code is available at: http://downloads.pf.itd.nrl.navy.mil/protolib/. |
| 168 |
However, it is important to note that the tarballs (other than the "nightly build") are |
| 169 |
not updated very often and the appropriate version of the Protolib source tree is |
| 170 |
generally packaged as part of source code distributions for stable releases of |
| 171 |
other NRL/Protean products. |
| 172 |
|
| 173 |
If you are interested in more information about ProtoLib, please contact |
| 174 |
[email protected]. There is also a ProtoLib Users mailing list. This mailing |
| 175 |
list is monitored by the ProtoLib developer(s). |
| 176 |
|
| 177 |
<hr> |
| 178 |
@section page_introduction_acknowledgements Acknowledgements |
| 179 |
|
| 180 |
Protolib was developed by the Networks and Communications Systems Branch |
| 181 |
of the Naval Research Library by: |
| 182 |
|
| 183 |
@li Brian Adamson |
| 184 |
@li Joe Macker |
| 185 |
|
| 186 |
<hr> |
| 187 |
@section page_introduction_authorization Authorization to Use and Distribute |
| 188 |
|
| 189 |
<em> |
| 190 |
* |
| 191 |
* AUTHORIZATION TO USE AND DISTRIBUTE |
| 192 |
* |
| 193 |
* Redistribution and use in source and binary forms, with or without |
| 194 |
* modification, are permitted provided that: |
| 195 |
* |
| 196 |
* (1) source code distributions retain this paragraph in its entirety, |
| 197 |
* |
| 198 |
* (2) distributions including binary code include this paragraph in |
| 199 |
* its entirety in the documentation or other materials provided |
| 200 |
* with the distribution, and |
| 201 |
* |
| 202 |
* (3) all advertising materials mentioning features or use of this |
| 203 |
* software display the following acknowledgment: |
| 204 |
* |
| 205 |
* "This product includes software written and developed |
| 206 |
* by Brian Adamson and Joe Macker of the Naval Research |
| 207 |
* Laboratory (NRL)." |
| 208 |
* |
| 209 |
* The name of NRL, the name(s) of NRL employee(s), or any entity |
| 210 |
* of the United States Government may not be used to endorse or |
| 211 |
* promote products derived from this software, nor does the |
| 212 |
* inclusion of the NRL written and developed software directly or |
| 213 |
* indirectly suggest NRL or United States Government endorsement |
| 214 |
* of this product. |
| 215 |
* |
| 216 |
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR |
| 217 |
* IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED |
| 218 |
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 219 |
|
| 220 |
|
| 221 |
</em> |
| 222 |
|
| 223 |
*/ |
| 224 |
|