summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorHarald Fernengel <harald@trolltech.com>2009-06-10 13:32:13 (GMT)
committerHarald Fernengel <harald@trolltech.com>2009-06-10 13:33:30 (GMT)
commit07c2b197b294043893ff792c851f5833736e41e3 (patch)
tree6b12480e6e3986a1d235f1af4c1747512d2cb485 /src
parenta293cab198f51ca8920c3da1b671f51b26a9cb4a (diff)
downloadQt-07c2b197b294043893ff792c851f5833736e41e3.zip
Qt-07c2b197b294043893ff792c851f5833736e41e3.tar.gz
Qt-07c2b197b294043893ff792c851f5833736e41e3.tar.bz2
doc: document the Symbian exception helpers
Diffstat (limited to 'src')
-rw-r--r--src/corelib/global/qglobal.cpp97
-rw-r--r--src/corelib/global/qglobal.h3
2 files changed, 95 insertions, 5 deletions
diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp
index 484c618..32c9139 100644
--- a/src/corelib/global/qglobal.cpp
+++ b/src/corelib/global/qglobal.cpp
@@ -3214,14 +3214,85 @@ bool QInternal::callFunction(InternalFunction func, void **args)
#include <typeinfo>
-const char* QSymbianLeaveException::what() const throw()
+/*! \macro QT_TRANSLATE_SYMBIAN_LEAVE_TO_EXCEPTION(function)
+ \relates QSymbianLeaveException
+
+ TRAP leaves from Symbian \a function and throws an appropriate
+ standard C++ exception instead.
+ This must be used when calling Symbian OS leaving functions
+ from inside Qt or standard C++ code, so that the code can respond
+ correctly to the exception.
+
+ \warning This macro is only available on Symbian.
+
+ \sa QT_TRANSLATE_EXCEPTION_TO_SYMBIAN_ERROR(), QT_TRANSLATE_EXCEPTION_TO_SYMBIAN_LEAVE()
+*/
+
+/*! \macro QT_TRANSLATE_EXCEPTION_TO_SYMBIAN_ERROR(error, function)
+ \relates QSymbianLeaveException
+ \ingroup qts60
+
+ Catch standard C++ exceptions from a \a function and convert them to a Symbian OS
+ \a error code, or \c KErrNone if there is no exception.
+ This must be used inside Qt or standard C++ code when using exception throwing
+ code (practically anything) and returning an error code to Symbian OS.
+
+ \warning This macro is only available on Symbian.
+
+ \sa QT_TRANSLATE_EXCEPTION_TO_SYMBIAN_LEAVE(), QT_TRANSLATE_SYMBIAN_LEAVE_TO_EXCEPTION()
+*/
+
+/*! \macro QT_TRANSLATE_EXCEPTION_TO_SYMBIAN_LEAVE(function)
+ \relates QSymbianLeaveException
+ \ingroup qts60
+
+ Catch standard C++ exceptions from \a function and convert them to Symbian OS
+ leaves. This must be used inside Qt or standard C++ code when using exception
+ throwing code (practically anything) and returning to Symbian OS from a leaving function.
+ For example inside a Symbian active object's \c RunL function implemented with Qt code.
+
+ \warning This macro is only available on Symbian.
+
+ \sa QT_TRANSLATE_SYMBIAN_LEAVE_TO_EXCEPTION(), QT_TRANSLATE_EXCEPTION_TO_SYMBIAN_ERROR()
+*/
+
+/*! \class QSymbianLeaveException
+ \ingroup qts60
+ \brief Exception class representing a Symbian leave code.
+
+ \warning This class is only available on Symbian.
+*/
+
+/*! \fn QSymbianLeaveException::QSymbianLeaveException(int error)
+
+ Constructs a QSymbianLeaveException object that stores the given
+ Symbian \a error code.
+*/
+
+/*! \fn const char *QSymbianLeaveException::what() const
+
+ Returns a C-style character string describing the general
+ cause of the current error.
+
+ The string is not localized.
+*/
+const char *QSymbianLeaveException::what() const throw()
{
- static const char str[] = "Symbian leave exception %d";
- static char msg[sizeof(str)+12];
- sprintf(msg, str, error);
+ static char msg[36];
+ snprintf(msg, sizeof(msg), "Symbian leave exception %d", error);
return msg;
}
+/*! \relates QSymbianLeaveException
+ \ingroup qts60
+
+ Throws a QSymbianLeaveException if the \a error parameter is a symbian error code.
+ This is the exception throwing equivalent of Symbian's User::LeaveIfError.
+
+ \warning This function is only available on Symbian.
+
+ \sa qt_translateExceptionToSymbianErrorL(), qt_translateExceptionToSymbianError()
+*/
void qt_translateSymbianErrorToException(int error)
{
if (error >= KErrNone)
@@ -3234,11 +3305,29 @@ void qt_translateSymbianErrorToException(int error)
}
}
+/*! \relates QSymbianLeaveException
+ \ingroup qts60
+
+ Convert a caught standard C++ exception \a aThrow to a Symbian leave
+
+ \warning This function is only available on Symbian.
+
+ \sa qt_translateSymbianErrorToException(), qt_translateExceptionToSymbianError()
+*/
void qt_translateExceptionToSymbianErrorL(const std::exception& aThrow)
{
User::Leave(qt_translateExceptionToSymbianError(aThrow));
}
+/*! \relates QSymbianLeaveException
+ \ingroup qts60
+
+ Convert a caught standard C++ exception \a aThrow to a Symbian error code
+
+ \warning This function is only available on Symbian.
+
+ \sa qt_translateSymbianErrorToException(), qt_translateExceptionToSymbianErrorL()
+*/
int qt_translateExceptionToSymbianError(const std::exception& aThrow)
{
const std::type_info& atype = typeid(aThrow);
diff --git a/src/corelib/global/qglobal.h b/src/corelib/global/qglobal.h
index 030840e..3d441e3 100644
--- a/src/corelib/global/qglobal.h
+++ b/src/corelib/global/qglobal.h
@@ -2468,10 +2468,11 @@ QT_LICENSED_MODULE(DBus)
#if defined(Q_OS_SYMBIAN)
#include <stdexcept>
+
class QSymbianLeaveException : public std::exception
{
public:
- QSymbianLeaveException(int err) : error(err){ }
+ inline QSymbianLeaveException(int err) : error(err) {}
const char* what() const throw();
public:
int error;