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

1 files changed, 18 insertions, 0 deletions

diff --git a/src/multimedia/audio/qaudioinput.cpp b/src/multimedia/audio/qaudioinput.cpp
index 10bab01c8b..c99e87055e 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
 */