Debian Codegraph @

protolib/doc/doxygen/mainpages/introduction.h

raw
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