Merge branch 'master' of git@scm.dev.troll.no:qt/qt-s60-public

Conflicts:
	src/network/ssl/ssl.pri

3 files changed, 341 insertions, 0 deletions

diff --git a/doc/src/exceptionsafety.qdoc b/doc/src/exceptionsafety.qdoc
new file mode 100644
index 0000000..4e3e89e
--- /dev/null
+++ b/doc/src/exceptionsafety.qdoc
@@ -0,0 +1,144 @@
+/****************************************************************************
+**
+** 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 exceptionsafety.html
+    \title Exception Safety
+    \ingroup architecture
+    \brief A guide to exception safety in Qt.
+
+    \bold {Preliminary warning}: Exception safety is not feature complete!
+    Common cases should work, but classes might still leak or even crash.
+
+    Qt itself will not throw exceptions. Instead, error codes are used.
+    In addition, some classes have user visible error messages, for example
+    \l QIODevice::errorString() or \l QSqlQuery::lastError().
+    This has historical and practical reasons - turning on exceptions
+    can increase the library size by over 20%.
+
+    The following sections describe Qt's behavior if exception support is
+    enabled at compile time.
+
+    \tableofcontents
+
+    \section1 Exception safe modules
+
+    \section2 Containers
+    
+    Qt's \l{container classes} are generally exception neutral. They pass any
+    exception that happens within their contained type \c T to the user
+    while keeping their internal state valid.
+
+    Example:
+
+    \code
+    QList<QString> list;
+    ...
+    try {
+        list.append("hello");
+    } catch (...) {
+    }
+    // list is safe to use - the exception did not affect it.
+    \endcode
+
+    Exceptions to that rule are containers for types that can throw during assignment
+    or copy constructions. For those types, functions that modify the container as well as
+    returning a value, are unsafe to use:
+
+    \code
+    MyType s = list.takeAt(2);
+    \endcode
+
+    If an exception occurs during the assignment of \c s, the value at index 2 is already
+    removed from the container, but hasn't been assigned to \c s yet. It is lost
+    without chance of recovery.
+
+    The correct way to write it:
+
+    \code
+    MyType s = list.at(2);
+    list.removeAt(2);
+    \endcode
+
+    If the assignment throws, the container still contains the value, no data loss occured.
+
+    Note that implicitly shared Qt classes will not throw in their assignment
+    operators or copy constructors, so the limitation above does not apply.
+
+    \section1 Out of memory handling
+
+    Most desktop operating systems overcommit memory. This means that \c malloc()
+    or \c{operator new} return a valid pointer, even though there is not enough
+    memory available at allocation time. On such systems, no exception of type
+    \c std::bad_alloc is thrown.
+
+    On all other operating systems, Qt will throw an exception of type std::bad_alloc
+    if any allocation fails. Allocations can fail if the system runs out of memory or
+    doesn't have enough continuous memory to allocate the requested size.
+
+    Exceptions to that rule are documented. As an example, \l QImage::create()
+    returns false if not enough memory exists instead of throwing an exception.
+
+    \section1 Recovering from exceptions
+
+    Currently, the only supported use case for recovering from exceptions thrown
+    within Qt (for example due to out of memory) is to exit the event loop and do 
+    some cleanup before exiting the application.
+
+    Typical use case:
+
+    \code
+    QApplication app(argc, argv);
+    ...
+    try {
+        app.exec();
+    } catch (const std::bad_alloc &) {
+        // clean up here, e.g. save the session
+        // and close all config files.
+
+        return 0; // exit the application
+    }
+    \endcode
+
+    After an exception is thrown, the connection to the windowing server
+    might already be closed. It is not safe to call a GUI related function
+    after catching an exception.
+*/
diff --git a/doc/src/platform-notes.qdoc b/doc/src/platform-notes.qdoc
index c8046c4..63b721a 100644
--- a/doc/src/platform-notes.qdoc
+++ b/doc/src/platform-notes.qdoc
@@ -512,6 +512,19 @@
 */
 
 /*!
+    \page platform-notes-symbian.html
+    \title Platform Notes - Symbian
+    \contentspage Platform Notes
+
+    This page contains information about the Symbian platforms Qt is currently known
+    to run on. More information about the combinations of platforms and compilers
+    supported by Qt can be found on the \l{Supported Platforms} page.
+
+    For information about mixing exceptions with symbian leaves,
+    see \l QSymbianLeaveException.
+*/
+
+/*!
     \page platform-notes-embedded-linux.html
     \title Platform Notes - Embedded Linux
     \contentspage Platform Notes
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.
+*/