2 // Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
3 // Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
4 // Stefan Bund <g0dil@berlios.de>
6 // This program is free software; you can redistribute it and/or modify
7 // it under the terms of the GNU General Public License as published by
8 // the Free Software Foundation; either version 2 of the License, or
9 // (at your option) any later version.
11 // This program is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
16 // You should have received a copy of the GNU General Public License
17 // along with this program; if not, write to the
18 // Free Software Foundation, Inc.,
19 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
21 /** \mainpage SENF: The Simple and Extensible Network Framework
23 The SENF Simple and Extensible Network Framework aims to be a complete set of libraries to
24 facilitate the development of network applications focusing on network protocols on the layers
25 below the application layer. However, the framework includes many general purpose utilities and
26 will be expedient to use well beyond its primary objective.
30 The main goals of this library are (in no particular order):
32 \li modular framework design
33 \li utilizing the power of modern C++
34 \li very low overhead for frequently called members
38 \section start Getting started
40 To get started using this library, begin by checking out the code from the <a
41 href="http://developer.berlios.de/svn/?group_id=7489">BerliOS SVN repository</a>. You may find
42 help on using the library at '\ref usage'. If you are interested in SENF, feel free to subscribe
43 to the <a href="http://developer.berlios.de/mail/?group_id=7489">SENF mailing lists</a>. If you
44 want to contribute, read the docs and \e please adhere to the \ref conventions.
47 <a href="../../Examples/doc/html/index.html">Examples</a>
50 /** \page usage Using the SENF framework
52 The SENF Framework is a collection of loosely coupled modules. The libraries are heavily object
53 oriented and template based. For compatibility reasons, the libraries are therefore built
54 together with every project making use of the framework.
56 When starting a new project based on the SENF framework, it is advisable, to make use of the
57 SENFSCons build environment and use SVN to manage the code repository. This is the
58 configuration, described in this documentation.
65 \section Preliminaries
67 Before starting the development, make sure to fulfill the following requirements:
69 \li GNU g++, version at least 3.4
70 \li The Boost libraries (http://www.boost.org)
71 \li The SCons build tool (http://www.scons.org)
73 If you want to build the documentation, you additionally need
75 \li Doxygen (http://www.doxygen.org)
76 \li The \c dia diagram editor (http://www.gnome.org/projects/dia/)
77 \li HTML \c tidy (http://tidy.sourceforge.net/)
78 \li The \c xsltproc XSLT processor (http://xmlsoft.org/XSLT/xsltproc2.html)
79 \li The \c graphviz library (http://www.graphviz.org)
82 The library is only tested with gcc-3.4 and 4.0 on Linux. On other POSIX platforms with a BSD
83 Socket API, the library should be usable, possibly with some tweaking (except for the Scheduler,
84 which relies on \c epoll)
87 /** \page build Building the framework
89 This procedure will test building the complete framework including the unit tests and the
90 Sniffer test application. This build is \e not needed to use the framework since every project
91 will include the full SENF source code itself (via Subversion).
93 After you have successfully built the library tests, you can continue to setup your own project
96 \see \ref components \n
99 \section checkout Getting the code
101 To access the code, check out the code from the BerliOS repository. Change to your development
102 directory and use the following subversion command
105 $ svn checkout http://svn.berlios.de/svnroot/repos/senf/trunk senf
108 This will create a new directory \c senf within the current directory. For further documentation
109 on the use of Subversion, see the \c svn manpage or the subversion homepage at
110 http://subversion.tigris.org. A very good introduction and reference to subversion is available
111 at http://svnbook.red-bean.com.
113 \section compile Building
115 To build the library, execute all unit tests and build the Sniffer test application, use
122 in the \c senf directory. This assumes, that you want to build the library with your default gcc
123 and requires the boost libraries to be available in the system include paths. If this is not the
124 case, you can take a look at <tt>SConfig.template</tt> file. Copy this file to <tt>SConfig</tt>
125 and comment out all the variables you don't want to change (The \e values in the template file
126 are just arbitrary examples).
129 /** \page components The SENF modules
131 The framework is made up of several modular components. When using the library, it is possible
132 to selectively choose to use only a subset of the implemented modules.
137 \section libSocket libSocket: C++ abstraction of the BSD socket API
139 This library provides a high performance and object oriented abstraction of the standard socket
140 API. It utilizes a flexible and extensible policy based design. The library provides predefined
141 types for the important socket types (UDP and TCP sockets etc) including raw and packet
144 \see <a href="../../Socket/doc/html/index.html">libSocket API
147 \section libPackets libPackets: Network packet manipulation
149 This library provides a very flexible infrastructure to parse, create and otherwise manipulate
150 packetized network data. Included is a library of several protocol parsers covering the basic
151 IPv4 and IPv6 network protocols down to the Ethernet layer.
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 standard UNIX \c select type
159 event dispatcher. It is based on the high performance \c epoll system call. It provides support
160 for read/write events as well as simple timer based events.
162 \see <a href="../../Scheduler/doc/html/index.html">libScheduler API reference</a>
164 \section libUtils libUtils: Collection of arbitrary utilities
166 This library is used be most all of the other modules for miscellaneous tools and utilities. We
169 \li Simple functions to manage daemon processes
170 \li Standard exception classes
171 \li senf::intrusive_refcount to simplify the implementation of classes usable with
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 high-resolution time values
177 \see <a href="../../Utils/doc/html/index.html">libUtils API reference</a>
179 \section senfscons SENFSCons, the SENF build environment
181 SENF relies on SCons (http://www.scons.org) to build. To further simplify the common tasks, SENF
182 includes a library of custom routines and builders comprising a very concise build
183 environment. Included are a number of templates to help bootstrapping a new project or
186 \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a>
189 /** \page svnsetup Setting up a new project using SENF
191 The preferred way to use SENF in a new project is to rely on Subversion and make use of the
192 SENFSCons build environment. The following sections will describe, how this setup works.
198 \section svnext Setting up the project repository
200 The most seamless integration is possible if you rely on Subversion to manage the new
201 project. Subversion does support 'external repositories'. This allows to import code from a
202 foreign repository into the checkout without importing it into your repository. The code will
203 always stay at the remote repository, updates are automatically available.
205 First setup a new empty repository as described for example in the Subversion book at
206 http://svnbook.red-bean.com or as mandated by your site policy. We will call the project 'Foo'
207 and assume, that the project has been checked out into the 'Foo' directory.
209 You now have to decide, which modules you want to use. Every module resides in it's own
210 subdirectory in the SENF repository. Instead of directly checking out the code, we will use \c
211 svn:externals. This will instruct \c svn to automatically check out the needed directories from
212 the BerliOS SENF repository. Change to the 'Foo' directory and type
215 $ svn propedit svn:externals .
218 The default editor (probably VI) will be started with the current value of the svn:externals
219 property (which will probably be empty). Now add all the modules you want plus \c senfscons and
220 possibly \c doclib (if you want to build the documentation). You will almost certainly need the
221 \c Utils module, since all other modules depend on it.
223 For example, if you want to use the \c Scheduler and \c Socket module, the file will look like
226 senfscons http://svn.berlios.de/svnroot/repos/senf/trunk/senfscons
227 Utils http://svn.berlios.de/svnroot/repos/senf/trunk/Utils
228 Scheduler http://svn.berlios.de/svnroot/repos/senf/trunk/Scheduler
229 Socket http://svn.berlios.de/svnroot/repos/senf/trunk/Socket
232 exit the editor and the property will be set. Now run
238 and the code will be checked out into the corresponding directories.
240 \section new_conf Configuring SENFSCons
242 To set up the build environment, copy the <tt>senfscons/SConstruct.template</tt> to
243 <tt>SConstruct</tt> in the project root. The default setup of this file is to build all
244 subdirectories (using the \c SConscript files of the subdirectories). You can add additional
245 global targets and configuration parameters here.
247 If you want to use a non-default compiler or the boost library is not installed in the system
248 directories, you will have to copy <tt>senfscons/SConfig.template</tt> to <tt>SConfig</tt> in
249 the project root and edit it there. You should \e never add \c SConfig to the repository since
250 it should only contain local settings necessary for building on your local system. You should
251 therefore add \c SConfig to the list of files ignored by Subversion in the project root. In the
255 $ svn propedit svn:ignore .
258 and add \c SConfig as a new line to the property.
260 \section new_build Building the project
262 You should now be able to build your project using
268 If you have not changed the \c SConstruct file, this will build all modules you have imported
269 into your project. To build and execute the unit tests, use
275 you can also build only a subdirectory by changing to it and running
281 \see <a href="../../senfscons/doc/html/index.html">SENFSCons reference</a> \n
282 <a href="http://www.scons.org/documentation.php">SCons documentation</a> \n
283 <a href="http://svnbook.red-bean.com">Subversion online book</a> \n
284 <a href="http://subversion.tigris.org">Subversion Homepage</a>
287 /** \page overview Introduction to the framework
289 The SENF framework is relatively complex and makes use of advanced features of the C++
290 language. To make the most efficient use of the framework, you should have at least a basic
291 understanding of C++ templates and the standard library concepts.
293 The library implementation at places makes heavy use of advanced template techniques and relies
294 on some very advanced template libraries from Boost. The aim was however for the \e external
295 interface of the library to be as simple as possible without sacrificing important functionality
296 or adversely impacting the runtime performance.
298 As already mentioned several times, the library relies on Boost (http://www.boost.org) as a
299 generic library of high quality reusable C++ components. It also makes frequent use of the
300 standard library. It is designed, to integrate well into both libraries and to use the same
303 \section startup Getting starting developing with SENF
305 To introduce the framework and it's general structure, a simple example application is provided
306 in the SENF repository in the \c Sniffer module. Peruse this example to get a first look at how
309 When building a network Application with SENF, you will use several modules:
311 \li Use the <a href="../../Socket/doc/html/index.html">Socket library</a> for network
312 communication needs. This library includes support for raw and packet sockets to allow low
313 level network access.
314 \li Use the <a href="../../Scheduler/doc/html/index.html">Scheduler library</a> to coordinate
315 the asynchronous event processing. This drastically reduces the number of threads needed in
316 your application and will greatly enhance the overall responsiveness.
317 \li To interpret low level network packets, use the <a
318 href="../../Packets/doc/html/index.html">Packets library</a>. This library will provide
319 efficient and convenient access to all protocol fields. It supports parsing as well as
320 modifying and creating packets. It has default support for the most important internet
321 protocols and is highly extensible with new protocols.
322 \li Go over the <a href="../../Utils/doc/html/index.html">Utils library</a>. It contains small
323 helpers to simplify tasks like daemonization, exception handling, debugging and so on.
325 The simplest way to get started is: copy the Sniffer application and start to modify it.
327 \see <a href="../../Examples/doc/html/index.html">Examples</a> \n
332 \section conventions Coding Conventions
334 Here we have laid down the coding conventions used throughout the SENF framework. Please ad here
335 to these conventions when changing or adding code. If you use emacs, you can use the C++ IDE for
336 emacs from http://g0dil.de which greatly simplifies following these conventions.
338 \subsection conventions_file_naming File Naming
340 Files should be named according to the main class they define. A single header file should
341 define only one main class. Exceptions to this rule are OK.
344 This simplifies finding the implementation/header for a given class and also reduces the
345 size of each single file.
347 The implementation is divided into a number of different files:
349 <table class="glossary"> <tr><td>\c .h</td><td>C public header</td></tr>
351 <tr><td>\c .hh</td><td>C++ public header</td></tr>
353 <tr><td>\c .ih</td><td>C++ internal header used only by the implementation. This header will
354 probably be included indirectly by the public header but is not meant to be perused by the
355 library user</td></tr>
357 <tr><td>\c .c</td><td>C implementation</td></tr>
359 <tr><td>\c .cc</td><td>C++ implementation of non-inline non-template functions and
362 <tr><td>\c .ct</td><td>C++ implementation of non-inline template functions and members</td></tr>
364 <tr><td>\c .cci</td><td>C++ implementation of inline non-template functions and
367 <tr><td>\c .cti</td><td>C++ implementation of inline template functions and members</td></tr>
369 <tr><td>\c .mpp</td><td>Special include file used for external iteration by the
370 Boost.Preprocessor library</td></tr> </table>
373 There are two part's to this: First, separating the implementation of inlines and templates
374 out of the header file makes the header file much easier to read. This is important, since
375 the header file will be used as a reference by the developers.
377 Separating inline from non-inline members is used together with the \c prefix_ convention
378 below to ensure the correct placement of inline vs non-inline members in the source
379 code. The C++ language requires, that inline members must be included into \e every
380 compilation unit, non-inline members however must be included \e only in one compilation
381 unit. Placing the inline members into a separate file allows to automate this: Simply moving
382 an implementation from one of the inline files into one of the non-inline files will change
383 the type of implementation accordingly.
385 \subsection conventions_type_naming Type Naming
387 SENF prefers the use of the CapitalziedLettersToSeparateWords convention for class names. In
388 this case, class names must start with a capital letter. There are some exceptions to this rule:
389 Types which define new basic data types to be used like other built-in types may be named using
390 lowercase letters plus underscores. Also, if a type or class is directly related to some other
391 library (STL or Boost) which uses the underscore convention, it might be more sensible to follow
392 this convention. This is open to debate.
395 Naming types with capital letters nicely gives a visual clue, that a symbol is a type
396 name. This can also be used by the editor to highlight type names correctly. Additionally,
397 this convention is compact and does not add additional or repeated overhead.
399 \subsection conventions_impl Implementation
401 Only in very few places, SENF allows the use of inline implementations (not to be confused with
402 inline functions). An \e implementation is inline, if it is written directly into the class
403 definition in the header file. Again there are exceptions to this rule but they are very few:
404 \li When defining simple exception classes, the 'what()' member may be defined inline if it
405 returns a string constant.
406 \li It may be OK to use inline implementations for one-line implementations in internal
408 \li The Packet library allows inline implementations for the definition of parsers since doing
409 so outside the declaration just gets to verbose and parsers definitions are quite length but
410 very simple and straight forward.
413 Implementing members inline inside the class declaration makes the declaration much harder
414 to read. Since the declaration in the header file will be used as a reference by the
415 developer, the header files should be as readable as possible.
417 Every function or method implementation in one of the implementation files must \e always be
418 prefixed with \c prefix_. This symbol is defined at the beginning of the file and undefined at
419 the end. The symbol must be defined to be \c inline in the \c .cti and \c .cci files and must be
420 defined empty in the \c .cc and \c .ct files.
423 Together with splitting inlines and non-inlines into separate files, this allows to
424 automatically include the inline definitions at the right places. See above.
432 // c-file-style: "senf"
433 // indent-tabs-mode: nil
434 // ispell-local-dictionary: "american"