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 href="xref.html">Current status: Cross reference of action points</a>\n
34 <a class="ext" href="http://developer.berlios.de/projects/senf">The BerliOS project page</a>\n
35 <a class="ext" href="http://openfacts.berlios.de/index-en.phtml?title=SENF+Network+Framework">The SENF Wiki at BerliOS</a>
38 /** \page usage Using the SENF framework
40 The SENF Framework is a collection of loosely coupled
41 modules. The libraries are heavily object oriented and template
42 based. For compatibility reasons, the libraries are therefore
43 built together with every project making use of the framework.
45 When starting a new Projekt based on the SENF framework, it is
46 advisable, to make use of the SENFSCons build environment and use
47 SVN to manage the code repository. This is the configuration,
48 described in this documentation.
55 \section Preliminaries
57 Before starting the devlopment, make sure to fulfill the following
60 \li GNU g++, version at least 3.4
61 \li The Boost libraries (http://www.boost.org)
62 \li The SCons build tool (http://www.scons.org)
64 If you want to build the documentation, you additionally need
66 \li Doxygen (http://www.doxygen.org)
67 \li The \c dia diagram editor (http://www.gnome.org/projects/dia/)
68 \li HTML \c tidy (http://tidy.sourceforge.net/)
69 \li The \c xsltproc XSLT processor (http://xmlsoft.org/XSLT/xsltproc2.html)
72 The library is only tested with gcc-3.4 and 4.0 on Linux. On other
73 POSIX platforms with a BSD Socket API, the library should be
74 usable, possibly with some tweaking (except for the Scheduler,
75 which relies on \c epoll)
78 /** \page build Building the framework
80 This procedure will test building the complete framework
81 including the unit tests and the Sniffer test application. This
82 build is \e not needed to use the framework since every project
83 will include the full SENF source code itself (via Subversion).
85 After you have successfully built the library tests, you can
86 continue to setup your own project using SENF.
88 \see \ref components \n
91 \section checkout Getting the code
93 To access the code, check out the code from the BerliOS
94 repository. Change to your development directory and use the
95 following subversion command
97 <pre class="fragment">
98 $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf</pre>
100 This will create a new directory \c senf within the current
101 directory. For further documentation on the use of Subversion, see
102 the \c svn manpage or the subversion homepage at
103 http://subversion.tigris.org. A very good introduction and
104 reference to subversion is available at
105 http://svnbook.red-bean.com.
107 \section compile Building
109 To build the library, execute all unit tests and build the Sniffer
110 test application, use
112 <pre class="fragment">
114 $ scons all_tests</pre>
116 in the \c senf directory. This assumes, that you want to build the
117 library with your default gcc and requires the boost libraries to
118 be available in the system include paths. If this is not the case,
119 you can take a look at <tt>SConfig.template</tt> file. Copy this
120 file to <tt>SConfig</tt> and comment out all the variables you
121 don't want to change (The \e values in the template file are just
125 /** \page components The SENF modules
127 The framework is made up of several modular components. When using
128 the library, it is possible to selectively choose to use only a
129 subset of the implemented modules.
134 \section libSocket libSocket: C++ abstraction of the BSD socket API
136 This library provides a high performance and object oriented
137 abstraction of the standard socket API. It utilizes a flexible and
138 extensible policy based design. The library provides predefined
139 types for the important socket types (UDP and TCP sockets etc)
140 including raw and packet sockets. \n
142 \see <a href="../../Socket/doc/html/index.html">libSocket API
145 \section libPackets libPackets: Network packet manipulation
147 This libarary provides a very flexible infrastructure to
148 parse, create and otherwise manipulate packetized network
149 data. Included is a library of several protocol parsers covering
150 the basic IPv4 and IPv6 network protocols down to the Ethernet
153 \see <a href="../../Packets/doc/html/index.html">libPackets API
156 \section libScheduler libScheduler: Asynchronous event handling
158 The scheduler library provides an object oriented interface to the
159 standard UNIX \c select type event dispatcher. It is based on the
160 high performance \c epoll system call. It provides support for
161 read/write events as well as simple timer based events.
163 \see <a href="../../Scheduler/doc/html/index.html">libScheduler API
166 \section libUtils libUtils: Collection of arbitrary utilities
168 This library is used be most all of the other modules for
169 miscellaneous tools and utilities. We have
171 \li Simple functions to manage daemon processes
172 \li Standard exception classes
173 \li senf::intrusive_refcount to simplify the implementation
174 of classes usable with boost::intrusive_ptr
175 \li boost::bind extensions
176 \li An interface to the \c g++ demangler integrated with type_info
177 \li Typedefs and rudimentary methods to simplify handling
178 high-resolution time values
180 \see <a href="../../Utils/doc/html/index.html">libUtils API
183 \section senfscons SENFSCons, the SENF build environment
185 SENF relies on SCons (http://www.scons.org) to build. To further
186 simplify the common tasks, SENF includes a library of custom
187 routines and builders comprising a very concise build
188 environment. Included are a number of templates to help
189 bootstrapping a new project or component.
191 \see <a href="../../senfscons/doc/html/index.html">SENFSCons
195 /** \page svnsetup Setting up a new project using SENF
197 The preferred way to use SENF in a new project is to rely on
198 Subversion and make use of the SENFSCons build environment. The
199 following sections will describe, how this setup works.
205 \section svnext Setting up the project repository
207 The most seamless integration is possible if you rely on
208 Subversion to manage the new project. Subversion does support
209 'external repositories'. This allows to import code from a foreign
210 repository into the checkout without importing it into your
211 repository. The code will always stay at the remote repository,
212 updates are automatically available.
214 First setup a new empty repository as described for example in the
215 Subversion book at http://svnbook.red-bean.com or as mandated by
216 your site policy. We will call the project 'Foo' and assume, that
217 the project has been checked out into the 'Foo' directory.
219 You now have to decide, which modules you want to use. Every
220 module resides in it's own subdirectory in the SENF
221 repository. Instead of directly checking out the code, we will use
222 \c svn:externals. This will instruct \c svn to auutomatically
223 check out the needed directories from the BerliOS SENF
224 repository. Change to the 'Foo' directory and type
226 <pre class="fragment">
227 $ svn propedit svn:externals .</pre>
229 The default editor (probably VI) will be started with the current
230 value of the svn:externals property (which will probably be
231 empty). Now add all the modules you want plus \c senfscons and
232 possibly \c doclib (if you want to build the documentation). You
233 will almost certainly neeed the \c Utils module, since all other
234 modules depend on it.
236 For example, if you want to use the \c Scheduler and \c Socket
237 module, the file will look like
239 <pre class="fragment">
240 senfscons http://svn.berlios.de/svnroot/repos/senf/trunk/senfscons
241 Utils http://svn.berlios.de/svnroot/repos/senf/trunk/Utils
242 Scheduler http://svn.berlios.de/svnroot/repos/senf/trunk/Scheduler
243 Socket http://svn.berlios.de/svnroot/repos/senf/trunk/Socket</pre>
245 exit the editor and the property will be set. Now run
247 <pre class="fragment">
250 and the code will be checked out into the corresponding
253 \section new_conf Configuring SENFSCons
255 To set up the build environment, copy the
256 <tt>senfscons/SConstruct.template</tt> to <tt>SConstruct</tt> in
257 the project root. The default setup of this file is to build all
258 subdirectories (using the \c SConscript files of the
259 subdirectories). You can add additonal global targets and
260 configuration parameters here.
262 If you want to use a non-default compiler or the boost library is
263 not installed in the system directories, you will have to copy
264 <tt>senfscons/SConfig.template</tt> to <tt>SConfig</tt> in the
265 project root and edit it there. You should \e never add \c SConfig
266 to the repository since it should only contain local settings
267 necessary for building on your local system. You should therefore
268 add \c SConfig to the list of files ignored by Subversion in the
269 project root. In the project root execute
271 <pre class="fragment">
272 $ svn propedit svn:ignore .</pre>
274 and add \c SConfig as a new line to the property.
276 \section new_build Building the project
278 You should now be able to build your project using
280 <pre class="fragment">
283 If you have not changed the \c SConstruct file, this will build
284 all modules you have importet into your project. To build and
285 execute the unit tests, use
287 <pre class="fragment">
288 $ scons all_tests</pre>
290 you can also build only a subdirectory by changing to it and
293 <pre class="fragment">
294 $ scons -u [target]</pre>
296 \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
297 <a class="ext" href="http://www.scons.org/documentation.php">SCons documentation</a> \n
298 <a class="ext" href="http://svnbook.red-bean.com">Subversion online book</a> \n
299 <a class="ext" href="http://subversion.tigris.org">Subversion Homepage</a>
302 /** \page overview Introduction to the framework
304 The SENF framework is relatively complex and makes use of advanced
305 features of the C++ language. To make the most efficient use of
306 the framework, you should have at least a basic understanding of
307 C++ templates and the standard library concepts.
309 The library implementation at places makes heavy use of advanced
310 template techniques and relies on some very advanced template
311 libraries from Boost. The aim was however for the \e external
312 interface of the library to be as simple as possible without
313 sacrificing important functionality or adversely impacting the
316 As already mentioned several times, the library relies on Boost
317 (http://www.boost.org) as a generic library of high quality
318 reusable C++ components. It also makes frequent use of the
319 standard library. It is designed, to integrate well into both
320 libraries and to use the same concepts and ideas.
322 \section startup Getting starting developing with SENF
324 To introduce the framework and it's general structure, a simple
325 example application is provided in the SENF repository in the \c
326 Sniffer module. Peruse this example to get a first look at how to
329 When building a network Application with SENF, you will use
332 \li Use the <a href="../../Socket/doc/html/index.html">Socket
333 library</a> for network communication needs. This library
334 includes support for raw and packet sockets to allow low level
337 href="../../Scheduler/doc/html/index.html">Scheduler
338 library</a> to coordinate the asynchronous event
339 processing. This drastically reduces the number of threads
340 needed in your application and will greatly enhance the overall
342 \li To interpret low level network packets, use the <a
343 href="../../Packets/doc/html/index.html">Packets
344 library</a>. This library will provide efficient and
345 convenient access to all protocol fields. It supports parsing as
346 well as modifying and creating packets. It has default support
347 for the most important internet protocols and is highly
348 extensible with new protocols.
349 \li Go over the <a href="../../Utils/doc/html/index.html">Utils
350 library</a>. It contains small helpers to
351 simplify tasks like daemonization, exception handling,
354 The simplest way to get started is: copy the Sniffer application
355 and start to modify it.
368 // ispell-local-dictionary: "american"