new symbian exception safety documentation

1 files changed, 184 insertions, 0 deletions

diff --git a/doc/src/symbian-exceptionsafety.qdoc b/doc/src/symbian-exceptionsafety.qdoc
new file mode 100644
index 0000000..212f707
--- /dev/null
+++ b/doc/src/symbian-exceptionsafety.qdoc
@@ -0,0 +1,184 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page symbianexceptionsafety.html
+    \title Exception Safety with Symbian
+    \ingroup qts60
+    \brief A guide to integrating exception safety in Qt with Symbian.
+
+    The following sections describe how Qt code can interoperate with Symbian's
+    exception safety system.
+
+    \tableofcontents
+
+    \section1 What the problem is
+    
+    Qt and Symbian have different exception systems. Qt works with standard C++ 
+    exceptions, whereas Symbian has its TRAP/Leave/CleanupStack system. So, what would 
+    happen if 
+    you mix the two systems? It could go wrong in a number of ways.
+
+    Cleanup ordering would be different between the two. When Symbian code 
+    leaves, the cleanup stack is cleaned up before anything else happens. After 
+    that, the objects on the call stack would be cleaned up as with a normal 
+    exception. So if there are any dependencies between stack based and cleanup stack 
+    owned objects, there could be problems due to this ordering. 
+
+    Symbian's \c XLeaveException, which is used when Symbian implements leaves as 
+    exceptions, is not derived from \c std::exception, so would not be caught in 
+    Qt catch statements designed to catch \c std::exception. 
+
+    Qt's and standard C++'s \c std::exception derived exceptions result in program 
+    termination if they fall back to a Symbian TRAP. 
+
+	These problems can be solved with barrier macros and helper functions that 
+	will translate between the two exception systems. Use them, in Qt code, 
+	whenever calling into or being called from Symbian code.
+
+    \section1 Qt calls to Symbian
+
+    When calling Symbian leaving functions from Qt code, we want to translate 
+    Symbian leaves to standard C++ exceptions. The following help is provided:
+
+    \list
+        \o \l qt_translateSymbianErrorToException(int error) takes a Symbian 
+        error code and throws an appropriate exception to represent it. 
+        This will do nothing if the error code is not in fact an error. The 
+        function is equivalent to Symbian's \c User::LeaveIfError.
+        \o \l QT_TRANSLATE_SYMBIAN_LEAVE_TO_EXCEPTION(f) takes a Symbian leaving 
+        code fragment f and runs it under a trap harness converting any resulting 
+        error into an exception.
+        \o \c TRAP and \c TRAPD from the Symbian libraries can be used to convert 
+        leaves to error codes. 
+    \endlist
+
+    \code
+    HBufC* buf=0;
+    // this will throw a std::bad_alloc because we've asked for too much memory
+    QT_TRANSLATE_SYMBIAN_LEAVE_TO_EXCEPTION(buf = HBufC::NewL(100000000));
+
+    _LIT(KStr,"abc");
+    TInt pos = KStr().Locate('c');
+    // pos is a good value, >= 0, so no exception is thrown
+    qt_translateSymbianErrorToException(pos);
+    
+    pos = KStr().Locate('d');
+    // pos == KErrNotFound, so this throws an exception
+    qt_translateSymbianErrorToException(pos);
+    \endcode
+    
+    \section1 Qt called from Symbian
+
+    When Qt code is called from Symbian, we want to translate standard C++ 
+    exceptions to Symbian leaves or error codes. The following help is 
+    provided:
+
+    \list
+        \o \l qt_translateExceptionToSymbianError(const std::exception& ex) - 
+        this takes a standard exception and gives an appropriate Symbian 
+        error code. If no mapping is known for the exception type, 
+        \c KErrGeneral is returned.
+        \o \l qt_translateExceptionToSymbianErrorL(const std::exception& ex) - 
+        this takes a standard exception and generates an appropriate Symbian 
+        leave.
+        \o \l QT_TRANSLATE_EXCEPTION_TO_SYMBIAN_ERROR(err, f) - this macro 
+        takes the standard C++ code fragment \c f, catches any std::exceptions 
+        thrown from it, and sets err to the corresponding Symbian error code. 
+        err is set to \c KErrNone otherwise.
+        \o \l QT_TRANSLATE_EXCEPTION_TO_SYMBIAN_LEAVE(f) - this macro takes the 
+        standard C++ code fragment \c f, catches any std::exceptions thrown from 
+        it, and throws a corresponding Symbian leave. 
+    \endlist
+    
+    \code
+    TInt DoTickL() // called from an active object RunL, ie Symbian leaves expected
+        {
+        // without the translation to Symbian Leave, we get a USER:0 panic
+        QT_TRANSLATE_EXCEPTION_TO_SYMBIAN_LEAVE({
+            int* x = new int[100000000];            // compiled as Qt code, will throw std::bad_alloc
+            delete [] x;
+        });
+        return 0;
+        }
+    \endcode
+
+    \section1 Common sense things
+
+    Try to minimise the interleaving of Symbian and Qt code, every switch 
+    requires a barrier. Grouping the code styles in different blocks will 
+    minimise the problems. For instance, examine the following code.
+
+    \code
+    1.    TRAPD(err, m_playUtility = CMdaAudioPlayerUtility::NewL(*this);
+    2.               QString filepath = QFileInfo( m_sound->fileName() ).absoluteFilePath();
+    3.               filepath = QDir::toNativeSeparators(filepath);
+    4.               m_playUtility->OpenFileL(qt_QString2TPtrC(filepath)));
+    \endcode
+
+    Line 1 starts a Symbian leave handling block, which is good because it 
+    also uses a Symbian leave generating function.
+
+    Line 2 creates a \l QString, uses \l QFileInfo and various member functions. 
+    These could all throw exceptions, which is not good inside a \c TRAP block.
+
+    Line 3 is unclear as to whether it might throw an exception, but since 
+    it's dealing with strings it probably does, again bad.
+
+    Line 4 is tricky, it calls a leaving function which is ok within a \c TRAP, 
+    but it also uses \l qt_QString2TPtrC. You might think this is safe, but 
+    there is a potential realloc call in there, so this can cause an unwelcome 
+    exception.
+
+    We could rewrite this with nested exception translations, but it's much 
+    easier to refactor it. 
+
+    \code
+    QString filepath = QFileInfo( m_sound->fileName() ).absoluteFilePath();
+    filepath = QDir::toNativeSeparators(filepath);
+    TPtrC filepathPtr(qt_QString2TPtrC(filepath));
+    TRAPD(err, m_playUtility = CMdaAudioPlayerUtility::NewL(*this);
+               m_playUtility->OpenFileL(filepathPtr));
+    \endcode
+
+    Now the exception generating functions are separated from the leaving 
+    functions.
+*/