Documents > BPS V2 C++ API
Public Member Functions
BpsException Class Reference

BPS error exception class. More...

#include <bpsexception.h>

List of all members.

Public Member Functions

BpsException & addLocation (const QString &aFilename, quint32 aLinenumber, const QString &aFunction)
 Add another location to an existing exception.
BpsException & appendMessage (const QString &aText)
 Append text to the error message of the exception.
 BpsException ()
 Default constructor for the BpsException objects.
 BpsException (const BpsException &aException)
 Copy constructor for the BpsException objects.
 BpsException (const QString &aFilename, quint32 aLinenumber, const QString &aFunction, const QString &aMessage)
 Standard constructor for the BpsException objects.
 BpsException (const QScriptValue &aException, const QString &aFilename=QString())
 Constructor from QtScript exceptions.
QString message () const
 Get message.
BpsException & setMessage (const QString &aMessage)
 Set the error message for the exception.
QString text () const
 Get the message, along with a log of the locations stack.
QScriptValue throwScriptError (QScriptContext *aContext) const
 Throw a script error of the exception.

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.

Examples:

database1.cpp.

Constructor & Destructor Documentation

BpsException::BpsException ( const BpsException &  aException)

Copy constructor for the BpsException objects.

Parameters:
[in]aExceptionReference of the BpsException object to copy.
BpsException::BpsException ( const QString &  aFilename,
quint32  aLinenumber,
const QString &  aFunction,
const QString &  aMessage 
)

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

For better convenience use the bpsMakeException macro: 

 throw bpsMakeException(tr("Some error message about %1.").arg(topic));
Parameters:
[in]aFilenameSource file name, most often provided by __FILE__ macro.
[in]aLinenumberSource file line number, most often provided by __LINE__ macro.
[in]aFunctionFunction name, most often provided by __FUNCTION__ macro.
[in]aMessageThe error message.
BpsException::BpsException ( const QScriptValue &  aException,
const QString &  aFilename = QString() 
)

Constructor from QtScript exceptions.

Parameters:
[in]aExceptionReference of the exception to copy.
[in]aFilenameSource file name if known. Will be used if script value has no file info.

Member Function Documentation

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:
[in]aFilenameSource file name, most often provided by __FILE__ macro.
[in]aLinenumberSource file line number, most often provided by __LINE__ macro.
[in]aFunctionFunction name, most often provided by __FUNCTION__ macro.
Returns:
Reference of current object.
BpsException& BpsException::appendMessage ( const QString &  aText)

Append text to the error message of the exception.

Parameters:
[in]aTextThe text to append to the message.
Returns:
Reference of current object.
QString BpsException::message ( ) const

Get message.

Returns:
The message of the exception.
BpsException& BpsException::setMessage ( const QString &  aMessage)

Set the error message for the exception.

Parameters:
[in]aMessageThe new error message.
Returns:
Reference of current object.
QString BpsException::text ( ) const

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

Returns:
Formatted text representation of the exception. 
 try {
     //...
     try {
         //...
         if (somethingwrong)
             throw bpsNewException("Something is wrong.");
         //...
     }
     catch (BpsException& exc) {
         throw bpsAddLocation(exc);
     }
     //...
 }
 catch (const BpsException& exc) {
     QMessageBox::critical(this, "Error", exc.text());
     // exc.text() =
     //     "Something is wrong.\n"
     //     "---\n"
     //     "myfile.cpp[45] MyClass::myfunc()\n"
     //     "myfile.cpp[49] MyClass::myfunc()\n";
 }
Examples:
database1.cpp.
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:
[in]aContextPointer to the script context.
Returns:
QScriptValue representation of the exception as Error object.
The documentation for this class was generated from the following file:
Back to top