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

#include <micxx.hxx>

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 Exception &	append (const char *format, va_list argptr)
	Append printf formatted text to the stored message.
virtual Exception *	clone () const
	Create a clone of this Exception.
virtual Exception *	getCause ()
	The cause for this Exception, or `0` if this Exception is also the root cause.
virtual const Exception *	getCause () 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 Exception &	getRootCause ()
	The root cause of this Exception.
virtual const Exception &	getRootCause () const
	The root cause of this Exception.
virtual Exception &	setCause (const Exception *cause)
	Set a clone of cause as the cause for this Exception.
virtual Exception &	setCode (long code)
	Set the code that identifies the reason for this Exception.
Exception &	operator= (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

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);
```

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());

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());
 }
```
__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:

right The 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:

filename	The source filename where this Exception is raised (typically `__FILE__`)
line	The source line where this Exception is raised (typically `__LINE__`)
cause	May be a catched Exception, that is stored as the reason that caused the newly created Exception.
code	Any code that identifies this Exception. The range of values is totally within the responsibility of the application.
format	A 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:

filename	The source filename where this Exception is raised (typically `__FILE__`)
line	The source line where this Exception is raised (typically `__LINE__`)
code	Any code that identifies the reason for this Exception. It's the responsibility of each application to define the valid range of code values.
format	A printf formatted string

micxx::Exception::Exception	(	const char *	filename,
		unsigned long	line,
		const char *	format = `0`,
			...
	)

Create a new unspecific (runtime) Exception.

Parameters:

filename	The source filename where this Exception is raised (typically `__FILE__`)
line	The source line where this Exception is raised (typically `__LINE__`)
format	A 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:

format	A printf formatted string
argptr	A 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

equal to getCause()->getRootCause(), if getCause() is not 0, or
*this, otherwise.

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

The root cause of this Exception.

The root cause of this Exception is either

equal to getCause()->getRootCause(), if getCause() is not 0, or
*this, otherwise.

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

Make this Exception a copy of the Exception right.

Parameters:

right The 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:

cause The 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:

code	It'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:

include/micxx/Exception.hxx

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation