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 lossly 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/)
70 The library is only tested with gcc-3.4 and 4.0 on Linux. On other
71 POSIX platforms with a BSD Socket API, the library should be
72 usable, possibly with some tweaking (except for the Scheduler,
73 which relies on \c epoll)
76 /** \page build Building the framework
78 This procedure will test building the complete framework
79 including the unit tests and the Sniffer test application. This
80 build is \e not needed to use the framework since every project
81 will include the full SENF source code itself (via Subversion).
83 After you have successfully built the library tests, you can
84 continue to setup your own project using SENF.
86 \see \ref components \n
89 \section checkout Getting the code
91 To access the code, check out the code from the BerliOS
92 repository. Change to your development directory and use the
93 following subversion command
95 <pre class="fragment">
96 $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf</pre>
98 This will create a new directory \c senf within the current
99 directory. For further documentation on the use of Subversion, see
100 the \c svn manpage or the subversion homepage at
101 http://subversion.tigris.org. A very good introduction and
102 reference to subversion is available at
103 http://svnbook.red-bean.com.
105 \section compile Building
107 To build the library, execute all unit tests and build the Sniffer
108 test application, use
110 <pre class="fragment">
112 $ scons all_tests</pre>
114 in the \c senf directory. This assumes, that you want to build the
115 library with your default gcc and requires the boost libraries to
116 be available in the system include paths. If this is not the case,
117 you can take a look at <tt>SConfig.template</tt> file. Copy this
118 file to <tt>SConfig</tt> and comment out all the variables you
119 don't want to change (The \e values in the template file are just
123 /** \page components The SENF modules
125 The framework is made up of several modular components. When using
126 the library, it is possible to selectively choose to use only a
127 subset of the implemented modules.
132 \section libSocket libSocket: C++ abstraction of the BSD socket API
134 This library provides a high performance and object oriented
135 abstraction of the standard socket API. It utilizes a flexible and
136 extensible policy based design. The library provides predefined
137 types for the important socket types (UDP and TCP sockets etc)
138 including raw and packet sockets. \n
140 \see <a href="../../Socket/doc/html/index.html">libSocket API
143 \section libPackets libPackets: Network packet manipulation
145 This libarary provides a very flexible infrastructure to
146 parse, create and otherwise manipulate packetized network
147 data. Included is a library of several protocol parsers covering
148 the basic IPv4 and IPv6 network protocols down to the Ethernet
151 \see <a href="../../Packets/doc/html/index.html">libPackets API
154 \section libScheduler libScheduler: Asynchronous event handling
156 The scheduler library provides an object oriented interface to the
157 standard UNIX \c select type event dispatcher. It is based on the
158 high performance \c epoll system call. It provides support for
159 read/write events as well as simple timer based events.
161 \see <a href="../../Scheduler/doc/html/index.html">libScheduler API
164 \section libUtils libUtils: Collection of arbitrary utilities
166 This library is used be most all of the other modules for
167 miscellaneous tools and utilities. We have
169 \li Simple functions to manage daemon processes
170 \li Standard exception classes
171 \li senf::intrusive_refcount to simplify the implementation
172 of classes usable with boost::intrusive_ptr
173 \li boost::bind extensions
174 \li An interface to the \c g++ demangler integrated with type_info
175 \li Typedefs and rudimentary methods to simplify handling
176 high-resolution time values
178 \see <a href="../../Utils/doc/html/index.html">libUtils API
181 \section senfscons SENFSCons, the SENF build environment
183 SENF relies on SCons (http://www.scons.org) to build. To further
184 simplify the common tasks, SENF includes a library of custom
185 routines and builders comprising a very concise build
186 environment. Included are a number of templates to help
187 bootstrapping a new project or component.
189 \see <a href="../../senfscons/doc/html/index.html">SENFSCons
193 /** \page svnsetup Setting up a new project using SENF
195 The preferred way to use SENF in a new project is to rely on
196 Subversion and make use of the SENFSCons build environment. The
197 following sections will describe, how this setup works.
203 \section svnext Setting up the project repository
205 The most seamless integration is possible if you rely on
206 Subversion to manage the new project. Subversion does support
207 'external repositories'. This allows to import code from a foreign
208 repository into the checkout without importing it into your
209 repository. The code will always stay at the remote repository,
210 updates are automatically available.
212 First setup a new empty repository as described for example in the
213 Subversion book at http://svnbook.red-bean.com or as mandated by
214 your site policy. We will call the project 'Foo' and assume, that
215 the project has been checked out into the 'Foo' directory.
217 You now have to decide, which modules you want to use. Every
218 module resides in it's own subdirectory in the SENF
219 repository. Instead of directly checking out the code, we will use
220 \c svn:externals. This will instruct \c svn to auutomatically
221 check out the needed directories from the BerliOS SENF
222 repository. Change to the 'Foo' directory and type
224 <pre class="fragment">
225 $ svn propedit svn:externals .</pre>
227 The default editor (probably VI) will be started with the current
228 value of the svn:externals property (which will probably be
229 empty). Now add all the modules you want plus \c senfscons and
230 possibly \c doclib (if you want to build the documentation). You
231 will almost certainly neeed the \c Utils module, since all other
232 modules depend on it.
234 For example, if you want to use the \c Scheduler and \c Socket
235 module, the file will look like
237 <pre class="fragment">
238 senfscons http://svn.berlios.de/svnroot/repos/senf/trunk/senfscons
239 Utils http://svn.berlios.de/svnroot/repos/senf/trunk/Utils
240 Scheduler http://svn.berlios.de/svnroot/repos/senf/trunk/Scheduler
241 Socket http://svn.berlios.de/svnroot/repos/senf/trunk/Socket</pre>
243 exit the editor and the property will be set. Now run
245 <pre class="fragment">
248 and the code will be checked out into the corresponding
251 \section new_conf Configuring SENFSCons
253 To set up the build environment, copy the
254 <tt>senfscons/SConstruct.template</tt> to <tt>Satscons</tt> in the
255 project root. The default setup of this file is to build all
256 subdirectories (using the \c SConscript files of the
257 subdirectories). You can add additonal global targets and
258 configuration parameters here.
260 If you want to use a non-default compiler or the boost library is
261 not installed in the system directories, you will have to copy
262 <tt>senfscons/SConfig.template</tt> to <tt>SConfig</tt> in the
263 project root and edit it there. You should \e never add \c SConfig
264 to the repository since it should only contain local settings
265 necessary for building on your local system. You should therefore
266 add \c SConfig to the list of files ignored by Subversion in the
267 project root. In the project root execute
269 <pre class="fragment">
270 $ svn propedit svn:ignore .</pre>
272 and add \c SConfig as a new line to the property.
274 \section new_build Building the project
276 You should now be able to build your project using
278 <pre class="fragment">
281 If you have not changed the \c SConstruct file, this will build
282 all modules you have importet into your project. To build and
283 execute the unit tests, use
285 <pre class="fragment">
286 $ scons all_tests</pre>
288 you can also build only a subdirectory by changing to it and
291 <pre class="fragment">
292 $ scons -u [target]</pre>
294 \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
295 <a class="ext" href="http://www.scons.org/documentation.php">SCons documentation</a> \n
296 <a class="ext" href="http://svnbook.red-bean.com">Subversion online book</a> \n
297 <a class="ext" href="http://subversion.tigris.org">Subversion Homepage</a>
300 /** \page overview Introduction to the framework
302 The SENF framework is relatively complex and makes use of advanced
303 features of the C++ language. To make the most efficient use of
304 the framework, you should have at least a basic understanding of
305 C++ templates and the standard library concepts.
307 The library implementation at places makes heavy use of advanced
308 template techniques and relies on some very advanced template
309 libraries from Boost. The aim was however for the \e external
310 interface of the library to be as simple as possible without
311 sacrificing important functionality or adversely impacting the
314 As already mentioned several times, the library relies on Boost
315 (http://www.boost.org) as a generic library of high quality
316 reusable C++ components. It also makes frequent use of the
317 standard library. It is designed, to integrate well into both
318 libraries and to use the same concepts and ideas.
320 \section startup Getting starting developing with SENF
322 To introduce the framework and it's general structure, a simple
323 example application is provided in the SENF repository in the \c
324 Sniffer module. Peruse this example to get a first look at how to
327 When building a network Application with SENF, you will use
330 \li Use the <a href="../../Socket/doc/html/index.html">Socket
331 library</a> for network communication needs. This library
332 includes support for raw and packet sockets to allow low level
335 href="../../Scheduler/doc/html/index.html">Scheduler
336 library</a> to coordinate the asynchronous event
337 processing. This drastically reduces the number of threads
338 needed in your application and will greatly enhance the overall
340 \li To interpret low level network packets, use the <a
341 href="../../Packets/doc/html/index.html">Packets
342 library</a>. This library will provide efficient and
343 convenient access to all protocol fields. It supports parsing as
344 well as modifying and creating packets. It has default support
345 for the most important TCP protocols and is highly extensible
347 \li Go over the <a href="../../Utils/doc/html/index.html">Utils
348 library</a>. It contains small helpers to
349 simplify tasks like daemonization, exception handling,
352 The simplest way to get started is: copy the Sniffer application
353 and start to modify it.
366 // ispell-local-dictionary: "american"