1 /** \mainpage SENF: The Simple and Extensible Network Framework
3 The SENF Simple and Extensible Network Framework aims to be a
4 complete set of libraries to facilitate the development of network
5 applications focusing on network protocols on the layers below the
6 application layer. However, the framework includes many general
7 purpose utilities and will be expedient to use well beyond its
12 The main goals of this library are (in no particular order):
14 \li modular framework design
15 \li utilizing the power of modern C++
16 \li very low overhead for frequently called members
20 \section start Getting started
22 To get started using this library, begin by checking out the code
24 href="http://developer.berlios.de/svn/?group_id=7489">BerliOS SVN
25 repository</a>. You may find help on using the library at '\ref
26 usage'. If you are interested in SENF, feel free to subscribe
28 href="http://developer.berlios.de/mail/?group_id=7489">SENF
33 <a class="ext" href="http://developer.berlios.de/projects/senf">The BerliOS project page</a>\n
34 <a class="ext" href="http://openfacts.berlios.de/index-en.phtml?title=SENF+Network+Framework">The SENF Wiki at BerliOS</a>
37 /** \page usage Using the SENF framework
39 The SENF Framework is a collection of lossly coupled
40 modules. The libraries are heavily object oriented and template
41 based. For compatibility reasons, the libraries are therefore
42 built together with every project making use of the framework.
44 When starting a new Projekt based on the SENF framework, it is
45 advisable, to make use of the SENFSCons build environment and use
46 SVN to manage the code repository. This is the configuration,
47 described in this documentation.
54 \section Preliminaries
56 Before starting the devlopment, make sure to fulfill the following
59 \li GNU g++, version at least 3.4
60 \li The Boost libraries (http://www.boost.org)
61 \li The SCons build tool (http://www.scons.org)
63 If you want to build the documentation, you additionally need
65 \li Doxygen (http://www.doxygen.org)
66 \li The \c dia diagram editor (http://www.gnome.org/projects/dia/)
69 The library is only tested with gcc-3.4 and 4.0 on Linux. On other
70 POSIX platforms with a BSD Socket API, the library should be
71 usable, possibly with some tweaking (except for the Scheduler,
72 which relies on \c epoll)
75 /** \page build Building the framework
77 This procedure will test building the complete framework
78 including the unit tests and the Sniffer test application. This
79 build is \e not needed to use the framework since every project
80 will include the full SENF source code itself (via Subversion).
82 After you have successfully built the library tests, you can
83 continue to setup your own project using SENF.
85 \see \ref components \n
88 \section checkout Getting the code
90 To access the code, check out the code from the BerliOS
91 repository. Change to your development directory and use the
92 following subversion command
94 <pre class="fragment">
95 $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf</pre>
97 This will create a new directory \c senf within the current
98 directory. For further documentation on the use of Subversion, see
99 the \c svn manpage or the subversion homepage at
100 http://subversion.tigris.org. A very good introduction and
101 reference to subversion is available at
102 http://svnbook.red-bean.com.
104 \section compile Building
106 To build the library, execute all unit tests and build the Sniffer
107 test application, use
109 <pre class="fragment">
111 $ scons all_tests</pre>
113 in the \c senf directory. This assumes, that you want to build the
114 library with your default gcc and requires the boost libraries to
115 be available in the system include paths. If this is not the case,
116 you can take a look at <tt>SConfig.template</tt> file. Copy this
117 file to <tt>SConfig</tt> and comment out all the variables you
118 don't want to change (The \e values in the template file are just
122 /** \page components The SENF modules
124 The framework is made up of several modular components. When using
125 the library, it is possible to selectively choose to use only a
126 subset of the implemented modules.
131 \section libSocket libSocket: C++ abstraction of the BSD socket API
133 This library provides a high performance and object oriented
134 abstraction of the standard socket API. It utilizes a flexible and
135 extensible policy based design. The library provides predefined
136 types for the important socket types (UDP and TCP sockets etc)
137 including raw and packet sockets. \n
139 \see <a href="../../Socket/doc/html/index.html">libSocket API
142 \section libPackets libPackets: Network packet manipulation
144 This libarary provides a very flexible infrastructure to
145 parse, create and otherwise manipulate packetized network
146 data. Included is a library of several protocol parsers covering
147 the basic IPv4 and IPv6 network protocols down to the Ethernet
150 \see <a href="../../Packets/doc/html/index.html">libPackets API
153 \section libScheduler libScheduler: Asynchronous event handling
155 The scheduler library provides an object oriented interface to the
156 standard UNIX \c select type event dispatcher. It is based on the
157 high performance \c epoll system call. It provides support for
158 read/write events as well as simple timer based events.
160 \see <a href="../../Scheduler/doc/html/index.html">libScheduler API
163 \section libUtils libUtils: Collection of arbitrary utilities
165 This library is used be most all of the other modules for
166 miscellaneous tools and utilities. We have
168 \li Simple functions to manage daemon processes
169 \li Standard exception classes
170 \li senf::intrusive_refcount to simplify the implementation
171 of classes usable with boost::intrusive_ptr
172 \li boost::bind extensions
173 \li An interface to the \c g++ demangler integrated with type_info
174 \li Typedefs and rudimentary methods to simplify handling
175 high-resolution time values
177 \see <a href="../../Utils/doc/html/index.html">libUtils API
180 \section senfscons SENFSCons, the SENF build environment
182 SENF relies on SCons (http://www.scons.org) to build. To further
183 simplify the common tasks, SENF includes a library of custom
184 routines and builders comprising a very concise build
185 environment. Included are a number of templates to help
186 bootstrapping a new project or component.
188 \see <a href="../../senfscons/doc/html/index.html">SENFSCons
192 /** \page svnsetup Setting up a new project using SENF
194 The preferred way to use SENF in a new project is to rely on
195 Subversion and make use of the SENFSCons build environment. The
196 following sections will describe, how this setup works.
202 \section svnext Setting up the project repository
204 The most seamless integration is possible if you rely on
205 Subversion to manage the new project. Subversion does support
206 'external repositories'. This allows to import code from a foreign
207 repository into the checkout without importing it into your
208 repository. The code will always stay at the remote repository,
209 updates are automatically available.
211 First setup a new empty repository as described for example in the
212 Subversion book at http://svnbook.red-bean.com or as mandated by
213 your site policy. We will call the project 'Foo' and assume, that
214 the project has been checked out into the 'Foo' directory.
216 You now have to decide, which modules you want to use. Every
217 module resides in it's own subdirectory in the SENF
218 repository. Instead of directly checking out the code, we will use
219 \c svn:externals. This will instruct \c svn to auutomatically
220 check out the needed directories from the BerliOS SENF
221 repository. Change to the 'Foo' directory and type
223 <pre class="fragment">
224 $ svn propedit svn:externals .</pre>
226 The default editor (probably VI) will be started with the current
227 value of the svn:externals property (which will probably be
228 empty). Now add all the modules you want plus \c senfscons and
229 possibly \c doclib (if you want to build the documentation). You
230 will almost certainly neeed the \c Utils module, since all other
231 modules depend on it.
233 For example, if you want to use the \c Scheduler and \c Socket
234 module, the file will look like
236 <pre class="fragment">
237 senfscons http://svn.berlios.de/svnroot/repos/senf/trunk/senfscons
238 Utils http://svn.berlios.de/svnroot/repos/senf/trunk/Utils
239 Scheduler http://svn.berlios.de/svnroot/repos/senf/trunk/Scheduler
240 Socket http://svn.berlios.de/svnroot/repos/senf/trunk/Socket</pre>
242 exit the editor and the property will be set. Now run
244 <pre class="fragment">
247 and the code will be checked out into the corresponding
250 \section new_conf Configuring SENFSCons
252 To set up the build environment, copy the
253 <tt>senfscons/SConstruct.template</tt> to <tt>Satscons</tt> in the
254 project root. The default setup of this file is to build all
255 subdirectories (using the \c SConscript files of the
256 subdirectories). You can add additonal global targets and
257 configuration parameters here.
259 If you want to use a non-default compiler or the boost library is
260 not installed in the system directories, you will have to copy
261 <tt>senfscons/SConfig.template</tt> to <tt>SConfig</tt> in the
262 project root and edit it there. You should \e never add \c SConfig
263 to the repository since it should only contain local settings
264 necessary for building on your local system. You should therefore
265 add \c SConfig to the list of files ignored by Subversion in the
266 project root. In the project root execute
268 <pre class="fragment">
269 $ svn propedit svn:ignore .</pre>
271 and add \c SConfig as a new line to the property.
273 \section new_build Building the project
275 You should now be able to build your project using
277 <pre class="fragment">
280 If you have not changed the \c SConstruct file, this will build
281 all modules you have importet into your project. To build and
282 execute the unit tests, use
284 <pre class="fragment">
285 $ scons all_tests</pre>
287 you can also build only a subdirectory by changing to it and
290 <pre class="fragment">
291 $ scons -u [target]</pre>
293 \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
294 <a class="ext" href="http://www.scons.org/documentation.php">SCons documentation</a> \n
295 <a class="ext" href="http://svnbook.red-bean.com">Subversion online book</a> \n
296 <a class="ext" href="http://subversion.tigris.org">Subversion Homepage</a>
299 /** \page overview Introduction to the framework
301 The SENF framework is relatively complex and makes use of advanced
302 features of the C++ language. To make the most efficient use of
303 the framework, you should have at least a basic understanding of
304 C++ templates and the standard library concepts.
306 The library implementation at places makes heavy use of advanced
307 template techniques and relies on some very advanced template
308 libraries from Boost. The aim was however for the \e external
309 interface of the library to be as simple as possible without
310 sacrificing important functionality or adversely impacting the
313 As already mentioned several times, the library relies on Boost
314 (http://www.boost.org) as a generic library of high quality
315 reusable C++ components. It also makes frequent use of the
316 standard library. It is designed, to integrate well into both
317 libraries and to use the same concepts and ideas.
319 \section startup Getting starting developing with SENF
321 To introduce the framework and it's general structure, a simple
322 example application is provided in the SENF repository in the \c
323 Sniffer module. Peruse this example to get a first look at how to
326 When building a network Application with SENF, you will use
329 \li Use the <a href="../../Socket/doc/html/index.html">Socket
330 library</a> for network communication needs. This library
331 includes support for raw and packet sockets to allow low level
334 href="../../Scheduler/doc/html/index.html">Scheduler
335 library</a> to coordinate the asynchronous event
336 processing. This drastically reduces the number of threads
337 needed in your application and will greatly enhance the overall
339 \li To interpret low level network packets, use the <a
340 href="../../Packets/doc/html/index.html">Packets
341 library</a>. This library will provide efficient and
342 convenient access to all protocol fields. It supports parsing as
343 well as modifying and creating packets. It has default support
344 for the most important TCP protocols and is highly extensible
346 \li Go over the <a href="../../Utils/doc/html/index.html">Utils
347 library</a>. It contains small helpers to
348 simplify tasks like daemonization, exception handling,
351 The simplest way to get started is: copy the Sniffer application
352 and start to modify it.
365 // ispell-local-dictionary: "american"