From: g0dil Date: Fri, 15 Dec 2006 14:39:23 +0000 (+0000) Subject: First version of overview documentation completed X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=6ce2bcb77328785691639894fe026090f004e57b;p=senf.git First version of overview documentation completed git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@164 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Doxyfile b/Doxyfile index 0bbcdbb..32f3140 100644 --- a/Doxyfile +++ b/Doxyfile @@ -72,7 +72,7 @@ RECURSIVE = NO EXCLUDE = doc EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = .* -EXAMPLE_PATH = +EXAMPLE_PATH = Sniffer EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO IMAGE_PATH = diff --git a/Example.dox b/Example.dox new file mode 100644 index 0000000..e42aac5 --- /dev/null +++ b/Example.dox @@ -0,0 +1,110 @@ +/** \page example Sniffer: A simple example application + + \dontinclude Sniffer.cc + + The Sniffer application is a simple command line network sniffer + like \c tcpdump or \c tethereal. The application uses a packet + socket to read Ethernet packets from the \c eth0 interface and + dumps the parsed packets out to the standard output. + + We will be looking at \c Sniffer.cc in the \c Sniffer + directory. We start by including the necessary headers + + \skip // Custom includes + \until Ethernet + + (The additional includes are part of a short-time fix which will + be removed as soon as possible). The example application now + contains a helper routine to produce a packet hexdump. We will + skip this routine here and go directly to the \c main function + + \skip main + \until try + + We catch all exceptions in a \c try block. This is good for a + deliverable binary. When debugging the application, it might be + better to let the exception \c abort the execution so you can get + a backtrace of the exception origin in the debugger. + + We now create a packet socket and bind it to the \c eth0 + interface. By uncommenting the last line, you may switch the + interface into promiscuous mode. + + \until // + + We will now read packets from the socket forever, that is until + the user hits Ctrl-C + + \skip while + \until read + + The next step is, to parse the data read from the socket as an + Ethernet packet + + \until ; + + Lets digest this line step by step: We declare a variable named \c + packet as a smart pointer to an \c EthernetPacket instance. \c ptr + is a typedef member of all Packet classes for the corresponding + smart pointer type. We then initialize this pointer with a call to + the static \c create member of the \c Packet class. This member + takes the type of Packet to parse as a template argument. We pass + \c EthernetPacket here. The function takes an iterator range as an + argument, and we pass it the complete packet just read by + giving the range \c begin() to \c end() of our just read \c data + string. + + The next step is, to write out the packet to the standard output + + \until \n\n + + The \c dump call will write out a complete representation of the + parsed packet data. The Packet library will \e not try to + interpret payload data as long as no exact indication of the + payload type is available (example: A UDP Payload is not parsed + further unless you explicitly tell the library, how to parse it). + Tools like \c tethereal guess the payload type by checking port + numbers and the payload data, however this is not advisable for a + general purpose packet library. + + The next line, \c hexdump, will write out the \e last packet + component. Packets are managed as a chain of headers. The last + header is normally a \c DataPacket holding the payload data. + + That's it. We finish of by catching the exception and giving as + much detail as possible if an exception is caught + + \until ; + \until } + \until } + + The \c prettyName function from the \c Utils library is used, to + get a nice, printable representation of the \e dynamic type of the + exception instance. It is an interface to the g++ demangler. This + is necessary since the \c name member of the C++ \c type_info + instance is a mangled name in C++. + + That's it. This is all, that's necessary to read and parse raw + network packets using the SENF library. To try out the example + application, check out the library, go to the \c Sniffer directory + and execute + + 
+      # scons -u
+      # ./Sniffer
+ + \see \ref components \n + \ref build \n + libSocket API reference \n + libPackets API reference \n + libUtils API reference + */ + + +// Local Variables: +// mode: c++ +// mode: flyspell +// mode: auto-fill +// ispell-local-dictionary: "american" +// End: + diff --git a/Mainpage.dox b/Mainpage.dox index 02c250b..54d75f8 100644 --- a/Mainpage.dox +++ b/Mainpage.dox @@ -48,7 +48,8 @@ \see \ref build \n \ref components \n - \ref svnsetup + \ref svnsetup \n + \ref overview \section Preliminaries @@ -71,10 +72,6 @@ which relies on \c epoll) \todo - \li Preliminaries: SVN access, Dependencies - \li Building the library -> Configuration - \li Setting up a project using this library (svn:externals) - \li Library components \li coding standards and patterns */ @@ -195,12 +192,16 @@ reference */ -/** \page svnsetup Setting up a new project using SENF via SVN +/** \page svnsetup Setting up a new project using SENF The preferred way to use SENF in a new project is to rely on Subversion and make use of the SENFSCons build environment. The following sections will describe, how this setup works. + \see \ref build \n + \ref components \n + \ref overview + \section svnext Setting up the project repository The most seamless integration is possible if you rely on @@ -249,34 +250,121 @@ and the code will be checked out into the corresponding directories. - \todo \li Configuring and building -> reference to the SENFSCons - dok - */ + \section new_conf Configuring SENFSCons + + To set up the build environment, copy the + satscons/SConstruct.template to Satscons in the + project root. The default setup of this file is to build all + subdirectories (using the \c SConscript files of the + subdirectories). You can add additonal global targets and + configuration parameters here. + + If you want to use a non-default compiler or the boost library is + not installed in the system directories, you will have to copy + satscons/SConfig.template to SConfig in the + project root and edit it there. You should \e never add \c SConfig + to the repository since it should only contain local settings + necessary for building on your local system. You should therefore + add \c SConfig to the list of files ignored by Subversion in the + project root. In the project root execute -/** \page example Sniffer: A simple Example application + 
+      $ svn propedit svn:ignore .
+ + and add \c SConfig as a new line to the property. + + \section new_build Building the project + + You should now be able to build your project using + + 
+      $ scons
+ If you have not changed the \c SConstruct file, this will build + all modules you have importet into your project. To build and + execute the unit tests, use + + 
+      $ scons all_tests
+ + you can also build only a subdirectory by changing to it and + running + + 
+      $ scons -u [target]
+ + \see SENFSCons reference \n + SCons documentation \n + Subversion online book \n + Subversion Homepage + */ + +/** \page overview Introduction to the framework + + The SENF framework is relatively complex and makes use of advanced + features of the C++ language. To make the most efficient use of + the framework, you should have at least a basic understanding of + C++ templates and the standard library concepts. + + The library implementation at places makes heavy use of advanced + template techniques and relies on some very advanced template + libraries from Boost. The aim was however for the \e external + interface of the library to be as simple as possible without + sacrificing important functionality or adversely impacting the + runtime performance. + + As already mentioned several times, the library relies on Boost + (http://www.boost.org) as a generic library of high quality + reusable C++ components. It also makes frequent use of the + standard library. It is designed, to integrate well into both + libraries and to use the same concepts and ideas. + + \section startup Getting starting developing with SENF + + To introduce the framework and it's general structure, a simple + example application is provided in the SENF repository in the \c + Sniffer module. Peruse this example to get a first look at how to + make use of SENF. + + When building a network Application with SENF, you will use + several modules: + + \li Use the Socket + library for network communication needs. This library + includes support for raw and packet sockets to allow low level + network access. + \li Use the Scheduler + library to coordinate the asynchronous event + processing. This drastically reduces the number of threads + needed in your application and will greatly enhance the overall + responsiveness. + \li To interpret low level network packets, use the Packets + library. This library will provide efficient and + convenient access to all protocol fields. It supports parsing as + well as modifying and creating packets. It has default support + for the most important TCP protocols and is highly extensible + with new protocols. + \li Go over the Utils + library. It contains small helpers to + simplify tasks like daemonization, exception handling, + debugging and so on. + + The simplest way to get started is: copy the Sniffer application + and start to modify it. + + \see \ref example \n + \ref components \n + \ref svnsetup \n + \ref build */ - \section code Coding practices - - The library heavily depends on the features of modern C++. As - such, it depends on a fairly recent and standards compliant C++ - compiler (the Library is developed using \c gcc with Version at - least 3.4). To meet the above defined goals, the library makes - quite heavy use of advanced templating techniques, so - understanding the implementation will require expertise in the - intricacies of C++ templates. However, it was deemed important to - keep the \e visible Interface of the Library as clean and simple - as possible without sacrificing the projects design goals. - - The library heavily depends on the \e Boost libraries (see - http://www.boost.org). The Boost libraries are an ever growing - collection of highest quality reusable C++ components. They are - designed with standardization in mind. Many of the libraries are - already in queue to be part of the next generation C++ standard. - // Local Variables: // mode: c++ +// mode: flyspell +// mode: auto-fill +// ispell-local-dictionary: "american" // End: diff --git a/Sniffer/Sniffer.cc b/Sniffer/Sniffer.cc index f1221b6..e2a4997 100644 --- a/Sniffer/Sniffer.cc +++ b/Sniffer/Sniffer.cc @@ -86,7 +86,7 @@ namespace { } } -int main (int argc, char * argv[]) +int main (int argc, char const * argv[]) { try { satcom::lib::PacketSocketHandle sock; @@ -104,7 +104,7 @@ int main (int argc, char * argv[]) std::cout << "\n\n"; } } - catch (std::exception & ex) { + catch (std::exception const & ex) { std::cerr << satcom::lib::prettyName(typeid(ex)) << ": " << ex.what() << "\n"; } } diff --git a/doclib/logo-head.png b/doclib/logo-head.png index 74f8ef5..35431fe 100644 Binary files a/doclib/logo-head.png and b/doclib/logo-head.png differ diff --git a/doclib/logo.xcf b/doclib/logo.xcf index faf3e5b..c3f7cfb 100644 Binary files a/doclib/logo.xcf and b/doclib/logo.xcf differ diff --git a/doclib/senf.css b/doclib/senf.css index 386ab21..ee41842 100644 --- a/doclib/senf.css +++ b/doclib/senf.css @@ -5,8 +5,8 @@ body { } #head { - height: 63px; - border-top: 4px solid #DECD40; + height: 62px; + border-top: 5px solid #DECD40; border-bottom: 1px solid #AF9D00; background: url(logo-head.png) top left no-repeat; background-color: #EDE497; @@ -15,7 +15,7 @@ body { #head h1 { margin: 0 0 0 100px; padding: 6px 0 0 0; - height: 34px; + height: 33px; background-color: #DECD40; border-bottom: 1px solid #AF9D00; font-size: 22px; diff --git a/satscons/SConstruct.template b/satscons/SConstruct.template index 51e4564..ef68cb9 100644 --- a/satscons/SConstruct.template +++ b/satscons/SConstruct.template @@ -6,7 +6,6 @@ import SatSCons SatSCons.UseBoost(); SatSCons.UseSTLPort(); -SatSCons.UseDoxygen(); env = SatSCons.MakeEnvironment(); env.Append(