Document Symbian platform security requirements on Qt APIs

Work done jointly by Gareth and me. Yields no qdoc errors.

Task-number: QTBUG-9342
Task-number: QTBUG-9120
Reviewed-by: Gareth Stockwell
Reviewed-by: David Boddie

7 files changed, 86 insertions, 0 deletions

diff --git a/src/corelib/io/qprocess.cpp b/src/corelib/io/qprocess.cpp
index 12a992a..af1fc82 100644
--- a/src/corelib/io/qprocess.cpp
+++ b/src/corelib/io/qprocess.cpp
@@ -551,6 +551,16 @@ void QProcessPrivate::Channel::clear()
     interpreter itself (\c{cmd.exe} on some Windows systems), and ask
     the interpreter to execute the desired command.
 
+    \section1 Symbian Platform Security Requirements
+
+    On Symbian, processes which use the functions kill() or terminate()
+    must have the \c PowerMgmt platform security capability. If the client
+    process lacks this capability, these functions will fail.
+
+    Platform security capabilities are added via the
+    \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}
+    qmake variable.
+
     \sa QBuffer, QFile, QTcpSocket
 */
 
@@ -2006,9 +2016,13 @@ void QProcess::start(const QString &program, OpenMode mode)
     event loop does not handle the WM_CLOSE message, can only be terminated by
     calling kill().
 
+    On Symbian, this function requires platform security capability
+    \c PowerMgmt. If absent, the process will panic with KERN-EXEC 46.
+
     \note Terminating running processes from other processes will typically
     cause a panic in Symbian due to platform security.
 
+    \sa \l {Symbian Platform Security Requirements}
     \sa kill()
 */
 void QProcess::terminate()
@@ -2023,6 +2037,10 @@ void QProcess::terminate()
     On Windows, kill() uses TerminateProcess, and on Unix and Mac OS X, the
     SIGKILL signal is sent to the process.
 
+    On Symbian, this function requires platform security capability
+    \c PowerMgmt. If absent, the process will panic with KERN-EXEC 46.
+
+    \sa \l {Symbian Platform Security Requirements}
     \sa terminate()
 */
 void QProcess::kill()
diff --git a/src/multimedia/audio/qaudioinput.cpp b/src/multimedia/audio/qaudioinput.cpp
index 10bab01..c99e870 100644
--- a/src/multimedia/audio/qaudioinput.cpp
+++ b/src/multimedia/audio/qaudioinput.cpp
@@ -146,6 +146,20 @@ QT_BEGIN_NAMESPACE
     \snippet doc/src/snippets/audio/main.cpp 0
 
     \sa QAudioOutput, QAudioDeviceInfo
+
+    \section1 Symbian Platform Security Requirements
+
+    On Symbian, processes which use this class must have the
+    \c UserEnvironment platform security capability.  If the client
+    process lacks this capability, calls to either overload of start()
+    will fail.
+    This failure is indicated by the QAudioInput object setting
+    its error() value to \l{QAudio::OpenError} and then emitting a
+    \l{stateChanged()}{stateChanged}(\l{QAudio::StoppedState}) signal.
+
+    Platform security capabilities are added via the
+    \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}
+    qmake variable.
 */
 
 /*!
@@ -197,6 +211,8 @@ QAudioInput::~QAudioInput()
      If a problem occurs during this process the error() is set to QAudio::OpenError,
      state() is set to QAudio::StoppedState and stateChanged() signal is emitted.
 
+     \sa {Symbian Platform Security Requirements}
+
      \sa QIODevice
 */
 
@@ -217,6 +233,8 @@ void QAudioInput::start(QIODevice* device)
     If a problem occurs during this process the error() is set to QAudio::OpenError,
     state() is set to QAudio::StoppedState and stateChanged() signal is emitted.
 
+    \sa {Symbian Platform Security Requirements}
+
     \sa QIODevice
 */
 
diff --git a/src/network/access/qnetworkaccessmanager.cpp b/src/network/access/qnetworkaccessmanager.cpp
index 03b7192..acf894c 100644
--- a/src/network/access/qnetworkaccessmanager.cpp
+++ b/src/network/access/qnetworkaccessmanager.cpp
@@ -138,6 +138,16 @@ static void ensureInitialized()
     can be:
     \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 1
 
+    \section1 Symbian Platform Security Requirements
+
+    On Symbian, processes which use this class must have the
+    \c NetworkServices platform security capability. If the client
+    process lacks this capability, operations will result in a panic.
+
+    Platform security capabilities are added via the
+    \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}
+    qmake variable.
+
     \sa QNetworkRequest, QNetworkReply, QNetworkProxy
 */
 
diff --git a/src/network/socket/qtcpserver.cpp b/src/network/socket/qtcpserver.cpp
index 404eee7..932126d 100644
--- a/src/network/socket/qtcpserver.cpp
+++ b/src/network/socket/qtcpserver.cpp
@@ -79,6 +79,16 @@
     use waitForNewConnection(), which blocks until either a
     connection is available or a timeout expires.
 
+    \section1 Symbian Platform Security Requirements
+
+    On Symbian, processes which use this class must have the
+    \c NetworkServices platform security capability. If the client
+    process lacks this capability, it will lead to a panic.
+
+    Platform security capabilities are added via the
+    \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}
+    qmake variable.
+
     \sa QTcpSocket, {Fortune Server Example}, {Threaded Fortune Server Example},
         {Loopback Example}, {Torrent Example}
 */
diff --git a/src/network/socket/qtcpsocket.cpp b/src/network/socket/qtcpsocket.cpp
index b1c7c1c..70852a5 100644
--- a/src/network/socket/qtcpsocket.cpp
+++ b/src/network/socket/qtcpsocket.cpp
@@ -60,6 +60,16 @@
 
     \bold{Note:} TCP sockets cannot be opened in QIODevice::Unbuffered mode.
 
+    \section1 Symbian Platform Security Requirements
+
+    On Symbian, processes which use this class must have the
+    \c NetworkServices platform security capability. If the client
+    process lacks this capability, it will result in a panic.
+
+    Platform security capabilities are added via the
+    \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}
+    qmake variable.
+
     \sa QTcpServer, QUdpSocket, QFtp, QNetworkAccessManager,
     {Fortune Server Example}, {Fortune Client Example},
     {Threaded Fortune Server Example}, {Blocking Fortune Client Example},
diff --git a/src/network/socket/qudpsocket.cpp b/src/network/socket/qudpsocket.cpp
index e208904..d5366d3 100644
--- a/src/network/socket/qudpsocket.cpp
+++ b/src/network/socket/qudpsocket.cpp
@@ -86,6 +86,16 @@
     \l{network/broadcastreceiver}{Broadcast Receiver} examples
     illustrate how to use QUdpSocket in applications.
 
+    \section1 Symbian Platform Security Requirements
+
+    On Symbian, processes which use this class must have the
+    \c NetworkServices platform security capability. If the client
+    process lacks this capability, operations will result in a panic.
+
+    Platform security capabilities are added via the
+    \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}
+    qmake variable.
+
     \sa QTcpSocket
 */
 
diff --git a/src/network/ssl/qsslsocket.cpp b/src/network/ssl/qsslsocket.cpp
index 9623570..7ad471c 100644
--- a/src/network/ssl/qsslsocket.cpp
+++ b/src/network/ssl/qsslsocket.cpp
@@ -156,6 +156,16 @@
     is being encrypted and encryptedBytesWritten()
     will get emitted as soon as data has been written to the TCP socket.
 
+    \section1 Symbian Platform Security Requirements
+
+    On Symbian, processes which use this class must have the
+    \c NetworkServices platform security capability. If the client
+    process lacks this capability, operations will fail.
+
+    Platform security capabilities are added via the
+    \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY}
+    qmake variable.
+
     \sa QSslCertificate, QSslCipher, QSslError
 */