Utils/Exception.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2006
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   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.
  12 //
  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.
  17 //
  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.
  22
  23 /** \file
  24     \brief Exception public header */
  25
  26 #ifndef HH_Exception_
  27 #define HH_Exception_ 1
  28
  29 // Custom includes
  30 #include <exception>
  31 #include <string>
  32 #include <iostream>
  33 #include <sstream>
  34 #include <boost/preprocessor/repeat.hpp>
  35 #include <boost/preprocessor/cat.hpp>
  36 #include <boost/utility.hpp>
  37
  38 //#include "Exception.mpp"
  39 ///////////////////////////////hh.p////////////////////////////////////////
  40
  41 /** \defgroup exception Exception classes
  42
  43     All exceptions in %senf are derived from senf::Exception. This class adds the possibility to
  44     extend the exception description while it is processed:
  45
  46     \code
  47     try {
  48
  49         // Some code which might raise an arbitrary senf exception
  50
  51     }
  52     catch (senf::Exception & e) {
  53         e << "\handling user " << user;
  54         throw;
  55     }
  56     \endcode
  57
  58     This will add the user information to any %senf exception thrown. The Exception is however not a
  59     stream. If you need to do more extensive formating, either use an intermediate string-stream or
  60     use <a href="http://www.boost.org/libs/format/doc/format.html">Boost.Format</a>:
  61
  62     \code
  63     try {
  64         // ...
  65     }
  66     catch (senf::Exception & e) {
  67         e << boost::format("\ncall id 0x%04x@%s") % id % address;
  68     }
  69     \endcode
  70
  71     senf::SystemException is thrown for all operating system errors (failures which result in the
  72     operating system setting the errno value). It is also derived from senf::Exception and can
  73     therefore be extended as well.
  74
  75     Defining your own exception classes derived from senf::Exception is very simple:
  76
  77     \code
  78     struct FooException : public senf::Exception
  79     { FooException() : senf::Exception("Foo hit the fan") {} };
  80     \endcode
  81  */
  82
  83 namespace senf {
  84
  85     /** \brief Generic exception base-class
  86
  87         Exception is a generic exception base-class which allows the exception to be later extended
  88         by catching and re-throwing it (See example in \ref exception).
  89
  90         \ingroup exception
  91       */
  92     class Exception
  93         : public std::exception
  94     {
  95     public:
  96         ///////////////////////////////////////////////////////////////////////////
  97         ///\name Structors and default members
  98         ///@{
  99
 100         virtual ~Exception() throw();
 101
 102         ///@}
 103         ///////////////////////////////////////////////////////////////////////////
 104
 105         virtual char const * what() const throw();
 106
 107         template <class Arg>
 108         Exception & operator<<(Arg const & arg); ///< Extend exception description
 109                                         /**< Adds \a arg converted to string to the end of the
 110                                              exception description string. This operator allows to
 111                                              use Exception instances like streams. The conversion is
 112                                              performed using <code>boost::lexical_cast</code> and is
 113                                              therefor identical to a streaming operation.
 114                                              \see \ref exception */
 115
 116     protected:
 117         Exception(std::string const & description = ""); ///< Initialize exception with string
 118                                         /**< \a description is the initial error description
 119                                              string. This should probably be a string constant
 120                                              describing the exception for most derived
 121                                              exceptions. */
 122
 123     private:
 124         std::string message_;
 125     };
 126
 127
 128     /** \brief Exception handling standard UNIX errors (errno)
 129
 130         This exception is thrown to signal generic \c errno failures. Normally the \c errno value is
 131         automatically taken from the \c errno variable but it may also be specified explicitly:
 132
 133         \code
 134         // Standard usage: Take \c errno from environment
 135         throw senf::SystemException("::open()")
 136             << " while opening configuration file: " << filename;
 137
 138         // You may however explicitly specify the errno value
 139         throw senf::SystemException("::open()", ENOFILE)
 140
 141         // Or leave the location information empty
 142         throw senf::SystemException(ENOFILE);
 143         throw senf::SystemException();
 144         \endcode
 145
 146         \ingroup exception
 147      */
 148     class SystemException : public Exception
 149     {
 150     public:
 151         ///////////////////////////////////////////////////////////////////////////
 152         ///\name Structors and default members
 153         ///@{
 154
 155         explicit SystemException(std::string const & where = "");
 156         explicit SystemException(int code);
 157         SystemException(std::string const & where, int code);
 158
 159         virtual ~SystemException() throw();
 160
 161         ///@}
 162         ///////////////////////////////////////////////////////////////////////////
 163
 164         int errorNumber() const;        ///< Error code (\c errno number)
 165         char const * description() const; ///< Error description (\c strerror() value)
 166
 167         bool anyOf(int c0, int c1=0, int c2=0, int c3=0, int c4=0, int c5=0,
 168                    int c6=0, int c7=0, int c8=0, int c9=0);
 169                                         ///< \c true, if errorNumber() is one of \a c0 ... \a c9
 170
 171
 172
 173     private:
 174         void init(std::string const & where, int code);
 175
 176         int code_;
 177     };
 178
 179 }
 180
 181 ///////////////////////////////hh.e////////////////////////////////////////
 182 #include "Exception.cci"
 183 //#include "Exception.ct"
 184 #include "Exception.cti"
 185 #endif
 186
 187 \f
 188 // Local Variables:
 189 // mode: c++
 190 // fill-column: 100
 191 // c-file-style: "senf"
 192 // indent-tabs-mode: nil
 193 // ispell-local-dictionary: "american"
 194 // compile-command: "scons -u test"
 195 // comment-column: 40
 196 // End: