BpsException Class Reference

BPS error exception class. More...

#include <bpsexception.h>

Public Types
enum	Severity { Info , Warning , Error , Fatal }
	Severity of the exception. More...

Public Member Functions
BpsException &	addLocation (const QString &aFilename, quint32 aLinenumber, const QString &aFunction)
	Add another location to an existing exception. More...
BpsException &	appendMessage (const QString &aText)
	Append text to the error message of the exception. More...
	BpsException ()
	Default constructor for the BpsException objects. More...
	BpsException (const BpsException &aException)
	Copy constructor for the BpsException objects. More...
	BpsException (const QScriptValue &aException, const QString &aFilename=QString())
	Constructor from QtScript exceptions. More...
	BpsException (const QString &aFilename, quint32 aLinenumber, const QString &aFunction, const QString &aMessage, Severity aSeverity)
	Standard constructor for the BpsException objects. More...
QString	message () const
	Get the plain message, without location trace information. More...
BpsException &	setMessage (const QString &aMessage)
	Set the error message for the exception. More...
BpsException &	setSeverity (Severity aSeverity)
	Set the error severity for the exception. More...
Severity	severity () const
	Get severity. More...
QString	text (int aMaxLocs=1) const
	Get the message, along with a log of the locations stack. More...
QScriptValue	throwScriptError (QScriptContext *aContext) const
	Throw a script error of the exception. More...

Related Functions
(Note that these are not member functions.)
#define	bpsMakeException(aMessage)   BpsException(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__), aMessage, BpsException::Error)
	Convenience macro to create a BpsException with severity of Error. More...
#define	bpsMakeExceptionFatal(aMessage)   BpsException(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__), aMessage, BpsException::Fatal)
	Convenience macro to create a BpsException with severity of Fatal. More...
#define	bpsMakeExceptionInfo(aMessage)   BpsException(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__), aMessage, BpsException::Info)
	Convenience macro to create a BpsException with severity of Info. More...
#define	bpsMakeExceptionWarning(aMessage)   BpsException(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__), aMessage, BpsException::Warning)
	Convenience macro to create a BpsException with severity of Warning. More...
#define	bpsTraceException(aException)   aException.addLocation(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__))
	Convenience macro to add a location to the traceback stack. More...

Detailed Description

BPS error exception class.

In the BPS environment error handling is heavily using exceptions (in contrast to the underlying Qt framework, where exceptions are for historical reasons not used in c++ at all). The base class of all exceptions thrown by the BPS c++ library is BpsException.

The class holds an error message, plus an arbitrary number of locations made up each by the source file name, the source file line number, and the function or method name. The first location is the place where the exception was thrown while the following locations are traceback informations collected by catching, tracing and rethrowing the exception.

BpsExceptions integrate seamless with script exceptions, so that exceptions thrown by c++ can be catched as Error objects by script code, and vice versa.

Member Enumeration Documentation

Severity

enum BpsException::Severity

Severity of the exception.

Enumerator
Info	Information, debug stop for example.
Warning	Uncritical, retry later for example.
Error	Critical error.
Fatal	Program should be aborted.

Constructor & Destructor Documentation

BpsException() [1/4]

BpsException::BpsException

(

)

Default constructor for the BpsException objects.

The severity is set to Error.

BpsException() [2/4]

BpsException::BpsException

(

const BpsException &

aException

)

Copy constructor for the BpsException objects.

Parameters

aException

Reference of the BpsException object to copy.

BpsException() [3/4]

BpsException::BpsException	(	const QString &	aFilename,
		quint32	aLinenumber,
		const QString &	aFunction,
		const QString &	aMessage,
		Severity	aSeverity
	)

Standard constructor for the BpsException objects.

This is the most used constructor variant in applications. Typical usage in throwing exceptions as:

throw BpsException( __FILE__, __LINE__, __FUNCTION__,
                    tr("Some error message about %1.").arg(topic), BpsException::Error);

For better convenience use the bpsMakeException macro:

throw bpsMakeException(tr("Some error message about %1.").arg(topic));

Parameters

aFilename	Source file name, most often provided by FILE macro.
aLinenumber	Source file line number, most often provided by LINE macro.
aFunction	Function name, most often provided by FUNCTION macro.
aMessage	The error message.
aSeverity	The error severity.

BpsException() [4/4]

BpsException::BpsException	(	const QScriptValue &	aException,
		const QString &	aFilename = QString()
	)

Constructor from QtScript exceptions.

Parameters

aException	Reference of the exception to copy.
aFilename	Source file name if known. Will be used if script value has no file info.

Member Function Documentation

addLocation()

BpsException& BpsException::addLocation	(	const QString &	aFilename,
		quint32	aLinenumber,
		const QString &	aFunction
	)

Add another location to an existing exception.

Typically used in catch blocks:

try {
    // doing some things here that might throw BpsException.
}
catch (BpsException& exc) {
    throw exc.addLocation(__FILE__, __LINE__, __FUNCTION__);
}

For better convenience use the macro bpsTraceException instead:

try {
    // doing some things here that might throw BpsException.
}
catch (BpsException& exc) {
    throw bpsTraceException(exc);
}

Parameters

aFilename	Source file name, most often provided by FILE macro.
aLinenumber	Source file line number, most often provided by LINE macro.
aFunction	Function name, most often provided by FUNCTION macro.

Returns

Reference of current object.

appendMessage()

BpsException& BpsException::appendMessage

(

const QString &

aText

)

Append text to the error message of the exception.

Parameters

aText

The text to append to the message.

Returns

Reference of current object.

message()

QString BpsException::message

(

)

const

Get the plain message, without location trace information.

Returns

The message of the exception.

setMessage()

BpsException& BpsException::setMessage

(

const QString &

aMessage

)

Set the error message for the exception.

Parameters

aMessage

The new error message.

Returns

Reference of current object.

setSeverity()

BpsException& BpsException::setSeverity

(

Severity

aSeverity

)

Set the error severity for the exception.

Parameters

aSeverity

The new error severity.

Returns

Reference of current object.

severity()

Severity BpsException::severity

(

)

const

Get severity.

Returns

The severity of the exception.

text()

QString BpsException::text

(

int

aMaxLocs = 1

)

const

Get the message, along with a log of the locations stack.

Parameters

aMaxLocs

The maximum number of locations to list.

Returns

Formatted text representation of the exception.

try {
    //...
    try {
        //...
        if (somethingwrong)
            throw bpsMakeException("Something is wrong.");
        //...
    }
    catch (BpsException& exc) {
        throw bpsTraceException(exc);
    }
    //...
}
catch (const BpsException& exc) {
    QMessageBox::critical(this, "Error", exc.text(2));
    // exc.text() =
    //     "Something is wrong.\n"
    //     "---\n"
    //     "myfile.cpp[45] MyClass::myfunc()\n"
    //     "myfile.cpp[49] MyClass::myfunc()\n";
}

throwScriptError()

QScriptValue BpsException::throwScriptError

(

QScriptContext *

aContext

)

const

Throw a script error of the exception.

This is useful in c++ code that was called from a script, for example in classes derived from QScriptable.

Note

In case the return type of the scriptable function or method is QScriptValue, make sure to return the result from throwScriptError to the scripting engine as in the example below.

QScriptValue myScriptableFunction(QScriptContext* aContext, QScriptEngine* aEngine)
{
    try {
        // Some code here that might throw a BpsException
        return result;
    }
    catch (const BpsException& exc) {
        return exc.throwScriptError(aContext);
    }
}

Parameters

aContext

Pointer to the script context.

Returns

QScriptValue representation of the exception as Error object.

Friends And Related Function Documentation

bpsMakeException

#define bpsMakeException (   aMessage )    BpsException(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__), aMessage, BpsException::Error)

related

Convenience macro to create a BpsException with severity of Error.

Parameters

aMessage

The error message.

Returns

The created BpsException.

See also

BpsException::BpsException(const QString& aFilename, quint32 aLinenumber, const QString& aFunction, const QString& aMessage, Severity aSeverity)

bpsMakeExceptionFatal

#define bpsMakeExceptionFatal (   aMessage )    BpsException(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__), aMessage, BpsException::Fatal)

related

Convenience macro to create a BpsException with severity of Fatal.

Note

This only creates the exception, but does not terminate the program. That has to be done in the catching block in case.

Parameters

aMessage

The error message.

Returns

The created BpsException.

See also

BpsException::BpsException(const QString& aFilename, quint32 aLinenumber, const QString& aFunction, const QString& aMessage, Severity aSeverity)

bpsMakeExceptionInfo

#define bpsMakeExceptionInfo (   aMessage )    BpsException(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__), aMessage, BpsException::Info)

related

Convenience macro to create a BpsException with severity of Info.

Parameters

aMessage

The error message.

Returns

The created BpsException.

See also

BpsException::BpsException(const QString& aFilename, quint32 aLinenumber, const QString& aFunction, const QString& aMessage, Severity aSeverity)

bpsMakeExceptionWarning

#define bpsMakeExceptionWarning (   aMessage )    BpsException(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__), aMessage, BpsException::Warning)

related

Convenience macro to create a BpsException with severity of Warning.

Parameters

aMessage

The error message.

Returns

The created BpsException.

See also

BpsException::BpsException(const QString& aFilename, quint32 aLinenumber, const QString& aFunction, const QString& aMessage, Severity aSeverity)

bpsTraceException

#define bpsTraceException (   aException )    aException.addLocation(__FILE__, __LINE__, QString::fromLatin1(__FUNCTION__))

related

Convenience macro to add a location to the traceback stack.

Parameters

aException

The exception to add current location to.

Returns

The exception with location ino added.

See also

BpsException::addLocation(const QString& aFilename, quint32 aLinenumber, const QString& aFunction)

---

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

• bpsexception.h