4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
8 // This program is free software; you can redistribute it and/or modify
9 // it under the terms of the GNU General Public License as published by
10 // the Free Software Foundation; either version 2 of the License, or
11 // (at your option) any later version.
13 // This program is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License
19 // along with this program; if not, write to the
20 // Free Software Foundation, Inc.,
21 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
23 /** \mainpage SENF: The Simple and Extensible Network Framework
25 The SENF Simple and Extensible Network Framework aims to be a complete set of libraries to
26 facilitate the development of network applications focusing on network protocols on the layers
27 below the application layer. However, the framework includes many general purpose utilities and
28 will be expedient to use well beyond its primary objective.
32 The main goals of this library are (in no particular order):
34 \li modular framework design
35 \li utilizing the power of modern C++
36 \li very low overhead for frequently called members
40 \section start Getting started
42 To get started using this library, begin by checking out the code from the <a
43 href="http://developer.berlios.de/svn/?group_id=7489">BerliOS SVN repository</a>. You may find
44 help on using the library at '\ref senf_usage'. If you are interested in SENF, feel free to subscribe
45 to the <a href="http://developer.berlios.de/mail/?group_id=7489">SENF mailing lists</a>. If you
46 want to contribute, read the docs and \e please adhere to the \ref senf_conventions.
48 \see \ref senf_usage\n
49 <a href="../../Examples/doc/html/index.html">Examples</a>
52 /** \page senf_usage Using the SENF framework
54 The SENF Framework is a collection of loosely coupled modules. The libraries are heavily object
55 oriented and template based. For compatibility reasons, the libraries are therefore built
56 together with every project making use of the framework.
58 When starting a new project based on the SENF framework, it is advisable, to make use of the
59 SENFSCons build environment and use SVN to manage the code repository. This is the
60 configuration, described in this documentation.
62 \see \ref senf_build \n
64 \ref senf_components \n
67 \section senf_preliminaries Preliminaries
69 Before starting the development, make sure to fulfill the following requirements:
71 \li GNU g++, version at least 3.4
72 \li The Boost libraries (http://www.boost.org)
73 \li The SCons build tool (http://www.scons.org)
75 If you want to build the documentation, you additionally need
77 \li Doxygen (http://www.doxygen.org)
78 \li The \c dia diagram editor (http://www.gnome.org/projects/dia/)
79 \li HTML \c tidy (http://tidy.sourceforge.net/)
80 \li The \c xsltproc XSLT processor (http://xmlsoft.org/XSLT/xsltproc2.html)
81 \li The \c graphviz library (http://www.graphviz.org)
84 The library is only tested with gcc-3.4 and 4.0 on Linux. On other POSIX platforms with a BSD
85 Socket API, the library should be usable, possibly with some tweaking (except for the Scheduler,
86 which relies on \c epoll)
89 /** \page senf_build Building the SENF framework
91 This procedure will test building the complete framework including the unit tests and the
92 Sniffer test application. This build is \e not needed to use the framework since every project
93 will include the full SENF source code itself (via Subversion).
95 After you have successfully built the library tests, you can continue to setup your own project
98 \see \ref senf_setup \n
99 \ref senf_components \n
102 \section senf_checkout Getting the code
104 To access the code, check out the code from the BerliOS repository. Change to your development
105 directory and use the following subversion command
108 $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf
111 This will create a new directory \c senf within the current directory. For further documentation
112 on the use of Subversion, see the \c svn man-page or the subversion homepage at
113 http://subversion.tigris.org. A very good introduction and reference to subversion is available
114 at http://svnbook.red-bean.com.
116 \section senf_compile Building
118 To build the library, execute all unit tests and build the Sniffer test application, use
125 in the \c senf directory. This assumes, that you want to build the library with your default gcc
126 and requires the boost libraries to be available in the system include paths. If this is not the
127 case, you can take a look at <tt>SConfig.template</tt> file. Copy this file to <tt>SConfig</tt>
128 and comment out all the variables you don't want to change (The \e values in the template file
129 are just arbitrary examples).
132 /** \page senf_setup Setting up a new project using SENF
134 The most simple way to use SENF for now is to checkout the svn repository and build SENF
135 yourselves. After you have built SENF, reference your SENF build directory from your build
136 environment. The most flexible way to do this, is to use a symbolic link to your SENF build.
138 Here an example \c SConstruct file for a project using SENF. This script expects SENF to be
139 found in the <tt>%senf</tt> sub-directory of the directory, where the \c SConstruct file is
140 found. This may either be a SENF checkout (if managing your project via subversion, you can use
141 <tt>svn:externals</tt> for this) or a symbolic link to your SENF checkout.
148 LIBS = [ 'senf', 'iberty', 'boost_regex', 'boost_iostreams' ],
149 CXXFLAGS = [ '-Wall', '-Woverloaded-virtual', '-Wno-long-long' ],
153 # If we have a symbolic link 'senf' pointing to our own senf build, use it (and assume
154 # it's in debug mode)
155 if os.path.exists('senf'):
156 print "\nUsing SENF in 'senf'\n"
159 CPPDEFINES = [ 'SENF_DEBUG' ],
160 LIBPATH = [ 'senf' ],
161 CPPPATH = [ 'senf/include' ],
162 CXXFLAGS = [ '-O0', '-g', '-fno-inline' ],
163 LINKFLAGS = [ '-g', '-rdynamic' ],
166 env.Execute([ 'scons -C senf libsenf.a' ])
168 print "\nUsing system installed SENF\n"
170 # replace 'mytarget' with the name of your target executable
173 source = glob.glob('*.cc'),
177 This script automatically set's up the build correctly when using a self-compiled SENF in debug
178 mode (which is the default mode):
179 \li It links in all the required libraries in the correct order: First \c libsenf, then the
180 other needed libraries \c liberty, \c libboost_regex and \c libboost_iostreams.
181 \li It defines the <tt>SENF_DEBUG</tt> preprocessor symbol correctly
182 \li It correctly sets the include and library path
183 \li It adds sensible debug flags
184 \li It adds <tt>-rdynamic</tt> to the link command. This is needed to get a nice backtrace from
186 \li It automatically rebuilds SENF if needed
188 \see \ref senf_components \n
192 /** \page senf_components The SENF modules
194 The framework is made up of several modular components. When using the library, it is possible
195 to selectively choose to use only a subset of the implemented modules.
197 \see \ref senf_overview
199 \section libPPI libPPI: Packet Processing Infrastructure
201 The Packet Processing Infrastructure implements a modular framework for implementing packet
202 oriented network applications. The library provides a larget set of pre-defined modules as well
203 as the necessary helpers to implement application specific processing modules.
205 \see <a href="../../PPI/doc/html/index.html">libPPI API reference</a>
207 \section libSocket libSocket: C++ abstraction of the BSD socket API
209 This library provides a high performance and object oriented abstraction of the standard socket
210 API. It utilizes a flexible and extensible policy based design. The library provides predefined
211 types for the important socket types (UDP and TCP sockets etc) including raw and packet sockets.
213 \see <a href="../../Socket/doc/html/index.html">libSocket API reference</a>
215 \section libPackets libPackets: Network packet manipulation
217 This library provides a very flexible infrastructure to parse, create and otherwise manipulate
218 packetized network data. Included is a library of several protocol parsers covering the basic
219 IPv4 and IPv6 network protocols down to the Ethernet layer.
221 \see <a href="../../Packets/doc/html/index.html">libPackets API reference</a>
223 \section libScheduler libScheduler: Asynchronous event handling
225 The scheduler library provides an object oriented interface to the standard UNIX \c select type
226 event dispatcher. It is based on the high performance \c epoll system call. It provides support
227 for read/write events as well as simple timer based events.
229 \see <a href="../../Scheduler/doc/html/index.html">libScheduler API reference</a>
231 \section libUtils libUtils: Collection of arbitrary utilities
233 This library is used be most all of the other modules for miscellaneous tools and utilities. We
236 \li Simple functions to manage daemon processes
237 \li Standard exception classes
238 \li senf::intrusive_refcount to simplify the implementation of classes usable with
240 \li boost::bind extensions
241 \li An interface to the \c g++ demangler integrated with type_info
242 \li Typedefs and rudimentary methods to simplify handling high-resolution time values
244 \see <a href="../../Utils/doc/html/index.html">libUtils API reference</a>
246 \section senfscons SENFSCons, the SENF build environment
248 SENF relies on SCons (http://www.scons.org) to build. To further simplify the common tasks, SENF
249 includes a library of custom routines and builders comprising a very concise build
250 environment. Included are a number of templates to help bootstrapping a new project or
253 \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a>
256 /** \page senf_overview Introduction to the framework
258 The SENF framework is relatively complex and makes use of advanced features of the C++
259 language. To make the most efficient use of the framework, you should have at least a basic
260 understanding of C++ templates and the standard library concepts.
262 The library implementation at places makes heavy use of advanced template techniques and relies
263 on some very advanced template libraries from Boost. The aim was however for the \e external
264 interface of the library to be as simple as possible without sacrificing important functionality
265 or adversely impacting the runtime performance.
267 As already mentioned several times, the library relies on Boost (http://www.boost.org) as a
268 generic library of high quality reusable C++ components. It also makes frequent use of the
269 standard library. It is designed, to integrate well into both libraries and to use the same
272 \section senf_startup Getting starting developing with SENF
274 To introduce the framework and it's general structure, a simple example application is provided
275 in the SENF repository in the \c Sniffer module. Peruse this example to get a first look at how
278 When building a network Application with SENF, you will use several modules:
280 \li Use the <a href="../../Socket/doc/html/index.html">Socket library</a> for network
281 communication needs. This library includes support for raw and packet sockets to allow low
282 level network access.
283 \li Use the <a href="../../Scheduler/doc/html/index.html">Scheduler library</a> to coordinate
284 the asynchronous event processing. This drastically reduces the number of threads needed in
285 your application and will greatly enhance the overall responsiveness.
286 \li To interpret low level network packets, use the <a
287 href="../../Packets/doc/html/index.html">Packets library</a>. This library will provide
288 efficient and convenient access to all protocol fields. It supports parsing as well as
289 modifying and creating packets. It has default support for the most important internet
290 protocols and is highly extensible with new protocols.
291 \li Go over the <a href="../../Utils/doc/html/index.html">Utils library</a>. It contains small
292 helpers to simplify tasks like daemonization, exception handling, debugging and so on.
294 The simplest way to get started is: copy the Sniffer application and start to modify it.
296 \see <a href="../../Examples/doc/html/index.html">Examples</a> \n
297 \ref senf_components \n
300 \section senf_conventions Coding Conventions
302 Here we have laid down the coding conventions used throughout the SENF framework. Please ad here
303 to these conventions when changing or adding code. If you use emacs, you can use the C++ IDE for
304 emacs from http://g0dil.de which greatly simplifies following these conventions.
306 \subsection senf_conventions_file_naming File Naming
308 Files should be named according to the main class they define. A single header file should
309 define only one main class. Exceptions to this rule are OK.
312 This simplifies finding the implementation/header for a given class and also reduces the
313 size of each single file.
315 The implementation is divided into a number of different files:
317 <table class="glossary"> <tr><td>\c .h</td><td>C public header</td></tr>
319 <tr><td>\c .hh</td><td>C++ public header</td></tr>
321 <tr><td>\c .ih</td><td>C++ internal header used only by the implementation. This header will
322 probably be included indirectly by the public header but is not meant to be perused by the
323 library user</td></tr>
325 <tr><td>\c .c</td><td>C implementation</td></tr>
327 <tr><td>\c .cc</td><td>C++ implementation of non-inline non-template functions and
330 <tr><td>\c .ct</td><td>C++ implementation of non-inline template functions and members</td></tr>
332 <tr><td>\c .cci</td><td>C++ implementation of inline non-template functions and
335 <tr><td>\c .cti</td><td>C++ implementation of inline template functions and members</td></tr>
337 <tr><td>\c .mpp</td><td>Special include file used for external iteration by the
338 Boost.Preprocessor library</td></tr> </table>
341 There are two part's to this: First, separating the implementation of inlines and templates
342 out of the header file makes the header file much easier to read. This is important, since
343 the header file will be used as a reference by the developers.
345 Separating inline from non-inline members is used together with the \c prefix_ convention
346 below to ensure the correct placement of inline vs non-inline members in the source
347 code. The C++ language requires, that inline members must be included into \e every
348 compilation unit, non-inline members however must be included \e only in one compilation
349 unit. Placing the inline members into a separate file allows to automate this: Simply moving
350 an implementation from one of the inline files into one of the non-inline files will change
351 the type of implementation accordingly.
353 \subsection senf_conventions_type_naming Type Naming
355 SENF prefers the use of the CapitalziedLettersToSeparateWords convention for class names. In
356 this case, class names must start with a capital letter. There are some exceptions to this rule:
357 Types which define new basic data types to be used like other built-in types may be named using
358 lowercase letters plus underscores. Also, if a type or class is directly related to some other
359 library (STL or Boost) which uses the underscore convention, it might be more sensible to follow
360 this convention. This is open to debate.
363 Naming types with capital letters nicely gives a visual clue, that a symbol is a type
364 name. This can also be used by the editor to highlight type names correctly. Additionally,
365 this convention is compact and does not add additional or repeated overhead.
367 \subsection senf_conventions_impl Implementation
369 Only in very few places, SENF allows the use of inline implementations (not to be confused with
370 inline functions). An \e implementation is inline, if it is written directly into the class
371 definition in the header file. Again there are exceptions to this rule but they are very few:
372 \li When defining simple exception classes, the 'what()' member may be defined inline if it
373 returns a string constant.
374 \li It may be OK to use inline implementations for one-line implementations in internal
376 \li The Packet library allows inline implementations for the definition of parsers since doing
377 so outside the declaration just gets to verbose and parsers definitions are quite length but
378 very simple and straight forward.
381 Implementing members inline inside the class declaration makes the declaration much harder
382 to read. Since the declaration in the header file will be used as a reference by the
383 developer, the header files should be as readable as possible.
385 Every function or method implementation in one of the implementation files must \e always be
386 prefixed with \c prefix_. This symbol is defined at the beginning of the file and undefined at
387 the end. The symbol must be defined to be \c inline in the \c .cti and \c .cci files and must be
388 defined empty in the \c .cc and \c .ct files.
391 Together with splitting inlines and non-inlines into separate files, this allows to
392 automatically include the inline definitions at the right places. See above.
394 Private data members are named with a trailing underscore character.
397 This helps distinguishing local variables from parameter names. The trailing underscore
398 does not interfere with other naming conventions and is allowed by the standard (underscore
399 at the beginning of the name are problematic since some classes of names beginning with an
400 underscore are reserved for the standard library implementation)
407 // c-file-style: "senf"
408 // indent-tabs-mode: nil
409 // ispell-local-dictionary: "american"
410 // compile-command: "scons doc"