The Micro C++ Library
micxx::Exception Class Reference

An Exception is able to represent an error code, a message text and a stack of exception causes. More...

#include <micxx.hxx>

List of all members.

Public Member Functions

 Exception (const Exception &right)
 Create a copy of Exception right.
 Exception (const char *filename, unsigned long line, const Exception &cause, long code=0, const char *format=0,...)
 Create a new Exception from a catched Exception cause.
 Exception (const char *filename, unsigned long line, long code, const char *format=0,...)
 Create a new Exception that is identified by a specific code.
 Exception (const char *filename, unsigned long line, const char *format=0,...)
 Create a new unspecific (runtime) Exception.
virtual ~Exception () throw ()
 Deallocates the stored Exception cause.
virtual Exceptionappend (const char *format, va_list argptr)
 Append printf formatted text to the stored message.
virtual Exceptionclone () const
 Create a clone of this Exception.
virtual ExceptiongetCause ()
 The cause for this Exception, or 0 if this Exception is also the root cause.
virtual const ExceptiongetCause () const
 The cause for this Exception, or 0 if this Exception is also the root cause.
virtual long getCode () const
 The code that identifies the reason for this Exception.
virtual const char * getFilename () const
 The source filename where this Exception was raised.
virtual unsigned long getLine () const
 The source line where this Exception was raised.
virtual std::string & getMessage ()
 The formatted message that describes the reason why this Exception was raised.
virtual const std::string & getMessage () const
 The const version of getMessage().
virtual const char * getName () const
 The class name of this Exception.
virtual ExceptiongetRootCause ()
 The root cause of this Exception.
virtual const ExceptiongetRootCause () const
 The root cause of this Exception.
virtual ExceptionsetCause (const Exception *cause)
 Set a clone of cause as the cause for this Exception.
virtual ExceptionsetCode (long code)
 Set the code that identifies the reason for this Exception.
Exceptionoperator= (const Exception &right)
 Make this Exception a copy of the Exception right.
virtual std::string toString () const
 A string representation of this Exception together with all causes processed recursively.
virtual const char * what () const throw ()
 Overwrites the inherited method from std::exception.

Static Public Member Functions

static std::string toString (long error)
 A string representation for the system error code error.

Static Public Attributes

static const long NULL_POINTER = 998
static const long UNEXPECTED_EOF = 999
static const long RIFF_INVALID_FOURCC = 2000
static const long AVI_INVALID_LENGTH = 2002
static const long MICXX_MAX = 9999

Detailed Description

An Exception is able to represent an error code, a message text and a stack of exception causes.

Examples

  1. Throwing an unspecific (runtime) Exception
    This is probably the most common scenario, where an unspecific exception is thrown somewhere within the code (maybe due to invalid parameters passed to a function call, or an object used in an invalid state etc.)
     throw Exception(__FILE__, __LINE__, "invalid argument: foo=%d", (signed) foo)
    
    If the exception is thrown because of a specific system error, e.g. signaled by errno (or GetLastError() on a Windows platform) you could pass an error description like
     throw Exception(__FILE__, __LINE__, "gettimeofday failed: %s (%d)",
                     Exception::toString(errno).c_str(),
                     (signed) errno);
    
  2. Throwing a specific Exception
    If an application or library as its own set of error codes, you could pass them like
     #define FILE_NOT_OPEN 1000
     ...
     throw Exception(__FILE__, __LINE__, FILE_NOT_OPEN, "file not open: %s", filename.c_str());
    
  3. Rethrowing a catched Exception
    If an Exception is catched it could be rethrown as the cause wrapped within either a new specific or unspecific Exception. This might end up in a chain of causes from the innermost root cause to the outermost cause that might finally be reported by the application.
     try
     {
         ...
     }
     catch (const Exception & exception)
     {
         throw Exception(__FILE__, __LINE__, exception, FILE_NOT_OPEN,
                         "file not open: %s", filename.c_str());
     }
    
  4. __MICXXTRY__ and __MICXXEND__
    Placing the two macros __MICXXTRY__ and __MICXXEND__ consistently around all code fragments that might potentially throw an Exception, it is very easy to record the whole path (call stack) from the location where an Exception was thrown up to the point where the exception is handled. This also works for any exception derived from std::exception and also for any other exception (althought the information is limited to the recorded path down to the point where the exception was thrown).
     void Foo::foo()
     {
         __MICXXTRY__
         // place your code in here...
         __MICXXEND__
     }
    
Author:
Norbert Klose
Date:
December, 2006

Constructor & Destructor Documentation

micxx::Exception::Exception ( const Exception right)

Create a copy of Exception right.

Parameters:
rightThe Exception to create the copy from.
micxx::Exception::Exception ( const char *  filename,
unsigned long  line,
const Exception cause,
long  code = 0,
const char *  format = 0,
  ... 
)

Create a new Exception from a catched Exception cause.

Parameters:
filenameThe source filename where this Exception is raised (typically __FILE__)
lineThe source line where this Exception is raised (typically __LINE__)
causeMay be a catched Exception, that is stored as the reason that caused the newly created Exception.
codeAny code that identifies this Exception. The range of values is totally within the responsibility of the application.
formatA printf formatted string
micxx::Exception::Exception ( const char *  filename,
unsigned long  line,
long  code,
const char *  format = 0,
  ... 
)

Create a new Exception that is identified by a specific code.

Parameters:
filenameThe source filename where this Exception is raised (typically __FILE__)
lineThe source line where this Exception is raised (typically __LINE__)
codeAny code that identifies the reason for this Exception. It's the responsibility of each application to define the valid range of code values.
formatA printf formatted string
micxx::Exception::Exception ( const char *  filename,
unsigned long  line,
const char *  format = 0,
  ... 
)

Create a new unspecific (runtime) Exception.

Parameters:
filenameThe source filename where this Exception is raised (typically __FILE__)
lineThe source line where this Exception is raised (typically __LINE__)
formatA printf formatted string
virtual micxx::Exception::~Exception ( ) throw () [virtual]

Deallocates the stored Exception cause.


Member Function Documentation

virtual Exception& micxx::Exception::append ( const char *  format,
va_list  argptr 
) [virtual]

Append printf formatted text to the stored message.

Parameters:
formatA printf formatted string
argptrA variable aruments list of type va_list
Returns:
*this
virtual Exception* micxx::Exception::clone ( ) const [virtual]

Create a clone of this Exception.

Returns:
A clone of this Exception. The returned address is allocated with new. The calling application takes ownership of the allocated memory and it is in the responsibility of the calling application to delete the pointer when it is no more needed.
virtual const Exception* micxx::Exception::getCause ( ) const [virtual]

The cause for this Exception, or 0 if this Exception is also the root cause.

virtual Exception* micxx::Exception::getCause ( ) [virtual]

The cause for this Exception, or 0 if this Exception is also the root cause.

virtual long micxx::Exception::getCode ( ) const [virtual]

The code that identifies the reason for this Exception.

It's the responsibility of each application to define the valid range of code values.

virtual const char* micxx::Exception::getFilename ( ) const [virtual]

The source filename where this Exception was raised.

virtual unsigned long micxx::Exception::getLine ( ) const [virtual]

The source line where this Exception was raised.

virtual std::string& micxx::Exception::getMessage ( ) [virtual]

The formatted message that describes the reason why this Exception was raised.

virtual const std::string& micxx::Exception::getMessage ( ) const [virtual]

The const version of getMessage().

virtual const char* micxx::Exception::getName ( ) const [virtual]

The class name of this Exception.

This should be overwritten by derived classes.

Returns:
This implementation simply returns "micxx::Exception".
virtual Exception& micxx::Exception::getRootCause ( ) [virtual]

The root cause of this Exception.

The root cause of this Exception is either

virtual const Exception& micxx::Exception::getRootCause ( ) const [virtual]

The root cause of this Exception.

The root cause of this Exception is either

Exception& micxx::Exception::operator= ( const Exception right)

Make this Exception a copy of the Exception right.

Parameters:
rightThe Exception to create the copy from.
virtual Exception& micxx::Exception::setCause ( const Exception cause) [virtual]

Set a clone of cause as the cause for this Exception.

If this Exception aleady has a cause, this cause is deleted before.

Parameters:
causeThe cause for which a clone is stored as the cause for this Exception. If cause is 0, the cause for this exception is (re-)set to 0 as well.
virtual Exception& micxx::Exception::setCode ( long  code) [virtual]

Set the code that identifies the reason for this Exception.

Parameters:
codeIt's the responsibility of each application to define the valid range of code values.
virtual std::string micxx::Exception::toString ( ) const [virtual]

A string representation of this Exception together with all causes processed recursively.

static std::string micxx::Exception::toString ( long  error) [static]

A string representation for the system error code error.

This is similar to strerror on UNIX like platforms and FormatMessageA on Windows based platforms.

virtual const char* micxx::Exception::what ( ) const throw () [virtual]

Overwrites the inherited method from std::exception.

Returns:
This implementation simply retuns getMessage().c_str().

Member Data Documentation

const long micxx::Exception::AVI_INVALID_LENGTH = 2002 [static]
const long micxx::Exception::MICXX_MAX = 9999 [static]
const long micxx::Exception::NULL_POINTER = 998 [static]
const long micxx::Exception::RIFF_INVALID_FOURCC = 2000 [static]
const long micxx::Exception::UNEXPECTED_EOF = 999 [static]

The documentation for this class was generated from the following file: